null null

[1]
NetBeans
Developing Applications with NetBeans IDE
Release 8.2
E74654-01
September 2016
Documentation for NetBeans users that describes how to use
the NetBeans IDE and provides detailed information on the
functionality available within it.
NetBeans Developing Applications with NetBeans IDE, Release 8.2
E74654-01
Copyright © 2013, 2016 Oracle and/or its affiliates. All rights reserved.
Primary Author: Alyona Stashkova, Catherine Pickersgill
This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it
on behalf of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software,
any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users
are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and
agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and
adaptation of the programs, including any operating system, integrated software, any programs installed on
the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to
the programs. No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management
applications. It is not developed or intended for use in any inherently dangerous applications, including
applications that may create a risk of personal injury. If you use this software or hardware in dangerous
applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other
measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages
caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of
their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks
are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD,
Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced
Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content,
products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and
expressly disclaim all warranties of any kind with respect to third-party content, products, and services
unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its
affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of
third-party content, products, or services, except as set forth in an applicable agreement between you and
Oracle.
Contents
Preface ............................................................................................................................................................ xxvii
Audience..................................................................................................................................................
Documentation Accessibility ................................................................................................................
Related Documents ................................................................................................................................
Conventions ............................................................................................................................................
xxvii
xxvii
xxvii
xxvii
What's New in This Guide ................................................................................................................... xxix
New and Changed Features for Release 8.2 ........................................................................................
xxix
1 Introduction to NetBeans IDE
1.1
1.2
About NetBeans IDE .................................................................................................................. 1-1
NetBeans IDE Developer Resources ........................................................................................ 1-1
2 Working with NetBeans IDE
2.1
2.2
2.2.1
2.2.2
2.2.3
2.3
2.3.1
2.3.2
2.3.3
2.3.4
2.3.5
2.4
2.4.1
2.4.2
2.4.3
2.4.4
2.4.5
2.4.6
2.4.7
2.5
2.5.1
About Working with NetBeans IDE.........................................................................................
Working with the Options Window .......................................................................................
How to Edit IDE Settings....................................................................................................
How to Export IDE Settings as Zip Archive ....................................................................
How to Import IDE Settings...............................................................................................
Managing IDE Windows ..........................................................................................................
How to Move a Window ....................................................................................................
How to Configure Window Behavior and Appearance ................................................
How to Simultaneously Display Multiple Files in the Editor .......................................
How to Clone the View of a Single File............................................................................
How to Manage Open Files................................................................................................
Customizing Toolbars in the IDE .............................................................................................
How to Show or Hide a Toolbar........................................................................................
How to Move a Toolbar ......................................................................................................
How to Add a Toolbar Button to a Toolbar .....................................................................
How to Remove a Button from a Toolbar ........................................................................
How to Reorder a Button in a Toolbar .............................................................................
How to Change the Size of Toolbar Buttons....................................................................
How to Add a New Toolbar to the Main Window.........................................................
Working with Keyboard Shortcuts ..........................................................................................
How to Add or Remove a Keyboard Shortcut for a Menu Command........................
2-1
2-2
2-2
2-2
2-2
2-3
2-4
2-5
2-5
2-5
2-5
2-6
2-6
2-6
2-6
2-6
2-7
2-7
2-7
2-7
2-7
iii
2.5.2
2.5.3
2.5.4
2.5.5
2.5.6
2.6
2.6.1
2.6.2
2.6.3
2.6.4
2.6.5
2.6.6
2.6.7
2.6.8
2.6.9
2.6.9.1
2.6.10
2.6.11
2.6.12
2.6.13
2.6.14
2.6.15
2.6.16
2.7
2.8
2.8.1
2.8.2
2.8.3
2.9
2.9.1
2.9.2
2.9.3
2.9.4
2.9.5
2.9.6
2.10
2.10.1
2.10.2
2.11
2.11.1
2.11.2
2.11.3
2.11.4
2.11.5
2.11.6
2.11.7
2.12
iv
How to Customize Keyboard Shortcuts........................................................................... 2-8
How to Switch Between Keyboard Shortcut Sets ........................................................... 2-8
How to Create a New Keyboard Shortcut Set ................................................................. 2-9
How to Use the Default Menu Shortcuts ......................................................................... 2-9
How to Customize Keyboard Shortcuts........................................................................ 2-15
Understanding the Source Editor Features .......................................................................... 2-15
How to Use the Toolbar................................................................................................... 2-16
How to Use the Left Margin............................................................................................ 2-17
How to Use the Error Stripe............................................................................................ 2-18
How to Use the Status Line ............................................................................................. 2-18
How to Use Syntax Coloring and Highlighting........................................................... 2-18
How to Use Insert Mode and Overwrite Mode ........................................................... 2-19
How to Set Editor Options .............................................................................................. 2-19
How to Insert and Highlight Occurrences in the Editor............................................. 2-20
How to Record Macros .................................................................................................... 2-21
Macro Keywords for NetBeans Java Editor........................................................... 2-21
How to Modify Source Editor Code Templates ........................................................... 2-22
How to Use Code Completion........................................................................................ 2-23
How to Use Hints ............................................................................................................. 2-25
How to Navigate Through Code.................................................................................... 2-26
How to Work with Import Statements .......................................................................... 2-27
How to Generate Code..................................................................................................... 2-28
Using General Editor Shortcuts ...................................................................................... 2-28
Setting Startup Parameters ..................................................................................................... 2-31
Setting Fonts and Colors for IDE Windows......................................................................... 2-32
How to Set Fonts and Colors for the Help Viewer ...................................................... 2-32
How to Set Fonts and Colors for the Output Window ............................................... 2-33
How to Set Fonts and Colors for the Terminal Window ............................................ 2-33
Managing Plugins in the IDE ................................................................................................. 2-33
How to Update the IDE from the Update Center ....................................................... 2-34
How to Install Downloaded Plugins ............................................................................. 2-34
How to Activate and Deactivate Plugins ...................................................................... 2-35
How to Globally Install Plugins ..................................................................................... 2-35
How to Add an Update Center....................................................................................... 2-36
How to Schedule Update Checks ................................................................................... 2-36
Displaying IDE Help in a Web Browser ............................................................................... 2-36
How to Extract IDE Help from a JAR File..................................................................... 2-37
How to View IDE Help in a Web Browser.................................................................... 2-37
Internationalizing Source Code ............................................................................................. 2-37
How to Enable Automatic Internationalization ........................................................... 2-37
How to Internationalize a Single File............................................................................. 2-38
How to Use the Internationalization Wizard ............................................................... 2-38
How to Insert an Internationalized String Into Source Code..................................... 2-39
How to Internationalize a String With the GUI Builder ............................................. 2-39
How to Test a Bundle for Internationalized Strings .................................................... 2-40
How to Add Arguments for Message Formats ............................................................ 2-40
Managing and Creating Projects ........................................................................................... 2-41
2.12.1
How to Create a Project ...................................................................................................
2.12.2
How to Work with Character Encodings for a Project................................................
2.12.2.1
Changing the Character Encoding of a Project .....................................................
2.12.3
How to Organize Projects into Groups .........................................................................
2.13
Working with Source Files in the IDE...................................................................................
2.13.1
How to Find Files in Projects ..........................................................................................
2.13.2
How to Specify Editor Formatting Options..................................................................
2.13.3
How to Compare Two Files ............................................................................................
2.13.4
How to Apply a Diff Patch to a File ...............................................................................
2.13.5
How to Access Files Outside of a Project ......................................................................
2.13.6
How to Create a File Template .......................................................................................
2.13.7
How to Work with Unknown File Extensions .............................................................
2.13.8
How to Specify Files to Ignore........................................................................................
2.13.9
How to Work with Character Encodings for Files.......................................................
2.13.10
How to Specify Action Items ..........................................................................................
2.13.11
How to Use Bookmarks in Files .....................................................................................
2.14
Working with Resource Bundles ...........................................................................................
2.14.1
How to Create and Delete Resource Bundles...............................................................
2.14.2
How to Edit a Resource Bundle......................................................................................
2.14.3
How to Add and Remove a Property ............................................................................
2.14.4
How to Add and Remove a Locale ................................................................................
2.14.5
How to Edit a Locale ........................................................................................................
2.15
Working with Javadoc Documentation ................................................................................
2.15.1
How to Add Javadoc to a Project ...................................................................................
2.15.2
How to Add the JDK Javadoc to the IDE ......................................................................
2.15.3
How to View Javadoc Documentation ..........................................................................
2.15.4
How to Generate Javadoc Documentation ...................................................................
2.15.5
How to Enter Javadoc Comments in Source Code ......................................................
2.15.6
How To Analyze and Fix Javadoc Comments .............................................................
2.16
Viewing IDE Notifications......................................................................................................
2-41
2-42
2-42
2-43
2-43
2-43
2-44
2-45
2-45
2-46
2-46
2-47
2-47
2-48
2-48
2-50
2-50
2-51
2-51
2-52
2-53
2-53
2-54
2-54
2-55
2-55
2-55
2-56
2-57
2-57
3 Versioning Applications with Version Control
3.1
About Versioning Applications with Version Control.......................................................... 3-1
3.2
Versioning Applications with Git............................................................................................. 3-1
3.2.1
Git Visualization Features .................................................................................................. 3-2
3.2.2
How to Initialize a Git Repository..................................................................................... 3-2
3.2.3
How to Clone a Git Repository.......................................................................................... 3-3
3.2.3.1
Cloning a Repository from GitHub using SSH protocol ........................................ 3-4
3.2.4
How to Add Files to a Repository ..................................................................................... 3-5
3.2.5
How to Commit Sources to a Git Repository .................................................................. 3-6
3.2.6
How to Revert Modifications............................................................................................. 3-7
3.2.7
How to Reset ........................................................................................................................ 3-7
3.2.8
How to Create a Tag............................................................................................................ 3-8
3.2.9
How to Compare File Revisions ........................................................................................ 3-8
3.2.10
How to Work with Branches.............................................................................................. 3-9
3.2.10.1
Creating a Branch ......................................................................................................... 3-9
3.2.10.2
Checking Out ............................................................................................................. 3-10
v
3.2.10.3
Merging.......................................................................................................................
3.2.10.4
Deleting .......................................................................................................................
3.2.11
How to Work with Remote Repositories ......................................................................
3.2.11.1
Fetching.......................................................................................................................
3.2.11.2
Pulling .........................................................................................................................
3.2.11.3
Pushing .......................................................................................................................
3.2.12
How to Set Git Global Options .......................................................................................
3.2.13
How to Shelve Changes (Git)..........................................................................................
3.2.14
How to Rebase (Git) .........................................................................................................
3.3
Versioning Applications with Subversion ...........................................................................
3.3.1
Subversion Visualization Features .................................................................................
3.3.2
Working with Subversion................................................................................................
3.3.3
How to View File Status Information ............................................................................
3.3.4
How to Work with Version Histories ............................................................................
3.3.4.1
Searching for Specific Revisions..............................................................................
3.3.4.2
Comparing Revisions in the Search History Window .........................................
3.3.5
How to Set Up Subversion ..............................................................................................
3.3.6
How to Check Out Files From a Remote Repository (Subversion) ...........................
3.3.7
How to Place Projects Under Version Control (Subversion)......................................
3.3.8
How To Update Files in a Local Working Directory (Subversion) ...........................
3.3.8.1
Updating Projects with Dependencies ...................................................................
3.3.9
How to Compare File Revisions in Subversion............................................................
3.3.9.1
Comparing File Revisions Graphically ..................................................................
3.3.10
How to Commit Local Changes to a Remote Repository (Subversion)....................
3.3.10.1
Ignoring Files..............................................................................................................
3.3.11
How to Work with Branches in Subversion .................................................................
3.3.11.1
Checking Out Branches ............................................................................................
3.3.11.2
Creating Branches......................................................................................................
3.3.11.3
Switching to a Branch ...............................................................................................
3.3.12
How to Revert Modifications (Subversion) ..................................................................
3.3.13
How to Recover Deleted Files (Subversion) .................................................................
3.3.14
How to Merge File Revisions in Subversion.................................................................
3.3.15
Resolving Merge Conflicts in Subversion .....................................................................
3.3.16
How to Create and Apply a Patch (Subversion) ..........................................................
3.3.17
How to Shelve Changes (Subversion) ...........................................................................
3.4
Versioning Applications with Mercurial..............................................................................
3.4.1
About Mercurial Visualization Features .......................................................................
3.4.2
How to View File Status Information in Mercurial .....................................................
3.4.2.1
Viewing Revision Information ................................................................................
3.4.3
How to Set Up Mercurial.................................................................................................
3.4.4
How to Clone an External Mercurial Repository.........................................................
3.4.5
How to Place Projects Under Version Control .............................................................
3.4.6
How to Use the Mercurial Diff Viewer..........................................................................
3.4.7
How to Use the Mercurial Status Window ...................................................................
3.4.8
How to Merge File Revisions ..........................................................................................
3.4.9
How to Switch Branches in the Repository ..................................................................
3.4.10
How to Commit Changes to the Repository.................................................................
vi
3-11
3-11
3-11
3-11
3-12
3-12
3-12
3-13
3-13
3-14
3-14
3-14
3-15
3-16
3-16
3-17
3-17
3-18
3-19
3-19
3-20
3-20
3-20
3-21
3-22
3-22
3-22
3-23
3-23
3-24
3-24
3-25
3-25
3-26
3-27
3-27
3-28
3-28
3-28
3-29
3-30
3-31
3-32
3-33
3-34
3-34
3-35
3.4.10.1
Updating Tasks ..........................................................................................................
3.4.10.2
Ignoring Files..............................................................................................................
3.4.10.3
Pushing Local Changes to the Shared Repository................................................
3.4.11
How to Set Mercurial Project Properties .......................................................................
3.4.12
How to Set Mercurial Global Options ...........................................................................
3.4.13
How to Enable Support for Mercurial Queues.............................................................
3.4.14
How to Create a Patch......................................................................................................
3.4.15
How to Refresh a Patch With Local Modifications......................................................
3.4.16
How to Compare Patch Revisions..................................................................................
3.4.17
How to Switch Between Patches ....................................................................................
3.4.18
How to Finish Applied Patches ......................................................................................
3.4.19
How to Shelve Changes (Mercurial)..............................................................................
3.4.20
How to Rebase (Mercurial) .............................................................................................
3.5
Versioning Applications with CVS .......................................................................................
3.5.1
How to Work with CVS ...................................................................................................
3.5.2
How to Use CVS with the IDE........................................................................................
3.5.3
How to View File Status Information (CVS).................................................................
3.5.3.1
Viewing Revision Information ................................................................................
3.5.4
How to Work with Version Histories ............................................................................
3.5.4.1
Comparing Revisions in the Search History Window .........................................
3.5.5
How to Set Up CVS ..........................................................................................................
3.5.6
How to Adjust CVS Settings in the IDE ........................................................................
3.5.7
How to Check Out Files from a Remote Repository (CVS)........................................
3.5.8
How to Update Files in a Local Working Directory (CVS).........................................
3.5.8.1
Updating Projects with Dependencies ...................................................................
3.5.9
How to Compare File Revisions in CVS........................................................................
3.5.10
How to Commit Local Changes to a Remote Repository (CVS)................................
3.5.10.1
Excluding Files from a Commit...............................................................................
3.5.10.2
Ignoring Files..............................................................................................................
3.5.11
How to Revert Modifications (CVS) ..............................................................................
3.5.12
How to Recover Deleted Files (CVS) .............................................................................
3.5.13
How to Work with Tags .................................................................................................
3.5.14
How to Work with Branches in CVS .............................................................................
3.5.14.1
Checking out Branches .............................................................................................
3.5.14.2
Switching to a Branch ...............................................................................................
3.5.14.3
Creating a Branch ......................................................................................................
3.5.15
How to Merge File Revisions from a Branch (CVS) ....................................................
3.5.16
How to Resolve Merge Conflicts ....................................................................................
3.5.17
How to Create and Apply a Patch .................................................................................
3.6
About Local History ................................................................................................................
3.6.1
About the IDE’s Local History Tools .............................................................................
3.6.2
How to Browse Local File History .................................................................................
3.6.3
How to Recover Deleted Files.........................................................................................
3.6.4
How to Revert a File to a Previous Version ..................................................................
3.6.5
How to Adjust Local History Settings ...........................................................................
3-36
3-36
3-36
3-37
3-37
3-38
3-38
3-39
3-40
3-40
3-41
3-41
3-42
3-42
3-42
3-42
3-43
3-44
3-45
3-46
3-46
3-46
3-47
3-48
3-48
3-48
3-49
3-50
3-50
3-50
3-51
3-51
3-51
3-52
3-52
3-52
3-53
3-53
3-54
3-55
3-55
3-55
3-56
3-56
3-57
vii
4 Working in a Collaborative Environment
4.1
About Working in a Collaborative Environment................................................................... 4-1
4.2
Working with Tasks.................................................................................................................... 4-2
4.2.1
About Task Repositories..................................................................................................... 4-2
4.2.2
How to Work with Tasks.................................................................................................... 4-2
4.2.2.1
Finding and Opening Tasks........................................................................................ 4-3
4.2.2.2
Creating and Saving Task Queries............................................................................. 4-3
4.2.2.3
Reporting New Tasks................................................................................................... 4-4
4.2.2.4
Updating and Resolving Tasks................................................................................... 4-4
4.2.3
How to Add a Task Repository ......................................................................................... 4-5
4.2.4
How to Add Support for JIRA ........................................................................................... 4-5
4.3
Working with the Tasks Window............................................................................................. 4-6
4.3.1
How to View Tasks.............................................................................................................. 4-6
4.3.2
How to Organize Tasks....................................................................................................... 4-7
4.3.3
How to Configure Tasks Window Settings ..................................................................... 4-8
5 Working with NetBeans Modules
5.1
About NetBeans Modules.......................................................................................................... 5-1
5.2
About the NetBeans Platform ................................................................................................... 5-2
5.3
Working with NetBeans Modules ............................................................................................ 5-2
5.4
Working with Rich-Client Applications .................................................................................. 5-3
5.5
Module and Rich-Client Application Tasks: Quick Reference............................................. 5-6
5.6
Setting Up Modules .................................................................................................................... 5-7
5.6.1
About Module Project Templates...................................................................................... 5-8
5.6.2
How to Create a Module Project ....................................................................................... 5-9
5.6.3
How to Create a Library Wrapper Module Project ..................................................... 5-10
5.6.4
How to Create a Module Suite Project .......................................................................... 5-11
5.6.5
How to Create a NetBeans Platform Application Project........................................... 5-11
5.7
Using the NetBeans APIs ........................................................................................................ 5-12
5.7.1
Generating Skeleton API Implementations .................................................................. 5-12
5.7.1.1
About Actions ............................................................................................................ 5-14
5.7.1.2
How to Create an Action .......................................................................................... 5-14
5.7.1.3
About Code Generators ............................................................................................ 5-16
5.7.1.4
How to Create a Code Generator ............................................................................ 5-16
5.7.1.5
About File Types........................................................................................................ 5-16
5.7.1.6
How to Create a File Type........................................................................................ 5-17
5.7.1.7
About Module Installers........................................................................................... 5-18
5.7.1.8
Installing Modules..................................................................................................... 5-18
5.7.1.9
How to Create a Module Installer/Activator........................................................ 5-18
5.7.1.10
About Options Panels ............................................................................................... 5-19
5.7.1.11
How to Create an Options Panel............................................................................. 5-19
5.7.1.12
About Quick Search Providers ................................................................................ 5-19
5.7.1.13
How to Create Quick Search Providers.................................................................. 5-19
5.7.1.14
About Windows......................................................................................................... 5-20
5.7.1.15
How to Create a Window......................................................................................... 5-20
5.7.1.16
About Wizards ........................................................................................................... 5-21
5.7.1.17
How to Create A Wizard.......................................................................................... 5-22
viii
5.7.2
5.7.3
5.7.4
5.7.5
5.7.6
5.8
5.8.1
5.8.2
5.8.3
5.8.4
5.8.5
5.9
5.9.1
5.9.2
5.9.3
5.9.4
5.10
5.10.1
5.11
5.11.1
5.11.2
5.12
5.12.1
5.13
5.13.1
5.13.2
5.13.3
5.13.4
5.14
5.14.1
5.14.2
5.14.3
5.15
5.15.1
5.15.2
5.15.3
5.15.4
Extending Skeleton API Implementations ....................................................................
How to Register the NetBeans Sources and Javadoc...................................................
How to Use the NetBeans Sources and Javadoc ..........................................................
How to Search for NetBeans APIs..................................................................................
Code Templates for NetBeans APIs ...............................................................................
Bundling Supporting Items ....................................................................................................
How to Bundle a Library .................................................................................................
How to Bundle a Project Template or Sample..............................................................
How to Bundle an Update Center's URL ......................................................................
How to Bundle a JavaHelp Help Set..............................................................................
How to Bundle a License .................................................................................................
Registering Modules................................................................................................................
About the System Filesystem..........................................................................................
About XML Layer Files....................................................................................................
How to Edit an XML Layer File......................................................................................
How to View the System Filesystem .............................................................................
Communicating Between Modules .......................................................................................
About Service Providers ..................................................................................................
Building Modules.....................................................................................................................
About NBM Files ..............................................................................................................
How to Build an NBM File ..............................................................................................
Trying Out a Module...............................................................................................................
Deploying Modules ..........................................................................................................
About Distributing Modules ..................................................................................................
About Update Centers .....................................................................................................
How to Generate an Autoupdate Descriptor ...............................................................
How to Bundle an Update Center's URL ......................................................................
Manually Registering an Update Center URL .............................................................
Branding a Rich-Client Application ......................................................................................
How to Brand the Window System ...............................................................................
How to Add a Splash Screen...........................................................................................
How to Remove Unwanted Modules ............................................................................
Distributing Rich-Client Applications ..................................................................................
How to Build a ZIP Distribution ....................................................................................
How to Build a JNLP Application..................................................................................
How to Run a Rich-Client Application..........................................................................
How to Use the NetBeans Shared JNLP Repository....................................................
5-24
5-25
5-25
5-25
5-26
5-29
5-30
5-31
5-31
5-32
5-33
5-33
5-33
5-33
5-34
5-34
5-35
5-35
5-36
5-37
5-37
5-37
5-38
5-38
5-38
5-39
5-39
5-40
5-40
5-41
5-41
5-41
5-42
5-42
5-42
5-43
5-43
6 Creating Java Projects
6.1
About Creating Java Projects ....................................................................................................
6.2
Using Java Project Templates....................................................................................................
6.2.1
Standard Project Templates................................................................................................
6.2.1.1
Source Folders ...............................................................................................................
6.2.1.2
Project Settings ..............................................................................................................
6.2.1.3
Switching a Java SE Project to a JavaFX Deployment Model.................................
6.2.1.4
Adding a JavaFX Class to a Java SE Project..............................................................
6.2.1.5
Project Folders...............................................................................................................
6-1
6-2
6-2
6-4
6-4
6-4
6-4
6-5
ix
6.2.2
Free-Form Templates .......................................................................................................... 6-5
6.2.2.1
Source Folders ............................................................................................................... 6-6
6.2.2.2
Project Settings .............................................................................................................. 6-6
6.2.2.3
IDE Commands and Ant Targets ............................................................................... 6-6
6.2.2.3.1
Creating a Target to Compile a Single File ........................................................ 6-6
6.2.2.3.2
Writing a Target for the Apply Code Changes Command ............................. 6-7
6.2.3
Creating Standard Projects ................................................................................................. 6-8
6.2.3.1
Managing the Classpath .............................................................................................. 6-8
6.2.3.1.1
Classpath and Standard Projects......................................................................... 6-8
6.2.3.1.2
Classpath and Free-form Projects ....................................................................... 6-9
6.2.3.1.3
Adding Annotation Processors to the Classpath........................................... 6-10
6.2.3.2
Creating Dependencies Between Projects.............................................................. 6-10
6.2.3.3
Editing IDE-Generated Ant Scripts......................................................................... 6-11
6.2.3.4
Customizing the IDE-Generated Ant Script .......................................................... 6-12
6.2.3.5
Working with a JavaFX Project................................................................................ 6-13
6.2.3.5.1
JavaFX Application and JavaFX FXML Applications ................................... 6-13
6.2.3.5.2
JavaFX Preloaders .............................................................................................. 6-13
6.2.3.5.3
Editing JavaFX Applications............................................................................. 6-13
6.2.3.5.4
Building and Running JavaFX Applications .................................................. 6-13
6.2.3.5.5
Debugging JavaFX Applications ...................................................................... 6-14
6.2.4
Creating Free-Form Projects............................................................................................ 6-14
6.2.4.1
Source Folders ............................................................................................................ 6-14
6.2.4.2
Project Settings ........................................................................................................... 6-14
6.2.4.3
IDE Commands and Ant Targets ............................................................................ 6-14
6.2.4.4
Adding a Source Directory to a Free-Form Project .............................................. 6-15
6.2.4.5
Declaring the Classpath in a Free-Form Project.................................................... 6-16
6.2.4.6
Mapping an Ant Target to an IDE Command....................................................... 6-17
6.2.4.7
Debugging Free-Form Projects ................................................................................ 6-20
6.2.4.8
Storing IDE Targets in a Separate Ant Script ........................................................ 6-20
6.2.4.9
Editing the project.xml File ...................................................................................... 6-21
6.2.4.9.1
Using Properties in the project.xml File.......................................................... 6-21
6.2.4.9.2
Validating the project.xml File ......................................................................... 6-22
6.2.5
Setting Up a Java Project Based on Existing Sources................................................... 6-22
6.3
Importing an Eclipse or JBuilder Project .............................................................................. 6-23
6.4
Setting the Main Project .......................................................................................................... 6-27
6.5
Adding Multiple Sources Roots to a Project ........................................................................ 6-27
6.6
Sharing a Library with Other Users ...................................................................................... 6-28
6.6.1
How to Share a Library.................................................................................................... 6-28
6.7
Adding a Javadoc to a Project ................................................................................................ 6-30
6.7.1
How to Add a Javadoc to a Project ................................................................................ 6-30
6.8
Setting the Target JDK............................................................................................................. 6-31
6.8.1
How to Register a New Java Platform........................................................................... 6-31
6.8.2
How to Set the Target JDK .............................................................................................. 6-32
6.8.3
How to Upload Java SE Embedded JRE to a Remote Device..................................... 6-33
6.9
Moving, Copying, and Renaming a Project ......................................................................... 6-33
6.9.1
How to Move, Copy, or Rename a Project .................................................................... 6-33
6.10
Deleting a Project ..................................................................................................................... 6-33
x
7 Working with Java Code
7.1
7.2
7.2.1
7.3
7.3.1
7.3.2
7.3.3
7.3.4
7.3.5
7.4
7.4.1
7.5
7.5.1
7.5.1.1
7.6
7.7
About Working with Java Code ............................................................................................... 7-1
Editing Java Code ....................................................................................................................... 7-1
How to Identify Java Source Files ..................................................................................... 7-2
Navigating in Java Code ............................................................................................................ 7-4
Browsing Java Files.............................................................................................................. 7-4
Browsing XML Files ............................................................................................................ 7-6
Browsing Ant Scripts........................................................................................................... 7-6
Browsing an XML File......................................................................................................... 7-6
How to Navigate Within Your Code ................................................................................ 7-7
Finding and Replacing Text ...................................................................................................... 7-8
How to Find and Replace Text .......................................................................................... 7-8
Using Regular Expressions........................................................................................................ 7-9
Regular Expression Constructs.......................................................................................... 7-9
Sample Regular Expressions.................................................................................... 7-10
Using Special Code Templates............................................................................................... 7-10
Using Java Editor Shortcuts.................................................................................................... 7-11
8 Building Java Projects
8.1
8.2
8.2.1
8.2.2
8.2.2.1
8.2.3
8.2.4
8.2.5
8.2.6
8.2.7
8.2.8
8.2.8.1
8.2.8.2
8.2.9
8.3
8.4
8.4.1
8.5
8.5.1
8.6
8.7
8.8
8.9
8.9.1
8.10
8.11
8.11.1
About Building Java Projects .................................................................................................... 8-1
Working with Ant ....................................................................................................................... 8-2
Using Ant with the IDE ...................................................................................................... 8-2
How to Edit an Ant Script .................................................................................................. 8-3
Writing Custom Ant Tasks.......................................................................................... 8-6
How to Run an Ant Script .................................................................................................. 8-6
How to Debug an Ant Script.............................................................................................. 8-7
How to Create a Shortcut to a Target ............................................................................... 8-7
How to Configure Ant Settings ......................................................................................... 8-8
How to Switch Versions of Ant ......................................................................................... 8-8
Ant Classpaths and Custom Tasks.................................................................................... 8-9
Adding Binaries to Ant's Classpath in the IDE ........................................................ 8-9
Build Scripts With an Explicit Classpath .................................................................. 8-9
How to Install Ant Documentation in the IDE............................................................. 8-10
Working with Builds ............................................................................................................... 8-10
Building a Java Project ............................................................................................................ 8-10
How to Build a Java Project............................................................................................. 8-11
Using a Build Server ................................................................................................................ 8-12
Creating a Build ................................................................................................................ 8-12
Compiling a Single Java File................................................................................................... 8-13
Building a JAR File................................................................................................................... 8-13
Packaging an Application as a Native Installer................................................................... 8-14
Preparing a JAR File for Deployment Outside the IDE...................................................... 8-16
Running an Application JAR Outside of the IDE ........................................................ 8-16
Using the Output Window ..................................................................................................... 8-17
Refactoring Java Projects......................................................................................................... 8-17
How to Undo Refactoring Changes ............................................................................... 8-18
xi
8.11.2
How to Find Class, Methods, and Field Usages ..........................................................
8.11.2.1
Classes and Interfaces ...............................................................................................
8.11.2.2
Methods ......................................................................................................................
8.11.2.3
Fields ...........................................................................................................................
8.11.2.4
Additional Find Mechanisms ..................................................................................
8.11.3
How to Rename a Class or Interface ..............................................................................
8.11.4
How to Rename a Field or Method ................................................................................
8.11.5
How to Move a Class to Another Java Package ...........................................................
8.11.6
How to Move an Inner Class One Level Up .................................................................
8.11.7
How to Move a Class Member to a Superclass ............................................................
8.11.8
How to Move a Class Member to a Subclass ................................................................
8.11.9
How to Copy a Class ........................................................................................................
8.11.10
How to Encapsulate a Field.............................................................................................
8.11.11
How to Change a Method’s Signature...........................................................................
8.11.12
How to Invert a Boolean Method or Variable ..............................................................
8.11.13
Replacing a Constructor ..................................................................................................
8.11.14
How to Introduce a Variable, Constant, Field, or Method .........................................
8.11.15
How to Inline a Variable, Method, or Constant ...........................................................
8.11.16
How to Extract a Superclass............................................................................................
8.11.17
How to Extract an Interface.............................................................................................
8.11.18
How to Use a Supertype Where Possible......................................................................
8.11.19
How to Convert an Anonymous Inner Class to a Regular Inner Class ....................
8.11.20
How to Safely Delete Java Code .....................................................................................
8.11.20.1
Handling Deletions When The Code Element is Referenced .............................
8.11.21
Using Hints in Source Code Analysis and Refactoring ..............................................
8.11.22
How to Refactor an Enterprise Bean..............................................................................
8.12
Working with Maven in the IDE ...........................................................................................
8.12.1
How to Create a New Maven Project ............................................................................
8.12.2
How to Configure Maven Settings.................................................................................
8.12.2.1
Configuring Maven Settings for the IDE ...............................................................
8.12.2.2
Configuring Maven Settings for Projects ...............................................................
8.12.2.3
Using Project Configurations...................................................................................
8.12.2.4
Binding IDE Actions to Maven Goals.....................................................................
8.12.2.5
Creating Custom Actions .........................................................................................
8.12.3
How to Work with the Maven POM..............................................................................
8.12.4
How to Manage Maven Project Dependencies ............................................................
8.12.5
How to Work with Maven Artifacts ..............................................................................
8.12.5.1
Visualizing Dependencies ........................................................................................
8.12.6
How to Build a Maven Project ........................................................................................
8.12.6.1
Executing Maven Goals in the IDE .........................................................................
8.12.6.2
Customizing the Build Process................................................................................
8.12.6.3
Executing Individual Goals......................................................................................
8.13
Working with Maven Repositories .......................................................................................
8.13.1
How to Work with Maven Repositories........................................................................
8-18
8-18
8-19
8-19
8-19
8-19
8-20
8-21
8-22
8-22
8-23
8-24
8-24
8-25
8-27
8-27
8-28
8-29
8-29
8-30
8-31
8-31
8-32
8-32
8-33
8-34
8-34
8-35
8-36
8-36
8-36
8-36
8-37
8-37
8-38
8-39
8-39
8-40
8-41
8-42
8-42
8-42
8-42
8-43
9 Testing and Profiling Java Application Projects
9.1
xii
About Testing and Profiling Java Application Projects ........................................................ 9-2
9.2
Testing Java Application Projects with Unit Tests ................................................................. 9-2
9.2.1
Test Types in the IDE .......................................................................................................... 9-2
9.2.2
Unit Test Structure............................................................................................................... 9-3
9.3
Creating a Unit Test.................................................................................................................... 9-3
9.3.1
Changing the JUnit Version ............................................................................................... 9-3
9.3.2
How to Create a Unit Test .................................................................................................. 9-3
9.4
Running a Unit Test.................................................................................................................... 9-5
9.4.1
How to Run a Unit Test ...................................................................................................... 9-5
9.4.2
Working with Unit Test Output ........................................................................................ 9-6
9.5
Debugging a Unit Test ............................................................................................................... 9-6
9.6
Configuring Unit Test Settings ................................................................................................ 9-6
9.6.1
How to Edit Unit Test Settings .......................................................................................... 9-6
9.6.2
How to Edit the Classpath for Compiling or Running Tests ........................................ 9-7
9.7
Creating a Selenium Test ........................................................................................................... 9-7
9.8
Configuring Selenium Server Settings..................................................................................... 9-7
9.9
Starting a Profiling Session........................................................................................................ 9-8
9.9.1
How to Profile a Project ...................................................................................................... 9-8
9.9.2
How to Calibrate the Profiler............................................................................................. 9-9
9.9.3
Understanding the Toolbar Icons................................................................................... 9-10
9.10
Selecting a Profiling Task........................................................................................................ 9-11
9.10.1
How to Select a Profiling Task........................................................................................ 9-11
9.10.2
Using a Load Generator Script ....................................................................................... 9-11
9.11
Attaching the Profiler .............................................................................................................. 9-12
9.11.1
How to Configure the Attach Settings........................................................................... 9-12
9.11.2
How to Attach the Profiler to a Local Application ..................................................... 9-13
9.12
Attaching the Profiler to a Remote Application .................................................................. 9-14
9.12.1
How to Attach to a Remote Application ....................................................................... 9-14
9.12.2
Attaching to a Remote Server ......................................................................................... 9-15
9.13
Profiling a Free-form Project ................................................................................................. 9-16
9.13.1
Profiling Free-form Web Projects ................................................................................... 9-17
9.13.1.1
A Typical Free-Form Project Profile Target .......................................................... 9-18
9.13.1.2
Writing a Target to Profile a Selected File.............................................................. 9-19
9.14
Taking and Accessing Snapshots of Profiling Data ............................................................ 9-20
9.14.1
Taking Snapshots During a Profiling Session .............................................................. 9-20
9.14.2
Taking Snapshots at the End of a Profiling Session..................................................... 9-22
9.14.3
Starting and Stopping the Application Finished Dialog............................................. 9-22
9.14.4
Accessing Snapshots......................................................................................................... 9-22
9.15
Taking a Heap Dump .............................................................................................................. 9-22
9.15.1
How to Take a Heap Dump ............................................................................................ 9-22
9.15.2
How to Analyze a Heap Dump Using Object Query Language (OQL) ................... 9-23
9.15.2.1
OQL Examples ........................................................................................................... 9-24
9.15.2.2
OQL built-in objects and functions ......................................................................... 9-24
9.15.2.3
Selecting Multiple Values......................................................................................... 9-28
9.15.2.4
Other Examples.......................................................................................................... 9-31
9.16
Setting a Profiling Point .......................................................................................................... 9-32
9.16.1
How to Set Profiling Points ............................................................................................. 9-33
9.16.2
How to Reset Profiling Results ....................................................................................... 9-33
xiii
9.16.3
How to Set a Stopwatch Profiling Point ........................................................................
9.17
Profiling Telemetry ..................................................................................................................
9.18
Profiling Methods ....................................................................................................................
9.18.1
Basic Methods Profiling Mode........................................................................................
9.18.1.1
Selecting Threads.......................................................................................................
9.18.1.2
Searching And Filtering Results..............................................................................
9.18.2
Advanced Methods Profiling Mode ..............................................................................
9.18.3
Selecting Classes And Methods For Profiling ..............................................................
9.18.4
Configuring Additional Options ....................................................................................
9.19
Profiling Objects .......................................................................................................................
9.19.1
Basic Profiling....................................................................................................................
9.19.1.1
Results View...............................................................................................................
9.19.1.2
Searching And Filtering Results..............................................................................
9.19.2
Advanced Profiling ..........................................................................................................
9.19.2.1
Objects Profiling Modes............................................................................................
9.19.2.2
Selecting Classes For Profiling.................................................................................
9.19.2.3
Configuring Additional Options.............................................................................
9.19.2.4
Objects Views .............................................................................................................
9.19.2.5
Expert Mode of Objects Profiling ............................................................................
9.20
Profiling Threads......................................................................................................................
9.21
Profiling Locks..........................................................................................................................
9.22
SQL Queries Profiling .............................................................................................................
9.23
Additional Functions when Running a Profiling Session..................................................
9-34
9-34
9-35
9-36
9-37
9-37
9-37
9-38
9-38
9-39
9-39
9-39
9-40
9-40
9-40
9-41
9-41
9-41
9-42
9-42
9-43
9-44
9-46
10 Running and Debugging Java Application Projects
10.1
About Running Java Application Projects ...........................................................................
10.1.1
Running Standard Projects..............................................................................................
10.1.2
Running Free-form Projects ............................................................................................
10.2
Working with Project Execution ............................................................................................
10.3
Running an Application..........................................................................................................
10.4
Running a Single File...............................................................................................................
10.4.1
Writing a Target to Run/Debug/Test a Single File.....................................................
10.4.1.1
Running the Selected File .........................................................................................
10.4.1.2
Getting a Reference to the Currently Selected File in the IDE ............................
10.4.1.3
Debugging the Selected File.....................................................................................
10.5
Setting the Runtime Classpath...............................................................................................
10.6
Setting the Main Class and Runtime Arguments................................................................
10.7
Setting JVM Arguments ..........................................................................................................
10.8
Debugging Applications .........................................................................................................
10.8.1
Debugging Free-form Projects ........................................................................................
10.8.1.1
How to Create a Debug Target for a Free-form Java Project ..............................
10.8.1.1.1
A Typical Free-form Project Debug Target...................................................
10.8.1.1.2
Manually Mapping a Target to a Menu Item ...............................................
10.8.1.1.3
Troubleshooting................................................................................................
10.8.1.2
How to Create a Debug Target for a Free-form Web Project ............................
10.8.1.2.1
Using the Debug Target ..................................................................................
10.8.1.2.2
Troubleshooting the Debug Target................................................................
xiv
10-1
10-2
10-2
10-2
10-2
10-3
10-3
10-4
10-4
10-5
10-6
10-7
10-8
10-8
10-9
10-9
10-10
10-12
10-12
10-12
10-15
10-16
10.8.2
Debugging GUI Projects ................................................................................................
10.8.2.1
GUI Snapshots..........................................................................................................
10.8.2.2
Working with the Visual Debugger......................................................................
10.8.2.2.1
Locating the Source Code for Components..................................................
10.8.2.2.2
Exploring Component Events ........................................................................
10.8.2.3
How to Configure Java Debugger Options .........................................................
10.9
Using the Debugger Windows.............................................................................................
10.9.1
Customizing a Debugger Window ..............................................................................
10.9.2
Choosing Current Context in the Debugger...............................................................
10.9.2.1
Debugger Windows and Context..........................................................................
10.9.2.2
The Source Editor and Context..............................................................................
10.9.3
Attaching Source Code to a JAR File ...........................................................................
10.9.4
Managing Breakpoints ...................................................................................................
10.9.4.1
How to Set a Java Breakpoint ................................................................................
10.9.4.2
How to Set a Conditional Breakpoint...................................................................
10.9.4.3
How to Organize Breakpoints Into a Group .......................................................
10.9.4.4
About Source Maps Support..................................................................................
10.9.5
Managing Debugging Sessions.....................................................................................
10.9.5.1
How to Manage a Local Debugging Session .......................................................
10.9.5.1.1
Debugging the Main Project ...........................................................................
10.9.5.2
How to Manage a Remote Debugging Session ...................................................
10.9.5.3
How to Step Through Your Program ...................................................................
10.9.5.4
How to Fix and Continue in a Debugging Session.............................................
10.9.5.5
How to Finish a Debugging Session .....................................................................
10.9.6
Viewing Program Information When Debugging .....................................................
10.9.6.1
Using the Variables Window .................................................................................
10.9.6.2
Using the Loaded Classes Window ......................................................................
10.9.6.3
Using the Events Window......................................................................................
10.9.6.4
Evaluating Variables in the Source Editor ...........................................................
10.9.6.5
How to Create a Watch...........................................................................................
10.9.6.6
How to Create a Fixed Watch ................................................................................
10.9.6.7
How to Pin a Watch ................................................................................................
10.9.6.8
Debugging Threads in the IDE ..............................................................................
10.9.6.8.1
Changing the Current Thread ........................................................................
10.9.6.8.2
Suspending and Resuming Threads..............................................................
10.9.6.8.3
Editor window icons........................................................................................
10.9.6.8.4
Multi-threaded Applications ..........................................................................
10.9.6.8.5
Viewing Source Code for a Thread................................................................
10.9.6.9
Using the Call Stack ................................................................................................
10.9.6.9.1
Changing the Current Call..............................................................................
10.9.6.9.2
Popping a Call From the Call Stack ...............................................................
10.9.6.10
How to Evaluate Code............................................................................................
10.9.6.11
How to Step Through an Expression....................................................................
10-18
10-18
10-19
10-19
10-20
10-20
10-21
10-21
10-22
10-22
10-22
10-22
10-24
10-25
10-26
10-27
10-27
10-27
10-28
10-28
10-29
10-29
10-30
10-31
10-31
10-31
10-32
10-32
10-32
10-33
10-33
10-34
10-34
10-34
10-34
10-35
10-35
10-35
10-35
10-36
10-36
10-36
10-37
11 Implementing Java GUIs
11.1
About Implementing Java GUIs ............................................................................................ 11-1
11.1.1
The IDE's Java GUI Tools ................................................................................................ 11-1
xv
11.2
Working with the GUI Builder .............................................................................................. 11-2
11.2.1
How to Create a New Form ............................................................................................ 11-3
11.2.2
How to Work with Containers ....................................................................................... 11-4
11.2.2.1
Controlling View Focus ............................................................................................ 11-4
11.2.2.2
Reordering Components Within a Container ....................................................... 11-4
11.2.3
How to Add a Component to a Form ............................................................................ 11-5
11.2.4
How to Select Components in a Form ........................................................................... 11-6
11.2.5
Controlling Selection Depth ............................................................................................ 11-6
11.2.6
How to Align Components ............................................................................................. 11-7
11.2.7
How to Size Components ................................................................................................ 11-8
11.2.8
How to Edit Component Properties .............................................................................. 11-8
11.2.9
How to Set Events with the Connection Wizard ......................................................... 11-9
11.2.10
How to Manage Component Events............................................................................ 11-10
11.2.10.1
Defining Event Handlers........................................................................................ 11-10
11.2.11
How to Modify GUI Source Code ................................................................................ 11-11
11.2.11.1
Modifying Code Generation for Form Components.......................................... 11-12
11.2.11.2
Setting Variable Modifiers for a Java Component.............................................. 11-12
11.2.11.3
Modifying Code Generation for a Property ........................................................ 11-12
11.2.11.4
Modifying GUI Form Code Outside of the IDE.................................................. 11-13
11.2.12
How to Create a Multiple Document Interface (MDI) Application ........................ 11-14
11.2.13
How to Create Accessible Forms.................................................................................. 11-15
11.2.14
How to Preview a Form................................................................................................. 11-15
11.3
Working with Layout Managers.......................................................................................... 11-15
11.3.1
How to Set the Layout Manager................................................................................... 11-17
11.3.2
How to Use the GridBag Customizer .......................................................................... 11-18
11.3.3
How to Use a Custom Layout Manager...................................................................... 11-19
11.3.4
How to Set Layout Properties ....................................................................................... 11-20
11.4
Adding a Bean to the Window............................................................................................. 11-20
11.5
Working with Database Applications and Beans Binding .............................................. 11-21
11.5.1
How to Bind Two Bean Properties............................................................................... 11-22
11.5.2
How to Bind Data to a Swing Components................................................................ 11-22
11.5.3
How to Use Special Binding Properties (Java Desktop Applications).................... 11-23
11.5.4
How to Convert Values Between Source and Target Properties (Java Desktop
Applications) 11-24
11.5.5
How to Validate Target Value Changes in Bindings (Java Desktop Applications)...........
11-25
11.6
Deploying GUI Applications................................................................................................ 11-26
11.6.1
Preparing a GUI Application for Distribution ........................................................... 11-26
11.6.2
Running a Standalone GUI Application...................................................................... 11-27
11.7
Configuring the GUI Builder................................................................................................ 11-27
12 Developing Web Applications
12.1
About Developing Web Applications...................................................................................
12.2
Creating Web Application Projects .......................................................................................
12.2.1
How to Create a Web Application Project ....................................................................
12.2.2
Setting Up a Web Project Based on Existing Sources ..................................................
12.3
Working with JSP Files............................................................................................................
xvi
12-1
12-2
12-3
12-3
12-4
12.3.1
How to Create a JSP File ..................................................................................................
12.3.2
How to Set Character Encoding .....................................................................................
12.3.3
How to Edit a JSP File ......................................................................................................
12.3.4
How to Access a Custom Tag from a JSP Page ............................................................
12.3.5
How to Access an Applet from a JSP Page .................................................................
12.3.6
How to Compile a JSP File ............................................................................................
12.3.7
How to View a JSP File's Servlet...................................................................................
12.3.8
How to Pass Request Parameters .................................................................................
12.3.9
How to Run a JSP File ....................................................................................................
12.4
Working with Tag Libraries .................................................................................................
12.4.1
How to use Tag Libraries .............................................................................................
12.4.2
How to Create a Tag Library Descriptor....................................................................
12.4.3
How to Edit a Tag Library Descriptor ........................................................................
12.4.4
How to Create a Tag File ..............................................................................................
12.4.5
How to Edit a Tag File ..................................................................................................
12.4.6
How to Create a Tag Handler ......................................................................................
12.4.7
How to Define TLD Information for a Tag Handler ................................................
12.5
Working with Applets...........................................................................................................
12.5.1
How to Create an Applet..............................................................................................
12.5.2
How to Create an Applet that is Called from a JNLP File.......................................
12.5.3
How to Run an Applet..................................................................................................
12.5.4
How to Generate an Applet Policy File.......................................................................
12.6
Working with Servlets..........................................................................................................
12.6.1
How to Create a Servlet Source File............................................................................
12.6.2
How to Edit a Servlet Source File.................................................................................
12.6.3
How to View the Servlet Generated from a JSP File .................................................
12.6.4
How to Specify Parameters for a JSP Page.................................................................
12.6.5
How to Run a Servlet ....................................................................................................
12.7
Using Filters ...........................................................................................................................
12.7.1
How to Create a Filter ...................................................................................................
12.7.2
How to Register a Filter ................................................................................................
12.8
Using Web Application Listeners........................................................................................
12.8.1
How to Create a Web Application Listener ...............................................................
12.8.2
How to Register a Web Application Listener ............................................................
12.9
Using WebSocket Endpoints ................................................................................................
12.9.1
How to Create a WebSocket Endpoint .......................................................................
12.9.2
How to Create a WebSocket Encoder or Decoder ....................................................
12.10 Configuring a Web Application..........................................................................................
12.10.1
How to Set Build Properties..........................................................................................
12.10.2
How to Edit Deployment Descriptors ........................................................................
12.11 Deploying a Web Application..............................................................................................
12.11.1
How to Deploy a Web Application.............................................................................
12.11.2
How to Change the Target Server ...............................................................................
12.12 Debugging a Web Application.............................................................................................
12.12.1
How to Debug a Web Application ..............................................................................
12.12.2
How to Debug a JSP File...............................................................................................
12.12.3
How to Debug a Servlet................................................................................................
12-5
12-5
12-9
12-9
12-10
12-10
12-11
12-12
12-12
12-13
12-13
12-13
12-14
12-15
12-16
12-17
12-17
12-18
12-18
12-19
12-19
12-20
12-21
12-21
12-22
12-22
12-23
12-23
12-24
12-24
12-25
12-25
12-26
12-26
12-27
12-27
12-28
12-28
12-29
12-29
12-30
12-31
12-33
12-33
12-33
12-34
12-34
xvii
12.13 Profiling a Web Application................................................................................................. 12-34
12.13.1
How to Profile a Standalone Web Application ......................................................... 12-34
12.13.2
How to Profile an Enterprise Application.................................................................. 12-35
13 Using Web Application Frameworks
13.1
About Using Web Application Frameworks .......................................................................
13.2
Working with the JavaServer Faces Framework ................................................................
13.2.1
How to Create a New Project with JSF Support..........................................................
13.2.2
How to Add Support for a JSF Component Suite.......................................................
13.2.3
How to Add JSF Support to an Existing Web Application........................................
13.2.4
How to Create a JSF Page ...............................................................................................
13.2.5
How to Edit a JSF page ...................................................................................................
13.2.6
How to Create a JSF Facelets Template ........................................................................
13.2.7
How to Create Composite Components ......................................................................
13.2.8
How to Create a JSF Managed Bean .............................................................................
13.2.9
How to Work with JSF Components in the Palette ....................................................
13.2.10
How to Create a JSF Form for Entity Data .................................................................
13.2.11
How to Generate a JSF Data Table from an Entity Class ..........................................
13.2.12
How to Generate JSF Pages from Entity Classes........................................................
13.2.13
How to Generate a Validation Constraint...................................................................
13.3
Working with the Spring Framework................................................................................
13.3.1
How to Create a New Project with Spring MVC Framework Support .................
13.3.2
How to Add Spring MVC Framework Support to an Existing Application ........
13.3.3
How to Create a Spring Configuration File ...............................................................
13.3.4
How to Organize Spring Configuration Files............................................................
13.3.4.1
Accessing the Spring Configuration Group Panel.............................................
13.3.4.2
Specifying Spring Configuration Files ................................................................
13.3.4.3
Organizing Spring Configuration Files into Groups.........................................
13.4
Working with the Struts Framework .................................................................................
13.4.1
How to Create a New Project with Struts Framework Support .............................
13.4.2
How to Add Struts Framework Support to an Existing Application ....................
13.5
Working with the Hibernate Framework..........................................................................
13.5.1
How to Create a New Project with Hibernate Support ...........................................
13.5.2
How to Add Hibernate Support to an Existing Application...................................
13.5.3
How to Create the Hibernate Configuration File......................................................
13.5.4
How to Edit the Hibernate Configuration File..........................................................
13.5.5
How to Create Hibernate Mapping Files ...................................................................
13.5.6
How to Generate Hibernate Mapping Files and POJOs from a Database ............
13.5.7
How to Create a Hibernate Reverse Engineering File..............................................
13.5.8
How to Create a Hibernate Utility Helper File .........................................................
13.5.9
How to Create and Execute a HQL Statement or Script ..........................................
13.6
Working with the Grails Framework.................................................................................
13.6.1
How to Create a New Project with Grails Framework Support .............................
13.6.2
How to Install a Grails Plugin into a Grails Application .........................................
13-1
13-1
13-3
13-4
13-5
13-5
13-5
13-7
13-8
13-8
13-9
13-10
13-11
13-12
13-13
13-13
13-15
13-15
13-16
13-16
13-16
13-17
13-17
13-17
13-18
13-18
13-18
13-19
13-19
13-20
13-20
13-21
13-21
13-22
13-23
13-23
13-24
13-24
13-25
14 Developing Enterprise Applications
14.1
xviii
About Developing Enterprise Applications......................................................................... 14-1
14.2
14.2.1
14.3
14.3.1
14.4
14.4.1
14.5
14.5.1
14.6
14.6.1
14.7
14.7.1
14.7.2
14.7.3
14.8
14.8.1
14.9
14.9.1
14.9.2
14.9.3
14.9.4
14.9.5
14.9.6
14.9.7
Adding Modules to the Project ..............................................................................................
How to Add a Module to an Existing Project...............................................................
Adding Resources to the Project............................................................................................
How to Add an External Resource to an EAR File ......................................................
Editing Deployment Descriptors ...........................................................................................
How to Edit an Enterprise Application's Deployment Descriptors ..........................
Building Enterprise Applications ..........................................................................................
How to Build an Enterprise Application Project and Sub-Projects ...........................
Verifying Enterprise Applications.........................................................................................
How to Verify a Project's Deployment Descriptors.....................................................
Deploying Enterprise Applications.......................................................................................
How to Run an Enterprise Application.........................................................................
How to Deploy an Enterprise Application ...................................................................
How to Undeploy an Enterprise Application ..............................................................
Packaging Enterprise Applications .......................................................................................
How to Redeploy a Project to a Different Server .........................................................
About Docker Platform Support............................................................................................
How to Register a Docker Instance ................................................................................
How to Manage Docker Images .....................................................................................
How to Manage a Container ...........................................................................................
How to Run a Docker Container ....................................................................................
How to Create a Dockerfile .............................................................................................
How to Edit a Dockerfile .................................................................................................
How to Build an Image from a Dockerfile ....................................................................
14-2
14-3
14-3
14-3
14-3
14-4
14-4
14-4
14-5
14-5
14-6
14-6
14-6
14-7
14-7
14-7
14-7
14-7
14-8
14-8
14-9
14-9
14-9
14-9
15 Developing Application Clients
15.1
About Developing Application Clients ................................................................................
15.2
Creating Application Clients..................................................................................................
15.2.1
How to create an enterprise application client.............................................................
15.2.2
How to edit the deployment descriptors of an enterprise application client ..........
15.2.3
How to add a module to an enterprise application.....................................................
15-1
15-1
15-2
15-2
15-3
16 Developing with Enterprise Beans
16.1
16.2
16.2.1
16.3
16.3.1
16.3.2
16.3.3
16.3.4
16.3.5
16.3.6
16.3.7
16.4
16.4.1
About Developing with Enterprise Beans............................................................................
Creating an EJB Module Project.............................................................................................
How to Create an EJB Module Project...........................................................................
Creating an Enterprise Bean...................................................................................................
How to Create Enterprise Beans.....................................................................................
How to Generate Session Beans for Entity Classes......................................................
How to Define a Business Method for an Enterprise Bean ........................................
How to Send JMS Messages ............................................................................................
How to Use a Service Locator .........................................................................................
How to Access a Connection Pool from a Java Class ..................................................
How to Send an Email from a Java File.........................................................................
Calling an Enterprise Bean ...................................................................................................
How to call an Enterprise Bean ....................................................................................
16-1
16-2
16-3
16-4
16-4
16-5
16-6
16-7
16-8
16-9
16-9
16-10
16-10
xix
16.5
Building and Deploying an EJB Module ............................................................................ 16-11
16.5.1
How to Build an EJB Module as Part of an Enterprise Application........................ 16-11
16.5.2
How to Build a Stand-alone EJB Module .................................................................... 16-12
16.5.3
How to Edit the Deployment Descriptors of an EJB Module................................... 16-13
16.5.4
How to Verify the Deployment Descriptors of an EJB Module............................... 16-14
16.5.5
How to Deploy a Stand-alone EJB Module................................................................. 16-15
16.5.6
How to Debug an EJB Module...................................................................................... 16-15
16.5.7
How to Profile an EJB Module...................................................................................... 16-16
16.5.8
How to Test an EJB Module .......................................................................................... 16-17
16.6
Developing EJB 2.1 Entity Beans ......................................................................................... 16-18
17 Developing with Java Persistence
17.1
17.2
17.2.1
17.2.2
17.2.3
17.2.4
17.2.5
17.3
17.3.1
17.3.2
17.3.3
17.3.4
17.4
17.4.1
17.5
17.5.1
About Developing with Java Persistence .............................................................................
Creating a Persistence Unit.....................................................................................................
Scope of the Persistence Unit ..........................................................................................
Persistence Provider .........................................................................................................
Data Source........................................................................................................................
Transaction Types.............................................................................................................
How to Create a Persistence Unit...................................................................................
Creating an Entity Class..........................................................................................................
How to Create an Entity Class ........................................................................................
How to Map Entity Classes .............................................................................................
How to Generate Entity Classes from a Database .......................................................
How to Obtain an Entity Manager.................................................................................
Generating JPA Controller Classes........................................................................................
How to Generate a JPA Controller Class from an Entity Class .................................
Adding Support for Java Persistence ....................................................................................
How to Add Support for Java Persistence to the Project ............................................
17-1
17-2
17-2
17-3
17-3
17-3
17-3
17-4
17-4
17-5
17-6
17-7
17-7
17-8
17-8
17-8
18 Developing Applications Using XML
18.1
18.2
18.2.1
18.2.2
18.2.3
18.2.4
18.2.5
18.2.6
18.3
18.4
18.5
18.6
18.7
About Developing Applications Using XML ......................................................................
Creating and Editing XML Documents ................................................................................
How to Create a Well-formed XML Document ...........................................................
How to Create a DTD-constrained XML Document ...................................................
How to Create an XML Schema-constrained Document ............................................
How to Edit an XML Document.....................................................................................
How to Validate an XML Document .............................................................................
How to Check that an XML Document is Well-formed..............................................
Generating a DTD from an Existing XML File ....................................................................
Creating an Empty DTD .........................................................................................................
Generating Documentation for a DTD .................................................................................
Registering a Local DTD or XML Schema............................................................................
Removing a DTD or XML Schema Entry from the User Catalog .....................................
18-1
18-1
18-2
18-2
18-3
18-3
18-4
18-4
18-5
18-5
18-5
18-6
18-6
19 Developing and Securing Web Services
19.1
xx
About Developing and Securing Web Services................................................................... 19-1
19.2
Working with Web Services ...................................................................................................
19.3
Creating Web Services.............................................................................................................
19.3.1
How to Create SOAP (JAX-WS) Web Services.............................................................
19.3.1.1
How to Add Operations to a JAX-WS Web Service .............................................
19.3.1.2
How to Use the JAX-WS Web Service Designer ...................................................
19.3.2
How to Create RESTful Web Services ...........................................................................
19.4
Configuring Web Services ......................................................................................................
19.4.1
Using Annotations and Deployment Descriptors........................................................
19.4.2
How to Configure a Web Service With Annotations ................................................
19.4.3
How to Configure a Web Service With Its Deployment Descriptor .......................
19.5
Creating JAX-WS Web Service Clients ...............................................................................
19.5.1
How to Work with JAX-WS Web Service Clients ......................................................
19.5.2
How to Set a Proxy for Web Services and Clients .....................................................
19.5.3
How to Generate a JAX-WS Web Service Client........................................................
19.5.4
How to Call a Web Service Operation.........................................................................
19.5.5
How to Asynchronously Call a Web Service Operation...........................................
19.5.6
How to Deploy a Web Service Client ..........................................................................
19.6
Creating RESTful Web Service Clients ...............................................................................
19.6.1
How to Work with RESTful Web Service Clients ......................................................
19.6.2
How to Generate RESTful Web Service Java Clients ................................................
19.6.3
How to Generate RESTful Web Service JavaScript Clients ......................................
19.6.4
How to Use the Web Services Manager ......................................................................
19.7
Deploying and Testing Web Services and Clients ............................................................
19.7.1
How to Test a JAX-WS Web Service ............................................................................
19.7.2
How to Test a RESTful Web Service ............................................................................
19.8
Creating Handlers..................................................................................................................
19.8.1
How to Create a Handler...............................................................................................
19.8.2
How to Configure Handlers .........................................................................................
19.8.3
Testing and Using Handlers .........................................................................................
19.9
Using JAXB for Java-XML Binding .....................................................................................
19.9.1
How to Generate Java Classes from XML Schema ....................................................
19.9.2
How to Marshall XML Elements From Java Classes .................................................
19.9.3
How to Unmarshall XML Elements to Java Classes..................................................
19.10 Configuring Quality of Service ............................................................................................
19.10.1
How to Configure Quality of Service ..........................................................................
19.10.2
How to Set Port Binding ................................................................................................
19.11 Securing an Operation...........................................................................................................
19.11.1
How to Secure an Operation’s Input Messages .........................................................
19.11.2
How to Secure a Message ..............................................................................................
19.11.3
How to Secure an Operation’s Output Messages ......................................................
19.11.4
How to Set Transport Options......................................................................................
19.11.5
How to Set Client Security ............................................................................................
19-2
19-3
19-3
19-5
19-6
19-6
19-7
19-9
19-10
19-11
19-11
19-12
19-12
19-15
19-16
19-16
19-17
19-18
19-18
19-19
19-20
19-21
19-21
19-21
19-22
19-22
19-23
19-23
19-23
19-23
19-24
19-25
19-25
19-26
19-26
19-27
19-27
19-28
19-28
19-29
19-30
19-30
20 Developing HTML5/JavaScript Applications
20.1
20.2
20.3
About Developing HTML5 Applications............................................................................. 20-1
Working with HTML5/JavaScript Applications................................................................. 20-2
Creating an HTML5/JavaScript Application Project ......................................................... 20-2
xxi
20.3.1
How to Create HTML5/JavaScript Applications for Mobile Platforms...................
20.3.2
How to Add Support for HTML5 Features to an Application...................................
20.3.3
How to Create a Node.js Application............................................................................
20.4
Running an HTML5 Application...........................................................................................
20.4.1
How to Specify the Browser............................................................................................
20.4.2
How to Run an Application ............................................................................................
20.4.3
How to Run a File .............................................................................................................
20.5
Integrating an HTML5 Project with a Browser ...................................................................
20.5.1
How to Install the Extension from the Chrome Web Store ........................................
20.5.2
How to Install the Extension Manually .........................................................................
20.6
Inspecting HTML5 Code with the Browser .........................................................................
20.7
Changing Browser Screen Sizes.............................................................................................
20.7.1
How to Switch Between Screen Sizes ............................................................................
20.7.2
How to Create a Custom Screen Size...........................................................................
20.8
Creating HTML5 Templates.................................................................................................
20.8.1
How to Create a Site Template .....................................................................................
20.9
Creating Cascading Style Sheets..........................................................................................
20.9.1
How to Create a Cascading Style Sheet.......................................................................
20.9.2
How to Add a CSS Rule to a Cascading Style Sheet..................................................
20.9.3
How to Add a Property to a CSS Rule.........................................................................
20.9.4
Creating a CSS Preprocessor File .................................................................................
20.9.5
How to Generate CSS Files Using a CSS Preprocessor .............................................
20.10 Creating JavaScript Files .......................................................................................................
20.10.1
How to Create a JavaScript File ....................................................................................
20.10.2
How to Edit a JavaScript File ........................................................................................
20.10.3
How to Debug a JavaScript File....................................................................................
20.10.4
How to Set JavaScript Breakpoints ..............................................................................
20.10.5
How to Run Unit Tests on JavaScript Files .................................................................
20.10.6
How to Add a JavaScript Library to a Project ............................................................
20.11 Using Grunt and Gulp Build Tools .....................................................................................
20.11.1
Installing Grunt.js ..........................................................................................................
20.11.2
Installing Gulp.js.............................................................................................................
20.11.3
Running Grunt Tasks .....................................................................................................
20.11.4
Running Gulp Tasks.......................................................................................................
20-2
20-4
20-4
20-5
20-5
20-6
20-6
20-7
20-7
20-7
20-8
20-9
20-9
20-10
20-10
20-10
20-10
20-11
20-11
20-11
20-12
20-13
20-14
20-14
20-14
20-15
20-16
20-17
20-20
20-21
20-21
20-21
20-22
20-22
21 Developing PHP Applications
21.1
About Developing PHP Applications...................................................................................
21.1.1
Databases ...........................................................................................................................
21.1.2
Remote Development.......................................................................................................
21.1.3
Frameworks .......................................................................................................................
21.2
Working with PHP Applications...........................................................................................
21.2.1
How to Create a PHP Project ..........................................................................................
21.2.2
How to Create a Run Configuration for the Project ....................................................
21.2.3
How to Synchronize Local and Remote Sources .........................................................
21.2.4
How to Run a Project .......................................................................................................
21.2.5
How to Test a PHP Project ..............................................................................................
21.3
Editing PHP Files .....................................................................................................................
xxii
21-1
21-1
21-1
21-2
21-2
21-2
21-3
21-4
21-4
21-5
21-5
21.3.1
How to Use Syntax Highlighting ...................................................................................
21.3.2
How to Use Code Completion........................................................................................
21.3.2.1
Snippets.......................................................................................................................
21.3.2.2
Context-Sensitive Proposals.....................................................................................
21.3.2.3
Code Templates and Abbreviations .......................................................................
21.3.2.4
Code Completion for Constructors.........................................................................
21.3.2.5
SQL Code Completion ..............................................................................................
21.3.2.6
PHP Namespaces.......................................................................................................
21.3.2.7
Overridden and Implemented Methods ................................................................
21.3.2.8
Annotations ................................................................................................................
21.3.3
How to Use Bracket Completion ....................................................................................
21.3.4
How to Use Parameter Hints ..........................................................................................
21.3.5
How to Use the Go To Declaration Feature ..................................................................
21.3.6
How to Use Rename Refactoring and Instant Rename ...............................................
21.3.7
How to Use Code Generators .........................................................................................
21.3.7.1
Constructors ...............................................................................................................
21.3.7.2
Getters and Setters.....................................................................................................
21.3.7.3
Overridden and Implemented Methods ..............................................................
21.3.8
How to Define Variable Type in Comments ..............................................................
21.3.9
About PHP 7 Support ....................................................................................................
21.4
Debugging PHP Applications..............................................................................................
21.4.1
How to Debug a PHP Project........................................................................................
21.4.2
How to Set Up XDebug..................................................................................................
21.4.2.1
Check If XDebug Is Installed .................................................................................
21.4.2.2
Install XDebug..........................................................................................................
21.4.2.3
Setting Up XDebug..................................................................................................
21.4.2.4
Testing XDebug .......................................................................................................
21.4.2.5
Setting Up Debugging Options in NetBeans IDE...............................................
21.4.3
How to Set PHP Breakpoints in the IDE .....................................................................
21.4.3.1
Setting Breakpoints .................................................................................................
21.4.4
How to Set the Current Context in the PHP Debugger ............................................
21.4.4.1
Debugger Windows and Context..........................................................................
21.4.4.2
The Source Editor and Context..............................................................................
21.4.5
How to Start a PHP Debugging Session......................................................................
21.4.5.1
Starting a PHP Debugging Session .......................................................................
21.4.5.2
Remote PHP Debugging and Path Mapping ......................................................
21.4.5.3
Stepping Through Your Program .........................................................................
21.4.5.4
Finishing a PHP Debugging Session ....................................................................
21.4.6
How to Use PHP Debugger Windows ........................................................................
21.4.6.1
Using the Breakpoints Window ............................................................................
21.4.6.1.1
Icons....................................................................................................................
21.4.6.1.2
Actions ...............................................................................................................
21.4.6.1.3
Grouping Breakpoints .....................................................................................
21.4.6.2
Using the Call Stack Window ................................................................................
21.4.6.2.1
Icons....................................................................................................................
21.4.6.3
Using the Threads Window ...................................................................................
21.4.6.4
Using the Variables Window .................................................................................
21-5
21-6
21-6
21-6
21-7
21-7
21-7
21-7
21-7
21-7
21-8
21-8
21-8
21-9
21-9
21-9
21-9
21-10
21-10
21-10
21-11
21-11
21-11
21-11
21-12
21-12
21-12
21-13
21-13
21-13
21-13
21-14
21-14
21-14
21-14
21-14
21-15
21-16
21-16
21-16
21-17
21-17
21-17
21-17
21-18
21-18
21-18
xxiii
21.4.6.4.1
Properties...........................................................................................................
21.4.6.5
Using the Watches Window...................................................................................
21.4.6.5.1
Properties...........................................................................................................
21.4.7
How to View Program Information.............................................................................
21.4.7.1
Viewing Variables When Debugging PHP Applications ..................................
21.4.7.2
Enabling and Creating Watches in PHP Code ....................................................
21.5
Testing PHP Applications.....................................................................................................
21.5.1
How to Configure PHP Unit Test Frameworks .........................................................
21.5.2
How to Run PHP Tests ..................................................................................................
21.5.3
How to Analyze PHP Code...........................................................................................
21.6
Using a Continuous Build Server With PHP .....................................................................
21-18
21-19
21-19
21-19
21-19
21-20
21-21
21-21
21-21
21-22
21-22
22 Developing Java ME Applications
22.1
About Developing Java ME Applications ............................................................................
22.1.1
About Java ME Embedded and CLDC Applications ..................................................
22.2
Understanding Java Platform Manager................................................................................
22.3
Creating Java ME Projects ......................................................................................................
22.3.1
How to Create a Java ME Embedded Application from a Template........................
22.3.1.1
Creating Embedded Application ............................................................................
22.3.2
How to Add a MIDlet to a Project Configuration........................................................
22.3.3
How to Add Push Registry Entries................................................................................
22.3.4
Adding API Permissions .................................................................................................
22.4
Customizing MIDlet Properties.............................................................................................
22.4.1
How to Customize the Application Descriptor (JAD) Attributes .............................
22.4.2
How to Customize MEEP Javadoc Settings..................................................................
22.5
Building Java ME Embedded Applications .........................................................................
22.5.1
How to Customize Compilation Options .....................................................................
22.5.2
How to Add Libraries and Resources to a Java ME Embedded Project.................
22.5.3
How to Customize MEEP Build Filter Settings..........................................................
22.5.4
How to Obfuscate a MIDlet Suite.................................................................................
22.5.5
How to Customize the JAR and JAD Files in a Build................................................
22.6
Working with Security and MIDlet Signing ......................................................................
22.6.1
How to Set Security through MIDlet Signing............................................................
22.6.2
How to Add or Creating a Keystore ............................................................................
22.6.3
How to Create a New Key Pair.....................................................................................
22.6.4
How to Export a Key to an Emulator Platform ..........................................................
22.7
Working with Java ME Embedded Project Configurations.............................................
22.7.1
How to Work with Java ME Embedded Project Configurations.............................
22.7.2
How to Customize Java ME Embedded Project Configurations.............................
22.7.2.1
Customizing Project Configurations ....................................................................
22.7.2.2
Customizing Platform Properties..........................................................................
22.7.2.3
Customizing the Application Descriptor (JAD) Attributes...............................
22.7.2.4
Adding MIDlets to a Project Configuration ........................................................
22.7.2.5
Customizing Compilation Options.......................................................................
22.7.2.6
Adding Libraries and Resources to a Java ME Embedded Project ..................
22.8
Running Java ME Embedded Applications .......................................................................
22.8.1
How to Customize Java ME Embedded Project Run Options .................................
xxiv
22-1
22-3
22-3
22-4
22-4
22-5
22-5
22-5
22-6
22-7
22-8
22-8
22-8
22-9
22-10
22-11
22-11
22-12
22-12
22-13
22-13
22-14
22-15
22-15
22-16
22-16
22-16
22-17
22-18
22-18
22-19
22-19
22-20
22-20
22.8.2
How to Run a MIDlet Suite with OTA Provisioning ................................................
22.8.3
How to Run Headless Builds ........................................................................................
22.9
Using Java ME Emulator Platforms ....................................................................................
22.9.1
How to Add MEEP Emulator Platforms .....................................................................
22.9.2
How to Customize Java ME Platform Properties ......................................................
22.9.3
How to Use the Java ME SDK.......................................................................................
22-20
22-21
22-21
22-21
22-22
22-23
23 Working with Web and Application Servers
23.1
About Working with Web and Application Servers ..........................................................
23.1.1
Web Browsers....................................................................................................................
23.1.2
Application Servers ..........................................................................................................
23.1.3
Understanding Connection Pools ..................................................................................
23.1.4
Common Application Server Tasks ...............................................................................
23.1.4.1
Setting Context Paths ................................................................................................
23.1.4.2
Starting and Stopping Servers .................................................................................
23.1.4.3
Removing Applications from Servers ....................................................................
23.1.5
Developing on the Cloud.................................................................................................
23.1.6
HTTP Server-Side Monitor..............................................................................................
23.2
Working with Web Browsers .................................................................................................
23.2.1
How to Configure a Web Browser .................................................................................
23.2.2
How to Change the Default Web Browser....................................................................
23.2.3
How to Open a Web Browser from the IDE .................................................................
23.2.4
How to Set a Proxy ...........................................................................................................
23.3
Working with Glassfish Application Servers ......................................................................
23.3.1
How to Register a Server Instance .................................................................................
23.3.2
How to View the Server in the IDE..............................................................................
23.3.3
How to Start and Stop the Server .................................................................................
23.3.4
How to View the Server Log File .................................................................................
23.3.5
How to Access the Server Admin Console .................................................................
23.3.6
How to Modify Server Properties ................................................................................
23.3.7
How to Set up a Connection Pool ................................................................................
23.3.8
How to Set up a JDBC Resource ...................................................................................
23.3.9
How to Set up a JMS Resource .....................................................................................
23.3.10
How to Set Up a JavaMail Session ...............................................................................
23.3.11
How to Register and Delete Resources........................................................................
23.3.12
How to Manage Users....................................................................................................
23.3.13
How to Configure Security Roles.................................................................................
23.3.14
How to Download and Install Server Updates ..........................................................
23.4
Working with Oracle WebLogic Application Servers ......................................................
23.4.1
How to Register a Server Instance ...............................................................................
23.4.2
How to View the Server in the IDE..............................................................................
23.4.3
How to Start and Stop the Server .................................................................................
23.5
Working with JBoss Application Servers ...........................................................................
23.5.1
How to Register a Server Instance ...............................................................................
23.5.2
How to View the Server in the IDE..............................................................................
23.5.3
How to Start and Stop the Server .................................................................................
23.5.4
How to Set up a Connection Pool ................................................................................
23-1
23-1
23-2
23-3
23-3
23-4
23-4
23-5
23-5
23-6
23-6
23-6
23-6
23-7
23-7
23-8
23-9
23-11
23-12
23-12
23-12
23-13
23-13
23-14
23-15
23-16
23-17
23-17
23-18
23-19
23-20
23-20
23-21
23-22
23-22
23-22
23-23
23-23
23-24
xxv
23.5.5
How to Access Application Server Utilities................................................................
23.6
Working with Tomcat Web Servers ....................................................................................
23.6.1
How to Register a Server Instance ...............................................................................
23.6.2
How to View the Server in the IDE..............................................................................
23.6.3
How to Start and Stop the Server .................................................................................
23.6.4
How to Configure the Server Properties .....................................................................
23.6.5
How to Edit the Configuration File..............................................................................
23.6.6
How to Authenticate the Server ...................................................................................
23.6.7
How to Set up a Connection Pool.................................................................................
23.7
Working with Web Applications on the Cloud.................................................................
23.7.1
About Web Applications on the Cloud .......................................................................
23.7.2
How to Register a Cloud Account in the IDE.............................................................
23.7.3
How to Develop Cloud Applications Locally ............................................................
23.7.4
How to Deploy Web Applications to the Cloud ........................................................
23.8
Working with the HTTP Server-Side Monitor...................................................................
23.8.1
How to Set up the HTTP Server-Side Monitor...........................................................
23.8.2
How to Analyze Session Data.......................................................................................
23.8.3
How to Save Session Data .............................................................................................
23.8.4
How to Replay Session Data .........................................................................................
23-25
23-25
23-26
23-27
23-28
23-29
23-31
23-32
23-32
23-34
23-35
23-35
23-36
23-36
23-37
23-37
23-39
23-40
23-41
24 Working and Connecting with Databases
24.1
About Working and Connecting with Databases ...............................................................
24.2
Working with the Database Tools .........................................................................................
24.2.1
How to Browse Database Structures .............................................................................
24.2.2
How to Create Database Tables......................................................................................
24.2.3
How to Create Database Views ......................................................................................
24.2.4
How to Add Columns to a Database .............................................................................
24.2.5
How to Delete Database Objects ....................................................................................
24.2.6
How to View and Modify Data in a Database..............................................................
24.2.7
How to Execute SQL Statements ....................................................................................
24.2.8
How to Obtain a Database Schema ................................................................................
24.2.9
How to Recapture a Schema from a Database .............................................................
24.3
Setting up a Database Connection.........................................................................................
24.3.1
How to Add a JDBC Driver.............................................................................................
24.3.2
How to Connect to the Java DB Database...................................................................
24.3.3
How to Connect to Oracle Database ............................................................................
24.3.4
How to Use MySQL Database with the IDE...............................................................
24.3.5
How to Enable Debug Mode.........................................................................................
xxvi
24-1
24-1
24-2
24-3
24-4
24-4
24-5
24-5
24-6
24-7
24-8
24-8
24-9
24-10
24-12
24-13
24-14
Preface
Welcome to the Developing Applications with NetBeans IDE User's Guide.
Audience
This document is intended for all users of NetBeans IDE and provides detailed
information on developing applications using the IDE.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle
Accessibility Program website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support
Oracle customers that have purchased support have access to electronic support
through My Oracle Support. For information, visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing
impaired.
Related Documents
For more information, see the following NetBeans IDE 8.2 documentation and
resources:
■
NetBeans IDE 8.2 Release Information
■
NetBeans IDE 8.2 Installation Instructions
■
NetBeans IDE 8.2 Release Notes
■
NetBeans IDE Documentation, Training & Support
■
NetBeans User FAQs
Conventions
The following text conventions are used in this document:
Convention
Meaning
boldface
Boldface type indicates graphical user interface elements associated
with an action, or terms defined in text or the glossary.
xxvii
xxviii
Convention
Meaning
italic
Italic type indicates book titles, emphasis, or placeholder variables for
which you supply particular values.
monospace
Monospace type indicates commands within a paragraph, URLs, code
in examples, text that appears on the screen, or text that you enter.
What's New in This Guide
The following topics introduce the new and changed features of NetBeans IDE 8.1 and
other significant changes that are described in this guide.
New and Changed Features for Release 8.2
NetBeans IDE 8.2 includes the following new and changed features for this document.
■
Developing C/C++ and Fortran Applications
–
This document does not contain specific information about using the IDE for
developing applications in C, C++, and Fortran. For information about
developing applications in C, C++, and Fortran, see the “C/C++ Fortran
Development" section in the IDE's integrated help viewer and search the help
for C/C++ topics.
–
An additional source for information about developing applications in C, C++,
and Fortran is the C/C++ Learning Trail on the netbeans.org site.
https://netbeans.org/kb/trails/cnd.html
■
■
■
■
■
Support for multiple carets in the IDE’s Source Editor. See Table 2–24, " Using
Multiple Carets".
Profiler improvements. See Chapter 9, "Testing and Profiling Java Application
Projects".
Debugger enhancements. See Section 10.9.4.4, "About Source Maps Support" and
Section 10.9.6.7, "How to Pin a Watch".
Docker platform support. See Section 14.9, "About Docker Platform Support".
Enhanced support for Grunt and Gulp. See Section 20.11, "Using Grunt and Gulp
Build Tools".
■
Support for ECMA Script 6. See Section 20.10.2, "How to Edit a JavaScript File".
■
PHP 7 support. See Section 21.3.9, "About PHP 7 Support".
xxix
xxx
1
Introduction to NetBeans IDE
1
This chapter provides an overview of NetBeans IDE.
[2]
This chapter contains the following sections:
■
About NetBeans IDE
■
NetBeans IDE Developer Resources
1.1 About NetBeans IDE
NetBeans IDE is a free, open source, integrated development environment (IDE) that
enables you to develop desktop, mobile and web applications. The IDE supports
application development in various languages, including Java, HTML5, PHP and C++.
The IDE provides integrated support for the complete development cycle, from project
creation through debugging, profiling and deployment. The IDE runs on Windows,
Linux, Mac OS X, and other UNIX-based systems.
The IDE provides comprehensive support for JDK 8 technologies and the most recent
Java enhancements. It is the first IDE that provides support for JDK 8, Java EE 7, and
JavaFX 2. The IDE fully supports Java EE using the latest standards for Java, XML,
Web services, and SQL and fully supports the GlassFish Server, the reference
implementation of Java EE.
1.2 NetBeans IDE Developer Resources
This section provides resources designed to get you up and running quickly on
NetBeans IDE. There are various channels for learning more about the IDE and for
providing feedback to the development team.
Table 1–1
NetBeans IDE Developer Resources
Resource
Description
netbeans.org
The web site for NetBeans IDE contains information and news
for the community of NetBeans users:
https://www.netbeans.org
NetBeans IDE Release
Documentation
The IDE release documentation provides details on system
requirements, supported technologies, installation instructions
and known issues for the release:
https://netbeans.org/community/releases/80/
Introduction to NetBeans IDE 1-1
NetBeans IDE Developer Resources
Table 1–1 (Cont.) NetBeans IDE Developer Resources
Resource
Description
NetBeans IDE
Documentation and
Tutorials
The Documentation section of the netbeans.org website contains
screencasts and tutorials that provide step-by-step instructions
for developing applications with NetBeans IDE.
The list of current tutorials are located at:
https://netbeans.org/kb/index.html
NetBeans IDE wiki
The NetBeans wiki provides additional documentation for the
NetBeans community that is not included in the NetBeans
User’s Guide: http://wiki.netbeans.org/Main_Page
You can find information on installation, configuration, licenses
and trouble-shooting at the NetBeans User FAQs:
http://wiki.netbeans.org/NetBeansUserFAQ
You can find information on plugin development and NetBeans
Platform API documentation at the NetBeans Developer FAQs:
http://wiki.netbeans.org/NetBeansDeveloperFAQ
1-2 NetBeans Developing Applications with NetBeans IDE
2
Working with NetBeans IDE
2
This chapter describes the basics of using and configuring NetBeans IDE.
[3]
This chapter contains the following sections:
■
About Working with NetBeans IDE
■
Working with the Options Window
■
Managing IDE Windows
■
Customizing Toolbars in the IDE
■
Working with Keyboard Shortcuts
■
Understanding the Source Editor Features
■
Setting Startup Parameters
■
Setting Fonts and Colors for IDE Windows
■
Managing Plugins in the IDE
■
Displaying IDE Help in a Web Browser
■
Internationalizing Source Code
■
Managing and Creating Projects
■
Working with Source Files in the IDE
■
Working with Resource Bundles
■
Working with Javadoc Documentation
■
Viewing IDE Notifications
2.1 About Working with NetBeans IDE
The IDE enables you to configure options for its many areas of functionality as well as
customize its workspace. The primary tools you can use to configure and update the
IDE include the following:
■
■
Options Window. The Options window enables you to set general IDE settings,
edit any of the IDE's configurable settings and set keyboard shortcuts. You open
the Options window by choosing Tools > Options. (On Mac OS X, choose
NetBeans > Preferences.)
Plugins Manager. The Plugins manager enables you to enable and disable
installed plugins and add new or updated plugins to the IDE.
For more information, see Section 2.9, "Managing Plugins in the IDE".
Working with NetBeans IDE
2-1
Working with the Options Window
You can also pass startup parameters to the IDE launcher in the
IDE-HOME/etc/netbeans.conf file by using startup switches. For more information,
see Section 2.7, "Setting Startup Parameters".
2.2 Working with the Options Window
The Options window enables you to change any of the IDE's configurable settings. You
select a category at the top of the window to display its settings in the lower pane.
Depending on the category, you can click on the tabs in the lower pane to access
additional settings. The changes are applied when you click Apply.
2.2.1 How to Edit IDE Settings
You use the Options window to specify global settings for the IDE. Settings that you
specify at the project level override the settings that you specify in the Options
window.
To edit IDE settings in the Options window:
1. Open the Options window by choosing Tools > Options from the main menu. (If
you are running on Mac OS X, choose NetBeans > Preferences.)
2.
Select the category in the upper pane to display the configurable settings.
3.
Modify the settings.
4.
Click Apply.
2.2.2 How to Export IDE Settings as Zip Archive
You can export your IDE settings as an archive that you can use as a backup or that
you can import into an installation of the IDE on another machine.
To export IDE settings as a zip archive:
1. Open the Options window by choosing Tools > Options from the main menu. (If
you are running on Mac OS X, choose NetBeans > Preferences.)
2.
Click Export at the bottom of the Options window.
3.
Specify the location and name of the zip archive that you want to create to contain
your settings.
4.
Select the Options categories that you want to export. Click OK.
2.2.3 How to Import IDE Settings
When you launch a new version of the IDE for the first time, you are prompted with
the option of importing settings from a previous version of the IDE. This prompt
occurs only if you have a user directory on your system from the previous version of
the IDE and the user directory is in the default location.
The settings that are imported include the following items:
■
Keyboard shortcuts
■
Most Source Editor font and color settings
■
Java Platform Manager contents
■
Library Manager contents
2-2 NetBeans Developing Applications with NetBeans IDE
Managing IDE Windows
■
Database drivers
■
Servers
You can recreate the conditions of the first launch at any time by deleting your current
userdir. When you restart the IDE you will be prompted with the option of importing
settings from a previous version of the IDE.
For more details about locating your current userdir, see the following FAQ.
http://wiki.netbeans.org/FaqWhatIsUserdir
If you delete your userdir you could lose other important
settings. In addition, you might also lose any modules you have
installed through the Update Center in the new version and you may
need to reinstall or reactivate those modules.
Note:
If you do not import the settings at the first launch but later decide that you would like
to import the settings from a previous installation, you can choose the settings that you
would like to import in the Options window.
Importing settings may overwrite your existing settings. To prevent possible loss of
your settings, use the Export settings function to create a backup of your IDE settings.
To import IDE settings:
1. Open the Options window by choosing Tools > Options from the main menu. (If
you are running on Mac OS X, choose NetBeans > Preferences.)
2.
Click Import at the bottom of the Options window.
3.
Click Browse and locate either of the following:
4.
■
the zip archive that contains your settings
■
the userdir of the IDE installation that has the settings that you want to import
Select the Options categories that you want to import. Click OK.
You will need to restart the IDE to apply the imported settings.
2.3 Managing IDE Windows
Each window in the IDE appears as a tab in the pane in which it resides. The IDE's
windowing system enables you to arrange windows anywhere in the IDE by dragging
and dropping. The IDE remembers the position of both manually and automatically
closed windows the next time they are opened.
Some windows only appear when you are performing a task to which they are related.
For example, the Debugger windows only appear when you are in a debugging
session. You can manually open task-related windows so that they are always open.
To open a task-related window, simply choose the window from the Windows menu.
The following table lists some keyboard shortcuts that you can use to navigate,
activate and select components in IDE windows.
Table 2–1
Keyboard Shortcut for Managing Windows
Keys
Action
Ctrl-0
Switch to Editor window
Working with NetBeans IDE
2-3
Managing IDE Windows
Table 2–1 (Cont.) Keyboard Shortcut for Managing Windows
Keys
Action
Ctrl-1
Switch to Project window
Ctrl-2
Switch to Files window
Ctrl-3
Switch to Favorites window
Ctrl-4
Switch to Output window
Ctrl-5
Switch to Services window
Ctrl-6
Switch to Action Items window
Ctrl-7
Switch to Navigator window
Ctrl-Shift-5
Switch to HTTP Monitor window
Ctrl-Shift-7
Switch to Properties window
Ctrl-Shift-1
Select file in Projects window
Ctrl-Shift-2
Select file in Files window
Ctrl-Shift-3
Select file in Favorites window
Ctrl-Shift-8
Opens the Palette
Ctrl-F4
Close window
Ctrl-Shift-F4
Close all documents
Shift-F4
Open Documents dialog box
Shift-Escape
Maximize window
Ctrl-Tab
Switch to recent window
Ctrl-W
Closes the current tab in the current window. If the window has
no tabs, the whole window is closed.
Alt-right
Displays the next tab in the current window.
Alt-left
Displays the previous tab in the current window.
Up arrow
Moves keyboard focus to the previous item in a group of items.
Navigates to the previous setting in a drop-down list in a
property sheet.
Down arrow
Moves keyboard focus to the next item in a group of items.
Navigates to the next setting in a drop-down list in a property
sheet.
Left arrow
Closes a folder (node).
Right arrow
Opens a folder (node).
F1
Show Help for selected component
2.3.1 How to Move a Window
The windowing system in the IDE enables you to drag window components to any
location in the IDE.
To move a window:
1. Click the window header and drag the window to the desired position. A red
preview box indicates the new location of the window after you release it.
2.
Drop the window.
2-4 NetBeans Developing Applications with NetBeans IDE
Managing IDE Windows
2.3.2 How to Configure Window Behavior and Appearance
How to configure window behavior and appearance
1. Choose Tools > Options from the main menu.
2.
Click the Windows tab in the Appearance category.
2.3.3 How to Simultaneously Display Multiple Files in the Editor
You can split the Source Editor, which enables you to work with multiple files or
different areas of the same file simultaneously. The Source Editor can be split
horizontally or vertically.
To simultaneously display multiple files in the Source Editor:
1. Open two or more files in the Source Editor.
2.
Click the tab of one of the files and drag it to the edge of the Source Editor pane
where you want the file to be placed. A red preview box indicates the new
position of the window.
3.
Release the mouse button to drop the window when the red preview box indicates
the window is in the new desired position.
To create a group of tabs:
1. Open two or more files in the Source Editor.
2.
Right-click the tab for one of the files and choose New Document Tab Group.
2.3.4 How to Clone the View of a Single File
You can create a clone of a tab if you want to open two tabs with the same file. If you
drag one of the tabs to split the editor view or create a tab group you can view
different parts of the same file simultaneously.
How to clone a tab:
1. Right-click the document tab in the Source Editor and choose Clone.
2.
Click the tab of the cloned document and drag it to the part of the window where
you want the copy to be placed.
2.3.5 How to Manage Open Files
How to navigate between open files:
1. Choose Window > Documents from the main menu.
2.
Select a document from the list in the Documents window.
3.
Click Switch to Document.
How to close or save open files:
1. Choose Window > Documents from the main menu.
2.
Select a document or documents from the list in the Documents window.
Working with NetBeans IDE
2-5
Customizing Toolbars in the IDE
You can use the ctrl and shift keys to select multiple documents.
3.
Click Close Document(s) or Save Document(s).
2.4 Customizing Toolbars in the IDE
The IDE provides comprehensive control over how toolbars are presented. You can
add and remove toolbars and position and control the visibility and contents of
toolbars. You can also create customized toolbar configurations.
Choose View > Toolbars from the main menu to see a list of the available toolbars. The
submenu displays all the toolbars in the IDE.
2.4.1 How to Show or Hide a Toolbar
Toolbars that are currently visible are indicated by a check mark in the Toolbars
submenu.
To show or hide a toolbar:
■
Choose View > Toolbars from the main menu and choose a toolbar name in the
submenu.
Alternatively, right-click the empty space in the toolbar area and choose the
toolbar name from the pop-up menu.
To find the name of a toolbar, rest the pointer on the textured drag area of the toolbar
to display a tool tip with the toolbar name.
2.4.2 How to Move a Toolbar
To move a toolbar:
■
Click in the textured drag area on the left side of the toolbar and drag the toolbar
to the desired location.
2.4.3 How to Add a Toolbar Button to a Toolbar
You can add buttons for many IDE commands and actions to the toolbar of the IDE.
To add a toolbar button to a toolbar:
1. Choose View > Toolbars > Customize to open the Customize Toolbars window.
2.
Select the button of the action you want to add to the IDE toolbar and drag and
drop the button onto the toolbar in the main window.
2.4.4 How to Remove a Button from a Toolbar
The Customize Toolbars window must be open when you are removing toolbar
buttons.
To remove a toolbar button from a toolbar:
1. Choose View > Toolbars > Customize to open the Customize Toolbars window.
2.
In the main window, click and drag the toolbar button above the toolbar.
Alternatively, you can drag the button from the toolbar into the Customize
Toolbars window.
2-6 NetBeans Developing Applications with NetBeans IDE
Working with Keyboard Shortcuts
2.4.5 How to Reorder a Button in a Toolbar
You can customize the order that buttons appear in the toolbar.
To reorder a button in a toolbar:
1. Choose View > Toolbars > Customize to open the Customize Toolbars window.
2.
In the main window, drag and drop the button to the desired position.
2.4.6 How to Change the Size of Toolbar Buttons
You can select either small or large icons for the toolbar buttons.
To change the size of toolbar buttons:
■
Choose View > Toolbars > Small Toolbar Icons
Alternately, right-click the empty space in the toolbar area and choose Small
Toolbar Icons from the popup menu.
2.4.7 How to Add a New Toolbar to the Main Window
You can create custom toolbars to group sets of buttons.
To add a new toolbar to the main window:
1. From the main window, choose View > Toolbars > Customize.
2.
In the Customize Toolbars window, click New Toolbar.
3.
In the New Toolbar dialog box, type a name for the toolbar and click OK.
4.
Drag icons from the Customize Toolbars window into the new toolbar.
The new toolbar must have at least one icon.
2.5 Working with Keyboard Shortcuts
You can edit keyboard settings for individual commands or switch between
preconfigured sets of keyboard shortcuts. The shortcut sets are designed for users that
are already used to the keyboard shortcuts of other editors and IDEs.
2.5.1 How to Add or Remove a Keyboard Shortcut for a Menu Command
You can use the Options window to customize the keyboard shortcuts for menu
commands.
To add or remove a keyboard shortcut for a menu command:
1. From the main window, choose Tools > Options.
2.
Click Keymap in the Options window.
3.
Locate the command for which you want to change a keyboard shortcut.
4.
Double-click in the text field in the Shortcut column of the command and type the
new keyboard shortcut.
As you press the key sequence, the correct syntax for that sequence automatically
appears in the text field. If you simultaneously hold down the Alt key, the Control key,
and the J key, "Alt+Ctrl+J" appears. You can only specify a keyboard shortcut that is
not being used by another command.
Working with NetBeans IDE
2-7
Working with Keyboard Shortcuts
To set keyboard shortcuts for recorded macros, go to Editor >
Macros in the Options window, select the macro name and edit the
keyboard shortcut.
Note:
2.5.2 How to Customize Keyboard Shortcuts
To customize keyboard shortcuts:
1. Choose Tools > Options > Keymap.
2.
Do either of the following:
■
Select a predefined set of keyboard shortcuts, which is called Profile.
■
Edit particular keyboard shortcuts.
You can save customized sets of your shortcuts as profiles. Then, you can switch from
one profile to another to quickly change multiple settings.
To create a custom profile of keyboard shortcuts:
1. In the Options > Keymap window, click Manage profiles.
2.
Select the profile you want to use as a base for your new profile and click
Duplicate.
3.
Enter the new profile name and click OK.
4.
Ensure that the new profile is selected and modify the shortcuts you need.
To edit a shortcut, double-click in the Shortcut field or click the ellipsis button (...).
As you press the sequence of keys, the syntax for them is added.
If you want to add special characters, such as Tab, Escape, or Enter, click the
ellipsis button (...) again and select the key from the pop-up window.
5.
When finished editing, click OK in the Options window.
To find a shortcut for a specific command, type the command
name in the Search field. To find a command by a combination, insert
the cursor in the Search in Shortcuts field and press the shortcut key
combination.
Note:
2.5.3 How to Switch Between Keyboard Shortcut Sets
You can use the Options window to switch between any of the existing keyboard
shortcuts sets. The IDE includes several sets of keyboard shortcuts with shortcut
mappings that correspond to the shortcuts in other editors and IDEs.
To switch between keyboard shortcut sets:
1. From the main window, choose Tools > Options.
2.
Click Keymap in the Options window.
3.
Choose an existing keyboard set from the Profiles drop-down list at the top of the
dialog box.
2-8 NetBeans Developing Applications with NetBeans IDE
Working with Keyboard Shortcuts
2.5.4 How to Create a New Keyboard Shortcut Set
You can configure the IDE to have multiple sets of keyboard shortcuts. You can use the
Options window to create custom sets of keyboard shortcuts.
To create a new keyboard shortcut set:
1. From the main window, choose Tools > Options.
2.
Click Keymap in the Options window.
3.
Choose an existing keyboard set from the Profiles drop-down list at the top of the
dialog box.
4.
Click Duplicate to duplicate the currently selected shortcut set. Then edit the
shortcuts in the new copy.
2.5.5 How to Use the Default Menu Shortcuts
There are keyboard shortcuts available to activate the following menu commands and
other general commands:
Table 2–2
File Menu
Keys
Command
Action
Ctrl-Shift-N
New
Creates a new project with the New Project wizard.
Ctrl-N
New
Creates a new file with the New File wizard.
Ctrl-Shift-O
Open File
Opens an existing project.
Ctrl-S
Save
Saves the current file.
Ctrl-Shift-S
Save All
Saves all files.
Ctrl-Alt-Shift-P
Print
Print the current file.
Table 2–3
Edit Menu
Keys
Command
Action
Ctrl-Z
Undo
Reverses (one at a time) a series of editor actions, except
Save.
Ctrl-Y
Redo
Reverses (one at a time) a series of Undo commands.
Ctrl-X
Redo
Reverses (one at a time) a series of Undo commands.
Ctrl-C
Copy
Copies the current selection to the clipboard.
Ctrl-V
Paste
Pastes the contents of the clipboard into the insertion
point.
Ctrl-Shift-V
Paste Formatted
Pastes the formatted contents of the clipboard into the
insertion point.
Delete
Delete
Deletes the current selection.
Select All
Ctrl-A
Selects everything in the current document or window.
Select Identifier
Alt-Shift-J
Selects the current identifier.
Ctrl-F3
Find Selection
Finds instances of the current selection.
F3
Find Next
Finds next instance of found text.
Shift-F3
Find Previous
Finds previous instance of found text.
Ctrl-F
Find
Finds previous instance of found text.
Working with NetBeans IDE
2-9
Working with Keyboard Shortcuts
Table 2–3
(Cont.) Edit Menu
Keys
Command
Action
Ctrl-H
Replace
Finds a string of text and replaces it with the string
specified.
Alt-F7
Find Usages
Finds usages and subtypes of selected code.
Ctrl-Shift-F
Find in Projects
Finds specified text, object names, object types within
projects.
Ctrl-Shift-H
Replace in
Projects
Replaces text, object names, object types within projects.
Table 2–4
View Menu
Keys
Command
Action
Ctrl-Minus
Collapse Fold
If the insertion point is in a foldable section of text,
collapses those lines into one line.
Ctrl-Plus
Expand Fold
If the currently selected line in the Source Editor
represents several folded lines, expands the fold to show
all of the lines.
Ctrl-Shift-Minus Collapse All
Collapses all foldable sections of text in the Source
Editor.
Ctrl-Shift-Plus
Expand All
Expands all foldable sections of text in the Source Editor.
Alt-Shift-Enter
Full Screen
Expand window to full length and breadth of screen.
Table 2–5
Navigate Menu
Keys
Command
Action
Alt-Shift-O
Go to File
Find and open a specific file.
Ctrl-O
Go to Type
Find and open a specific class or interface.
Ctrl-Alt-Shift-O
Go to Symbol
Find and open a specific symbol.
Alt-Shift-B
Go to Spring Bean Find and open a specific Spring bean.
Ctrl-Shift-T
Go to Test
Find and open a specific test.
Ctrl-Back Quote Go to Previous
Document
Open the document last opened before the current one.
Ctrl-Shift-B
Go to Source
Displays the source file containing the definition of the
selected class.
Ctrl-B
Go to Declaration Jump to the declaration of the item under the cursor.
Ctrl-Shift-P
Go to Super
Implementation
Ctrl-Q
Last Edit Location Scroll the editor to the last place where editing occurred.
Alt-Left
Back
Navigate back
Alt-Right
Forward
Navigate forward
Ctrl-G
Go to Line
Jump to the specified line.
Ctrl-Shift-M
Toggle Bookmark Set a bookmark on a line of code.
Jump to the super implementation of the item under the
cursor.
Ctrl-Shift-Period Next Bookmark
Cycle forward through the bookmarks.
Ctrl-Shift-Comm Previous
a
Bookmark
Cycle backwards through the bookmarks.
2-10 NetBeans Developing Applications with NetBeans IDE
Working with Keyboard Shortcuts
Table 2–5 (Cont.) Navigate Menu
Keys
Command
Action
Ctrl-Period
Next Error
Scrolls the Source Editor to the line that contains the next
build error.
Ctrl-Comma
Previous Error
Scrolls the Source Editor to the line that contains the
previous build error.
Ctrl-Shift-1
Select in Projects
Opens Projects window and selects current document
within it.
Ctrl-Shift-2
Select in Files
Opens Files window and selects current document
within it.
Ctrl-Shift-3
Select in Favorites Opens Favorites window and selects current document
within it.
Table 2–6
Source Menu
Keys
Command
Action
Alt-Shift-F
Format
Formats the selected code or the entire file if nothing is
selected.
Alt-Shift-Left
Shift Left
Moves the selected line or lines one tab to the left.
Alt-Shift-Right
Shift Right
Moves the selected line or lines one tab to the right.
Alt-Shift-Up
Move Up
Moves the selected line or lines one line up.
Alt-Shift-Down
Move Down
Moves the selected line or lines one line down.
Ctrl-Shift-Up
Duplicate Up
Copy the selected line or lines one line up.
Ctrl-Shift-Down Duplicate Down
Copy the selected line or lines one line down.
Ctrl-Slash or
Ctrl-Shift-C
Toggle Comment
Toggles the commenting out of the current line or
selected lines.
Ctrl-Space
Complete Code
Shows the code completion box.
Alt-Insert
Insert Code
Pops up a context aware menu that you can use to
generate common structures such as constructors,
getters, and setters.
Alt-Enter
Fix Code
Display editor hints. The IDE informs you when a hint is
available when the light bulb is displayed.
Ctrl-Shift-I
Fix Imports
Generates the import statements required by the classes
specified in the file.
Ctrl-P
Show Method
Parameters
Selects the next parameter. You must have a parameter
selected (highlighted) for this shortcut to work.
Ctrl-Shift-Space
Show
Documentation
Show documentation for item under the cursor.
Ctrl-Shift-K
Insert Next
Matching Word
Generates the next word used elsewhere in your code as
you type its beginning characters.
Ctrl-K
Insert Previous
Matching Word
Generates the previous word used elsewhere in your
code as you type its beginning characters.
Table 2–7
Refactor Menu
Keys
Command
Action
Ctrl-R
Rename
Inplace rename.
Working with NetBeans IDE 2-11
Working with Keyboard Shortcuts
Table 2–7 (Cont.) Refactor Menu
Keys
Command
Action
Ctrl-M
Move
Inplace move.
Alt-Delete
Safely Delete
Before deleting, display references.
Table 2–8
Run Menu
Keys
Command
Action
F6
Run Project
Runs the main project or the currently selected project if
no main project is set.
Alt-F6
Test Project
Starts unit test for project.
F11
Build Project
Builds the main project or the currently selected project
if no main project is set.
Shift-F11
Clean and Build
Project
Deletes all previously compiled files and distributable
outputs and builds the main project or the currently
selected project if no main project is set.
Shift-F6
Run File
Runs the currently selected file.
Ctrl-F6
Test File
Starts unit test for current file.
F9
Compile File
Compiles the file. If you select a folder, the IDE compiles
only the files that are new or have changed since the last
compile.
Alt-F9
Check File
Checks file dependencies in the currently selected
project when building.
Alt-Shift-F9
Validate File
Validates file dependencies in the currently selected
project when building.
Ctrl-F11
Repeat
Build/Run
Runs/builds the currently selected project once again.
Table 2–9
Debug Menu
Keys
Command
Action
Ctrl-F5
Debug Project
Debugs the main project or the currently selected project
if no main project is set.
Ctrl-Shift-F5
Debug File
Starts debugging session for currently selected file.
Ctrl-Shift-F6
Debug Test File
Starts debugging test for file.
Shift-F5
Finish Debugger
Session
Ends the debugging session.
F5
Continue
Resumes debugging until the next breakpoint or the end
of the program is reached.
F8
Step Over
Executes one source line of a program. If the line is a
method call, executes the entire method then stops.
Shift-F8
Step Over
Expression
Steps over the expression and then stops the debugging.
F7
Step Into
Executes one source line of a program. If the line is a
method call, executes the program up to the method's
first statement and stops.
Shift-F7
Step into Next
Method
Runs the current project to the specified method and
then steps into the method.
2-12 NetBeans Developing Applications with NetBeans IDE
Working with Keyboard Shortcuts
Table 2–9 (Cont.) Debug Menu
Keys
Command
Action
Ctrl-F7
Step Out
Executes one source line of a program. If the line is a
method call, executes the methods and returns control to
the caller.
F4
Run to Cursor
Runs the current project to the cursor's location in the
file and stop program execution.
Ctrl-F8
Toggle Line
Breakpoint
Adds a line breakpoint or removes the breakpoint at the
cursor location in the program.
Ctrl-Shift-F8
New Breakpoint
Sets a new breakpoint at the specified line, exception, or
method.
Ctrl-Shift-F7
New Watch
Adds the specified variable to watch.
Ctrl-F9
Evaluate
Expression
Opens the Evaluate Expression dialog box.
Ctrl-Alt-Up
Make Callee
Current
Makes the method being called the current call. Only
available when a call is selected in the Call Stack
window.
Ctrl-Alt-Down
Make Caller
Current
Makes the calling method the current call. Only
available when a call is selected in the Call Stack
window.
Table 2–10
Profile Menu
Keys
Command
Action
Alt-F2
Profile Project
Profiles the main project or the currently selected project
if no main project is set.
Ctrl-Shift-F2
Rerun Profiling
Session
Enables you to start a new profiling session that uses the
settings from the previous profiling session. The
shortcut for this action is active only when no profiling
session is in progress.
Alt-Shift-F2
Modify Profiling
Session
Opens the Select Profiling Task when a profiling session
is in progress. You can modify the profiling task or
criteria without stopping the application that you are
profiling. The shortcut invokes this action only when no
profiling session is in progress.
Ctrl-F2
Take Snapshot of
Collected Results
Takes a snapshot of the collected profiling results and
displays the results in a new window.
Table 2–11
Tools Menu
Keys
Command
Action
Ctrl-Shift-J
Insert
Internationalized
String
Enables you to add an internationalization string as you
create the source.
Table 2–12
Window Menu
Keys
Command
Action
Ctrl-0
Editor
Switches to the Source Editor.
Ctrl-1/Ctrl-Shift Projects
-1
Opens the Projects window.
Working with NetBeans IDE 2-13
Working with Keyboard Shortcuts
Table 2–12 (Cont.) Window Menu
Keys
Command
Action
Ctrl-2/Ctrl-Shift Files
-2
Opens the Files window.
Ctrl-3/Ctrl-Shift Favorites
-3
Opens the Favorites window.
Ctrl-4
Output Window
Opens the Output window.
Ctrl-5
Services
Opens the Services window.
Ctrl-Shift-6
Tasks
Opens the Tasks window.
Ctrl-6
Action Items
Opens the Action Items window.
Ctrl-7
Navigator
Opens the Navigator.
Alt-Shift-1
Debugging >
Variables
Opens the Variables debugger window.
Alt-Shift-2
Debugging >
Watches
Opens the Watches debugger window.
Alt-Shift-3
Debugging > Call Opens the Call Stack debugger window.
Stack
Alt-Shift-4
Debugging >
Loaded Classes
Opens the Loaded Classes debugger window.
Alt-Shift-5
Debugging >
Breakpoints
Opens the Breakpoints debugger window.
Alt-Shift-6
Debugging >
Sessions
Opens the Sessions debugger window.
Alt-Shift-7
Debugging >
Threads
Opens the Threads debugger window.
Alt-Shift-8
Debugging >
Sources
Opens the Sources debugger window.
Ctrl-W
Close Window
Closes the current tab in the current window. If the
window has no tabs, the whole window is closed.
Shift-Escape
Maximize
Window
Maximizes the Source Editor or the present window.
Alt-Shift-D
Configure
Window > Dock
Pins a detached window to the IDE.
Ctrl-Shift-W
Close All
Documents
Closes all open documents in the Source Editor.
Shift-F4
Documents
Opens the Documents dialog box, in which you can save
and close groups of open documents.
Ctrl-Tab (Ctrl-')
Switch to Recent
Window
Toggles through the open windows in the order that
they were last used. The dialog box displays all open
windows and each of the open documents in the Source
Editor.
Table 2–13
Help Menu
Keys
Command
Action
F1
Help
Displays the help topic for the current UI element in the
JavaHelp viewer.
2-14 NetBeans Developing Applications with NetBeans IDE
Understanding the Source Editor Features
Table 2–13 (Cont.) Help Menu
Keys
Command
Action
Shift-F1
Javadoc Index
Search
Lets you search the Javadoc index.
2.5.6 How to Customize Keyboard Shortcuts
NetBeans IDE supports customizable shortcuts to improve your productivity but and
increase your overall typing speed.
To customize keyboard shortcuts:
1. Choose Tools > Options > Keymap.
2.
Do either:
■
Select a predefined set of keyboard shortcuts, which is called Profile.
■
Edit particular keyboard shortcuts.
You can save customized sets of your shortcuts as profiles. Then, you can switch from
one profile to another to quickly change multiple settings.
To create a custom profile of keyboard shortcuts:
1. In the Options > Keymap window, click Manage profiles.
2.
Select the profile you want to use as a base for your new profile and click
Duplicate.
3.
Enter the new profile name and click OK.
4.
Ensure that the new profile is selected and modify the shortcuts you need.
To edit a shortcut, double-click in the Shortcut field or click the ellipsis button (...).
As you press the sequence of keys, the syntax for them is added.
If you want to add special characters, such as Tab, Escape, or Enter, click the
ellipsis button (...) again and select the key from the pop-up window.
5.
When finished editing, click OK in the Options window.
To find a shortcut for a specific command, type the command name in the Search field.
To find a command by a combination, insert the cursor in the Search in Shortcuts field
and press the shortcut key combination.
2.6 Understanding the Source Editor Features
The Source Editor is a full-featured text editor that is integrated with the GUI Builder,
the compiler, the debugger, and other parts of the IDE. You can generally open the
Source Editor by double-clicking a node in the Projects window, Files window, or
Navigator window.
The top of the Source Editor has a tab for each open document. Each tab shows the
name of the document. The name of the document is displayed in bold if the
document has been modified and has not been saved. You can right-click the tab to
open a popup menu that lists commands that can be invoked on the tab.
If multiple files are open, you can split the Source Editor view by clicking and
dragging the tab. As you drag to different parts of the editing area, you see a red
outline that shows you the location of the new window. When one of these boxes
Working with NetBeans IDE 2-15
Understanding the Source Editor Features
appears, you can drop the document and split the pane. You must close the split file if
you want the editor to return to its unsplit state.
2.6.1 How to Use the Toolbar
The editor toolbar is at the top of the Source Editor window. The toolbar has buttons
for various navigating and editing shortcuts, which vary according to the type of file
you are editing. Hold the cursor over a button to display a description of the
command.
How to toggle the editor toolbar:
■
Choose View > Show Editor Toolbar to hide or display the editor toolbar.
The following table provides descriptions of icons that are used in the source editor
toolbar.
Table 2–14
Icons in Source Editor Toolbar
Icon
Description
Source/History
Toggle between source code and local history views. Local
history includes diffs between all save points.
Last Edit (Ctrl+Q)
Back (Alt+LEFT)
Forward (Alt+RIGHT)
Find Selection (Ctrl+F3)
Find Previous
Occurrence (Shift+F3)
Find Next Occurrence
(F3)
Toggle Highlight
Search (Alt+Shift+H)
Toggle Rectangular
Selection (Ctrl+Shift+R)
Previous Bookmark
Next Bookmark
Toggle Bookmark
Shift Line Left
(Alt+Shift+LEFT)
Shift Line Right
(Alt+Shift+RIGHT)
Start Macro Recording
Moves to the last edit you made.
Moves back to previously opened document.
Moves forward to next opened document.
Finds the item in which the cursor is currently inserted.
Moves the insertion point to the previous found occurrence of
the text that you previously searched for.
Moves the insertion point to the next found occurrence of the
text that you previously searched for.
Turns off or turns on the highlighting of search text.
Turns off or turns on the rectangular block selection.
Moves the insertion point to the previous bookmark in the file.
Moves the insertion point to the next bookmark in the file.
Inserts a bookmark on the current line or removes a bookmark
on the current line.
Reduces the indentation by one tab stop.
Increases the indentation by one tab stop.
Starts recording a macro containing keystrokes and cursor
movements.
2-16 NetBeans Developing Applications with NetBeans IDE
Understanding the Source Editor Features
Table 2–14 (Cont.) Icons in Source Editor Toolbar
Icon
Description
Stop Macro Recording
Stops macro recording.
Check XML document is well-formed.
Check XML (Alt+F9)
Validate XML
(Alt+Shift+F9)
Validate XML document against DTD or schema specified in
document.
Run XSL transformation on open XSLT document.
Run XSL
Next Matching
Completes the word you are typing to match the next word in
the file that matches the word you are typing.
Previous Matching
Completes the word you are typing to match the closest
previous word in the file that matches the word you are typing.
Comment
Uncomment
Comments out the selected lines
Removes the comment marks from the selected lines
2.6.2 How to Use the Left Margin
The left margin displays annotation glyphs that indicate line status, such as
breakpoints, the program counter, or build errors. You can right-click the left margin to
display a pop-up menu with a list of commands and options.
If you click the left margin of a Java, JavaScript or PHP file, a breakpoint is set on the
corresponding line. You can click the left margin of a line to remove a breakpoint.
For more information about setting breakpoints and other glyphs used by the
debugger, see Chapter 10.9.4, "Managing Breakpoints."
The following table shows some of the annotation glyphs that can appear in the left
margin of the Source Editor.
Table 2–15
Glyph
Table of Common Editor Glyphs and Descriptions
Description
The line contains an error. You can place the mouse pointer over
the glyph to display a tooltip with information on the error.
The line contains a method that overrides a method from
another class. Place your mouse pointer over the glyph to
display a tooltip with name of the overridden method's class.
This glyph only applies to Java classes.
The line contains a method that implements a method from an
interface or an abstract class. Place your mouse pointer over the
glyph to display a tooltip with name of the implemented
method's class. This glyph only applies to Java classes.
The line is bookmarked. You can cycle forward and backward
through your Source Editor bookmarks by pressing
Ctrl-Shift-Period/Comma. You can add or remove a bookmark
by pressing Ctrl-Shift-M.
Working with NetBeans IDE 2-17
Understanding the Source Editor Features
Table 2–15 (Cont.) Table of Common Editor Glyphs and Descriptions
Glyph
Description
The line contains a debugging line breakpoint. You can remove
the breakpoint by clicking the glyph. You can set another
breakpoint by clicking in the left margin next to the line where
you want the breakpoint to appear.
The line contains multiple annotation glyphs. Click the glyph to
cycle through the annotations.
2.6.3 How to Use the Error Stripe
The error stripe is the strip to the right of the right scroll bar and contains marks for
various things in your file, such as errors, bookmarks, and comments for the To Do list.
The error stripe represents the whole file, not just the lines currently displayed. You
can immediately identify whether your file has any errors without having to scroll
through the entire file. You can double-click a mark in the error stripe to jump to the
line that the mark refers to.
2.6.4 How to Use the Status Line
The Source Editor status line is beneath the horizontal scroll bar. The first area of the
status line shows the current line number and row number in the form line:row. The
second area of the status line indicates the insertion mode (INS or OVR). The text area
on the right is used for status messages.
2.6.5 How to Use Syntax Coloring and Highlighting
Source code displayed in the Source Editor is syntactically colored. For example, all
Java keywords are shown in blue and all Java comments in light gray. Guarded blocks
of Java code generated by the GUI Builder have a light blue background and cannot be
edited.
To customize semantic coloring settings for the Java Editor:
■
Choose Tools > Options > Fonts & Colors.
The IDE provides several preset coloring schemes, which are called profiles. You can
create new profiles with custom colors and quickly switch between them.
To save custom colors in a new profile:
1. In the Options > Fonts & Colors window, click Duplicate next to the Profile
drop-down list.
2.
Enter the new profile name and click OK.
3.
Ensure that the new profile is currently selected and choose Java from the
Language drop-down list.
4.
Select a category and change the font, font color (Foreground), background color,
and effects for this category.
Use the Preview window to view the results.
5.
Click OK.
2-18 NetBeans Developing Applications with NetBeans IDE
Understanding the Source Editor Features
All NetBeans IDE settings and profiles are stored in the
NetBeans userdir (refer to the FAQ on how to locate the userdir for
your operating system). When upgrading to newer versions of
NetBeans, you can export old settings and import them to the newer
version.
Note:
In addition to coloring, the Source Editor highlights similar elements with a particular
background color. Thus, you can think of the highlighting feature as an alternative to
the Search command, because in combination with error stripes, it gives you a quick
overview of where the highlighted places are located within a file.
The IDE highlights usages of the same element, matching braces, method exit points,
and exception throwing points.
If you place the cursor in an element, such as a field or a variable, all usages of this
element are highlighted. Note that error stripes in the Editor's right margin indicate
the usages of this element in the entire source file. Click the error stripe to quickly
navigate to the desired usage location.
To rename all the highlighted instances:
■
Choose Refactor > Rename (or Ctrl-R).
2.6.6 How to Use Insert Mode and Overwrite Mode
When the Source Editor is in insert mode, the default insertion point is a vertical bar,
and text that you type is inserted. In overwrite mode, the default insertion point is a
solid block, and text that you type replaces the existing text.
Use the Insert key to toggle between the two modes.
Whenever the insertion point in the Source Editor is located immediately after a brace,
bracket, or parenthesis, the matching brace, bracket, or parenthesis is highlighted.
If the Source Editor beeps when you try to enter new text, the file is a read-only file.
2.6.7 How to Set Editor Options
You can set options for the source editor in the Options window. The Editor category
in the Options window contains tabs where you can set options for editor features,
including code completion, formatting and folding.
You can set options for the colors of text and background colors in the Fonts and
Colors category. The IDE includes several fonts and colors settings that are saved as
profiles. You can choose to use one of the default settings profiles or create a custom
profile that saves your font and color preferences.
How to set global editor options:
1. Choose Tools > Options from the main menu.
2.
Click the Editor category and then click a tab to edit the settings for that feature.
How to specify global fonts and colors in the editor:
1. Choose Tools > Options from the main menu.
2.
Click the Fonts & Colors category and then click a tab to edit the settings for that
feature.
Working with NetBeans IDE 2-19
Understanding the Source Editor Features
3.
Select an item in the Category or Highlighting pane and then modify the color or
other properties for that element in the right pane of the Options window.
How to enable a default profile:
1. Choose Tools > Options from the main menu.
2.
Click the Fonts & Colors category.
3.
Select a profile from the Profiles drop-down list.
When you select a profile you can see an example of the new settings in the Preview
pane.
How to create a custom profile for fonts and colors
1. Choose Tools > Options from the main menu.
2.
Click the Fonts & Colors category.
3.
Select a profile from the Profile drop-down list to use as a base for the custom
profile.
4.
Click Duplicate and type a name for the new profile.
5.
Modify the font and color options as desired.
When you modify the new profile you can see an example of the new settings in
the Preview pane.
6.
Click Apply in the Options window.
How to set formatting options for a project:
1. Right-click the project node in the Projects window and choose Properties.
2.
Select the Formatting category in the Project Properties window.
3.
Select Use project specific options in the Formatting panel and specify the
options.
2.6.8 How to Insert and Highlight Occurrences in the Editor
By default, the IDE automatically inserts matching pairs of braces, brackets, and
quotes. When you type an opening curly brace and then press Enter, the closing brace
is added automatically. For (, [, ", and ', the editor inserts a matching pair.
To enable inserting matching pairs:
1. Choose Tools > Options > Editor > Code Completion.
2.
Select the Insert Closing Brackets Automatically checkbox.
By default the editor highlights the occurrences of various code symbols and
keywords when the insert cursor is located in one of the occurrences. You can disable
the highlighting completely or limit the highlighting to specific elements.
How to select types of occurrences to highlight in the editor:
1. Choose Tools > Options from the main menu, and then click the Highlighting tab
in the Editor category.
2.
Select a language in the drop-down list.
3.
Deselect the types of elements that you do not want to be highlighted.
2-20 NetBeans Developing Applications with NetBeans IDE
Understanding the Source Editor Features
You can disable the highlighting of all types of elements for the specified language by
deselecting Mark Occurrences Of Symbol Under Caret.
2.6.9 How to Record Macros
You can use macros in the source editor that can generate common source code
snippets or perform common editor tasks. After you record a macro you can assign a
keyboard shortcut to run the macro on the current file.
How to record a macro:
1. Click the Start Macro Recording icon in the toolbar of the source editor.
2.
Perform the tasks or type the code that you want to record.
3.
Click the Stop Macro Recording icon in the toolbar.
When you click Stop Macro Recording the IDE opens the New Macro Dialog.
4.
Type a name for the macro. Click OK.
5.
Select the new macro in the Editor Macros dialog box and click Set Shortcut.
6.
Type a shortcut in the Add Shortcut dialog box. Click OK.
7.
Click OK in the Editor Macros dialog box.
The new macro will not be saved if you click Cancel in the Editor Macros dialog
box.
To view or modify your saved macros, choose Tools > Options in the main menu and
click the Macros tab in the Editor category.
A special macro syntax is used to define these macros. For example, if you want to
clear the current line in the editor from the cursor, your macro definition would be as
follows: selection-end-line remove-selection.
Then you can assign "Ctrl+L" as the keyboard shortcut for this macro. Whenever you
press that key combination, the whole line, from the position of the cursor, will be
deleted.
2.6.9.1 Macro Keywords for NetBeans Java Editor
To get a complete list of all macro keywords, you create a NetBeans API action, which
will get EditorKit from the JEditorPane in an opened editor, call EK.getActions(), and
dump Action.NAME property of each action to System.out (together with
Action.SHORT_DESCRIPTION).
A short list of macro keywords is as follows:
Macro
Description
abbrev-debug-line
Debug Filename and Line Number
adjust-caret-center
Move Insertion Point to Center
adjust-window-center
Scroll Insertion Point to Center
completion-show
Show Code Completion Popup
fix-imports
Fix Imports
make-getter
Replace Variable With its Getter
remove-line
Delete Line
Working with NetBeans IDE 2-21
Understanding the Source Editor Features
Macro
Description
select-next-parameter
Select Next Parameter
toggle-toolbar
Toggle Toolbar
word-match-next
Next Matching Word
For a complete list of macro keywords, see the following document.
http://wiki.netbeans.org/FaqEditorMacros
2.6.10 How to Modify Source Editor Code Templates
Code Templates are abbreviations that you type into the code and that the editor
expands into code blocks. The templates can include placeholder values. After you
expand a code template, you go through the expanded block and replace the
placeholder values.
The IDE includes default code templates for various languages. You can use the
Options window to create, remove and modify code templates.
To modify an existing code template:
1. Choose Tools > Options from the main menu, and then click Code Templates tab
in the Editor category.
2.
Select a language from the drop-down list to see the code templates available for
that language.
3.
Select a code template from the list.
4.
Type in the Expanded Text tab to modify the expanded code that the template
produces.
5.
Type in the Description tab to modify the description of the code template. Click
OK in the Options window.
To remove an existing code template:
1. Choose Tools > Options from the main menu, and then click the Editor category.
2.
Select a language from the drop-down list to see the code templates available for
that language.
3.
Select a code template from the list.
4.
Click Remove.
To create a code template:
1. Choose Tools > Options from the main menu, and then click the Editor category.
2.
Select a language from the drop-down list.
3.
Click New.
4.
Type an abbreviation for the new code template in the dialog box.
5.
Type the expanded code in the Expanded Text tab.
6.
Type a description for the code in the Description tab.
7.
Click OK in the Options window.
2-22 NetBeans Developing Applications with NetBeans IDE
Understanding the Source Editor Features
2.6.11 How to Use Code Completion
The NetBeans IDE's Source Editor helps you quickly complete and generate code
through the "smart" code completion feature. In a general sense, code completion is
very useful when you want to fill in the missing code, look at the options available in
the context of your application, and generate blocks of code when needed.
Use code completion to:
■
■
■
generate code from the code completion window
complete keywords in your code. The editor analyzes the context and suggests the
most relevant keywords
choose a name that matches the type of a new field or a variable that you are
adding
■
complete Javadoc tags after you type the "@" symbol
■
suggest parameters for variables, methods, or fields
■
quickly fill in the most commonly used prefixes and single suggestions
To invoke code completion:
■
Press Ctrl-Space (or choose Source > Complete Code from the main menu) to
open the code completion box.
While you are typing, the list of suggestions shortens. The suggestions listed
include those imported in your source file and symbols from the java.lang
package.
The suggestions that are the most relevant for the context of your code are
displayed at the top, above the black line in the code completion window.
If the "smart" suggestions are not the ones you want to use, press Ctrl-Space again
to see a complete list.
To invoke tooltips with method parameters:
■
Press Ctrl-P (or choose Source > Show Method Parameters from the main menu).
The editor guesses on the parameters for variables, methods, or fields and displays the
suggestions in a pop-up box.
For example, when you select a method from the code completion window which has
one or more arguments, the Editor highlights the first argument and displays a tooltip
suggesting the format for this argument. To move to the next argument, press the Tab
or Enter keys.
To fill in the most commonly used prefixes and single suggestions:
1. Type a name or part of a name (for example, System.out.p) and wait for code
completion to show all fields and methods that start with "p." All the suggestions
will be related to "print."
2.
Press the Tab key and the editor automatically fills in the "print".
You can continue and type "l" and, after pressing Tab, the "println" will be added.
To customize the code completion settings:
■
Select Tools > Options > Editor > Code Completion.
Working with NetBeans IDE 2-23
Understanding the Source Editor Features
To invoke the code completion window automatically when you are typing
certain characters:
1. Select Tools > Options > Editor > Code Completion.
2.
On the Code Completion tab, select the Auto Popup Completion Window
checkbox.
The default character is ".", but you can add your own characters.
To add characters that invoke the code completion window:
1. Select Java from the Language drop-down list.
2.
Type your characters in the Auto Popup Triggers for Java field.
The code completion window will pop up every time you type the specified
characters.
Note: When the Auto Popup Completion Window checkbox is
disabled, you need to press Ctrl-Space each time you want to use code
completion.
In the code completion window, the following icons are used to distinguish different
members of the Java language.
Table 2–16
Icon
Icons in the Code Completion Window
Meaning
Variants
(if any)
Meaning
Annotation type
Class
Package
Enum type
Code Template
Constructor
New constructor (generate)
Protected constructor
Private constructor
Package private constructor
Field
Protected field
Private field
Package private field
Static field
Protected static field
Private static field
Package private static field
Interface
2-24 NetBeans Developing Applications with NetBeans IDE
Understanding the Source Editor Features
Table 2–16 (Cont.) Icons in the Code Completion Window
Icon
Meaning
Variants
(if any)
Meaning
Java keyword
Method
Protected method
Private method
Package private method
Static method
Protected static method
Private static method
Package private static
method
Local variable
Attribute
2.6.12 How to Use Hints
While you are typing, the Source Editor checks your code and provides suggestions of
how you can fix errors and navigate through code.
For the most common coding mistakes, you can see hints in the left-hand margin of
the Editor. The hints are shown for many types of errors, such as missing field and
variable definitions, problems with imports, braces, and other. Click the hint icon and
select the fix to add.
Hints are displayed automatically by default.
To view all hints:
Choose Source > Fix Code (or press Alt-Enter).
■
To limit the number of categories for which hints are displayed:
Choose Tools > Options > Editor > Hints.
1.
2.
From the Language drop-down list, select the language and view a list of elements
for which hints are displayed (their checkboxes are selected).
3.
To disable hints for some categories, clear the appropriate checkboxes.
Working with NetBeans IDE 2-25
Understanding the Source Editor Features
On the Hints tab, you can also disable or limit the scope of
dependency scans (Dependency Scanning option). These steps can
significantly improve the performance of the IDE.
Note:
The IDE detects compilation errors in your sources by locating and
recompiling classes that depend on the file that you are modifying
(even if these dependencies are in the files that are not opened in the
editor). When a compilation error is found, red badges are added to
source file, package, or project nodes. Dependency scanning within
projects can be resource consuming and degrade performance,
especially if you are working with large projects.
To improve IDE's performance, you can do one of the following:
■
■
Limit the scope of dependency scans to the Source Root (search
for dependencies only in the source root where the modified class
is located) or current Project.
Disable dependency scanning (choose Project Properties > Build
> Compiling and deselect the Track Java Dependencies option).
In this case, the IDE does not scan for dependencies or updates
the error badges when you modify a file.
To surround pieces of your code with various statements:
■
Select a block in your code that you want to surround with a statement and click
the bulb icon in the left-hand margin (or press Alt-Enter). The editor displays a list
of suggestions from which you select the statement you need.
You can surround pieces of your code with various statements, such as for, while, if,
try/catch, and other.
2.6.13 How to Navigate Through Code
Use the Go To.. commands located under the Navigate menu item to quickly jump to
target locations.
To go to declaration:
1. Hold down the Ctrl key and click the usage of a class, method, or field to jump to
its declaration. You can also place the cursor on the member (a class, method, or
field).
2.
Choose Navigate > Go To Declaration.
To go to source:
1. Hold down the Ctrl key and click a class, method, or field to jump to the source
code, if the source is available. You can also place the cursor on the member (a
class, method, or field).
2.
Choose Navigate > Go To Source in the main menu.
To go to type, file, or symbol:
■
If you know the name of the type (class, interface, annotation or enum), file, or
symbol to where you want to jump, choose Navigate > Go to Type (Go to File, or
Go to Symbol) and type the name in the new window.
2-26 NetBeans Developing Applications with NetBeans IDE
Understanding the Source Editor Features
Note:
You can use prefixes, camel case, and wildcards.
To go to line:
1. Choose Navigate > Go To Source in the main menu.
2.
Enter the line number to which you want to jump.
To quickly return to your last edit:
■
Even if your last edit is in another file or project, press Ctrl-Q or use the button in
the top left corner of the Source Editor toolbar.
The last edited document opens, and the cursor is at the position, which you
edited last.
To switch between open files:
■
To go to the previously edited file or move forward, choose Navigate > Back or
Navigate > Forward, or press the corresponding buttons on the editor toolbar.
The file opens and the cursor is placed at the location of your last edit. When you
click one of the buttons, you can expand the list of the recent files and click to
navigate to any of them.
■
To toggle between files, press Ctrl-Tab to display all open files in a pop-up
window, hold down the Ctrl key and press several times the Tab key to choose the
file you would like to open.
To go to bookmarks:
■
Choose Navigate > Bookmark History Popup Next in the main menu, to go to
your next bookmark.
■
Choose Navigate > Bookmark History Popup Previous in the main menu, to go
to the previous bookmark.
2.6.14 How to Work with Import Statements
There are several ways of how you can manage import statements in NetBeans IDE.
The IDE's Java Editor constantly checks your code for the correct use of import
statements and immediately warns you when non-imported classes or unused import
statements are detected.
When a non-imported class is found, the
error mark appears in the IDE's left-hand
margin (this margin is also called the glyph margin). Click the error mark and choose
whether to add the missing import or create this class in the current package.
When you select a class from the code completion window, the
Editor automatically adds an import statement for it.
Note:
To add all missing import statements at once:
■
Choose Source > Fix Imports from the menu (or press Ctrl-Shift-I) while you are
typing.
Working with NetBeans IDE 2-27
Understanding the Source Editor Features
To quickly see if your code contains unused or missing
imports, watch the error stripes in the right-hand margin: orange
stripes mark missing or unused imports.
Note:
To add an import only for the type at which the cursor is located:
■
Press Alt-Shift-I.
To remove one unused import or all unused imports:
■
If there are unused import statements in your code, press the
warning mark in
the Editor left-hand margin and choose either to remove one unused import or all
unused imports.
Note:
In the Editor, unused imports are underlined.
2.6.15 How to Generate Code
When working in the Source Editor, you can automatically generate pieces of code in
one of the two ways: by using code completion or from the Code Generation dialog
box.
To insert code from the Code Generation dialog box:
■
Choose Source > Insert Code (or Press Alt-Insert anywhere in the Editor).
The suggested list is adjusted to the current context.
In the IDE's Source Editor, you can automatically generate various constructs and
whole methods, override and delegate methods, add properties and more.
To generate code from the Code Completion window:
■
Press Ctrl-Space to open the code completion window and choose the most
appropriate item.
The Editor generates a piece of code appropriate for the current context.
In the code completion window, the constructors that can be
automatically generated are marked with the
icon and the generate
note.
Note:
2.6.16 Using General Editor Shortcuts
The IDE includes keyboard shortcuts that you can use to activate many Source Editor
operations.
In the following table, multikey shortcuts are written in the following format: Ctrl-U,
T. To use this shortcut, hold down the Ctrl key and press U, then release both keys and
press T.
Table 2–17
Scrolling and Selecting
Keys
Action
Ctrl-down arrow
Scrolls the window up without moving the insertion point.
Ctrl-up arrow
Scrolls the window down without moving the insertion point.
2-28 NetBeans Developing Applications with NetBeans IDE
Understanding the Source Editor Features
Table 2–17 (Cont.) Scrolling and Selecting
Keys
Action
Ctrl-[
Moves the insertion point to the highlighted matching bracket.
This shortcut only works when the insertion point is
immediately after the opening or closing bracket.
Ctrl-Shift-[
Selects the block between a pair of brackets. This shortcut only
works when the insertion point is immediately after either the
opening or closing bracket.
Ctrl-G
Jumps to any specified line.
Ctrl-A
Selects all text in the file.
Table 2–18
Modifying Text
Keys
Action
INSERT
Switches between insert text and overwrite text mode.
Ctrl-Shift-J
Opens the Internationalize dialog box that you can use to insert
an internationalized string at the insertion point.
Ctrl-U, U
Makes the selected characters or the character to the right of the
insertion point uppercase.
Ctrl-U, L
Makes the selected characters or the character to the right of the
insertion point lowercase.
Ctrl-U, S
Reverses the case of the selected characters or the character to
the right of the insertion point.
Table 2–19
Code Folding
Keys
Action
Ctrl-Minus (-)
Collapses the block of code the insertion point is on.
Ctrl-Plus (+)
Expands the block of code the insertion point is next to.
Ctrl-Shift-Minus (-)
Collapses all blocks of code.
Ctrl-Shift-Plus (+)
Expands all blocks of code.
Table 2–20
Cutting, Copying, Pasting, and Deleting Text
Keys
Action
Ctrl-Z
(Undo) Reverses (one at a time) a series of editor actions, except
Save.
Ctrl-Y
(Redo) Reverses (one at a time) a series of Undo commands.
Ctrl-X
(Cut) Deletes the current selection and places it into the
clipboard.
Shift-Delete
(Cut) Deletes the current selection and places it into the
clipboard.
Ctrl-C
(Copy) Copies the current selection to the clipboard.
Ctrl-Insert
(Copy) Copies the current selection to the clipboard.
Ctrl-V
(Paste) Pastes the contents of the clipboard at the insert point.
Delete
(Delete) Deletes the current selection.
Ctrl-E
Deletes the current line.
Working with NetBeans IDE 2-29
Understanding the Source Editor Features
Table 2–20 (Cont.) Cutting, Copying, Pasting, and Deleting Text
Keys
Action
Ctrl-U
Deletes text in the following sequence:
Ctrl-Backspace
Table 2–21
■
text preceding insertion point on same line
■
indentation on same line
■
line break
■
text on previous line
Removes the text in the current word preceding the insertion
point.
Searching for Text
Keys
Action
Ctrl-F3
Searches for the word the insertion point is on and highlights all
occurrences of that word.
F3
Selects the next occurrence of the word in your current search.
Shift-F3
Selects the previous occurrence of the word in your current
search.
Alt-Shift-H
Switches highlighting of search results on or off.
Ctrl-F
Opens the Find dialog box.
Ctrl-H
Opens the Find and Replace dialog box.
Table 2–22
Setting Tabs
Keys
Action
Tab
Shifts all text to right of insertion point to the right.
Alt-Shift-Right
Shifts text in line containing the insertion point to the right.
Alt-Shift-Left
Shifts text in line containing the insertion point to the left.
Table 2–23
Using Bookmarks
Keys
Action
Ctrl-Shift-M
Sets or unsets a bookmark at current line.
Ctrl-Shift-Period/Comma
Goes to next/previous bookmark.
Table 2–24
Using Multiple Carets
Keys
Keys
Keys
(Windows/Linux)
(Mac OS)
(Eclipse/Idea)
Ctrl-Shift-Click
Cmd-Shift-Click
Ctrl-Shift-Click
Add or remove a caret.
Ctrl-J
Cmd-J
Alt-J
Add a caret for the next
occurrence.
Ctrl-Alt-Shift-J
Ctrl-Cmd-Shift-J
Ctrl-Alt-Shift-J
Add a caret for all
occurrences.
Alt-Shift-[
Ctrl-Shift-[ or
Alt-Cmd-Up
Alt-Shift-[
Add a caret in the previous
line.
2-30 NetBeans Developing Applications with NetBeans IDE
Description
Setting Startup Parameters
Table 2–24 (Cont.) Using Multiple Carets
Keys
Keys
Keys
(Windows/Linux)
(Mac OS)
(Eclipse/Idea)
Alt-Shift-]
Ctrl-Shift-] or
Alt-Cmd-Down
Alt-Shift-]
Add a caret in the next line.
Alt-Shift-J
Ctrl-Shift-J
Alt-Shift-J
Remove the last added
caret.
Ctrl-Shift-L
Cmd-Shift-L or
Alt-Cmd-V
Ctrl-Shift-L
Paste clipboard content as
lines over the multiple
carets.
Escape
Escape
Escape
Remove all extra carets and
return to the regular mode.
Description
2.7 Setting Startup Parameters
You can pass startup parameters to the IDE launcher using the
IDE-HOME/etc/netbeans.conf file or on the command line. The launcher reads the
netbeans.conf file prior to parsing the command-line options, including any
parameters you have added. The netbeans.conf file contains details on some of the
available startup switches, including switches to modify the heap size.
Table 2–25
Description of Common Switches
Switch
Description
--help (or -h)
Prints descriptions of common startup parameters.
--jdkhome jdk-home-dir
Uses the specified version of the JDK instead of the default JDK.
By default on Microsoft Windows systems, the IDE's launcher
looks into the registry and uses the latest JDK available.
You should back up your user directory before you upgrade the
JDK that the IDE uses. If you later need to revert to the previous
JDK, switch to the backed up user directory to ensure that you
do not lose any settings.
To switch the IDE's user directory, use the --userdir switch that
is detailed below.
--cp:p
additional-classpath
Prefixes the specified class path to the IDE's class path.
--cp:a
additional-classpath
Appends the specified class path to the IDE's class path.
--open file
Opens the file in the Source Editor.
--open file:line number
Opens the file in the Source Editor at the specified line.
--laf UI-class-name
Selects the given class as the IDE's look and feel. The following
are two examples of look and feel classes.
--fontsize size
■
com.sun.java.swing.plaf.motif.MotifLookAndFeel
■
javax.swing.plaf.metal.MetalLookAndFeel
Sets the font size, expressed in points, in the IDE's user interface.
If this option is not used, the font size is 11 points.
--locale
Activates the specified locale.
language[:country[:variant
]]
Working with NetBeans IDE 2-31
Setting Fonts and Colors for IDE Windows
Table 2–25 (Cont.) Description of Common Switches
Switch
Description
--userdir userdir
Explicitly specifies the user directory, which is the location
where user settings are stored.
If this option is not used in UNIX environments, the user
directory is set in the HOME directory by default. If this option
is not set on Microsoft Windows systems, the user directory is
the one you specified when you first launched the IDE.
You can determine the current user directory in the About dialog
box.
--cachedirpath
Specifies the directory to store the user cache.
-Jjvm-flags
Passes the specified flags directly to the JVM software.
-J-Dsun.java2d.noddraw=t Prevents the use of DirectX for rendering. This switch might
rue
prevent problems that occur on some Microsoft Windows
systems with faulty graphics cards.
When adding startup switches, you can break options into
multiple lines.
Note:
For information about your userdir and cachedir, see the following document.
http://wiki.netbeans.org/FaqWhatIsUserdir
For information about performance-related startup switches, see the following
document.
http://performance.netbeans.org/howto/jvmswitches/
For information about modifying the JVM heap size, see the following FAQ on the
NetBeans wiki.
http://wiki.netbeans.org/FaqSettingHeapSize
2.8 Setting Fonts and Colors for IDE Windows
You can customize the font and color properties that are used in various windows in
the IDE. Font properties include the font family, style, variant, weight, and size. Color
properties include the color of text, the background color of text, and the color of
borders.
2.8.1 How to Set Fonts and Colors for the Help Viewer
You can customize the font and color properties that are used to display the pages in
the help viewer. Font properties include the font family, style, variant, weight, and
size. Color properties include the color of text, the background color of text, and the
color of borders.
To set fonts and colors for displaying help pages:
1. From the main window, choose File > Open File.
2.
In the Open dialog box, navigate to
IDE-install-directoryide/docs/org/netbeans/modules/usersguide and open
the file ide.css.
2-32 NetBeans Developing Applications with NetBeans IDE
Managing Plugins in the IDE
The ide.css file is the style sheet that describes how to present the fonts and
colors in the help pages.
3.
Edit ide.css to your preferences.
4.
Choose File > Save.
5.
Open the help viewer and verify your changes.
2.8.2 How to Set Fonts and Colors for the Output Window
You can customize the font and color properties that are used to display the pages in
the help viewer. Font properties include the font family, style, variant, weight, and
size. Color properties include the color of text, the background color of text, and the
color of borders.
To set fonts and colors for the Output window:
1. Choose Tools > Options from the main menu.
2.
Click the Output tab in the Miscellaneous category.
2.8.3 How to Set Fonts and Colors for the Terminal Window
You can customize the font and color properties that are used to display the pages in
the help viewer. Font properties include the font family, style, variant, weight, and
size. Color properties include the color of text, the background color of text, and the
color of borders.
To set fonts and colors for the Terminal:
1. Choose Tools > Options from the main menu.
2.
Click the Terminal tab in the Miscellaneous category.
2.9 Managing Plugins in the IDE
The IDE's Plugins manager enables you to update and manage your IDE's plugins
dynamically. You can minimize startup time and save memory by deactivating the
plugins that you do not need. Deactivated plugins are not deleted from your
installation directory, but are simply ignored by the IDE. You can re-activate them at
any time.
You can also choose to uninstall plugins from the IDE. Uninstalled plugins are
removed from your installation directory. To use an uninstalled plugins, you need to
install it again.
You use the Plugins manager to connect to the update centers to check if there are new
plugins or new versions of already installed plugins available. If new or updated
plugins are available, you can select, download, and install them using the Plugins
manager.
A plugin generally consists of a group of dependent modules. Some IDE plugins are
grouped together and referred to as a Feature. Each Feature generally corresponds to a
technology and can contain a number of plugins that support that technology. When
you activate or deactivate a Feature, the IDE activates or deactivates the corresponding
plugins.
When you update a plugin, the update usually consists of updating one or more of the
modules that make up the plugin. Some plugins may be dependent on modules in
other plugins in order for the functionality to be implemented. The Plugins manager
Working with NetBeans IDE 2-33
Managing Plugins in the IDE
warns you when this is the case. Deactivating a plugin usually consists of deactivating
the individual modules that make up the plugin.
2.9.1 How to Update the IDE from the Update Center
When you use the Plugins manager to update the IDE, the IDE checks the registered
update centers to see if there are new plugins or new versions of already installed
plugins available. If new or updated plugins are available, you can select, download,
and install the plugins using the Plugins manager. You can set the frequency that the
IDE checks for updates in the Settings tab of the Plugins manager.
Alternatively, you can choose Help > Check For Updates from the main menu to open
the Plugin Installer. The Plugin Installer will check for updates of installed in plugins.
If updates are available, you can step through the installer to install the updates.
In addition to the default IDE Update Center, you can choose from several update
centers that offer different types of plugins, such as experimental new plugins or old
plugins that are no longer in regular distribution.
To update installed plugins from the Update Center:
1. Choose Tools > Plugins from the main menu to open the Plugins manager.
2.
Click the Updates tab to display available updates of installed plugins.
3.
In the left pane, select the plugins you wish to update and click Update.
4.
Complete the pages in the installer to download and install the update.
The left pane of the Updates tab displays the installed plugins which have updates
available from the update centers. By default, the IDE regularly checks the registered
update centers for available updates of installed plugins. If no plugins are displayed in
the left pane, it means that no updates were available the last time the IDE checked the
update center.
To add new plugins from the Update Center:
1. Choose Tools > Plugins from the main menu to open the Plugins manager.
2.
Click the Available Plugins tab to display plugins that are available but not
installed.
3.
In the left pane, select the plugins you wish to add and click Install.
4.
Complete the pages in the installer to download and install the plugin.
Some plugins may require you to restart the IDE to complete
the update process or to activate or deactivate them.
Note:
2.9.2 How to Install Downloaded Plugins
If you have already downloaded a plugin’s .nbm file, you can manually install it
without having to connect to an update center.
To install a downloaded plugin:
1. Choose Tools > Plugins from the main menu and select the Downloaded tab.
2.
Click Add Plugins and browse to the location of the downloaded .nbm file. Select
the file and click Open.
3.
Repeat the previous step for each plugin that you wish to add.
2-34 NetBeans Developing Applications with NetBeans IDE
Managing Plugins in the IDE
4.
Click Install and complete the pages of the installer to install the plugin.
If the plugin that you have selected in the file chooser does not appear in the
Downloaded tab of the Plugins manager, you probably have the same or a newer
version of that plugin already installed. You can check the Installed tab to verify that
the plugin is installed and activated.
2.9.3 How to Activate and Deactivate Plugins
The IDE enables you to deactivate installed plugins that you do not need to minimize
startup time and save memory. Deactivated plugins are not deleted from your
installation directory, but are simply ignored by the IDE. You can re-activate them at
any time. You do not need to download the plugins again.
To activate or deactivate an installed plugin:
1. Choose Tools > Plugins from the main menu and then click the Installed tab in
the Plugins manager.
2.
In the left pane, select the plugin you wish to activate or deactivate.
The icon in the Active column indicates the status of the plugin.
3.
Click Activate or Deactivate to activate or deactivate the plugin.
The icon for the plugin in the left pane reflects the new status of the plugin.
4.
Click Close to exit the Plugins manager.
If you want to completely remove a plugin from your local system, select the checkbox
for the plugin in the left pane and then click Uninstall.
The following table defines the icons used in the Installed tab of the Plugins manager
to indicate the status of plugins.
Table 2–26
Plugin Status Icons
Icon
Description
The plugin is installed and activated.
The plugin will be fully deactivated after you restart the IDE.
The plugin is installed but deactivated.
2.9.4 How to Globally Install Plugins
If you are using a multi-user installation of the IDE, you can install a plugin globally so
that the plugin is available to all users. When you install or update a plugin using the
Plugins manager, the IDE places the plugin JAR and docs in your user directory. The
IDE places JAR and docs for globally installed plugins in your installation directory
instead of an individual user directory.
To globally install a plugin:
1. Choose Tools > Plugins to open the Plugins manager.
2.
Click the Settings tab and then select Force install into shared directories in the
Plugin Install Location drop-down list.
3.
Click the Available Plugins tab, select the Install checkbox for the plugin and click
Install.
Working with NetBeans IDE 2-35
Displaying IDE Help in a Web Browser
You can also install manually downloaded plugins in the Downloaded tab.
4.
Follow the wizard instructions to complete the installation of the plugin.
5.
Restart the IDE to activate the new plugin, if necessary.
To install a plugin globally, you must have write access for the IDE installation
directory.
2.9.5 How to Add an Update Center
The IDE's Plugins manager enables you to update your IDE's installed plugins from
registered update centers. You can specify the update centers you want the IDE to
check and how often the IDE checks the update centers.
You can manage the registered update centers in the Settings tab of the Plugins
manager. In addition to the default IDE Update center, you can add other update
centers that offer different types of plugins, such as experimental new plugins or old
plugins that are no longer in regular distribution.
To add an update center:
1. Choose Tools > Plugins from the main menu to open the Plugins manager.
2.
Click the Settings tab to display the registered update centers.
3.
Click Add to open the Update Center Customizer dialog box.
4.
Type the name of the update center and the URL and click OK.
In the Settings tab of the Plugins manager you can also do the following:
■
■
■
Deactivate an update center by deselecting the Active checkbox for the update
center you wish to deactivate. You can reactivate the update center later if you
wish.
Edit the details of an update center by selecting the update center in the left pane
and clicking Edit in the right pane.
Remove an update center by selecting the update center in the left pane and
clicking Remove in the right pane.
2.9.6 How to Schedule Update Checks
By default, the IDE periodically checks the update centers for new updates. You can
set the interval or specify that the IDE should not automatically check for updates.
To schedule update checks:
1. In the Settings tab of the Plugins manager, choose a frequency from the Check
Interval drop-down list. Choose Never if you do not want the IDE to automatically
check for updates.
2.
Click Proxy Settings if you need to set any proxy settings needed to enable the IDE
to access the update centers.
2.10 Displaying IDE Help in a Web Browser
The online help is designed to be viewed in the JavaHelp viewer, which is integrated
into the IDE. If you prefer, you can view the online help in the IDE's web browser or in
another HTML browser.
2-36 NetBeans Developing Applications with NetBeans IDE
Internationalizing Source Code
2.10.1 How to Extract IDE Help from a JAR File
The online help is divided into several help sets. Most help sets are packaged in a JAR
file, while a few help sets are packaged in a zip file. Help sets are typically stored in
the ide/modules/docs directory in your installation directory.
To extract the online help from a JAR file:
1. In a command window, change to the install-directory/ide/modules/docs
directory and list the files in that directory.
2.
Use the jar command-line utility to unpack the JAR file in which you are
interested. On Microsoft Windows systems and UNIX systems, the command is as
follows:
jar xf jar-file
For jar-file, use the file name of the JAR file from which you want to extract
files.
The Jar tool makes copies of the files and writes them to the current directory. The
directory structure is reproduced according to the package structure in the archive.
2.10.2 How to View IDE Help in a Web Browser
To view the online help in a web browser:
1. From the IDE main window, choose View > Web Browser.
2.
In the web browser use the File Browser and navigate to the files you just
extracted.
2.11 Internationalizing Source Code
The IDE's internationalization tools let you easily insert internationalization strings
while you write your code as well as internationalize files that are already written. You
can also check resource bundles to make sure each key referenced by your code exists.
When you internationalize existing source files, the IDE searches for every
customizable occurrence of a quoted text string. If you decide to internationalize the
string, the IDE replaces it with a method call and adds the string to the appropriate
resource bundle. You can select from several code formats for generating
internationalized strings, or you can use your own custom format.
2.11.1 How to Enable Automatic Internationalization
As you design a form in the GUI Builder, you can have the code generated as
internationalized code.
To turn on automatic internationalization for a form:
1. Open the form and make sure that the form appears in the Design view.
2.
In the Navigator window, select the root node for the form.
3.
In the Properties window, select the Automatic Internationalization checkbox.
Working with NetBeans IDE 2-37
Internationalizing Source Code
2.11.2 How to Internationalize a Single File
The Internationalize dialog box enables you to replace hard-coded strings in a single
file with internationalized strings. If you need to internationalize several Java sources
into one or more resource bundles, use the Internationalization wizard.
To internationalize source code:
1. In the Files or Projects window, right-click the class file you want to
internationalize and choose Tools > Internationalization > Internationalize.
The Internationalize dialog box opens enabling you to edit each string in the file
consecutively.
■
■
If a resource bundle already exists for the file, the bundle properties file in
which the strings are saved is displayed in the Bundle Name field. The
Replace String field also displays a preview of the internationalized string.
If no resource bundle exists for the file, the Bundle Name and Replace String
fields are empty. You can click the ellipsis (...) button to specify a properties file
or create a new one in which to save internationalized strings.
2.
If you want to change the method used to generate the localized string, click
Format.
3.
If you want to add arguments to the method call, click Arguments. You can only
add arguments to the method call if you use the java.text.MessageFormat or
org.openide.util.NbBundle.getMessage formats.
4.
Check that the key and value are correct. By default, the Internationalize dialog
box gives the key the same name as the string being replaced.
5.
Click Replace to generate the internationalized string.
The next string to be internationalized is then displayed in the Value text field.
6.
Click Skip to ignore any strings you do not want to internationalize.
The IDE automatically dismisses the dialog box once the last string has been
replaced.
To get information about the highlighted string in the Source Editor, click Info to see
the name of the component containing the string and the property that the string is
associated with.
2.11.3 How to Use the Internationalization Wizard
The Internationalization wizard enables you to replace hard-coded strings with
internationalized strings in multiple files. If you are localizing the source into more
than one language, the Internationalization wizard also lets you specify the localized
string for multiple locales.
To automatically internationalize strings in multiple source files:
1. Choose Tools > Internationalization > Internationalization Wizard from the main
window.
2.
Click Add Source(s) to add one or more source files to internationalize. Click Next
to proceed.
3.
Click Select All if you want a single resource bundle to contain the key and value
pairs for all the listed sources. To select a resource bundle for specific source files,
select the desired sources and click Select Resource. In the Select Resource dialog
box, select the desired .properties file or create a new file. Click Next to proceed.
2-38 NetBeans Developing Applications with NetBeans IDE
Internationalizing Source Code
To modify key and value pairs:
1.
From the Source drop-down list, select the source file in which you want to
create the variable.
2.
Select the Generate Field checkbox and set the variable's modifiers.
3.
Type the name of the identifier in the Identifier text field.
4.
The Init String field gives you a preview of the code that the variable will use
to reference the resource bundle. To change this code, click Format and select
the desired code format from the Init Code Format Editor.
5.
Click Next to generate the field.
4.
In the Modify Found Strings pane, set the key name and localized values for each
of the strings you want to internationalize by entering a new value in the
appropriate column. Use the Source drop-down list to switch between source files.
Deselect the checkbox in the first column for any string you do not want to
internationalize.
5.
To change the code format used to generate the internationalized string or add
arguments to the method call, click the ellipsis button (...) at the end of the string's
row.
6.
Click Finish to internationalize the strings for all of the selected source files.
2.11.4 How to Insert an Internationalized String Into Source Code
The Insert Internationalized String command enables you to add internationalization
strings one at a time as you create the source.
To insert an internationalized string into your source code:
1. In the Source Editor, put the insertion point at the location in the source file where
you want to insert an internationalized string.
2.
Right-click the desired location and choose Tools > Internationalization > Insert
Internationalized String from the pop-up menu, or use the keyboard shortcut
(Ctrl-Shift-J).
The Insert Internationalized String dialog box appears enabling you to edit each
string in the file consecutively. To choose a different .properties file or create a
new file, click the ellipsis (...) button.
3.
Click Format if you want to change the method used to generate the localized
string.
4.
Click Arguments if you want to add arguments to the method call. You can only
add arguments to the method call if you use the java.text.MessageFormat or
org.openide.util.NbBundle.getMessage formats.
5.
Type in values for the Key and Value properties and click OK.
2.11.5 How to Internationalize a String With the GUI Builder
If you need to internationalize a GUI application, you can use the GUI Builder to
replace a GUI component's hard-coded text with internationalized strings.
To insert an internationalized string with the GUI Builder:
1. Open the desired file in the GUI Builder by double-clicking its node in the Files or
Projects window.
Working with NetBeans IDE 2-39
Internationalizing Source Code
2.
Select the appropriate GUI component in the Navigator window.
3.
In the Properties window, select the property that you want to internationalize (for
example, the text property of jLabel).
4.
Select Resource Bundle from the drop-down list at the top of the dialog box.
The property editor switches to resource bundle mode.
If a resource bundle already exists for the source, the bundle properties file into
which the internationalized strings will be saved is displayed in the Bundle Name
field.
5.
If no .properties file is listed in the Bundle Name field, click the ellipsis (...)
button next to the field to open the Select Resource Bundle dialog box. In the
dialog box, specify an existing .properties file or create a new file. Click OK to
return to the property editor.
6.
If you want to change the method used to generate the internationalized string,
click the Format button.
7.
If you want to add arguments to the method call, click Arguments. You can add
arguments to the method call only if you use the java.text.MessageFormat or
org.openide.util.NbBundle.getMessage formats.
8.
Type in values for the Key and Value properties and click OK.
2.11.6 How to Test a Bundle for Internationalized Strings
You can check resource bundles for missing key and value pairs by using the
Internationalization Test wizard. The wizard looks for all internationalized string keys
(with a customizable meaning) in the source and checks for a corresponding key and
value pair in the specified resource bundle. You can use the wizard to add any missing
pairs.
To test a bundle for internationalized strings:
1. Choose Tools > Internationalization > Internationalization Test Wizard.
2.
Click Add Source(s) and select one or more source files to test in the Select Sources
dialog that appears. Click Next to proceed.
3.
Specify the resource bundles for the source files. Click Select All to check one
resource bundle for all the listed sources. To select a specific resource bundle for
one or more source files, select the desired sources and click Select Resource. Click
Next to proceed.
The wizard lists all of the internationalized strings with missing key and value
pairs in the selected file. The wizard automatically suggests key names and values
for the string.
4.
Use the Source drop-down list to switch between source files. Deselect the
checkbox in the first column for any string you do not want to include in the
resource bundle. Change the key name and value for any string by typing a new
value in the appropriate column.
5.
Click Finish to add the missing key and value pairs to the resource bundle.
2.11.7 How to Add Arguments for Message Formats
The java.text.MessageFormat code format lets you use strings that are constructed
dynamically at runtime. The dynamically added elements are stored in an array of
2-40 NetBeans Developing Applications with NetBeans IDE
Managing and Creating Projects
objects, which is passed as a parameter to java.text.MessageFormat. You can use the
Message Format Arguments dialog box to specify the values of these objects.
You can add arguments when you use the org.openide.util.NbBundle.getMessage
format. This format is part of the NetBeans APIs and is used to build modules for the
IDE. Consult the NetBeans API documentation for more information on this format.
To enter substitution parameters for a message format:
1. In the Internationalize dialog box, click the Format button.
2.
Select the java.text.MessageFormat format or the
org.openide.util.NbBundle.getMessage format from the Replace Code Format
drop-down list. Then click OK.
3.
In the Internationalize dialog box, click the Arguments button.
4.
Click the Add button next to the Arguments text field.
A series of parameters, beginning with 0, is added to the text field.
5.
Type a value for the parameter in the Code field.
6.
Use the Add and Remove buttons to add or remove message parameters. When
you are done, click OK to close the dialog box.
7.
Finish entering values for the key and value fields as normal.
The arguments you supply are substituted for the {arguments} wild card in the
following format:
java.text.MessageFormat(java.util.ResourceBundle.getBundle("bundle
name").getString("key"), new Object[] {arg1, arg2, arg3})
2.12 Managing and Creating Projects
A NetBeans project is a group of source files and the settings with which you build,
run, and debug those source files. In the IDE, all development has to take place within
a project. For applications that involve large code bases, it is often advantageous to
split your application source code into several projects.
2.12.1 How to Create a Project
NetBeans IDE provides wizards that enable you to create projects that are based on
project templates. The IDE includes several project templates designed to support
different types of development including general Java applications, Java web and
enterprise applications, HTML5 applications and PHP applications.
To create a project:
1. Choose File > New Project (Ctrl-Shift-N) from the main menu.
2.
Select the appropriate project template in the New Project wizard.
3.
Follow the steps in the remainder of the wizard.
For information on creating a Java Application Project, see Chapter 6, "Creating Java
Projects."
For information on creating a Java Web Application Project, see Chapter 12,
"Developing Web Applications."
For information on creating a Java EE Project, see Chapter 14, "Developing Enterprise
Applications."
Working with NetBeans IDE 2-41
Managing and Creating Projects
For information on creating an HTML5 Application Project, see Chapter 20,
"Developing HTML5/JavaScript Applications."
For information on creating a PHP Application Project, see Chapter 21, "Developing
PHP Applications."
For information on creating a Java ME Application Project, see Chapter 22,
"Developing Java ME Applications."
2.12.2 How to Work with Character Encodings for a Project
By default, newly-created projects in the IDE use UTF-8 character encoding. This
encoding determines how the IDE interprets characters beyond the ASCII character
set. The IDE displays and saves any new files you create using the encoding set by the
project in which they reside. If you want to change encoding properties, the IDE
provides you with the ability to do so manually.
The IDE implements the FileEncodingQuery (FEQ) layer model. FEQ is an interface
for obtaining information about which encoding can be used for reading from/writing
to a particular file. The layer model prioritizes encoding based on the following
hierarchy:
1.
File FEQ. The encoding value declared within a file.
2.
Project FEQ. The value of the current global project encoding in a session.
3.
Fallback FEQ. The encoding of the locale in which the IDE is running.
Project created in NetBeans IDE 5.x and older did not implement the FEQ and will be
opened using the fallback FEQ, the default locale set by your system's environment.
WARNING: If you change the project encoding property on a
project that already contains files that were created using a specific
character encoding, there is a risk that compiling and running the
project may not succeed. This is due to the fact that the
programming compiler needs to be passed an encoding value, and
there can only be one such value. Neither the IDE nor the
programming language performs automatic encoding detection of
files.
2.12.2.1 Changing the Character Encoding of a Project
When you change the encoding for a project, all new files are created using the new
project encoding.
To change the character encoding for a project:
1. Right-click the project node in the Projects window and choose Properties.
2.
In the left column under Categories, select Sources.
3.
In the Encoding drop-down list, select the character encoding that you want to be
applied to the project. Click OK. The new encoding is applied to the project you
are working in.
The new value that you set for project encoding is retained as
the global project encoding value for new projects. Therefore, when
you create a new project, the IDE uses the encoding value of the
previously created project for the new project.
Note:
2-42 NetBeans Developing Applications with NetBeans IDE
Working with Source Files in the IDE
2.12.3 How to Organize Projects into Groups
You can create groupings of projects so that you can open and close several projects at
once. In addition, each group can have a different main project. After you create a
project group, that project group is available in the Project Group menu. When you
select a project group from that menu, all other open projects are closed. If you want to
close all open projects, choose File > Project Group > (none).
To create a project group:
1. Choose File > Project Groups from the main menu.
2.
Click New Group in the Manage Groups dialog box.
3.
Type the name of the new group in the Create New Group dialog box.
4.
Select the options for the group. Click Create Group.
If you select the Automatically Save Project List option in the dialog box, projects
that you open or close will automatically be added to or removed from the group.
To create a project group that contains a specific set of projects:
1. Close any projects that you do not want to include in the group.
2.
Choose File > Project Groups to open the Manage Groups dialog box.
3.
Click New Group.
4.
Select Free Group in the Create New Group dialog box.
5.
Select Use Currently Open Projects.
If you created a free group and deselected the Automatically Save Project List option
when you created the group, you can perform the following steps to modify the
contents of the group.
To modify the contents of a free group:
1. Open the project group that you want to modify.
2.
Open any projects that you want to add to the group.
3.
Close any projects that you want to remove from the group.
4.
Choose File > Project Groups.
5.
Select the group or groups in the Manage Groups dialog box. Click Properties.
6.
Select Automatically Save Project List in the Project Group Properties dialog box.
Click OK.
2.13 Working with Source Files in the IDE
The IDE provides tools that enable you to find, compare and move the files in your
projects. You can also modify the properties of files and create file templates that you
can use when you create files.
For information on editing Java source files, see Chapter 7, "Working with Java Code."
2.13.1 How to Find Files in Projects
You can use the Find in Projects command to locate the occurrences of specific text
strings in files in your project. You can invoke the command from the popup menu in
the Projects, Files and Favorites windows.
Working with NetBeans IDE 2-43
Working with Source Files in the IDE
The results of the search are displayed in the Search Results window. The Search
Results window displays a node for each file that contains the search string. When a
file contains more than one occurrence of the string you can expand the node to view a
list of each occurrence in the file. You can double-click an occurrence in the Search
Results window to open the file in the editor at the line containing the search string.
To find a string in project files:
1. Right-click the project or folder that you want to search and choose Find in the
popup menu to open the Find in Projects dialog.
Alternatively, you can select an element in the Projects, Files or Favorites windows
and choose Edit > Find in the main menu.
2.
Type the search string in the Containing Text field.
3.
Specify any additional options that you want to apply to the search string.
4.
Specify the Scope of the search.
By default the scope is the folder that you selected, but you can use the drop-down
menu to modify the scope.
5.
Specify any File Name Patterns to limit the search to certain types of files.
6.
Click Find.
2.13.2 How to Specify Editor Formatting Options
You can specify how the source editor formats source code for various languages. You
can specify formatting options globally to apply to all files in that language and also at
the project level to specify the options for a specific project.
To specify global editor formatting options:
1. Choose Tools > Options in the main menu to open the Options window.
2.
Click the Formatting tab in the Editor category.
3.
Select a language in the Languages drop-down list.
4.
Select a formatting category in the Category drop-down list.
5.
Specify the formatting options for the category. Click Apply in the Options
window.
In addition to global settings, you can specify the editor formatting options at the
project level that will only apply to the current project. You can also use the formatting
options specified for an existing project and apply the options to the current project.
To specify editor formatting options for a project:
1. Right-click the project node in the Projects window and choose Properties in the
popup menu.
2.
Select Formatting in the Project Properties window.
3.
Select Use project-specific options.
4.
Select a language in the Languages drop-down list.
Alternatively, click Load from other project to use the formatting options from an
existing project.
5.
Select a formatting category in the Category drop-down list.
2-44 NetBeans Developing Applications with NetBeans IDE
Working with Source Files in the IDE
6.
Specify the formatting options for the category. Click OK.
2.13.3 How to Compare Two Files
You can use the diff viewer included in the IDE to compare source files. You can export
a diff patch file directly from the diff viewer window.
The IDE can display diffs in either of two modes:
■
■
Graphical Diff Viewer. (Default) The graphical diff viewer displays the two files
side by side and uses background highlight colors to display the differences
between the two files. By default, changed lines are highlighted in blue, added
lines are highlighted in green, and removed lines are highlighted in red.
Textual Diff Viewer. The textual diff viewer shows you the diff output in text so
that you can copy and paste the output into a file or into an email.
You can use either the built-in diff engine or a command-line diff engine.
■
■
Built-in Diff Engine. (Default) The built-in diff engine enables you to compare
two files without your needing a command-line diff executable installed on your
system.
Command-line Diff Engine. Before you can use the command-line diff engine on
a Microsoft Windows system, you must have a command-line diff executable (for
example, from a Cygwin distribution) installed on your system. For the UNIX
environment, there is a diff executable installed and available to you by default.
You can specify the diff engine in the Diff tab in the Miscellaneous category of the
Options window. You can open the Diff tab by clicking Options in the diff viewer
window or by choosing Tools > Options in the main menu.
To compare two files:
1. Select two files in the IDE.
2.
Right-click and choose Tools > Diff from the pop-up menu to run the diff
command.
By default, the IDE opens the diff viewer window in graphical mode. You can click
the Textual tab to view the diff in the textual diff viewer.
You can click Options in the diff viewer window to open the Options window and
select the diff engine that is used to find differences between files.
3.
Click Export in the diff viewer window to save the diff as a diff patch file.
2.13.4 How to Apply a Diff Patch to a File
A patch file enables you to modify or patch a file based on the differences between the
two versions of the file. The differences between the versions are contained in a diff
patch file. Patch files enable software developers who are not sharing a common
repository to distribute and integrate changes that have been made to the code. The
IDE enables you to create and apply patches that update copies of source files so that
you do not have to incorporate the changes manually.
You can apply a patch to an individual file or a folder. Patches that are applied to
folders use relative paths to the files within them. Folder patches must be applied on
the same folder node that the patch was created on to ensure that the patch is applied
properly. If you are uncertain to which file or folder the patch should be applied, you
can find the context information in the patch file itself. Patch files generated by the IDE
Working with NetBeans IDE 2-45
Working with Source Files in the IDE
contain the context in which the patch was originally created in the first few lines of
the file.
How to apply a patch file to a file:
1. In the Projects window, right-click the file or folder to which you want to apply the
diff patch and choose Tools > Apply Diff Patch in the popup menu.
2.
Locate the patch file in the file browser and click Patch.
When you apply the patch, the IDE applies the changes contained in the selected patch
to the chosen file or folder and informs you that patch is successfully applied. In the
Question dialog box, click Yes to view applied changes in the Diff Viewer or No to
close the dialog box.
For details on applying patches to files that are under version control, see
Section 3.3.16, "How to Create and Apply a Patch (Subversion)," and Section 3.5.17,
"How to Create and Apply a Patch."
2.13.5 How to Access Files Outside of a Project
When developing applications, you must create a project for your source code and
related files. If you need to access a file outside of your projects, you can do either of
the following things:
■
■
Choose File > Open File in the main menu and navigate to the location of the file
on your system.
Use the Favorites window to access the file.
To use the Favorites window:
1. Choose Window > Favorites (Ctrl-3) in the main menu.
2.
Right-click in the Favorites window and choose Add to Favorites.
3.
Select the folder that you want to access and click OK.
Project-level commands, such as Run Project, are not available from the Favorites
window. For such commands to be available, you need to have a project open in the
Projects window.
2.13.6 How to Create a File Template
You can save a file as a template and add it to the types of templates available in the
template chooser in the New File wizard.
To create a new template:
1. In the Projects window, right-click the file you would like to turn into a template
and choose Save As Template.
2.
In the Save As Template dialog box, select a category for the template and click
OK.
To modify a an existing template:
1. Choose Tools > Templates from the main menu.
2.
In the Template Manager, expand the appropriate category node and select the
template.
3.
Click Open in Editor.
2-46 NetBeans Developing Applications with NetBeans IDE
Working with Source Files in the IDE
4.
In the Source Editor, make the desired changes to the template.
5.
Choose File > Save from the main menu.
In the Template Manager, you can click Duplicate to create new templates based on
existing templates. You can create new folders and move templates between folders.
Templates are not project-specific. If you modify a template
that is used by a wizard in the IDE the modified template will be used
by that wizard for generating files in all projects.
Note:
2.13.7 How to Work with Unknown File Extensions
If you want to work with a file of a type that the IDE does not recognize, you can
associate it with one of the file types that the IDE is familiar with.
To register a file extension as belonging to a specific file type:
1. Choose Tools > Options from the main menu.
2.
Click the Files tab in the Miscellaneous category.
3.
Click New to open the Enter New File Extension dialog box.
4.
Enter the file extension that you want to register and click OK.
5.
In the Associated File Type (MIME) field, select the file and MIME type that you
want to associate with your new file extension.
For some object types, such as Java objects, it is not possible to
add an extension.
Note:
2.13.8 How to Specify Files to Ignore
If you have files that you do not want to be recognized by the IDE, you can configure
the IDE to ignore these files.
Note: If you set the IDE to ignore .class files, these files are not
visible in the Files window under the build folder.
To specify files to be ignored:
1. From the main window, choose Tools > Options and click Miscellaneous.
2.
Click the Files tab and use the Ignored Files Pattern field to enter a POSIX-style
regular expression to specify the files you want ignored.
Table 2–27
Table of useful characters for regular expressions
Character
Description
|
Or.
^
Matches all file or directory names beginning with the
subsequent characters.
$
Matches all file or directory names ending with the preceding
characters.
\
Escape character. Necessary if you want to match to a period (.)
or other special character.
Working with NetBeans IDE 2-47
Working with Source Files in the IDE
Table 2–27 (Cont.) Table of useful characters for regular expressions
Character
Description
.*
Wildcard.
2.13.9 How to Work with Character Encodings for Files
When creating a file for a project, the files are created using the specified project
encoding. Some file types declare the encoding in the file (for example, HTML, JSP,
and XML files). Therefore, when the IDE creates these files, it automatically includes
character encoding declarations in the file template.
When determining the character encoding for a file, the IDE applies the
FileEncodingQuery (FEQ) layer model. It first determines whether the encoding is
declared in the file. If no encoding declaration can be found, the IDE presumes the file
encoding is specified by the project's encoding property. If the project encoding is not
specified (for example, imported or older projects), the IDE applies the encoding set by
the environment in which it runs.
To change the encoding for a file (for example, HTMl, XML, or JSP files) you need to
change the encoding and charset specified in the corresponding tag in the file. When
an encoding is specified in a file, this setting overrides the encoding set in the project.
To manually change the character encoding for a file:
1. Open the file in the Source editor.
2.
Modify the encoding and charset tags for the file, if available.
WARNING: The IDE does not convert characters when the
encoding of a file changes. If you manually change the encoding
declaration within the file, and that encoding does not match the
project encoding, you may encounter problems when compiling and
running the project. The encoding tag affects how file contents are
viewed internally - not only during runtime, but also during the
design phase such as when you add content in the Source Editor.
WARNING: Manually changing the character encoding declaration
within a file changes how the IDE reads and displays that file.
When you change the file encoding, the IDE does not convert the
existing contents of the file to the new encoding. Care should be
taken when changing the encoding of a file because the file may
contain characters that cannot be saved or that may not display
properly in the new encoding.
2.13.10 How to Specify Action Items
You can create a list of things that you need to resolve in your various projects and
view the list as entries in the Action Items window. The list of action items can include
compilation errors that are identified by the IDE, issues in an issue tracker and tasks
that are identified by specific ToDo character patterns in project files. The IDE
automatically scans your projects for action items and displays the items in the Action
Items window.
2-48 NetBeans Developing Applications with NetBeans IDE
Working with Source Files in the IDE
Action items are created by some types of errors and by the occurrence of specific
character patterns in the file. The list of action items can include the following types of
items.
■
Compiler errors
■
Hudson tasks
■
Issues
■
Maven POM problems
■
TODO
■
Whitelist violations
By default, you can create action items by adding comments that contain the following
patterns to a file.
■
TODO
■
XXX
■
FIXME
■
Javadoc comments that contain the @todo keyword (Java projects)
To create a custom pattern:
■
Choose Tools > Options from the main menu.
■
■
Click the Action Items tab in the Team category.
Click Add and type the new pattern in the table. Click OK.
To edit or remove a pattern:
■
Choose Tools > Options from the main menu.
■
■
Click the Action Items tab in the Team category.
Select a pattern in the table and click Edit to edit the selected pattern or Remove to
delete the selected pattern. Click OK.
The IDE includes the following patterns as action items by default.
■
■
The pattern <<<<<<, which denotes merge conflicts in CVS and other version
control systems
Lines where compiler errors are registered (Java projects)
To open the Action Items window:
■
Choose Window > Action Items.
You can double-click an entry in the Action Items window to jump to the line of the
file where the action item needs to be resolved or open the issue in the IDE.
To create a filter for items in the Action Items window:
1. Choose Window > Action Items to open the Action Items window.
2.
Click the Filter button in the Action Items window toolbar to open the Action
Items Filter dialog box.
3.
Click New to create a new filter and type a name for the filter.
4.
Select the types of action items that you want to be displayed.
Working with NetBeans IDE 2-49
Working with Resource Bundles
5.
(Optional) Click the Keywords tab and specify any additional criteria that needs to
be met.
6.
Click OK.
To apply a filter to the list of action items, click the arrow on the Filter button and
select a filter from the drop-down list.
2.13.11 How to Use Bookmarks in Files
Bookmarks enable you to quickly navigate to a specific line in a file. After you set a
bookmark in a file you can use keyboard shortcuts to jump to the bookmark or
between bookmarks in the file. You can view a list of your bookmarks in the
Bookmarks window. When you double-click a bookmark in the Bookmarks window
the IDE opens the file in the source editor at the line that contains the bookmark.
How to toggle a bookmark in a file:
1. Place the insert cursor in the line in the file.
2.
Type Ctrl-Shift-M.
How to move between bookmarks in a file:
1. Type Ctrl-Shift-Period or Ctrl-Shift-Comma to open the Bookmarks popup menu.
2.
Use the up and down arrows to navigate in the popup menu. Select a bookmark in
the menu to open the file at the line containing the bookmark or select
<Bookmarks> in the popup menu to open the Bookmarks window.
How to view a list of all bookmarks:
1. Choose Windows > IDE Tools > Bookmarks from in the main menu.
2.14 Working with Resource Bundles
Resource bundles store selected characteristics of an object as key and value pairs in a
set of .properties files. You can store a variety of characteristics in resource bundles,
like localized strings used to internationalize your code or properties for an Ant script.
The IDE displays resource bundles as properties object nodes (
) that contain
nodes for each of its locales (
) and keys (
).
When used for internationalizing source code, the IDE stores each locale's
characteristics in a .properties file which is contained within the resource bundle.
Each key corresponds to the name of a property and must be the same for each locale.
The key value is the localized string displayed by the object at runtime and can vary
for each locale.
The IDE also enables you to automate the process of internationalizing your source
code. You can use the IDE's internationalization features to:
■
Automatically replace hard-coded strings with internationalized ones
■
Insert new internationalized strings as you write code
■
Check your resource bundles to ensure they contain all of the necessary keys
Though resource bundles and locales are both .properties
files, the IDE displays resource bundles and the locales they contain
using different icons in the Files window to avoid confusion.
Note:
2-50 NetBeans Developing Applications with NetBeans IDE
Working with Resource Bundles
2.14.1 How to Create and Delete Resource Bundles
The IDE enables you to manage resource bundles and the various key and locale pairs
stored within them. When you use the New wizard to create a new properties file, the
IDE automatically creates a .properties file for the default locale to which you can
then add specific properties and additional locales.
A properties file is created with a .properties suffix. The Files window displays a
properties object node (
) for the resource bundle with one locale subnode (
)
for the default locale.
To create a resource bundle:
1. Choose File > New to open the New wizard.
2.
Select the project in which you want to create the resource bundle.
3.
Expand the Other node in the Categories pane, select Properties File in the File
Types pane, and click Next.
4.
Type the file name in the File Name field.
5.
Enter the location where you want to create the resource bundle. Click Finish.
To delete a resource bundle:
1. Right-click the properties file in the Files window and choose Delete.
2.
In the verification dialog box, click Yes to remove the file.
2.14.2 How to Edit a Resource Bundle
There are two ways of editing the properties files contained in your resource bundles:
■
■
In the Source Editor as text files. The Source Editor displays one text file for each
of the resource bundle's locales. Each locale file lists all the key and value pairs for
that locale
In the Properties Editor, a special editor that is displayed inside the Source Editor.
The Properties Editor displays key and value pairs for all locales of your resource
bundle in table layout.
To edit a properties file in the Properties Editor:
1. In the Files window, right-click the properties object node (
) and choose Open.
The Properties Editor is displayed showing all existing keys and their values for
each locale.
2.
If you want to change a property's key, type the new name in the Key column.
3.
If you want to change a property's value for a locale, type the new value in the
locale's Value column.
4.
If you want to add or remove keys, use the New Property and Remove Property
keys.
To edit a property file as a text file:
1. Right-click the properties object node and choose Edit to edit the default locale.
2.
If you want to edit a different locale, expand the properties object node, right-click
the node for the locale you want to modify and choose Edit.
Working with NetBeans IDE 2-51
Working with Resource Bundles
2.14.3 How to Add and Remove a Property
The IDE's Properties Editor enables you to manage the properties in all of the locales
in your resource bundle. You can also add a property to or remove a property from
only one locale.
To add a new property to all locales in a resource bundle:
1. In the Files window, right-click the properties object node (
) and choose Open.
The Properties Editor is displayed showing all existing keys and their values for
each locale.
2.
In the Properties Editor, click the New Property button.
3.
Enter a key and its default value for the new property.
You can also add a comment along with the key and value. The comment is
displayed when you click the value for that locale's key.
4.
Click OK.
The property appears in the Properties Editor with the default value entered for
each existing locale.
5.
If you want to set a different value for each locale, enter the new values in each
locale's column.
6.
Choose File > Save to save the file.
To add a new property to a specific locale:
1. In the Files window, expand the properties object node for the resource bundle
that contains the locale.
2.
Right-click the node of the locale to which you want to add a property and choose
Add Property.
3.
Enter a key and a value for the new property and click OK.
4.
Choose File > Save to save the file.
To remove a property from all locales in a resource bundle:
1. In the Files window, right-click the properties object node and choose Open.
2.
In the Properties Editor, select the key for the property you want to remove.
3.
Click the Remove Property button.
4.
Click Yes in the verification dialog box.
To remove a property from a specific locale:
1. In the Files window, right-click the properties object node and choose Delete.
2.
Click Yes in the verification dialog box
You can also delete an entire resource bundle and all of the .properties files
contained within it by right-clicking its properties object node (
) and choosing
Delete.
2-52 NetBeans Developing Applications with NetBeans IDE
Working with Resource Bundles
2.14.4 How to Add and Remove a Locale
The New Locale dialog box provides an extensive list of predefined locales. It also lets
you define your own locale by choosing the appropriate language code, country code,
and language variant.
To add a locale:
1. Right-click the properties object node (
Locale.
) in the Files window and choose Add
2.
Select a language code, country code, and variant from the drop-down lists. You
can also select from the list of predefined locales in the bottom of the dialog box.
3.
Click OK to add the locale.
To remove a locale:
1. Expand the resource bundle's object node in the Files window.
2.
Right-click the locale and choose Delete.
You can also delete an entire resource bundle and all of the .properties files
contained within it by right-clicking its properties object node (
) and choosing
Delete.
2.14.5 How to Edit a Locale
The localized strings for each locale are stored in that locale's .properties file. You
can modify a locale in the Source Editor as a text file or in the Properties Editor. You
can also edit a specific locale using its customizer.
To edit a locale in the Properties Editor:
1. Right-click the properties object node (
) in the Files window and choose Open.
The Properties Editor is displayed showing all existing keys and their values for
each locale.
2.
If you want to change a property's key, type the new name in the Key column.
3.
If you want to change a property's value for a locale, type the new value in the
locale's Value column.
4.
If you want to add or remove keys, use the New Property and Remove Property
keys.
To edit a locale as a text file in the Source Editor:
1. Right-click the properties object node and choose Edit to edit the default locale.
2.
If you want to edit a different locale, expand the properties object node, right-click
the node for the locale you want to modify and choose Edit.
To edit a locale using the customizer:
1. Expand the properties object node in the Files window.
2.
Right-click the desired locale and choose Customize.
The Locale customizer opens listing the locale name and each existing key.
3.
If you want to switch locales, click the ellipsis (...) button. This option is not
available for the default locale.
Working with NetBeans IDE 2-53
Working with Javadoc Documentation
4.
If you want to add a new property to the locale, click Add Key and enter the key
name and value.
5.
If you want to remove a property from the locale, select the property and click
Remove Key.
Note: You cannot edit the existing values of properties with the
customizer.
2.15 Working with Javadoc Documentation
Javadoc is a tool for generating API documentation in HTML format from doc
comments in source code.
NetBeans supports the Javadoc standard for Java documentation: both viewing and
generating Javadoc. It provides a solid documentation tool when working with code.
2.15.1 How to Add Javadoc to a Project
You can make Javadoc documentation for a JAR file's class available in the IDE by
associating that documentation with the JAR file.
When you add a required project to a project's classpath, the required project's Javadoc
and sources are automatically added to the project as well.
When you create a Java class library for a single JAR file, you can simply add the JAR
file to the project's classpath to make the associated Javadoc and source code available.
If your Java library contains multiple JAR files, however, you must add the library
itself to the classpath. Adding the library to the classpath also makes it easier to share
the project with other developers.
To add Javadoc for a JAR file:
1. Choose Tools > Libraries from the main menu.
2.
In the left pane of the Ant Library Manager, select the project library within which
the JAR file you want to add Javadoc documentation to is located.
Only libraries already registered with the IDE are listed in the
Ant Library Manager's Class Libraries list.
Note:
3.
If the JAR file for which you want to add Javadoc documentation has not already
been added to a registered library, create a new empty library using the New
Library button. Next, in the Classpath tab click Add JAR/Folder and specify the
location of the JAR file containing the compiled class files.
You can also associate the Javadoc with a JAR file using the
project's Project Properties window. However, doing so creates the
association only for that project. Open the Project Properties dialog
box by right-clicking the project node and choosing Properties. Select
the Libraries node in the Categories pane. Then select the JAR with
which you want to associate the Javadoc and click Edit. You can then
specify the sources to be associated.
Note:
A class library can contain multiple JAR files as well as their Javadoc
documentation and source code.
2-54 NetBeans Developing Applications with NetBeans IDE
Working with Javadoc Documentation
4.
In the Javadoc tab, click Add ZIP/Folder and specify the location of the Javadoc
files.
5.
Click OK to exit the Ant Library Manager.
2.15.2 How to Add the JDK Javadoc to the IDE
The API documentation for your Java platform can be used for reference or as a
learning tool.
To add JDK Javadoc to the IDE:
1. Choose Tools > Java Platforms from the main window.
2.
Select the platform to which you want to add Javadoc in the left panel of the
dialog box.
3.
In the Javadoc tab, click Add ZIP/Folder and specify the location of the Javadoc
files. Click Close.
You can download and install Java SE Documentation files
from the Oracle Technology Network (for example, JDK 7
documentation is available at
http://www.oracle.com/technetwork/java/javase/documentation/
java-se-7-doc-download-435117.html.)
Note:
2.15.3 How to View Javadoc Documentation
After you add a Javadoc library to the project, you can view the documentation for any
of the library's classes in the Source Editor, browse the documentation in your external
browser, and search the library using the Javadoc Index Search.
To view Javadoc documentation for any elements of code you are writing, you must
add the Javadoc library containing the documentation to the project.
To view Javadoc documentation:
■
In the Source Editor, place the pointer on the code element whose documentation
you want to display and do one of the following:
■
–
Choose Source > Show Documentation (or press Ctrl-Shift-Space) to view
Javadoc documentation for the selected element in a separate IDE window.
–
Press Alt-F1 to view Javadoc documentation in an external browser window.
–
Choose Window > Other > Javadoc to open the Javadoc page that will show
Javadoc dynamically for the code elements you are editing.
Choose Help > Javadoc Index Search (Shift-F1). The Javadoc Index Search
window opens in an editor tab and displays the results of the search for the code
element that is currently selected in the Source Editor. The HTML Viewer displays
the Javadoc for the selected element in the search results. Click the Toggle the
Display of the HTML Viewer button to hide or show the HTML viewer. You can
double-click an element in the search results to open the Javadoc documentation
for the element in a page in your browser.
2.15.4 How to Generate Javadoc Documentation
For each of your projects, you can produce a set of Javadoc HTML pages that describe
the project's classes, inner classes, interfaces, constructors, methods, and fields. The
Working with NetBeans IDE 2-55
Working with Javadoc Documentation
Javadoc is constructed from the structure of your code and the Javadoc comments
embedded in your code. You can also configure how the IDE generates Javadoc
documentation for each of your projects.
To generate Javadoc documentation for a project:
1. Select the project in the Projects window.
2.
Choose Run > Generate Javadoc for Project.
The IDE generates the Javadoc to the dist/javadoc folder in your project directory
and opens the index page in the IDE's designated web browser.
You can select multiple projects in the Projects window and generate Javadoc
documentation for them at once by choosing Run > Generate Javadoc (number of
selected projects) Projects from the main IDE's menu.
To configure how the IDE generates Javadoc documentation:
1. In the Projects window, right-click the project node and choose Properties.
2.
Expand the Build node and select Documenting in the left pane of the dialog box.
3.
Set the desired options and click OK.
In Free-form projects the Generate Javadoc command is
disabled by default. If your Ant script contains a target for generating
Javadoc documentation, you can map the target to the Generate
Javadoc command in the Project Properties dialog box's Build and
Run panel.
Note:
To create a Javadoc stub:
■
Place the cursor above a method or a class that has no Javadoc, type /**, and
press Enter.
The IDE creates a skeletal structure for a Javadoc comment filled with some
content. If you have a Javadoc window open, you will see the changes
immediately while you are typing.
2.15.5 How to Enter Javadoc Comments in Source Code
You can use editor hints to automatically generate basic Javadoc comments for code
elements in your source files. The generated comments include required tags for the
particular code element. For example, if a method takes a parameter, a @param tag is
inserted. You can also use hints to generate corrections to Javadoc comments, such as
when the comments contain incorrect tags.
You are notified of an editor hint by a light bulb icon that appears in the left margin of
the Source Editor. You can read the hint by clicking the light bulb icon or by pressing
Alt-Enter. You can generate the code suggested by the hint by clicking the hint or by
pressing Enter.
The hints for Javadoc generation are turned off by default.
To turn on hints for Javadoc comments:
1. Choose Tools > Options > Editor > Hints.
2.
On the Hints tab, select Java from the Language drop-down list.
3.
Select the Javadoc checkbox or expand it to fine-tune your choice.
2-56 NetBeans Developing Applications with NetBeans IDE
Viewing IDE Notifications
By default, the Javadoc hints work for protected elements and public elements. If you
would like to change the scope of the hints, expand the Javadoc node and select one of
the subnodes. Then choose the radio button for the scope to which you would like the
hints to apply.
For more information about Javadoc tags, see:
http://java.sun.com/javase/6/docs/technotes/tools/solaris/javadoc.html
For information on how to write Javadoc comments, see:
http://java.sun.com/products/jdk/javadoc/writingdoccomments/index.html
2.15.6 How To Analyze and Fix Javadoc Comments
To identify the places in your code that need Javadoc comments and quickly insert
these comments, you can use the Javadoc Analyzer tool available in the Java Editor.
To analyze and fix Javadoc comments:
1. Select a project, a package, or an individual file and choose Tools > Analyze
Javadoc from the main menu.
The Analyzer window displays suggestions for adding or fixing Javadoc
comments, depending on the scope of your selection.
2.
Select one or several checkboxes where you would like to fix Javadoc and click the
Fix Selected button.
3.
Click Go Over Fixed Problems and use the Up and Down arrows to actually add
your comments. This might be helpful if you selected to fix several instances at
once and now want to revisit the stubs.
2.16 Viewing IDE Notifications
The Notifications window displays a list of all notifications that occurred in the
current IDE session. Notifications indicate the change in the status of various IDE
processes, including available IDE updates, the status of builds and test results. A new
notification is indicated by a notification icon in the status bar of the IDE. The
notification icon is displayed in the status bar until you view the notification.
How to view IDE notifications:
1. Perform either of the following to view the list of IDE notifications.
2.
■
Click the Notifications icon in the status bar, if available.
■
Choose Window > IDE Tools > Notifications from the main menu.
Select a notification in the list to display details about the notification.
Working with NetBeans IDE 2-57
Viewing IDE Notifications
2-58 NetBeans Developing Applications with NetBeans IDE
3
Versioning Applications with Version Control
3
This chapter describes using popular version control packages with the NetBeans IDE.
[4]
This chapter contains the following sections:
■
About Versioning Applications with Version Control
■
Versioning Applications with Git
■
Versioning Applications with Subversion
■
Versioning Applications with Mercurial
■
Versioning Applications with CVS
■
About Local History
3.1 About Versioning Applications with Version Control
Versioning applications with version control is a method of coordinating the efforts of
multiple team members, sometimes at different locations in an organization, in a way
that avoids problems that can arise when different people may be working on the
same application. To help prevent making conflicting changes to a source file, version
control typically uses a workflow similar to this:
■
■
■
Each user updates a file before working on it, to ensure starting with the latest
changes and revisions
Each user checks out (or locks) the file to prevent other team members from
conflict
After making changes (and verifying them in a local build or other method), the
user checks in (or commits) the file to the team’s shared repository
Although these techniques help prevent conflicting changes being made to the team’s
shared files, version control systems also contain tools for resolving conflicts and for
reverting to previous versions in the case of problems with newly introduced material.
The rest of this chapter describes how each of the version control systems (Git,
Subversion, and Mercurial) apply these principles to the practice of versioning
applications, and also include information on available tools for working in a file’s
local history.
3.2 Versioning Applications with Git
Git is a free and open source, distributed version control system designed to handle
everything from small to very large projects with speed and efficiency.
Versioning Applications with Version Control 3-1
Versioning Applications with Git
The IDE's Git support enables you to perform versioning tasks directly from your
project within the IDE. You can call Git commands on both files and directories in the
Projects, Files and Favorites windows, in the IDE. The IDE also provides a graphical
Diff Viewer, enabling you to compare file revisions, as well as supporting inline diff
directly in the editor.
The advantages of a distributed revision control system like Git are:
■
Better support for distributed teams by removing a centralized bottleneck.
■
Better scalability with large numbers of concurrent users.
■
After the initial clone, faster to work with, independent of a user's network
infrastructure.
3.2.1 Git Visualization Features
The IDE provides several file status information tools that simplify the process of
working with version-controlled files, including:
■
■
Color Coding. Enables you to view the current status of version-controlled files.
Annotations. Enables you to view revision and author information for each line of
version-controlled files.
Since Git is a distributed revision control system, you typically begin by cloning an
external repository to work with. This clone is a complete copy of the repository
including the revision history. You can clone this local copy as often as you like, and
when you want to you can push your changes back to the original repository provided
you have permissions, or export your changes and send them to the owner if you do
not.
For further documentation on the Git support and Git itself, see the following
resources:
■
■
■
■
NetBeans Git Home:
http://netbeans.org/projects/versioncontrol/pages/Git_main
NetBeans Git User’s Guide:
https://netbeans.org/kb/docs/ide/git.html
Git Home:
http://git-scm.com/
Git Documentation:
http://git-scm.com/documentation
3.2.2 How to Initialize a Git Repository
The IDE enables you to initialize a Git repository from existing files that are not in
source control yet.
To initialize a Git repository:
1. In the Projects window, select an unversioned project and choose either:
2.
■
Versioning > Initialize Git Repository from the node's context menu.
■
Team > Git > Initialize Repository from the IDE's main menu.
In the Initialize a Git Repository dialog box, specify the path to the repository you
are going to store your versioned files, or click Browse and browse for the
directory required.
3-2 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Git
3.
Click OK.
A .git subfolder is created in the folder you specified in step 2 (your NetBeans
project folder by default), which is your Git repository where all the data of your
project snapshots are stored. Git starts versioning all files in the folder you
specified. You can view files being added to the repository from the Output
window (Window > Output).
■
■
All the project files are marked Added in your Working Tree.
After you initialized the Git repository, you either add files or directly commit
them to the Git repository.
3.2.3 How to Clone a Git Repository
The IDE enables you to clone an external Git Repository and to make it available
within the IDE. You effectively create a copy or clone of the entire repository to work
with in the IDE.
To clone a Git Repository:
1. Choose Team > Git > Clone from the IDE's main menu. The Clone Repository
wizard displays.
2.
In the Remote Repository panel of the wizard, specify the URL that contains the
connection protocol and the location of the Git repository, user name and
password (you can save the latter for the future if required).
3.
(Optional) Press Proxy Configuration to display the Options dialog box and set
the proxy server settings. Click OK when finished.
4.
Click Next to switch to the next step of the wizard.
5.
In the Remote Branches panel, select the repository branch(es) to be fetched to
your local repository. Click Next.
6.
In the Destination Directory panel, specify the following:
■
■
■
■
■
7.
In the Parent Directory field, the path to the directory intended for the cloned
repository on your hard drive (alternatively, click the Browse button and
navigate to the directory). The Parent Directory field is pre-filled with the path
to the default NetBeansProjects directory where all NetBeans projects are
stored.
In the Clone Name field, the name of the local folder where the original project
will be cloned to. By default Clone Name is filled out with the actual Git
repository name.
In the Checkout Branch field, selected the branch to be checked out into the
working tree.
In the Remote Name field, the name that represents the original repository
being cloned. origin is the default alias of the repository being cloned. It is a
recommended value.
Leave the Scan for NetBeans Projects after Clone checkbox selected to activate
after-scanning right after the clone finishes. (The plugin searches for NetBeans
projects in the cloned resources and offers to open the found projects.)
Click Finish.
After a Git repository is cloned, the metadata .git folder is created inside the
folder you selected in the wizard.
Versioning Applications with Version Control 3-3
Versioning Applications with Git
Select the Scan for NetBeans projects after clone option if you
intend to immediately work with the cloned sources.
Note:
If the sources contain projects, a dialog will appear prompting you to
open them in the IDE.
If the sources do not contain a project, the dialog will appear
prompting you to create a new project from the sources and then open
them in the IDE. When you create a new project for such sources,
select the appropriate project category in the Create Project wizard
and then use the Create Project with Existing Sources template in that
category.
The IDE supports the following Git URLs:
Protocol
Access Method
Example
file
Direct repository access (on local disk)
file:///path_to_repository
or
path_to_repository
http
Access using HTTP protocol
http://hostname/path_to_
repository
https
Access using HTTP protocol with SSL
encryption
https://hostname/path_to_
repository
ssh
Access using SSH protocol
ssh://hostname/path_to_repository
sftp
Access using SFTP protocol
sftp://hostname/path_to_
repository
git
Access using GIT protocol
git://hostname/path_to_repository
3.2.3.1 Cloning a Repository from GitHub using SSH protocol
To clone a repository from GitHub using the SSH protocol, proceed as follows:
You need to have a GitHub account and be a project member
in order to clone using SSH.
Note:
1.
Choose Team > Git > Clone from the main menu. The Clone Repository wizard
displays.
2.
At the Remote Repository page of the Clone Repository wizard, specify the path
to the repository required in the Repository URL field, for example,
[email protected]:tstupka/koliba.git.
3.
Verify git is specified in the Username text field.
4.
Select the Private/public key option.
5.
(Skip if using SSH-agent or Pageant for automated SSH access to the Git server.)
Complete the following steps to access the Git server using your private SSH key
and a passphrase:
1.
Specify the path to the key file, for example C:\Users\key.
3-4 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Git
The OpenSSH private key format is required. Keys generated
by PuTTYgen for Microsoft Windows must be converted to the
OpenSSH format before using them in the IDE.
Note:
2.
Enter the passphrase for the key file, for example, abcd.
3.
(Optional) Select the Save Passphrase option if required.
6.
(Applies if using SSH-agent or Pageant for automated SSH access to the Git
server.) Leave the Private Key File and Passphrase fields empty to get
authenticated access from the IDE to the Git server through correctly configured
SSH-agent or Pageant.
7.
(Optional) Click Proxy Configuration to display the Options dialog box and set
the proxy server settings. Click OK when finished.
8.
Click Next.
9.
At the Remote Branches page, select the repository branch(es) to be fetched
(downloaded) to your local repository, for example master.
10. Click Next.
11. At the Destination Directory page, specify the following:
■
In the Parent Directory field, the path to the directory intended for the cloned
repository on your hard drive (alternatively, click the Browse button and
navigate to the directory).
The Parent Directory field is pre-filled with the path to the default
NetBeansProjects directory where all NetBeans projects are stored.
■
In the Clone Name field, the name of the local folder where the original
project will be cloned to.
By default, Clone Name is filled out with the actual Git repository name.
■
■
In the Checkout Branch field, select the branch to be checked out into the
working tree.
In the Remote Name field, the name that represents the original repository
being cloned.
origin is the default alias of the repository being cloned. It is a recommended
value.
■
Leave the Scan for NetBeans Projects after Clone checkbox selected to
activate after-scanning right after the clone finishes. (The plugin searches for
NetBeans projects in the cloned resources and offers to open the found
projects.)
12. Click Finish.
After the repository is cloned, the Clone Completed message displays.
13. Choose the desired option.
3.2.4 How to Add Files to a Repository
The IDE enables you to track a new file and also to stage changes to an already tracked
file in the Git repository. You effectively add your sources into a local Git repository.
The repository files are placed under a .git directory under the project directory.
Versioning Applications with Version Control 3-5
Versioning Applications with Git
To add files to a Git Repository:
When adding files to a Git repository, the IDE composes and saves snapshots of your
project first in the Index. After you perform the commit, the IDE saves those snapshots
in the HEAD. The IDE allows you to choose between two workflows:
■
■
Explicitly add new or modified files to the Index and then commit only those that
are staged in the Index to the HEAD.
Skip adding new or modified files to the Index and commit the required files
directly to the HEAD.
To add files to the index and then commit those that are staged:
1. In the Projects window, right-click the file you want to add.
2.
In the context menu, choose Git > Add. This adds the file contents to the Index
before you commit it.
3.
In the Projects window, right-click the file you want to commit.
4.
In the Commit dialog box, select the Changes between HEAD and Index toggle
button. This displays the list of files that are already staged.
5.
Commit the file as described in Section 3.2.5, "How to Commit Sources to a Git
Repository."
To skip adding files to the Index and commit the files directly:
1. In the Projects window, right-click the file you want to commit.
2.
In the context menu, choose Git > Commit.
3.
In the Commit dialog box, select the Select the Changes between Index and
Working Tree toggle button. This displays the list of files that are not staged.
4.
Commit the file as described in Section 3.2.5, "How to Commit Sources to a Git
Repository."
3.2.5 How to Commit Sources to a Git Repository
The IDE enables you to commit files to a Git repository. The IDE executes the commit
and stores your modifications to the repository upon a successful commit.
To commit versioned files to a repository:
1. Choose Team > Commit from the IDE's main menu. The Commit dialog box
displays.
2.
Type in a commit message in the Commit Message text area. Alternatively, you can
do any of the following:
■
■
Click Recent Messages to view and select from a list of messages that you
have previously used.
Click Load Template to select a message template.
3.
Specify the Author's and Committer's names in the respective fields.
4.
Select the files to be committed in the Files to Commit section.
5.
In the Update Task section, specify and modify tasks related to the change being
committed, if required.
6.
After specifying actions for individual files, click Commit.
3-6 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Git
The IDE's status bar, located in the bottom right of the
interface, displays as the commit action takes place.
Note:
Upon a successful commit, versioning badges disappear in the
Projects, Files and Favorites windows, and the color coding of
committed files returns to black.
3.2.6 How to Revert Modifications
You can throw away local changes made to selected files in your Working Tree and
replace those files with the ones in the Index or HEAD.
To revert modifications:
1. Select the versioned project, file or folder for which you want to revert changes.
2.
Choose Team > Revert Modifications from the IDE's main menu or Git > Revert
Modifications from the selected item's context menu.
3.
In the Revert Modifications dialog box, select any of the following options:
■
Revert All Uncommitted Changes in Working Tree and Index. Deletes all
uncommitted changes and returns to the state of files in HEAD.
–
■
Revert Uncommitted Changes in Working Tree to the State in Index. Deletes
uncommitted changes in Working Tree and returns to the current state of files
in Index.
–
■
4.
Remove also New Files and Folders. Deletes new files and folders that
have not been committed to HEAD.
Remove also New Files and Folders. Deletes new files and folders that
have been created in Working Tree but have not been added to Index.
Revert only Uncommitted Changes in Index to HEAD. Deletes uncommitted
changes in Index and returns to the state of files in HEAD.
Click Revert. The IDE replaces the selected files with those you specified in the
selected option.
3.2.7 How to Reset
You can cancel changes and bring your repository back to a particular commit.
To reset:
1. Select the versioned project, file or folder.
2.
Select Team > Revert/Recover > Reset from the IDE's main menu or Git >
Revert/Recover > Reset from the selected item's context menu.
3.
In the Git Reset dialog box, specify any of the following options:
■
Revision. Specify the required revision by entering a commit ID, existing
branch, or tag name in the Revision field or click Select to view the list of
revisions maintained in the repository. The following fields display
information specific to the selected revision:
–
Commit ID. A unique identifier of the specified revision.
–
Author. A unique identifier of the specified revision.
–
Message. A message specified during the commit of the revision.
Versioning Applications with Version Control 3-7
Versioning Applications with Git
■
4.
Options. Choose any of the reset modes below:
–
Do Not Modify Index or Working Tree (--soft). Select to move HEAD to
the specified commit and leave all changes in Index and Working Tree.
–
Modify Working Tree (--mixed). Select to overwrite all changes in Index
and leave changes in Working Tree.
–
Update Index and Working Tree (--hard). Select to overwrite all changes
that are made in your Index and Working Tree.
Click Reset. The IDE discards changes in accordance with the selected option.
3.2.8 How to Create a Tag
You can create tags to refer to a particular commit. This can simplify searching for
elements in a specific commit.
To create a tag:
1. Specify the following in the Create Tag dialog box:
■
Tag Name. Specify the name of the tag being created.
■
Tag Message. Enter a comment to be included with the tag.
■
Force Update. Select to displace an existing tag with an identical name.
■
2.
3.
Revision. Type a specific revision of the selected item by entering a commit
ID, existing branch, or tag name. Alternatively, click Select to open the Select
Revision dialog box where you can view the list of revisions maintained in the
repository and choose the required one.
Review information pertinent to the specified revision in the following fields:
■
Commit ID. A unique identifier of the specified revision.
■
Author. Name of a person who committed the revision.
■
Message. A message specified during the commit of the revision.
Click Create.
The tag is added to the specified revision.
3.2.9 How to Compare File Revisions
The IDE's graphical Diff Viewer enables you to compare revisions of a file side by side
using color coding to emphasize the differences between the files being compared.
To access the Diff Viewer, select a version-controlled file or folder (for example, from
the Projects, Files or Favorites window) and choose either Git > Diff > Diff To HEAD
from the context menu or Team > Diff > Diff To HEAD from the main menu.
The following table lists the Git commands available in the toolbar of the Diff Viewer:
Icon
Name
Function
Changes between HEAD and Working
Tree
Displays a list of files that are either
already staged or only
modified/created and not staged yet.
Changes between HEAD and Index
Displays a list of files that are staged.
3-8 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Git
Icon
Name
Function
Changes between Index and Working
Tree
Displays files that have differences
between their staged and working tree
states
Go to Next Difference
Displays next difference in the file.
Go to Previous Difference
Displays previous difference in the file.
Refresh Statuses
Refreshes the status of the selected files
and folders. Files displayed in the
Versioning window can be refreshed to
reflect any changes that may have been
made externally.
Revert Modifications
Displays the Revert Modifications
dialog box.
Commit Changes
Displays the Commit dialog box.
The Diff Viewer provides the following UI components:
Blue
Indicates lines that have been changed since the earlier revision.
Green
Indicates lines that have been added since the earlier revision.
Red
Indicates lines that have been removed since the earlier revision.
The following icons allow you to make changes directly to your local working copy:
Inserts the highlighted text into your Working Tree copy.
Reverts the whole local Working Tree copy.
Removes the highlighted text from the local Working Tree copy.
3.2.10 How to Work with Branches
The IDE enables you to maintain different versions of an entire code base using
branches, which involves:
■
creating a branch
■
checking out a branch
■
merging branches
■
deleting branches
3.2.10.1 Creating a Branch
Creating a branch enables you to work on a separate version of your file system for
stabilization or experimentation purposes without disturbing the main trunk.
To create a local branch:
1. In the Projects or Files window, choose a project or folder from the repository in
which you want to create the branch.
Versioning Applications with Version Control 3-9
Versioning Applications with Git
2.
Choose Team > Branch/Tag > Create Branch from the main menu (alternatively,
right-click the versioned project or folder and choose Git > Branch/Tag > Create
Branch in the context menu). The Create Branch dialog box displays.
3.
In the Branch Name field, enter the name of the branch being created.
4.
Type a specific revision of the selected item by entering a commit ID, existing
branch, or tag name in the Revision field or press Select to view the list of revisions
maintained in the repository and choose a required one.
5.
Review the Commit ID, Author, Message fields information specific to the revision
being branched from and click Create. The branch is added to the Branches/Local
folder of the Git repository.
3.2.10.2 Checking Out
To edit files on a branch that already exists, you can check out the branch to copy the
files to your Working Tree.
To check out a revision:
1. Choose Team > Checkout > Checkout Revision from the main menu. The
Checkout Selected Revision dialog box displays.
2.
Specify the revision required by entering a commit ID, existing branch, or tag
name in the Revision field or press Select to view the list of revisions maintained
in the repository and specify a required one.
Specify the revision required by entering a commit ID, existing
branch, or tag name in the Revision field or press Select to view the
list of revisions maintained in the repository and specify a required
one.
Note:
3.
Review the Commit ID, Author, Message fields information specific to the revision
being checked out.
4.
To create a new branch out of the checked out revision, choose the Checkout as
New Branch option and enter the name in the Branch Name field.
5.
Press Checkout to check out the revision. Files in the Working Tree and in the
Index are updated to match the version in the specified revision.
To check out files:
1. Choose Team > Checkout > Checkout Files from the main menu. The Checkout
Selected Paths dialog box displays.
2.
(Optional) Select the Update Index with Entries from the Selected Revision
option to update the Index with the state in the selected revision prior to the
checkout itself.
3.
(Enabled if the Update Index with Entries from the Selected Revision option is
selected.) Specify the required revision by clicking Select.
4.
Review the Commit ID, Author, Message fields information specific to the
revision being checked out.
5.
Click Checkout to complete checking out the files.
3-10 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Git
3.2.10.3 Merging
Merging enables you to port modifications from a repository revision to the Working
Tree.
To merge:
1. Choose Team > Branch/Tag > Merge Revision from the main menu. The Merge
Revision dialog box displays.
2.
Specify the revision required by entering a commit ID, existing branch, or tag
name in the Revision field or press Select to view the list of revisions maintained
in the repository and specify a required one.
3.
Review the Commit ID, Author, Message fields information specific to the revision
being merged.
4.
Click Merge. A three-way merge between the current branch, your Working Tree
contents, and the specified branch is done.
After merging, you must still commit the changes in order for
them to be added to the HEAD.
Note:
3.2.10.4 Deleting
You can delete an unnecessary local branch.
To delete a branch:
1. Select Team > Repository Browser from the main menu.
2.
In the Git Repository Browser, select the branch to be deleted.
The branch must be inactive, that is, not currently checked out
into the Working Tree.
Note:
3.
Right-click the selected branch and select Delete Branch from the popup menu.
4.
In the Delete Branch dialog box, click OK to confirm the branch deletion. The
branch is removed from the local repository as well as the Git Repository Browser.
3.2.11 How to Work with Remote Repositories
The IDE enables you to work with remote repositories hosted on the Internet or
network, which involves:
■
fetching
■
pushing
■
pulling
3.2.11.1 Fetching
Fetching gets the changes from the original remote repository that you do not have
yet. It never changes any of your local branches. Fetching gets all the branches from
remote repositories, which you can merge into your branch or just inspect at any time.
To fetch updates from a remote repository:
1. Select Team > Remote > Fetch.
Versioning Applications with Version Control
3-11
Versioning Applications with Git
2.
In the first panel of the wizard, select either the Configured repository (to use the
path to the repository configured earlier) or Specify Git Repository Location
option (to define the path to a remote repository that has not been accessed yet, its
name, login, password, private key file, passphrase, and proxy configuration if
required). Click Next.
3.
In the second panel of the wizard, select the branches to fetch changes from. Click
Finish. A local copy of a remote branch is created. The selected branches are
updated in the Branches > Remote directory in the Git Repository Browser. Next
the fetched updates can be merged into a local branch.
3.2.11.2 Pulling
When pulling some updates from a remote Git repository, the changes are fetched
from it and merged into the current HEAD of your local repository.
To pull from a remote repository:
1. Select Team > Remote > Pull.
2.
At the Remote Repository page of the wizard, select either the Configured
repository (to use the path to the repository configured earlier) or Specify Git
Repository Location option (to define the path to a remote repository that has not
been accessed yet, its name, login, password, private key file, and passphrase, if
required) and click Next.
3.
At the Remote Branches page of the wizard, select the branches from which you
wish to pull changes and then click Finish. Your local repository is synchronized
with the origin repository.
3.2.11.3 Pushing
Pushing enables you to contribute changes from your local Git repository into a public
Git repository.
To push to a remote repository:
1. Select Team > Remote > Push.
2.
In the first panel of the wizard, select either the Configured repository (to use the
path to the repository configured earlier) or Specify Git Repository Location
option (to define the path to a remote repository that has not been accessed yet, its
name, login, password, private key file, and passphrase, if required) and click
Next.
3.
In the second panel of the wizard, select the branch(es) to push your edits to. Click
Next.
4.
In the third panel of the wizard, select the branch(es) to be updated in the Remotes
directory of your local repository and click Finish. The specified remote repository
branch is updated with the latest state of your local branch.
3.2.12 How to Set Git Global Options
Git allows you to set global options, which affect output window tabs, new files
during a commit, adding a signed-off-by line to the commit log message, and ignoring
non-sharable folders.
To set Git global options:
1. Select Tools > Options. The IDE's Options window opens.
3-12 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Git
2.
Select the Team > Versioning tabs, then select Git under Versioning Systems.
The following Git Global Options properties can be set:
Automatically open Output
window tabs
If selected, the Output window displays when
versioning operations that involve interaction
with the Git repository take place (for example,
clone, fetch, pull, push).
Exclude new files from commit
automatically
Select to omit new files during the commit.
Add Signed-off-by line by the
committer at the end of the commit
log message
Select to add a committer's name as a signer in a
log message during the commit.
Permanently ignore non-sharable
folders
When selected, the IDE ignores files and folders
not meant to commit (for example, build and
dist for J2SE projects) and adds paths to them to
the .gitignore file.
3.2.13 How to Shelve Changes (Git)
Shelving allows to make changes to a project without committing and pushing them to
the Git versioning system.
To temporarily set aside some not yet committed changes in a working directory
as a patch file:
1. Select a versioned project, file, or folder.
2.
Select Team > Shelve > Shelve Changes from the main menu.
3.
Specify the name for a patch to be shelved in the Patch Name field.
4.
Specify the options for the patch in the Options pane of the dialog box.
5.
Click Shelve.
The IDE stashes away the not yet committed changes contained in the selected
project, file, or folder into a patch file and reverts the modified files in the working
copy (the working copy gets clear of the local changes). The previously modified
files become up to date.
3.2.14 How to Rebase (Git)
Rebasing applies changes from one line of work onto another in the order they were
introduced.
To forward-port local commits to another destination commit:
1. Select a versioned project, file or folder.
2.
Select Team > Branch/Tag > Rebase from the main menu.
Alternatively, right-click the selected item and select Git > Branch/Tag > Rebase
from the context menu.
3.
Set the required properties in the Select Commits to Rebase dialog.
4.
Click Rebase to complete rebasing according to the defined settings.
Versioning Applications with Version Control
3-13
Versioning Applications with Subversion
3.3 Versioning Applications with Subversion
Subversion is a type of version control system that aids developer groups working
with shared source files in common repositories by managing file revision history
information.
The IDE's Subversion support enables you to manage changes to version-controlled
files as you work. In the IDE, you can call Subversion commands on both files and
directories in the Projects, Files, Versioning, and Favorites windows. The IDE also
provides a graphical Diff Viewer, enabling you to compare file revisions, as well as a
History Viewer, allowing you to search a file or folder's history for versions based on
specific criteria.
The IDE's Subversion support allows you to:
■
■
Rename documents in your repository and keep the whole history of the
document's revisions.
Treat commits as whole entities. If you attempt to commit changes to several files
and the commit fails, no files are changed in the repository
3.3.1 Subversion Visualization Features
The IDE provides several file status information tools that simplify the process of
working with version-controlled files, including:
■
■
Color Coding. Enables you to view the current status of version-controlled files.
Annotations. Enables you to view revision and author information for each line of
version-controlled files.
3.3.2 Working with Subversion
The following table outlines the basic workflow when working with Subversion in the
IDE.
Task
Details
Set Up Subversion
See Section 3.3.5, "How to Set Up Subversion."
Synchronize local
files with repository
Check out files from a repository. See Section 3.3.6, "How to Check Out
Files From a Remote Repository (Subversion)."
Import your project into a Subversion repository. See Section 3.3.7,
"How to Place Projects Under Version Control (Subversion)."
Edit Sources
Make changes to local copies of versioned files.
Diff file revisions between repository versions and your local working
copies. See Section 3.3.9, "How to Compare File Revisions in
Subversion."
Merge changes in repository revisions with the local copies. See
Section 3.3.14, "How to Merge File Revisions in Subversion."
Update Local
Versions
Update local versions of files with changes committed to the
Subversion repository. See Section 3.3.8, "How To Update Files in a
Local Working Directory (Subversion)."
Resolve Conflicts
Resolve conflicts between local versions of files with changes
committed to Subversion repository revisions. See Section 3.3.15,
"Resolving Merge Conflicts in Subversion."
Commit Sources
Commit local changes to files into the repository. See Section 3.3.10,
"How to Commit Local Changes to a Remote Repository (Subversion)."
3-14 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Subversion
3.3.3 How to View File Status Information
The IDE's Subversion support enables you to view and manage the evolution of
changes in version-controlled files.
You can view version status information in many of the IDE's windows, including the
Versioning, Projects, Files, and Favorites windows. The Versioning window, however,
represents the primary place within which to manage version-controlled files by
displaying a list of all of the new, modified, and removed files in the currently selected
project or directory.
To open the Versioning window, select either:
■
Subversion > Show Changes from the context menu of a version-controlled file or
folder from the Projects, Files, or Favorites window.
■
Team > (Subversion >) Show Changes from the main menu.
■
Window > Versioning > Subversion from the main menu.
The IDE's Subversion support provides file status information in the following ways:
Task
Details
Status Labels
Textual indication of file status in the Versioning, Projects, Files, and
Favorites windows. To display status labels, select View > Show
Versioning Labels from the main menu.
Status Color
Textual indication of file status in the Versioning, Projects, Files, and
Favorites windows. To display status labels, select View > Show
Versioning Labels from the main menu.
Status Badges
Graphical indication of the status of files contained within your project,
folder, and package nodes. Displayed in the Projects, Files, and
Favorites windows.
Revision Annotations Displays commit message, author, date, and revision number
information in the left margin of files open in the Source Editor. To
display annotations, select a versioned file and select Show
Annotations (or Subversion > Show Annotations) from its context
menu. Alternatively, select Versioning, > Show Annotations from the
main menu.
The IDE displays version-controlled files using the following color coding and font
styles:
Color Coding
Description
Indicates that the file is a new local file that does not yet exist in the
repository.
Indicates that the file has been modified locally.
Indicates that the file contains conflicts. You must employ the Resolve
Conflicts command (Subversion > Resolve Conflicts) for such files.
Indicates that the file is ignored by Subversion and will not be included
when calling versioning commands. In the Versioning window, grey
text signifies deleted files.
Versioning Applications with Version Control
3-15
Versioning Applications with Subversion
Color Coding
Description
Indicates that the file is excluded when calling the Commit command.
All other Subversion commands, however, work as usual. Note that
files displayed in the strike-through style only appear in the Versioning
window and Commit dialog. They will not appear in Diff panes, nor
will their parent folders (or packages) display badges if they are
modified.
Current Subversion file status is indicated by adding the following badges to project,
package and directory icons:
Badge
Description
A blue badge on a folder or package node marks folders or packages
that contain locally modified or new files. In the case of packages, this
badge applies only to the package itself and not its subpackages. For
folders, the badge indicates local modifications in that folder or any of
its subfolders.
A red badge on a folder or package node marks folders or packages
that contain files for which the repository copy of the file contains
changes which conflict with the local version. In case of packages, this
badge applies only to the package itself and not its subpackages. For
folders, the badge indicates local modifications in that folder or any of
its subfolders.
Note: Parent folders (or packages) of files excluded from commits and displayed in the
strike-through style will not display badges if they are modified.
3.3.4 How to Work with Version Histories
Searching the histories of files can be helpful when you need to find specific commits,
for example when backporting bugs. The IDE's Search Histories window enables you
to view a summary of a file's evolution over time by revision number.
You can view file histories in the IDE's Search History window. To do so, select a
versioned file (for example, from the Projects, Files, or Favorites window) and select
either Subversion > Search History from the context menu or Team > (Subversion >)
Search History from the main menu. Alternatively, in the Versioning window you can
select Search History from a file's context menu.
3.3.4.1 Searching for Specific Revisions
Using the Search History window, you can search a file or folder's history for versions
based on several criteria. These are:
Criteria
Description
Message
The description submitted with the commit.
Username
The author of the commit
From
The tag, revision number, or date from which the commit was made.
To
The tag, revision number, or date before which the commit was made.
To search for a specific revision:
1. Select the file or folder for which you want to find a specific revision.
3-16 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Subversion
2.
Select Team > (Subversion >) Search History from the main menu. Alternatively,
you can select Subversion > Search History from the selected file's context menu.
The IDE displays the file's revision history in the Search History window.
3.
Enter search criteria information in the Message, Username, From, and To fields.
You can also use the Browse buttons to designate any tag, branch, revision, or date
you want to limit your search to.
4.
Click Search. The IDE displays the file's revision history in the Search History
window.
If you want to perform a diff, or revert (that is, 'rollback')
changes from a specific commit, you can do so from the displayed
revision history using the Diff and Revert links to the right of each
revision.
Note:
3.3.4.2 Comparing Revisions in the Search History Window
You can compare a file with previous versions from within the Search Histories
window using the Diff button.
To view revision differences in the Search History window:
1. Click the Diff button in the toolbar.
2.
Select the revision against which you want to compare your local working copy.
The IDE displays a diff of the file's revisions within the Search History window.
Note that you can navigate between the differences using the Previous Difference (
) and Next Difference ( ) buttons.
3.3.5 How to Set Up Subversion
Before you can take advantage of the IDE's Subversion support, you need to have
Subversion client software installed on your system. The IDE supports Subversion
client versions 1.3.x and higher. The IDE's Subversion support works by interacting
with the Subversion client to carry out the commands.
You can download Subversion as a binary package from the following link:
http://www.collab.net/downloads/subversion
Though the Subversion site does not guarantee the quality of the binary downloads,
you might find them easier to work with. For example, the executable binary for
Microsoft Windows systems sets up the environment variable that enables your
system and the IDE to recognize the Subversion installation. If you do not use an
installer, follow the Subversion installation instructions closely to make sure that you
set up everything correctly on your system.
If you are using Mac OS X, you may need to manually register the Subversion
executable home folder in the IDE. See Specifying the Path to the Subversion
Executable in the Guided Tour of Subversion for more details:
http://netbeans.org/kb/docs/ide/subversion.html
After the Subversion client is set up, you can run Subversion commands from the
IDE's Team > Subversion menu. To check out files from a Subversion repository, select
Team > (Subversion >) Checkout. In the process of checking out, the IDE
automatically registers the working directory where your local copies of
version-controlled files and their status information will be stored.
Versioning Applications with Version Control
3-17
Versioning Applications with Subversion
If you have already checked out files from a Subversion repository (using Subversion
client 1.3.x or higher), the IDE automatically recognizes the files as versioned files if
those files are part of an open IDE project or if they are added to the Favorites window.
You can call Subversion commands on such files from the Subversion menu or by
right-clicking a file or folder and choosing from the Subversion submenu.
3.3.6 How to Check Out Files From a Remote Repository (Subversion)
In order to work on shared files located in a remote repository, you need to copy the
necessary files and directories to your local working directory. This is done by
checking out the files from the repository.
To check out files from a remote repository:
1. Select Team > (Subversion >) Checkout from the main menu. The Subversion
Checkout wizard opens.
2.
In the first panel of the wizard, enter a URL that contains the connection protocol
and the location of the repository.
■
■
■
If you enter a protocol such as http://, https://, or svn://, User and
Password fields appear in the wizard. Fill in these fields as necessary.
If you enter svn+ssh://, you must supply the command to establish the
external tunnel.
If you are using a proxy, click the Proxy Configuration button and enter the
required information.
Click Next.
3.
In the Folders to Checkout panel of the wizard, specify the folder that you want to
check out in the Repository Folder field or click Browse to choose from a list of all
folders in the repository.
■
To check out only the contents of the folder you are specifying (rather than the
folder itself), select the Skip "<selected_folder>" and check out only its
content option.
4.
If you need to specify a revision number, enter the information in the Repository
Revision field or click the Browse button to view and select from a list of all
revisions in the repository.
5.
Specify the local folder into which you want to check out the selected folders.
Alternatively, click the Browse button to navigate to the desired directory on your
system.
6.
Click Finish to check out the files. The IDE initiates the checkout action and the
IDE's status bar indicates the progress of the files downloading from the
repository to your local working directory. You can also view files being checked
out from the Output window (Ctrl+4).
Select the Scan for NetBeans projects after Checkout option if
you intend to immediately work with the checked-out sources. If the
sources contain projects, a dialog will appear prompting you to open
them in the IDE. If the sources do not contain a project, the dialog will
appear prompting you to create a new project from the sources and
then open them in the IDE. When you create a new project for such
sources, select the appropriate project category and then use the “With
Existing Sources” template in that category.
Note:
3-18 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Subversion
3.3.7 How to Place Projects Under Version Control (Subversion)
The IDE enables you to place any project you are working on under version control.
You effectively import your sources into the remote repository. To do so, you need to
be able to access a Subversion repository for which you have write privileges.
To place an IDE project under version control:
1. In the Projects window, select an unversioned project and then select either:
■
■
Versioning > Import into Subversion Repository from the node's context
menu.
Team > Subversion > Import into Repository from the IDE's main menu.
The Subversion Import wizard opens.
2.
In the Subversion Repository page of the Import wizard, specify the protocol and
location of the Subversion repository as defined by the Subversion URL.
Depending on your selection, you may require to specify further settings, such as
repository username and password, or, in the case of svn+ssh://, you must
specify the tunnel command to establish the external tunnel. Click Next.
3.
In the Repository Folder panel, specify the repository folder in which you want to
place the project in the repository. A folder containing the name of your project is
suggested for you in the Repository Folder text field by default.
4.
In the text area beneath Specify the Message, enter a description of the project you
are importing into the repository.
5.
Click Finish to initiate the import, or optionally, click Next to continue to a third
panel that enables you to preview all files that are prepared for import. From this
panel, you can choose to exclude individual files from import, or identify the
MIME types of files before importing. Upon clicking Finish, the IDE uploads the
project files to the repository and the Output window opens to display the
progress.
The IDE supports the following Subversion protocol types:
Protocol
Access Method
Example
file
Direct repository access (on local disk)
file:///repository_path[@REV]
http
Access using WebDAV protocol to a
Subversion-aware server
http://hostname/repository_
path[@REV]
https
Access using HTTP protocol with SSL
encryption
https://hostname/repository_
path[@REV]
svn
Access using custom protocol to an
svnserve server
svn://hostname/repository_path[@REV]
svn+ssh
Access using SVN protocol through an svn+ssh://hostname/repository_
external SSH tunnel
path[@REV]
3.3.8 How To Update Files in a Local Working Directory (Subversion)
Updating files or folders enables you to incorporate any changes that other developers
have committed to the repository since your previous checkout or update.
To update a local version of a file or folder:
■
Select a versioned file (for example, in the Projects, Files, or Favorites window)
and select Subversion > Update. Alternatively, select a file in the Versioning
Versioning Applications with Version Control
3-19
Versioning Applications with Subversion
window and select Update from the context menu. The IDE incorporates any
changes existing in the repository version of the file.
It is recommended that you perform an update on all files
prior to committing them to the repository. Doing so allows you to
become aware of any conflicts prior to performing the commit.
Note:
3.3.8.1 Updating Projects with Dependencies
If you are working on a project for which there are other required projects, you can
update both the main project and all dependent projects using the IDE's Update with
Dependencies command.
To update an entire project and all dependent projects:
1. Right-click the project node in the Projects window.
2.
Select Subversion > Update With Dependencies. The IDE incorporates any
changes existing in the repository version of all of the projects with your local
working copy.
3.3.9 How to Compare File Revisions in Subversion
The Diff command compares different revisions of a file and displays the differences
found graphically.
3.3.9.1 Comparing File Revisions Graphically
The IDE's graphical Diff Viewer enables you to compare different versions of a file side
by side using color coding to emphasize the differences between the files being
compared.
The previous ( ) and next ( ) difference buttons in the toolbar enable you to
navigate among the differences in the file. You can also refresh the status and update
files from within the Diff Viewer using the Refresh Diff ( ) and Update ( ) buttons.
When you are finished comparing the files, you can commit your changes using the
Diff Viewer's Commit button ( ).
To generate a graphical diff comparing a repository revision to your working
copy:
■
Right-click a versioned file node in the Projects, Files, or Versioning window and
select Diff (or Subversion > Diff). The IDE displays the results in the Diff Viewer
in a new tab of the main window.
Note: If you want to perform a diff on all files contained in a folder,
select a folder and select Subversion > Diff from the context menu.
All files that contain differences between your local version and the
repository version will be listed in the upper pane of the Diff Viewer.
You can then view individual diffs on files by clicking a file from the
list.
To make changes to a file while comparing it in the Diff Viewer:
1. Navigate through differences between the two versions using the previous
difference and next difference arrow icons.
2.
Click any of the displayed icons to perform immediate changes to your local copy.
3-20 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Subversion
Your local copy appears in the right pane of the Diff Viewer.
You can also make changes to your local copy by typing directly into it
in the Diff Viewer.
Note:
Any changes made in the Diff Viewer are automatically saved as they
occur.
The following icons enable you to make changes directly within the Diff Viewer:
■
■
■
Replace. Inserts the highlighted text from the previous revision into the current
revision
Move All. Reverts the file's current version to the state of the selected previous
version.
Remove. Removes the highlighted text from the current version so that it mirrors
the previous version.
3.3.10 How to Commit Local Changes to a Remote Repository (Subversion)
Once your working copies of version-controlled files have been edited, you can then
place changes into the repository using the Subversion Commit action.
Subversion versioned files and folders must be recognized by
the IDE as such in order to call Subversion actions on them. To do so,
you must first check out sources from a Subversion repository.
Note:
To commit changes in local files to a remote repository:
1. Select a version-controlled file or folder (for example, from the Projects, Files, or
Favorites window) and select Subversion > Commit from the context menu. The
Commit Dialog opens, listing all files that contain local changes. If the files you
want to commit do not already exist in the repository, the commit action will add
them.
2.
Enter a commit message in the Commit Message text area, indicating the purpose
of the commit.
■
3.
Click the Recent Messages icon in the upper right corner of the dialog to view
recent commit messages.
Click Commit. The IDE executes the commit and sends your local changes to the
repository.
Note: It is recommended that you perform an update (Subversion >
Update) on any files prior to committing them to the repository. By
doing so, you will be able to identify and handle any conflicts arising
from repository changes prior to performing your commit.
When working in the Commit dialog, you can exclude individual files from a commit.
To do so, click on the Commit Action column for the specific file and select Exclude
from Commit. The file name responds by displaying in strike-through text.
Versioning Applications with Version Control
3-21
Versioning Applications with Subversion
3.3.10.1 Ignoring Files
If your local working directory includes files or directories that you do not want to
place under version control, you can set the IDE to ignore them permanently using the
Ignore command.
You cannot employ the Ignore command on files that already
exist in the repository.
Note:
To ignore local files in your working directory:
1. Select the file or directory you wish to ignore from the Projects, Files, Favorites, or
Versioning window.
2.
Select Ignore (or Subversion > Ignore) from the context menu of selected file or
directory. The IDE ignores the file or directory whenever Subversion commands
are called on it or on the directory within which it is stored.
To change the status of ignored files so that they can be acted
upon in Subversion, select the specific file and select Subversion >
Unignore.
Note:
3.3.11 How to Work with Branches in Subversion
The IDE's Subversion support enables you to:
■
checkout branches from a remote repository.
■
create branches in the repository you are working from.
■
switch to a branch in the repository you are working from.
For more information on working with branches, see the Subversion documentation
at:
http://svnbook.red-bean.com/
3.3.11.1 Checking Out Branches
If you need to edit files on a branch folder that already exists, you can check out the
branch to copy the files to a local working directory. You must however create a new
local working directory within which to checkout the branch.
To checkout a branch to your local working directory:
1. Select Team > (Subversion >) Checkout from the main menu. The Subversion
Checkout wizard opens.
2.
In the first panel of the wizard, enter a URL that contains the connection protocol
and location to the repository. Depending on your protocol selection and
connection requirements, enter any required parameters, such as username,
password, proxy configuration, etc. Click Next.
3.
In the Folders to Checkout panel of the wizard, specify the folder that represents
the branch you want to check out in the Repository Folder field. You can click
Browse to choose from a list of all folders in the repository. Specify the revision
number if you want to work from a specific revision.
3-22 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Subversion
■
To check out only the contents of the folder you are specifying (that is, not the
folder itself), select the Skip "<selected_folder>" and check out only its
content option.
4.
Specify the local working directory into which you want to checkout the selected
branch folder. Alternatively, click the Browse button to navigate to the desired
directory on your system.
5.
Click Finish to check out the branch folder. The IDE initiates the checkout action
and the IDE's status bar indicates the progress of the files downloading from the
repository to your local working directory. You can also view files being checked
out from the Output window (Ctrl+4).
3.3.11.2 Creating Branches
If you want to work on a separate version of your file system for stabilization or
experimentation purposes, you can do so by creating a branch. To create a branch in
Subversion, you are effectively copying a version-controlled project or folder and
adding it to a new location within the repository. The IDE's Subversion support
enables you to select a source from either your local working copy, or browse to a
location in the repository you are working from. You can create branches in the IDE by
choosing Subversion > Copy To from a versioned file or folder's context menu.
To create a branch:
1. Select the versioned project or folder (for example, in the Projects, Files, or
Favorites window) that you want to be the root of your branch and select
Subversion > Copy To. The Subversion Copy dialog box opens.
2.
Under Source, select Local Folder if you want to create a branch from your local
working copy, otherwise select Remote Folder to specify the version maintained in
the repository.
■
■
You can specify a specific revision of the selected item by entering a revision
number in the Revision text box. Clicking the Search button adjacent to the
Revision text box allows you to view revisions maintained in the repository.
Click the Skip selected Folder and copy only its Contents option if you want
to avoid including the selected folder when creating a copy.
3.
Under Destination, select the target location for the new branch copy. In
Repository Location, type in a path relative to the repository, otherwise click the
Browse button to open a new dialog that aids in browsing the repository folders.
4.
Enter a description for the new branch folder in the Copy Description text area. If
you want to switch to the branch after creating it, select the Switch to Copy
checkbox.
5.
Click Copy. The IDE creates the branch by copying the folder contents to the
specified location in the repository.
3.3.11.3 Switching to a Branch
If you want to switch your local working copy to point to a branch or other location in
the repository, you can do so using the Subversion Switch to command.
To switch to a branch or other location in the repository:
1. Select a versioned file or folder (for example, from the Projects, Files, or Favorites
window) and select either Subversion > Switch to Copy from the context menu or
Versioning Applications with Version Control
3-23
Versioning Applications with Subversion
Team > (Subversion >) Switch to from the IDE's main menu. The Subversion
Switch dialog box opens.
2.
For Repository Folder, enter the branch folder you want to switch to, or click
Browse to view a list of all locations in the repository.
■
3.
If you need to specify a previous revision, enter the revision number for the
selected location. Leave blank if you require the most recent revision. To
display a log of all revisions for the selected location, you can click the Search
button.
Click Switch. The IDE updates your working copy to reflect the content
maintained by the newly selected branch location in the repository. Note that any
differences arising between your local working copy and the location that you are
switching to will be overwritten by the new location.
3.3.12 How to Revert Modifications (Subversion)
Occasionally it may be desirable or necessary to revert changes made to files in your
local working copy. You may need to either revert changes made locally, or retrieve
revisions from the repository, and undo any changes to files caused by these revisions.
The IDE enables you to do this using the Revert Modifications command.
To revert modifications:
1. Select the versioned file for which you want to revert changes (for example, from
the Projects, Files, Favorites or Versioning window) and select Revert
Modifications (or Subversion > Revert Modifications). The Revert Modifications
dialog box opens, enabling you to specify criteria.
If you have created files or folders since the point to which you are reverting, you
can delete them by selecting the Remove Newly Added Files and Folders option.
2.
In the Revert Modifications dialog box, select one of three options:
■
■
■
3.
Revert Local Changes. Reverts any changes made in your local working copy
to the previously committed or updated version.
Revert Modifications from Single Commit. Reverts the local working copy to
the repository revision made prior to the previous commit. (Specify a revision
number in the Revision text field.)
Revert Modifications from Previous Commits. Reverts the local working
copy to a specified revision from the repository. (Specify starting and ending
revision numbers in the corresponding text fields.)
Click Revert. The IDE reverts any changes in the local file to a state that
corresponds with the repository version, according to the specified parameters.
3.3.13 How to Recover Deleted Files (Subversion)
When working with version-controlled sources, you may sometimes find it useful to
be able to recover locally deleted files from the repository. The IDE's version control
support enables you to recover versioned files by performing a revert delete action on
files maintained in your local working copy.
To revert deletes made to files in your local working copy:
1. Right-click the project or folder that previously contained the deleted files (for
example, from the Projects, Files, or Favorites window) and select Subversion >
Show Changes from the context menu. The Versioning window opens in the
3-24 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Subversion
bottom panel of the IDE displaying file changes. The file names of recently deleted
files display in grey text with status listed as Locally Deleted.
2.
Right-click the file you want to recover and select Revert Delete.
3.
In the Confirm Overwrite dialog that displays, click Yes to enable the IDE to
recover the file from its local history repository. The file disappears from the
Versioning window and is relisted in the project directory within your local
working copy.
3.3.14 How to Merge File Revisions in Subversion
The Merge command is useful for porting changes from a specific repository revision
to your local working copy of a file or folder. You can also port the changes made
within a given range of revisions to your local working copy.
To port changes from a revision or range of revisions to your local working
copy:
1. In the Projects, Files, or Favorites window, right-click the files or folders on which
you want to perform the merge operation and select Subversion > Merge
Changes.
2.
In the dialog that appears, fill in the following fields:
■
■
■
■
3.
Merge From. Select one of the following types of merge:
–
One Repository Folder. Port changes from one repository folder.
–
Two Repository Folders. Port changes from two repository folders.
–
One Repository Folder Since Its Origin. Port changes that have occurred
between the time of the folder's creation and the revision number that you
specify in the Ending Revision Field.
Repository Folder. The folder from which you want to port changes. (If you
select Two Repository Folders in the Merge From field, this field is replaced by
First Repository Folder and Second Repository Folder fields.)
Starting Revision. If merging from a single revision, enter the revision
number. If merging changes that occurred within a range of revisions, enter
the starting point of that range.
Ending Revision. If merging changes that occurred within a range of
revisions, enter the ending point of that range.
Click Merge. The IDE incorporates any differences found in the selected revision
to the local copy of the file. If merge conflicts occur, the file's status is updated to
Merge Conflict to indicate this.
After merging file changes to your local working directory,
you must still commit changes using the Commit command in order
for them to be added to the repository.
Note:
3.3.15 Resolving Merge Conflicts in Subversion
When merge conflicts occur, a Merge Conflict badge ( ) appears on the parent folder
(or package) of file. Within the file itself, each conflict is marked with arrows followed
by the lines from the two revisions that caused the conflict.
Versioning Applications with Version Control
3-25
Versioning Applications with Subversion
Merge conflicts must be resolved prior to checking your local
file into the repository.
Note:
To resolve merge conflicts graphically with the Merge Conflicts Resolver:
1. In the Projects, Files, Favorites, or Versioning window, select the file whose status
indicates that there is a conflict and select Resolve Conflicts from the menu. The
Merge Conflicts Resolver displays with merge conflicts highlighted in red.
2.
Use the Next ( ) and Previous ( ) difference buttons in the upper-left corner to
navigate to each conflict in the file.
3.
For each conflict, click Accept above the pane containing the text that you wish to
accept. Once you have chosen the correct text, it is highlighted in green and
displayed in the Merge Result pane. The text you did not choose is highlighted in
blue.
4.
If neither pane contains the text you want, exit the Merge Conflict Resolver and
edit your source file manually. When you are done making changes, right-click the
file and select Resolve Conflicts (or Subversion > Resolve Conflicts) from the
context menu. Then repeat the procedure, beginning with Step 1.
5.
After resolving each conflict, click OK to exit the Merge Conflict Resolver. The IDE
updates your local working copy with the desired changes.
Once you have resolved each merge conflict, you still need to
commit the file to add your changes to the repository copy.
Note:
3.3.16 How to Create and Apply a Patch (Subversion)
Patch files enable software developers who are not sharing a common repository to
distribute and integrate changes that have been made to the code. The IDE enables you
to create and apply patches that update copies of source files so that you do not have
to incorporate the changes manually.
To create a patch file:
1. Select a versioned file (for example, in the Projects, Files, or Favorites window) for
which you want to create a patch.
2.
Select Team > (Subversion >) Export Diff Patch from the main menu. The Export
Diff Patch dialog opens.
3.
Select one of the following:
■
■
4.
Save to File. When selected, enter a name for the patch file and specify the
location where you want to save the patch.
Attach to Task. When selected, select the task repository and specify a task ID
and description. The patch file is added as an attachment to the specified task.
Click OK. A patch file is created containing the differences between the source file
versions.
the Export Diff Patch command is only available on files and
folders which contain local or remote changes that have not already
been merged.
Note:
3-26 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Mercurial
To apply a patch to a local file or folder:
1. Select a versioned file or folder (for example, in the Projects, Files, or Favorites
window) on which you want to apply the patch.
2.
Select Team > (Subversion >) Apply Diff Patch from the main menu. The Apply
Diff Patch dialog displays.
3.
In the dialog, type the path or navigate to the patch file you want to apply.
4.
Click Patch. The patch is applied to the selected file and a dialog opens,
confirming that the patch was applied successfully. Click Yes to view changes in
the IDE's Diff Viewer.
Note: Because patches on folders use relative paths to the files within
them, folder patches must be applied on the same folder node that the
patch was created on to ensure that the patch is applied properly.
If you are uncertain to which file or directory the patch should be
applied, you can find the context information in the patch file itself.
Patch files generated by the IDE contain the context in which the
patch was originally created in the first few lines of the file.
3.3.17 How to Shelve Changes (Subversion)
Shelving allows to make changes to a project without committing them to Subversion.
To temporarily set aside some not yet committed changes in a working directory
as a patch file:
1. Select a versioned project, file, or folder.
2.
Select Team > Shelve > Shelve Changes from the main menu.
3.
Specify the name for a patch to be shelved in the Patch Name field.
4.
Click Shelve.
The IDE stashes away the not yet committed changes contained in the selected
project, file, or folder into a patch file and reverts the modified files in the working
copy (the working copy gets clear of the local changes). The previously modified
files become up to date.
3.4 Versioning Applications with Mercurial
Mercurial is a fast, lightweight Source Control Management system designed for
efficient handling of very large distributed projects. Unlike Subversion, Mercurial
works with distributed repositories which are commonly used in many open source
projects today and support distributed development without any centralized control.
The IDE's Mercurial Plugin support enables you to manage changes to
version-controlled files as you work. In the IDE, you can call Mercurial commands on
both files and directories in the Projects, Files and Favorites windows. The IDE also
provides a graphical Diff Viewer, enabling you to compare file revisions, as well as
supporting inline diff directly in the editor.
The advantages of a distributed revision control system like Mercurial are:
■
Better support for distributed teams by removing a centralized bottleneck
■
Better scalability with large numbers of concurrent users
Versioning Applications with Version Control
3-27
Versioning Applications with Mercurial
■
After the initial clone, faster to work with, independent of a user's network
infrastructure
3.4.1 About Mercurial Visualization Features
The IDE provides several file status information tools that simplify the process of
working with version-controlled files, including:
■
■
Color Coding. Enables you to view the current status of version-controlled files.
Annotations. Enables you to view revision and author information for each line of
version-controlled files.
The IDE's Mercurial support is similar in style to the IDE's Subversion support. The
main difference is as Mercurial is a distributed revision control system, you typically
begin by cloning an external repository to work with. This clone is a complete copy of
the repository including the revision history. You can clone this local copy as often as
you like, and when you want to you can push your changes back to the original
repository provided you have permissions, or export your changes and send them to
the owner if you do not.
For further documentation on the Mercurial Plugin support and Mercurial itself, see
the following resources:
NetBeans Mercurial Home: http://wiki.netbeans.org/MercurialVersionControl
Mercurial Home: http://mercurial.selenic.com/wiki/
Understanding Mercurial:
http://mercurial.selenic.com/wiki/UnderstandingMercurial
Mercurial Man Pages:
http://www.selenic.com/mercurial/wiki/index.cgi/ManPages
3.4.2 How to View File Status Information in Mercurial
The IDE's Mercurial support enables you to view and manage the evolution of changes
in version-controlled files.
3.4.2.1 Viewing Revision Information
The IDE's Mercurial support enables you to view version status information in many
of the IDE's windows, including the Status, Projects, Files, and Favorites windows. The
Status Window, however, represents the primary place within which you manage
version-controlled files by displaying a list of all of the new, modified, and removed
files in the currently selected project or directory.
To open the Status window, choose either:
■
Mercurial > Status from the context menu of a version-controlled file or folder
from the Projects, Files, or Favorites window.
■
Team > Mercurial > Status from the main menu.
■
Window > Versioning > Mercurial from the main menu.
The IDE's Mercurial support provides file status information in the following ways:
■
Status Labels. Textual indication of file status in the Status, Projects, Files, and
Favorites windows. To display status labels, select View > Show Versioning
Labels from the main menu.
3-28 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Mercurial
■
■
■
Status Color. Graphical indication of file status in the Status, Projects, Files, and
Favorites windows.
Status Badges. Graphical indication of the status of files contained within your
project, folder, and package nodes. Displayed in the Projects, Files, and Favorites
windows.
Revision Annotations. Displays commit message, author, date, and revision
number information in the left margin of files open in the Source Editor. To display
annotations, select a versioned file and select Show Annotations (or Mercurial >
Show Annotations) from its context menu. Alternatively, select Versioning, >
Show Annotations from the main menu.
The IDE displays version-controlled files using the following color coding and font
styles:
■
■
■
■
■
Green. Indicates that the file is a new local file that does not yet exist in the
repository.
Blue. Indicates that the file has been modified locally.
Red. Indicates that the file contains conflicts. You must employ the Resolve
Conflicts command (Mercurial > Resolve Conflicts) for such files.
Grey. Indicates that the file is ignored by Mercurial and will not be included when
calling versioning commands. In the Status window, grey text signifies deleted
files.
Strike-through. Indicates that the file is excluded when calling the Commit
command. All other Mercurial commands, however, work as usual. Note that files
displayed in the strike-through style only appear in the Status window and
Commit dialog. They will not appear in Diff panes, nor will their parent folders (or
packages) display badges if they are modified.
Current Mercurial file status is indicated by adding the following badges to project,
package and directory icons:
■
■
Locally Modified Badge. A blue badge on a folder or package node marks folders
or packages that contain locally modified or new files. In the case of packages, this
badge applies only to the package itself and not its subpackages. For folders, the
badge indicates local modifications in that folder or any of its subfolders.
Conflict Badge. A red badge on a folder or package node marks folders or
packages that contain files for which the repository copy of the file contains
changes that conflict with the local version. In case of packages, this badge applies
only to the package itself and not its subpackages. For folders, the badge indicates
local modifications in that folder or any of its subfolders.
The IDE enables you to clone an external Mercurial Repository and to make it
available within the IDE. You effectively create a copy or clone of the entire repository
to work with in the IDE. To do so, you need to be able to access a Mercurial repository
that you have read privileges for.
Note that the parent folders (or packages) of files excluded from commits and
displayed in the strike-through style will not display badges if they are modified.
3.4.3 How to Set Up Mercurial
Before you can take advantage of the IDE's Mercurial support, you need to have
Mercurial client software installed on your system. The IDE supports Mercurial client
versions 1.04 and higher. The IDE's Mercurial support works by using the same
commands as the Mercurial command line interface.
Versioning Applications with Version Control
3-29
Versioning Applications with Mercurial
You can download Mercurial as either sources or as a binary package from the
following link:
http://mercurial.selenic.com/wiki/Download?action=show&redirect=BinaryPack
ages
To set the path to the Mercurial executable file in the IDE:
1. Select Tools > Options (NetBeans > Preferences on OS X) from the main menu.
The Options dialog opens.
2.
Select the Team icon along the top of the dialog, then click the Versioning tab. In
the left pane under Versioning Systems, select Mercurial. User-defined options for
Mercurial display in the main window of the dialog.
3.
In the Mercurial Executable Path text field, either type in the path to the
executable file or click Browse to navigate to it on your system. Note that you
need not include the Mercurial executable file in the path.
4.
Click OK.
After the Mercurial client is set up, you can run Mercurial commands from the IDE's
Team > Mercurial menu. To clone an external Mercurial repository, select Team >
Mercurial > Clone Other. In the process of cloning, the IDE automatically imports all
of the history and status information for the cloned files.
If you have already cloned a Mercurial repository, the IDE automatically recognizes
the files as versioned files if those files are part of an open IDE project or if they are
added to the Favorites window. You can call Mercurial commands on such files from
the Mercurial menu or by right-clicking a file or folder and choosing from the
Mercurial submenu.
3.4.4 How to Clone an External Mercurial Repository
The IDE enables you to clone an external Mercurial Repository and to make it
available within the IDE. You effectively create a copy or clone of the entire repository
to work with in the IDE. To do so, you need to be able to access a Mercurial repository
that you have read privileges for.
To clone a Mercurial Repository:
1. Select Team > Mercurial > Clone Other from the IDE's main menu. The Mercurial
Clone Other wizard opens.
2.
In the Mercurial Repository panel of the wizard, enter a URL that contains the
connection protocol and the location of the repository.
3.
Click Next.
4.
In step 2 of the wizard, Clone External Repository, specify the default pull and
push paths to the repository.
5.
In step 3 of the wizard, Destination Directory, specify the Parent directory into
which you want to place the Clone of the repository. Alternatively, you can click
the Browse button to navigate to the desired directory on your system.
6.
Specify the Clone Name.
7.
Click Finish. The IDE initiates the clone action and the IDE's status bar indicates
the progress of the files downloading from the repository to your local working
directory. You can also view files being cloned from the Output window (Ctrl+4).
3-30 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Mercurial
Select the Scan for NetBeans projects after clone option if you
intend to immediately work with the cloned sources.
Note:
If the sources contain projects, a dialog will appear prompting you to
open them in the IDE.
If the sources do not contain a project, the dialog will appear
prompting you to create a new project from the sources and then open
them in the IDE. When you create a new project for such sources,
select the appropriate project category in the Create Project wizard
and then use the Create Project with Existing Sources template in that
category.
The IDE supports the following Mercurial URLs:
Protocol
Access Method
Example
file
Direct repository access (on
local disk)
file:///repository_path
http
Access using WebDAV
protocol to a Mercurial-aware
server
http://hostname/repository_path
https
Access using HTTP protocol
with SSL encryption
https://hostname/repository_path
static-http
Access using HTTP also, albeit static-http://hostname/repository_path
slower, allows access to a
Mercurial repository where
you simply use a web server to
publish the .hg directory as
static content
ssh
Access using SSH
ssh://hostname/repository_path
SSH requires an accessible shell account on the destination machine and a copy of
Mercurial (hg) in the remote path or specified with as remotecmd.
path is relative to the remote user's home directory by default. Use an extra slash at the
start of a path to specify an absolute path: ssh://example.com//tmp/repository
Mercurial does not use its own compression through SSH; the right thing to do is to
configure it in your ~/.ssh/config, for example:
■
Host *.mylocalnetwork.example.com
Compression no
■
Host *
Compression yes
3.4.5 How to Place Projects Under Version Control
The IDE enables you to place any project you are working on under version control.
You effectively import your sources into a local Mercurial repository. The repository
files are placed under a .hg directory under the project directory.
To place an IDE project under version control:
1. In the Projects window, select an unversioned project and select either:
Versioning Applications with Version Control
3-31
Versioning Applications with Mercurial
Versioning > Initialize Mercurial Repository from the node's context menu.
Team > Mercurial > Initialize Repository from the IDE's main menu.
2.
Putting the project under Mercurial revision control. The IDE initiates the
Mercurial initialize action and the IDE's status bar indicates the progress of the
repository creation under your local working directory. You can also view files
being added to the repository from the Output window (Ctrl+4).
All the project files are now registered in the repository as Locally New.
The new files and their status can be viewed by clicking on Mercurial > Show
Changes from the context menu.
3.
Select Mercurial > Commit from the project's context menu to commit these
project files to the Mercurial repository. The Commit - [ProjectName] dialog box
opens.
4.
Type your message in the Commit Message text area, and then click Commit.
The committed files are placed together with the .hg directory
in the Mercurial repository directory. The commit details are available
in the IDE Output window (Ctrl+4 on Windows/Command-4 on OS
X).
Note:
3.4.6 How to Use the Mercurial Diff Viewer
The IDE's graphical Diff Viewer enables you to compare revisions of a file side by side
using color coding to emphasize the differences between the files being compared.
You access the Diff Viewer in one of the following manners:
■
■
Select a version-controlled file or folder (for example, from the Projects, Files or
Favorites window) and select either Mercurial > Diff from the context menu or
Team > Mercurial > Diff from the main menu
Select the Diff view from the Status Window
The Diff Viewer tool bar provides you with the following functionality:
■
■
Navigate among differences found in the compared files. Choose to view
differences as they appear from top to bottom by clicking the appropriate icon:
–
Go to previous difference.
–
Go to next difference.
Refresh the status of the diff (for example, in the event that changes to your local
working directory have been made externally), and update the status of the
repository versions of files listed in the diff:
–
■
Update the working directory from the repository
Commit any changes contained in your local working directory:
–
Commit the selected item to the repository.
The Diff Viewer provides the following UI components:
Blue
Indicates lines that have been changed since the earlier revision.
Green
Indicates lines that have been added since the earlier revision.
Red
Indicates lines that have been removed since the earlier revision.
3-32 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Mercurial
The following icons allow you to make changes directly to your local working copy:
Replace
Inserts the highlighted text into your Working Tree copy.
Move All
Reverts the whole local Working Tree copy.
Remove
Removes the highlighted text from the local Working Tree copy.
3.4.7 How to Use the Mercurial Status Window
The Mercurial Status window presents a real-time view of the changes made in your
local working copy for selected version-controlled directories. It opens by default in
the bottom panel of the IDE, listing added, deleted or modified files.
To open the Status window, select Window > Versioning > Mercurial from the main
menu. Alternatively, you can select a versioned file or folder (for example, from the
Projects, Files, or Favorites window) and either select Mercurial > Status from the
node's context menu, or select Team > Status from the main menu.
By default, the Status window displays a list of all modified files within the selected
package or folder. The toolbar label includes the current revision of the working
directory and the Mercurial ChangeSet ID. You can click the column headings above
the listed files to sort the files by name, status or location.
The Status window toolbar includes buttons that enable you to invoke the most
common Mercurial tasks on all files displayed in the list. The following table lists the
Mercurial commands available in the toolbar of the Status window:
Icon
Name
Function
file
Changes between HEAD and Working
Tree
Displays a list of files that are either
already staged or only
modified/created and not staged yet.
http
Refresh status
Refreshes the status of the selected
files. Files displayed in the Status
window can be refreshed to reflect any
changes that may have been made
externally.
https
Diff All
Opens the Diff Viewer providing you
with a side-by-side comparison of your
local copies and the versions
maintained in the repository.
ssh
Update All
Updates the working directory from
the repository.
sftp
git
Update Target
Allows you to specify the revision to
update the working directory to.
Commit All
Enables you to commit local changes to
the repository.
You can access other Mercurial commands in the Status window by selecting a table
row that corresponds to a modified file, and choosing a command from the context
menu. You can, for example, perform the following actions on a file:
■
■
■
Open. Open the file in the Source Editor.
Diff. Launch the Diff Viewer for this file, to compare the local file with that stored
in the Repository.
Commit. Launches the Commit Dialog to allow this file to be Committed.
Versioning Applications with Version Control
3-33
Versioning Applications with Mercurial
■
■
■
■
■
Mark as Resolved. Allows you to mark a file that is in a Conflict state after a
Merge as resolved.
Show Annotations. Displays commit message, author, date, and revision number
information in the left margin of files open in the Source Editor.
Revert Modifications. Enables you to revert any changes to the copy in your local
working directory back to the current version maintained in the repository.
Revert Delete. Enables you to revert any delete actions that you have committed
to files in your local working copy. When you invoke the Revert Delete command,
the specified file will be retrieved from the repository and reinstated into your
local working copy.
Exclude from Commit. Allows you to mark the file to be excluded when
performing a commit.
Note:
You can also exclude files from a commit in the Commit dialog
box.
You can select multiple files in the Status window by holding down
the Ctrl key when you select files.
3.4.8 How to Merge File Revisions
NetBeans IDE enables you to merge changes between repository revisions and your
local working copy. Specifically, this combines two separate changesets in a repository
into a new changeset that describes how they combine.
To merge file revisions:
1. In the Projects, Files, or Favorites window, right-click the files or folders on which
you want to perform the merge operation and select Mercurial > Branch/Tag >
Merge Changes. The Merge with Revision dialog displays.
2.
In the Choose From Revisions drop-down list, select the revision.
You are porting all changes made on a local working copy file from the time it was
created.
3.
Ensure the Description, Author, and Date data are correct.
4.
Click Merge.
The IDE incorporates any differences found between the repository revisions and
your local copy of the file. If merge conflicts occur, the file's status is updated to
Merge Conflict to indicate this.
After merging revisions to your local working copy, you must
still commit changes using the Commit command in order for them to
be added to the repository.
Note:
3.4.9 How to Switch Branches in the Repository
The Switch Branch In Repository dialog box enables you to switch the branch that
your working directory is on to a branch that already exists in your repository.
To switch a branch:
1. In the Choose from Branches list, specify the branch you want to switch to.
3-34 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Mercurial
2.
(Optional) Specify your filtering criteria in the Filter text field to filter the
displayed branches.
3.
Review information specific to the branch in the following fields:
■
Author: Name of a person who committed the revision.
■
Date: Date when a commit was made.
■
Description: A message specified during the commit of the revision.
4.
(Optional) Select the Do a Forced Update option to switch to a selected branch
even if your local changes are lost.
5.
Click Switch.
The name of the branch you have switched to is displayed in a
label that follows the project name. Select View > Show Versioning
Labels from the main menu to display a label.
Note:
3.4.10 How to Commit Changes to the Repository
Mercurial versioned files and folders must be recognized by the IDE as such in order
to call Mercurial actions on them. To do so, you must first clone sources from an
external repository or place the project under Mercurial control.
It is a good idea to update any copies you have against the repository prior to
performing a commit in order to ensure that conflicts do not arise.
To perform an update on sources that you have modified:
■
Select Team > Update from the main menu.
Once your working copies of version-controlled files have been edited, you can then
place changes into the repository using the Mercurial Commit action. If you have an
task repository set up with your source code repository, the commit dialog box lets
you associate your commit action with an existing task.
To commit changes in local files to the repository:
1. Select a version-controlled file or folder (for example, from the Projects, Files, or
Favorites window) and select Mercurial > Commit from the context menu. The
Commit Dialog opens, listing all files that contain local changes. If the files you
want to commit do not already exist in the repository, the commit action will add
them.
2.
Enter a commit message in the Commit Message text area, indicating the purpose
of the commit.
■
3.
Click the Recent Messages icon (
view recent commit messages.
) in the upper right corner of the dialog to
Click Commit. The IDE executes the commit and sends your local changes to the
repository. You can also view files being committed to the repository from the
Output window (Ctrl+4).
When working in the Commit dialog, you can exclude
individual files from a commit. To do so, click on the Commit Action
column for the specific file and select Exclude from Commit. The file
name responds by displaying in strike-through text.
Note:
Versioning Applications with Version Control
3-35
Versioning Applications with Mercurial
3.4.10.1 Updating Tasks
You can update a task associating your commit action with an existing task in your
repository's task repository. To do so, click on the Update Task heading in the Commit
dialog box to expand it, then specify the following:
Element
Description
Task Repository
Specify the task repository that your source code repository uses, by
selecting a task repository from the drop-down list. The drop-down
provides you with a list of all task repositories registered with the IDE.
If your source code repository's task repository is not registered, click
the New button to register it.
Task
Specify the task ID. You can do this by typing in the ID, or part of the
description.
You can also specify the following options:
Element
Description
Resolve as FIXED:
When selected, the status of the task is marked as Resolved.
Add Commit
When selected, the commit message is added to the task.
Message from Above
Add Revision
Information to the
Task
When selected, the task is updated to include the revision information
such as the author, date, etc. You can click Change Format to modify
the format of the revision information that is added to the task.
Add Task
Information to
Commit Message
When selected, the task ID and summary are added to the commit
message. You can click Change Format to modify the format of the task
information that is added to the message.
After Commit
When selected, the task is updated after you commit the changes.
After Push
When selected, the task is updated only after the changes are pushed to
the source code repository.
3.4.10.2 Ignoring Files
If your local working directory includes files or directories that you do not want to
place under version control, you can set the IDE to ignore them permanently using the
Ignore command.
You cannot employ the Ignore command on files that already exist in the repository.
To ignore local files in your working directory:
1. Select the file or directory you wish to ignore from the Projects, Files, Favorites, or
Status window.
2.
Select Ignore (or Mercurial > Ignore) from the context menu of selected file or
directory. The IDE ignores the file or directory whenever Mercurial commands are
called on it or on the directory within which it is stored.
To change the status of ignored files so that they can be acted upon in Mercurial, select
the specific file and select Mercurial > Unignore.
3.4.10.3 Pushing Local Changes to the Shared Repository
Before pushing changes that you have committed locally to the shared repository, you
need to synchronize your local repository with the shared repository.
3-36 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Mercurial
To synchronize your local repository with the shared repository:
Select Team > Remote > Fetch from the main menu.
■
After you perform a successful Fetch, your local repository becomes synchronized
with the shared repository.
To push changes:
■
Select Team > Remote > Push Current Branch, Team > Remote > Push All
Branches, or Team > Remote > Push from the main menu.
The output from a successful Push will list any changesets created.
Since you maintain a copy of the entire repository on your
system, the general practice is to make multiple commits to your local
repository and only after the particular task is complete, perform the
push to the shared repository.
Note:
3.4.11 How to Set Mercurial Project Properties
Open the Mercurial Properties Dialog in one of the following ways:
■
■
Select Team > Mercurial > Properties from the IDE's main menu
Select Mercurial > Properties from the context menu of a Mercurial-versioned
project
The following table describes the Mercurial properties that can be set:
Element
Description
default-pull
Specify the local repository path to Pull changes from when choosing
Mercurial > "Pull from - default" from the Mercurial controlled
project's context menu.
default-push
Specify the local repository path to Push changes to when choosing
Mercurial > "Push to - default" from the Mercurial controlled project's
context menu.
username
Set the username to record when committing changes to the repository.
This property overrides the global Mercurial User Name Option for
this project.
Note: To Push to other external locations select Team > Mercurial >
Share > Push Other.
To Pull from other external locations select Team > Mercurial > Share
> Pull Other.
3.4.12 How to Set Mercurial Global Options
Open the Mercurial Options window:
■
■
Select Tools > Options. The IDE's Options window opens.
Select the Team > Versioning tabs, then select Mercurial under Versioning
Systems.
The following list describes the Mercurial Global Options property that can be set.
Versioning Applications with Version Control
3-37
Versioning Applications with Mercurial
Element
Description
Mercurial User Name Set the username to record when committing changes to the repository.
May be overridden for a given project using the Mercurial Project
Properties username setting.
Mercurial Executable Set the executable path to the installed Mercurial Hg executable. You
Path
only need to use this if Mercurial has been placed somewhere other
than your standard PATH.
Default Export
Filename
Set the export filename used when using Team > Export Diff Patch
from the IDE's main menu when a Mercurial-versioned project is
selected. The following identifiers can used in the filename:
%b: Project Directory name
%r: Current revision number being exported.
%h: Changeset ID being exported.
Mercurial Status
Labels
Set the Status labels to be displayed in the Project view for a Mercurial
controlled project. To enable, select View > Show Versioning Labels
from the IDE's main menu. The following labels can used:
{status}: Status of the file.
{revision}: Revision of the file.
{folder}: Branch or Tag Name.
Mercurial Extensions Opens a dialog to allow you to add Mercurial extensions. Currently,
the NetBeans IDE adds the hgk extension to support the Mercurial >
View from the a Mercurial project's context menu. You can change its
location from this dialog if necessary.
Select the Automatically open Output window option to set
the Output window to display when versioning operations that
involve interaction with the repository take place (for example, clone,
fetch, pull, push). This option is selected by default.
Note:
3.4.13 How to Enable Support for Mercurial Queues
Since Mercurial Queues is an extension, you must explicitly enable it before you can
use it.
To start running Mercurial Queues on your Mercurial repository:
1. On your system, browse to the .hgrc file. The default location of the .hgrc file on
OS X and Linux is $HOME/.hgrc, on Windows - %USERPROFILE%\Mercurial.ini.
2.
Add the following lines to your .hgrc file:
[extensions]
hgext.mq =
3.
Save the file.
3.4.14 How to Create a Patch
To create a patch:
1. In the Projects window, select a versioned project and select Team > Queues >
Create Patch (alternatively, right-click the project name and select Mercurial >
Queues > Create Patch from the context menu).
3-38 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Mercurial
The Create Patch dialog box displays.
2.
Specify the name for a patch in the Patch Name text field.
3.
Provide the description of a patch in the Patch Message field.
Alternatively, select either of the following options and click OK afterwards:
■
■
click Recent Messages to select a message from a list of most recent commit
messages
click Load Template to select a message template for a commit message
Note: The provided description of a patch will be used as a commit
message when turning the patch into a permanent changeset.
4.
Select files to be included into the patch in the Files To Include In Patch table.
5.
(Optional) Specify information pertinent to a task related to the created patch
using the fields of the Update Task area.
6.
Click Create Patch.
A new patch is created and added to the .hg/patches directory.
3.4.15 How to Refresh a Patch With Local Modifications
To save your progress into the patch you are creating, you need to complete the
following steps:
1.
Select Team > Queues > Refresh Patch from the main menu (alternatively,
right-click the project name and select Mercurial > Queues > Refresh Patch from
the context menu).
The Refresh Patch dialog box displays.
2.
Provide the description of a patch in the Patch Message field.
Alternatively, select either of the following options and click OK afterwards:
■
■
click the Recent Messages button to select a message from a list of most recent
commit messages
click the Load Template button to select a message template for a commit
message.
Note: The provided description of a patch will be used as a commit
message when turning the patch into a permanent changeset.
3.
Select files to be included into the patch in the Files To Include In Patch table.
4.
(Optional) In the Update Task area, specify information pertinent to a task related
to the changes being committed.
5.
Click Refresh Patch.
The patch you are working on is updated.
Versioning Applications with Version Control
3-39
Versioning Applications with Mercurial
3.4.16 How to Compare Patch Revisions
To generate a patch for review and compare revisions of a patch side by side
1. Select Team > Queues > Diff from the main menu (alternatively, right-click the
project name and select Mercurial > Queues > Diff from the pop-up menu).
The Diff Viewer displays differences found in the current patch and all your
uncommitted/unrefreshed local changes in side-by-side panels
2.
Review and revise differences found in the compared files using either Graphical
or Textual Diff Viewer.
The Graphical Diff Viewer highlights changes in the files using
the following color encoding.
Note:
Element
Description
Blue
Indicates lines that have been changed since the earlier patch.
Green
Indicates lines that have been added since the earlier patch.
Red
Indicates lines that have been removed since the earlier patch.
The following icons enable you to make changes directly within the Graphical Diff
Viewer.
Element
Description
Replace
Inserts the highlighted text from the previous patch into the current
patch.
Replace All
Reverts current version of a patch to the state of its selected previous
version.
Remove
Removes the highlighted text from the current version of a patch so
that it mirrors the previous version of a patch.
3.4.17 How to Switch Between Patches
To switch to a particular patch in a patch queue series:
To switch between patches there must be no local modifications
in the working copy, otherwise the switch fails.
Note:
1.
Select Team > Queues > Go To Patch from the main menu (alternatively,
right-click the project name and select Mercurial > Queues > Go To Patch from
the context menu).
The Go To Patch dialog box displays a list of all patches available in a stack.
Note:
Names of applied patches display in bold.
3-40 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with Mercurial
Note: Select Team > Queues > Pop All Patches to remove the
applied patches from the top of the stack and update the working
directory to undo the effects of the applied patches.
2.
Select the required patch and click Go.
The IDE applies the changes contained in the selected patch to the chosen project,
file, or folder.
3.4.18 How to Finish Applied Patches
Once your work on a patch is done, it can be turned into a permanent changeset.
To turn all applied patches in a patch queue series into regular changesets:
1. Select Team > Queues > Finish Patches from the main menu (alternatively,
right-click the project name and select Mercurial > Queues > Finish Patches from
the context menu).
The Finish Patches dialog box displays.
2.
Select the name of a patch to be finished in the patches field.
All patches in the series before the selected patch will also be
finished.
Note:
3.
Click Finish Patches.
The IDE turns all applied patches up to the selected patch into regular changesets.
3.4.19 How to Shelve Changes (Mercurial)
Shelving allows to make changes to a project without committing and pushing them to
Mercurial.
To temporarily set aside some not yet committed changes in a working directory
as a patch file:
1. Select a versioned project, file, or folder.
2.
Select Team > Shelve > Shelve Changes from the main menu.
3.
Specify the name for a patch to be shelved in the Patch Name field.
4.
Leave the Back up any Locally Modified files to <file>.orig option selected to get
all local changes stored in a <file>.orig file directly in the working copy (if
required).
5.
Leave the Remove Newly Added Files and Folders option selected to get all
newly added files and folders deleted (if required).
6.
Click Shelve.
After a patch with all the modifications is created and shelved,
the local, not yet committed, modifications are reverted in the
working copy (that is the working copy gets clear of the local
changes). The previously modified files become up to date.
Note:
Versioning Applications with Version Control
3-41
Versioning Applications with CVS
3.4.20 How to Rebase (Mercurial)
Sometimes it is required to move revisions from a point to another.
To append the private changes on top of any destination commit:
1. Select a versioned project, file or folder in the Projects window.
2.
Select Team > Branch/Tag > Rebase from the main menu.
Alternatively, right-click the selected item and choose Mercurial > Branch/Tag >
Rebase from the context menu.
3.
Set the required properties in the Select Changesets to Rebase dialog box.
4.
Click Rebase to complete rebasing according to the defined settings.
3.5 Versioning Applications with CVS
CVS (Concurrent Version System) is a type of version control system that aids
developer groups working with shared source files in common repositories by
managing file revision history information.
The IDE's CVS built-in support enables you to manage changes to version-controlled
files as you work. In the IDE, you can call CVS commands on both files and directories
in the Projects, Files, Versioning, and Favorites windows. For an overview of the
typical workflow when using CVS in the IDE, see Section 3.5.1, "How to Work with
CVS.".
3.5.1 How to Work with CVS
The following table outlines the basic workflow when working with CVS in the IDE.
Element
Description
Set up CVS
Set up CVS. See Section 3.5.5, "How to Set Up CVS."
Synchronize local
files with repository
Check out files from a repository. See Section 3.5.7, "How to Check Out
Files from a Remote Repository (CVS)."
Import your project into a CVS repository.
Edit sources
Make changes to local copies of versioned files.
Diff file revisions between repository versions and your local working
copies. See Section 3.5.16, "How to Resolve Merge Conflicts."
Merge changes in repository revisions with the local copies. See
Section 3.5.15, "How to Merge File Revisions from a Branch (CVS)."
Update local versions Update local versions of files with changes committed to the CVS
repository. See Section 3.5.8, "How to Update Files in a Local Working
Directory (CVS)."
Resolve conflicts
Resolve conflicts between local versions of files with changes
committed to CVS repository revisions. See Section 3.5.9, "How to
Compare File Revisions in CVS."
Commit sources
Commit local changes to files into the repository. See Section 3.5.10,
"How to Commit Local Changes to a Remote Repository (CVS)."
3.5.2 How to Use CVS with the IDE
The IDE's CVS support enables you to manage the evolution of changes in
version-controlled files by displaying status information directly in the IDE's various
3-42 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with CVS
windows (for example, Projects, Files, Favorites, Versioning) so that you can call CVS
commands as you work.
The Versioning window presents a real-time view of the changes in selected
directories. It opens at the bottom of the IDE whenever you view changes made in
version-controlled files. By default, the Versioning window displays a list of all
modified files within the selected package or folder.
You can open the Versioning window by selecting Team > (CVS >) Show Changes
from the main menu. Alternatively, you can right-click any versioned project,
directory, or file and select CVS > Show Changes.
Using the filter buttons in the toolbar, you can limit the list of displayed files to either
locally or remotely modified files. The Versioning window toolbar also includes
buttons that enable you to invoke the most common CVS tasks on all files displayed in
the list, such as committing, updating, refreshing status, and performing diffs.
The following CVS commands are available in the Versioning window's toolbar:
Element
Description
Refresh status
Refreshes the status of the selected files and folders. Files displayed in
the Versioning window can be refreshed to reflect any changes that
may have been made externally.
Diff all
Opens the Diff Viewer providing you with a side-by-side comparison
of your local copies and the versions maintained in the repository.
Update all
Updates all selected files from the repository.
Update local versions Update local versions of files with changes committed to the CVS
repository.
Commit All
Enables you to commit local changes to the repository.
You can call CVS commands on versioned-controlled files (those existing within a
registered working directory) using the CVS menu in the IDE's main window. In
addition, many CVS commands are available in the context-sensitive menu for a
selected file or directory.
You can access the CVS commands context-sensitive menu by right-clicking a file or
directory in any of the following:
■
Projects window
■
Files window
■
Favorites window
■
Versioning window
■
History Viewer
■
Source Editor (that is, from the tab of an open file)
The IDE's status bar, located in the bottom right of the
interface, displays the current command's status.
Note:
3.5.3 How to View File Status Information (CVS)
The IDE's CVS support enables you to view and manage the evolution of changes in
version-controlled files.
Versioning Applications with Version Control
3-43
Versioning Applications with CVS
3.5.3.1 Viewing Revision Information
The IDE's CVS support enables you to view version status information in many of the
IDE's windows, including the Versioning, Projects, Files, and Favorites windows. The
Versioning window, however, represents the primary place within which to manage
version-controlled files by displaying a list of all of the new, modified, and removed
files in the currently selected project or directory.
To open the Versioning window, choose either:
■
CVS > Show Changes from the context menu of a version-controlled file or folder
from the Projects, Files, or Favorites window.
■
Team > (CVS >) Show Changes from the main menu.
■
Window > Versioning > CVS from the main menu.
The IDE's CVS support provides file status information in the following ways:
Element
Description
Status Labels
Textual indication of file status in the Versioning, Projects, Files, and
Favorites windows. To display status labels, select View > Show
Versioning Labels from the main menu.
Status Color.
Graphical indication of file status in the Versioning, Projects, Files, and
Favorites windows.
Status Badges
Graphical indication of the status of files contained within your project,
folder, and package nodes. Displayed in the Projects, Files, and
Favorites windows.
Revision Annotations Displays commit message, author, date, and revision number
information in the left margin of files open in the Source Editor. To
display annotations, select a versioned file and select Show
Annotations (or CVS > Show Annotations) from its context menu.
Alternatively, select Versioning, > Show Annotations from the main
menu.
The IDE displays version-controlled files using the following color coding and font
styles:
Element
Description
Green
Indicates that the file is a new local file that does not yet exist in the
repository.
Blue
Indicates that the file has been modified locally.
Red
Indicates that the file contains conflicts. You must employ the Resolve
Conflicts command (CVS > Resolve Conflicts) for such files.
Grey
Indicates that the file is ignored by CVS and will not be included when
calling versioning commands. In the Versioning window, grey text
signifies deleted files.
Strike-through
Indicates that the file is excluded when calling the Commit command.
All other CVS commands, however, work as usual. Note that files
displayed in the strike-through style only appear in the Versioning
window and Commit dialog. They will not appear in Diff panes, nor
will their parent folders (or packages) display badges if they are
modified.
Current CVS file status is indicated by adding the following badges to project, package
and directory icons:
3-44 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with CVS
Element
Description
Locally Modified
Badge
A blue badge on a folder or package node marks folders or packages
that contain locally modified or new files. In the case of packages, this
badge applies only to the package itself and not its subpackages. For
folders, the badge indicates local modifications in that folder or any of
its subfolders.
Conflict Badge
A red badge on a folder or package node marks folders or packages
that contain files for which the repository copy of the file contains
changes which conflict with the local version. In case of packages, this
badge applies only to the package itself and not its subpackages. For
folders, the badge indicates local modifications in that folder or any of
its subfolders
3.5.4 How to Work with Version Histories
Searching the histories of files can be helpful when you need to find specific commits,
when backporting bugs for example. The IDE's Search Histories window enables you
to view a summary of a file's evolution over time by revision number.
You can view file histories in the IDE's Search History window. To do so, select a
versioned file (for example, from the Projects, Files, or Favorites window) and select
either CVS > Search History from the context menu or Team > (CVS >) Search
History from the main menu. Alternatively, in the Versioning window you can select
Search History from a file's context menu.
Using the Search History window, you can search a file or folder's history for versions
based on several criteria. The Search Histories window enables you to search for
changes in version controlled files by:
Element
Description
Message
The description submitted with the commit.
Username
The author of the commit.
From Tag
The tag, revision number, or date from which the commit was made.
To Tag
The tag, revision number, or date before which the commit was made.
To search for a specific revision:
1. Select the file or folder for which you want to find a specific revision.
2.
Select CVS > Search Histories from the context menu. The IDE opens the Search
History window to display the selected item's revision history.
3.
Enter search criteria information in the Message, Name, From, and To fields. You
can also use the Browse buttons to designate any tag, branch, revision, or date you
want to limit your search to.
4.
Click Search. The IDE displays the file's revision history in the Search History
window.
If you want to view other files that were included in a specific
commit, you can broaden your search using the "your_project" and
Open Projects links to the right of each revision.
Note:
Versioning Applications with Version Control
3-45
Versioning Applications with CVS
3.5.4.1 Comparing Revisions in the Search History Window
You can compare a file with previous versions from within the Search Histories
window using the Diff button.
To view revision differences in the Search History window:
1. Click the Diff button in the toolbar.
2.
Select the revision against which you want to compare your local working copy.
The IDE displays a diff of the file's revisions within the Search History window.
Note that you can navigate between the differences using the Previous Difference
and Next Difference buttons.
3.5.5 How to Set Up CVS
In the IDE, no special setup is necessary in order to use CVS. You need only to check
out the files located in a remote repository to a local working directory on your
system. In the process of checking out, the IDE automatically registers the working
directory where your local copies of version-controlled files and their status
information will be stored.
If you have previously checked out files to a local working directory on your system
using another CVS executable or the command line, you can still work with the files
using the IDE's CVS support. The IDE automatically recognizes the files as versioned
files, enabling you to call CVS commands on them. See Checking Out Files from a
Remote Repository for more information.
If you want to set up a local repository, you must do so
manually using a CVS command line client. For information, see the
CVS documentation at http://ximbiot.com/cvs/manual/.
Note:
3.5.6 How to Adjust CVS Settings in the IDE
The IDE enables you to make changes to CVS settings, such as:
■
■
■
applying arbitrary metadata to files or directories by adding, removing, or
modifying the status label format of versioning labels for versioned files
adjusting CVS settings in the IDE, such as excluding new files from commit
actions automatically
limiting the number of characters per line in commit messages
To change the status label format for versioned files:
■
In the Status Label Format text box, enter the format in which you want the status
labels to be displayed. You can enter your own label, otherwise specify a
CVS-reserved label by clicking Add Variable and selecting from the available
options.
Note: In order to make versioning labels visible, select View from
the main menu, then select the Show Versioning Labels option.
Versioning labels display in light grey text to the immediate right of
versioned files in the Projects, Files, Favorites windows.
3-46 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with CVS
To automatically exclude new files from commit actions:
■
Select the Apply "Exclude from Commit" On New Files Automatically option.
When selected, newly created files will have to be manually included in commit
actions.
To limit the number of characters per line in commit messages:
1. Select the Wrap Commit Messages To (characters) option.
2.
In the adjacent text box, enter the number of characters to indicate the length of
each line. Commit messages longer than the specified number of characters will be
wrapped to multiple lines.
3.5.7 How to Check Out Files from a Remote Repository (CVS)
In order to work on shared files located in a remote repository, you need to copy the
necessary files and directories to your local working directory. This is done by
checking out the files from the repository.
To check out files from a remote repository:
1. Select Team > (CVS >) Checkout from the main menu.
2.
On the first page of the CVS Checkout wizard, specify the location of the CVS
repository by choosing it from the CVS Root drop-down menu. If you are
unfamiliar with the syntax, you can click the Edit button and enter the required
information using the dialog. For information on supported CVS protocols, view
supported CVS root types below.
3.
Enter your password in the Password field.
4.
If you are using a proxy, click the Proxy Configuration button and enter the
required information. Click Next.
5.
On the Module to Checkout page, specify the modules you want to check out in
the Module field or click the Browse button to choose from a list of all modules in
the repository. Note that if you do not specify a module, the entire repository will
be checked out.
6.
If you need to specify a specific branch, revision number, or tag for the checkout,
enter the information in the Branch field or click the Browse button to choose from
a list of all branches in the repository.
7.
Specify the local working directory into which you want to check out the selected
modules or branches. Alternatively, you can click the Browse button to navigate to
the desired directory on your system.
8.
Click Finish to check out the files. The IDE initiates the check out command and
the IDE's Status bar, displayed in the lower right corner of the IDE, indicates the
progress of the files downloading from the repository to your local working
directory.
If the checked-out sources contain a project, a dialog will appear prompting you to
open them in the IDE. If the sources do not contain a project, the dialog will appear
prompting you to create a new project from the sources and then open them in the
IDE.
The IDE directly supports the following CVS root types:
Versioning Applications with Version Control
3-47
Versioning Applications with CVS
Element
Description
pserver
For connecting to pserver repositories.
:pserver:[email protected]:/repository_path
ext
For connecting to CVS repositories using SSH, etc.
:ext:[email protected]:/repository_path.
The following root types require an external CVS executable:
Element
Description
fork
For protocol access to local CVS repository :fork:/repository_path
local
For direct access to local CVS repository :local:/repository_path
3.5.8 How to Update Files in a Local Working Directory (CVS)
Updating files or folders enables you to incorporate any changes that other developers
have committed to the repository since your previous checkout or update.
To update a local version of a file or folder:
■
Select a versioned file (for example, in the Projects, Files, or Favorites window)
and select CVS > Update. Alternatively, select a file in the Versioning window and
select Update from the context menu. The IDE incorporates any changes existing
in the repository version of the file.
It is recommended that you perform an update on all files
prior to committing them to the repository. Doing so allows you to
become aware of any conflicts prior to performing the commit.
Note:
3.5.8.1 Updating Projects with Dependencies
If you are working on a project for which there are other required projects, you can
update both the main project and all dependent projects using the IDE's Update with
Dependencies command.
To update an entire project and all dependent projects:
1. Right-click the project node in the Projects window.
2.
Select CVS > Update With Dependencies. The IDE incorporates any changes
existing in the repository version of all of the projects with your local working
copy.
3.5.9 How to Compare File Revisions in CVS
The Diff command compares different revisions of a file and displays the differences
found graphically.
The IDE's graphical Diff Viewer enables you to compare different versions of a file side
by side using color coding to emphasize the differences between the files being
compared.
The previous and next difference buttons in the toolbar enable you to navigate among
the differences in the file. You can also refresh the status and update files from within
the Diff Viewer using the Refresh Diff and Update buttons. When you are finished
3-48 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with CVS
comparing the files, you can commit your changes using the Diff Viewer's Commit
button.
To generate a graphical diff comparing a repository revision to your working
copy:
■
Right-click a versioned file node in the Projects, Files, or Versioning window and
select Diff (or CVS > Diff). The IDE displays the results in the Diff Viewer in a
new tab of the main window.
If you want to perform a diff on all files contained in a folder, select a folder and then
select CVS > Diff from the context menu. All files that contain differences between
your local version and the repository version will be listed in the upper pane of the
Diff Viewer. You can then view individual diffs on files by clicking a file from the list.
To make changes to a file while comparing it in the Diff Viewer:
1. Navigate through differences between the two versions using the previous
difference and next difference arrow icons.
2.
Click any of the displayed icons to perform immediate changes to your local copy.
Note: Your local copy appears in the right pane of the Diff Viewer.
You can also make changes to your local copy by typing directly into it
in the Diff Viewer.
Any changes made in the Diff Viewer are automatically saved as they
occur.
The following icons enable you to make changes directly within the Diff Viewer:
Element
Description
Replace
Inserts the highlighted text from the previous revision into the current
revision.
Move All
Reverts the file's current version to the state of the selected previous
version.
Remove
Removes the highlighted text from the current version so that it
mirrors the previous version.
3.5.10 How to Commit Local Changes to a Remote Repository (CVS)
Once your working copies of version-controlled files have been edited, you can then
place your changes into the repository using the Commit command.
Note: Project directories must be located within a local working directory that is
registered with the IDE in order to call CVS commands on them.
To commit changes in local files to a remote repository:
1. In the Versioning window, confirm that you want to commit the listed files.
2.
Ensure that your local copies of the files are up-to-date by clicking the Update All
button prior to committing your changes.
3.
Once the Update command has finished, commit the files by clicking the Commit
All button. If the files you want to commit do not already exist in the repository,
the Commit command will add them.
Versioning Applications with Version Control
3-49
Versioning Applications with CVS
4.
Enter a message describing your changes in the CVS Commit dialog that appears
and click Commit. The IDE executes the Commit command and the selected files
are committed to the repository.
Click the Recent Messages icon in the upper right corner of the dialog to view recent
commit messages.
You can also commit files or directories from the Projects
window, Files window, or Favorites window by right-clicking the files
or directories you wish to commit and choosing CVS > Commit.
Note:
3.5.10.1 Excluding Files from a Commit
The IDE enables you to specify which files in your local working directory are
recognized when using CVS commands. Using the Exclude from Commit command,
you can set the IDE to temporarily disregard files when making commits.
To exclude local files in your working directory:
1. Select the files or directories you wish to ignore in the Versioning window, Projects
window, Files window, or Favorites window.
2.
Right-click and select the CVS > Exclude from Commit option. If you have the
Versioning window opened, note that the IDE displays the file or directory name
in strike-through text and disregards the item whenever the commit command is
called. Note that the files remain excluded until you include them.
To remove the exclude status from a file or directory, right-click the selected file or
directory, select CVS and deselect the Exclude from Commit option.
3.5.10.2 Ignoring Files
If your local working directory includes files or directories that you do not want to
place under version control, you can set the IDE to ignore them permanently using the
Ignore command.
To ignore local files in your working directory:
1. Select the files or directories you wish to ignore in the Versioning window, Projects
window, Files window, or Favorites window.
2.
Right-click and select CVS > Ignore. Note that the Ignore command is unavailable
for files that already exist in the repository. The IDE ignores the file or directory
whenever CVS commands are called on them or the directories within which they
are stored.
3.5.11 How to Revert Modifications (CVS)
Occasionally it may be desirable or necessary to revert local file changes to their
current status maintained in the repository. The IDE enables you to do this using the
Revert Modifications command.
To revert modifications:
1. Select the versioned file for which you want to revert changes (for example, from
the Projects, Files, Favorites or Versioning window) and select Revert
Modifications (or CVS > Revert Modifications) from the context menu. A
Confirm Overwrite dialog displays notifying you that your local copy is about to
be overwritten with the current repository version.
3-50 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with CVS
2.
Click Yes to initiate the process. Your selected file will be overwritten with the
repository version and changes are automatically reflected if the file is already
opened in the IDE's editor.
3.5.12 How to Recover Deleted Files (CVS)
When working with version-controlled sources, you may sometimes find it useful to
be able to recover locally deleted files from the repository. The IDE's version control
support enables you to recover versioned files by performing a revert delete action on
files maintained in your local working copy.
To revert deletes made to files in your local working copy:
1. Select the project or folder that previously contained the deleted files (for example,
from the Projects, Files or Favorites window) and select CVS > Show Changes
from the context menu. The Versioning window opens in the bottom panel of the
IDE displaying file changes. The file names of recently deleted files display in grey
text with status listed as Locally Deleted.
2.
Right-click the file you want to recover and select Revert Delete.
3.
In the Confirm Overwrite dialog that displays, click Yes to enable the IDE to
recover the file from its local history repository. The file disappears from the
Versioning window and is relisted in the project directory within your local
working copy.
3.5.13 How to Work with Tags
It is often helpful to tag version controlled files for reference purposes, when you want
to mark the point a particular branch was made, for example. Using the CVS Tag
command you can attach an existing tag to a file or folder or create a new tag.
To apply a tag to a file or directory:
1. Right-click the file or folder and select CVS > Tag.
2.
Enter the tag name in the text field. Alternatively, click Browse to select from a list
of existing tags.
If the tag you entered does not already exist, a new tag will be created.
3.
If you want to ensure that the tag is not attached to local revisions that are not up
to date, select the Avoid Tagging Locally Modified Files checkbox.
4.
If you want to move an existing tag to the current revision in your local working
directory, select the Move Existing Tags checkbox. The IDE attaches the tag on the
specified file or directory.
3.5.14 How to Work with Branches in CVS
The IDE's CVS support enables you to maintain different versions of an entire code
base using branches. Branches are created by attaching a branch tag to a file or folder
in the repository. When you modify files in a branch it does not affect the files in the
main code line or “trunk”. You can, however, merge any modifications you make in
the branch back to the trunk at a later stage.
Versioning Applications with Version Control
3-51
Versioning Applications with CVS
3.5.14.1 Checking out Branches
If you need to edit files on a branch that already exists, you can check out the branch to
copy the files to a local working directory. You must, however, create a new local
working directory within which to checkout the branch.
To check out a branch to a local working directory:
1. Select Team > (CVS >) Checkout from the main menu.
2.
On the first page of the CVS Checkout wizard, specify the location of the CVS
repository by choosing a preconfigured URL from the CVS Root drop-down menu.
If you are unfamiliar with the syntax, click Edit and enter the required information
in the Edit CVS Root dialog.
3.
Enter your repository password in the Password field.
4.
If you are using a proxy, click the Proxy Configuration button and enter the
required information. Click Next.
5.
On the Module to Checkout page, specify the files and directories you want to
check out in the Module field or click the Browse button to choose from a list of all
modules in the repository.
6.
Specify the branch, revision number, or tag to checkout in the Branch field or click
the Browse button to choose from a list of all branches in the repository.
7.
Specify the local working directory into which you want to check out the selected
branches. Alternatively, you can click the Browse button to navigate to the desired
directory on your system.
8.
Click Finish to check out the files. The IDE initiates the checkout command for the
branch. The IDE's Status bar, displaying in the lower right corner of the IDE,
indicates the progress of the files downloading from the repository branch to your
local working directory.
3.5.14.2 Switching to a Branch
If you want to switch a project, directory, or file to a branch that already exists for
stabilization or experimentation purposes, you can do so using the Switch to Branch
command.
To switch to a branch:
1. In the Projects, Files, or Versioning window, right-click the file or folder you want
to be the root of your branch and select CVS > Switch to Branch.
2.
In the Switch to Branch dialog, enter a branch name or click Browse to see a list of
available branches.
3.
Click Switch. The IDE moves the selected file to the specified branch by adding a
branch tag.
3.5.14.3 Creating a Branch
If you want to work on a separate version of your file system for stabilization or
experimentation purposes, you can do so by creating a branch. Branches are created by
adding a branch tag to a project, directory, or file revision.
To create a branch:
1. In the Projects, Files, or Versioning window, right-click the file or folder you want
to be the root of your branch and select CVS > Branch.
3-52 NetBeans Developing Applications with NetBeans IDE
Versioning Applications with CVS
2.
In the Branch dialog, enter a Branch name or click Browse to see a list of available
branches.
3.
If you want to tag the file or directory, select the Tag Before Branching checkbox
and enter a Tag name.
4.
If you want to switch to the new branch after creating it, select the Switch to This
Branch Afterwards checkbox.
5.
Click Branch. The IDE creates the branch by adding a branch tag to the selected
file or directory.
When you add a branch tag, the branch is created in the
repository immediately and does not require using the Commit
command.
Note:
3.5.15 How to Merge File Revisions from a Branch (CVS)
The Merge command is useful for incorporating changes made on different branches
of the repository with your local working copy of a file or directory. Any changes you
make on one branch can be merged to another branch, including back to the trunk.
You can also merge the difference between two earlier revisions with your local
working copy.
To merge a file from a branch with your local working copy:
1. In the Projects, Files, Favorites, or Versioning window, select the files or folders
that you want to merge into your local working copy and select CVS > Merge
Changes from Branch.
2.
In the dialog that appears, select the branch you want to merge the changes from.
If you want to merge changes from a branch other than the trunk, enter the branch
name or click Browse to see a list of available branches.
3.
If you want to merge changes after a specific tag, select the Merge Only Changes
Made after Tag checkbox and designate the tag in the Tag Name field.
Alternatively, you can click Browse to choose from a list of available tags.
4.
If you want to tag the merge, select the Tag Trunk after Merge (or Tag branch_
name after Merge) checkbox and enter the desired tag name. Alternatively, click
Browse to choose from a list of available tags.
5.
Click Merge. The IDE incorporates any differences found in the branch version
into your local copy of the file. If merge conflicts occur, the file's status is updated
to Merge Conflict to indicate this.
After merging file changes from a branch to your local working directory, you must
still commit the changes using the Commit command in order for them to added to the
repository.
3.5.16 How to Resolve Merge Conflicts
When merge conflicts occur, a Merge Conflict badge appears on the parent folder (or
package) of file. Within the file itself, each conflict is marked with arrows followed by
the lines from the two revisions that caused the conflict.
Merge conflicts must be resolved prior to checking your local
file into the repository.
Note:
Versioning Applications with Version Control
3-53
Versioning Applications with CVS
To resolve merge conflicts graphically with the Merge Conflicts Resolver:
1. Right-click the node of the file whose status indicates that there is a conflict and
select Resolve Conflicts from the pop-up menu. The Merge Conflicts Resolver is
displayed with merge conflicts highlighted in red.
2.
Use the Next and Previous difference buttons in the upper-left corner to navigate
to each conflict in the file.
3.
For each conflict, click Accept above the pane containing the text that you wish to
accept. Once you have chosen the correct text, it is highlighted in green and
displayed in the Merge Result pane. The text you did not choose is highlighted in
blue.
4.
If neither pane contains the text you want, exit the Merge Conflict Resolver and
edit your source file manually. When you are done making changes, right-click the
node of the file and choose CVS > Update from the context menu. Then repeat the
procedure, beginning from Step 1.
5.
After resolving each conflict, click OK to exit the Merge Conflict Resolver. The IDE
updates your local working copy with the desired changes.
You can also resolve conflicts manually in the Source Editor. To
do so, open the file in the editor. For each conflict in the file, delete the
arrows and text that you do not want, then save the file. The IDE
updates your local working copy with the desired changes.
Note:
Once you have resolved each merge conflict, you still need to commit
the file to add your changes to the repository copy.
3.5.17 How to Create and Apply a Patch
Patch files enable software developers who are not sharing a common repository to
distribute and integrate changes that have been made to the code. The IDE enables you
to create and apply patches that update copies of source files so that you do not have
to incorporate the changes manually.
To create a patch file:
1. Select a versioned file (for example, in the Projects, Files, or Favorites window) for
which you want to create a patch.
2.
Select Team > (CVS >) Export Diff Patch from the main menu. The Export Diff
Patch dialog opens.
3.
In the dialog, enter a name for the patch file and specify the location where you
want to save the patch.
4.
Click Export. A patch file is created in the specified location containing the
differences between the source file versions.
The Export Diff Patch command is only available on files and
folders which contain local or remote changes that have not already
been merged.
Note:
To apply a patch to a local file or folder:
1. Select a versioned file or folder (for example, in the Projects, Files, or Favorites
window) on which you want to apply the patch.
3-54 NetBeans Developing Applications with NetBeans IDE
About Local History
2.
Select Team > (CVS >) Apply Diff Patch from the main menu. The Apply Diff
Patch dialog displays.
3.
In the dialog, type the path or navigate to the patch file you want to apply.
4.
Click Patch. The patch is applied to the selected file and a dialog opens,
confirming that the patch was applied successfully. Click Yes to view changes in
the IDE's Diff Viewer.
Note: Because patches on folders use relative paths to the files within
them, folder patches must be applied on the same folder node that the
patch was created on to ensure that the patch is applied properly.
If you are uncertain to which file or directory the patch should be
applied, you can find the context information in the patch file itself.
Patch files generated by the IDE contain the context in which the
patch was originally created in the first few lines of the file.
3.6 About Local History
The IDE provides built-in versioning support for local projects and files. Similar to
conventional versioning systems, the IDE maintains an internal history of recent
changes made to sources in your local working directory. Whenever you save a file,
this is registered as a 'commit' of a new version of the file in the local history. You can
inspect all revisions in the local history and diff them against the current files.
3.6.1 About the IDE’s Local History Tools
The IDE provides a Graphical Diff Viewer. Enables you to select previously saved
versions of a file and compare differences between versions graphically.
3.6.2 How to Browse Local File History
The IDE's local history functionality automatically maintains previous versions of your
project sources. You can use local history tools to do the following:
■
create versions of a file
■
compare two versions side-by-side
■
revert your current file to a previous version
■
recover previously deleted files
Each time you make changes to, then save (Ctrl+S) a file, the IDE automatically creates
a new version of that file.
To examine previous versions for a specific file:
1. Select the file from the Projects or Files window and select History > Show
History. A graphical Diff Viewer opens in the main window.
2.
Select a version from the table displayed in the upper area of the graphical diff
viewer. Note that versions are chronologically ordered. Upon selecting a version,
the file automatically displays on the left side in the Diff Viewer below.
Versioning Applications with Version Control
3-55
About Local History
Select a version from the table displayed in the upper area of
the graphical diff viewer. Versions are chronologically ordered. Upon
selecting a version, the file automatically displays on the left side in
the Diff Viewer below.
Note:
3.6.3 How to Recover Deleted Files
The IDE's local history repository maintains previous versions of your project sources,
including files or folders which you have recently deleted.You can take advantage of
the IDE's local history tools to recover previously deleted files and reinstate them into
your project.
If you have previously deleted files and they are still maintained in the IDE's local
history repository, you can invoke the Revert Deleted command to retrieve them.
To recover previously deleted files:
■
From the Projects or Files window, right-click the project or directory that
previously contained the files which you deleted and select History > Revert
Deleted. The previously deleted files reappear beneath the project or folder you
selected.
In order to recover deleted files using the Revert Deleted
command, files must not be created or deleted externally.
Note:
3.6.4 How to Revert a File to a Previous Version
The IDE's local history functionality enables you to revert your current file to a
previous version. You do this by using the graphical Diff Viewer.
If you want to examine a previous version and revert only specific changes in your
current file to areas within that version, you can perform a side-by-side comparison
between the two versions in the Diff Viewer, and revert changes in your current file
based on the comparison.
To revert changes in a file using the Diff Viewer:
1. From the Projects or Files window, right-click the file you want to revert changes
to and select History > Show History. The graphical Diff Viewer opens.
2.
Select a version from the table displayed in the upper area of the viewer. The
selected version displays on the left side in the Diff Viewer below and is compared
against your current version.
3.
After examining differences between the two versions, use the icons displayed in
the Diff Viewer to make changes:
■
■
■
Replace. Inserts the highlighted text from the previous revision into the
current revision
Move All. Reverts the file's current version to the state of the selected previous
version.
Remove. Removes the highlighted text from the current version so that it
mirrors the previous version.
Any changes made using the Diff Viewer's icons are immediately applied to the
file's current version.
3-56 NetBeans Developing Applications with NetBeans IDE
About Local History
You can make changes to your current version directly in the graphical Diff Viewer. To
do so, place the cursor directly in the Current Version pane and edit where
appropriate. The current version is instantaneously updated to reflect changes.
3.6.5 How to Adjust Local History Settings
The IDE's local file history support currently enables you to adjust the duration of time
for which files are locally stored on your system.
To adjust the local history storage duration:
1. Select Tools > Options from the main menu.
2.
Select the Team category along the top of the Options window.
3.
Under Versioning Systems in the left column select History.
4.
In the corresponding text field, enter an integer for the number of days you want
the IDE to retain local history versions.
Versioning Applications with Version Control
3-57
About Local History
3-58 NetBeans Developing Applications with NetBeans IDE
4
Working in a Collaborative Environment
4
This chapter describes how to use the collaborative tools that are included in the IDE.
[5]
This chapter contains the following sections:
■
About Working in a Collaborative Environment
■
Working with Tasks
■
Working with the Tasks Window
4.1 About Working in a Collaborative Environment
Developers who are collaborating on a project require a set of tools and an
infrastructure that can help them stay connected to each other and work together as a
team. In addition to sharing sources, team members need to be able to share
information and communicate with each other, and how they share information
depends on the type of information they need to share.
In a collaborative environment, team members have different roles and requirements.
For example, in addition to software developers, a team might also include people in
the following roles:
■
Quality assurance
■
Project management
■
Documentation
■
User experience design
■
Marketing
Not all team members use the same tools, but communication between members can
be simplified when the infrastructure and tools are integrated. The IDE provides
integrated support for the following collaborative tools and services:
Issue Tracking. (Bugzilla, JIRA) An issue tracker enables developers and users to
report and track tasks that are associated with a project and provides a valuable
feedback mechanism for people involved in the project. The integration of an issue
tracking system in the IDE enables developers to find, view and resolve project tasks
from within the IDE.
Version Control Systems. (Subversion, Mercurial, Git) The IDE provides integrated
support for version control systems to help developers manage the history of file
revisions. For more information about using version control systems in the IDE, see
Section 3, "Versioning Applications with Version Control."
Working in a Collaborative Environment 4-1
Working with Tasks
Team Server. A Team Server can provide an infrastructure of services for each project
hosted on the designated server. After you log in to a registered Team Server, you can
open and create projects and access many of the available services from the IDE.
To register and use a Team Server in the IDE, you need to install the Team plugin from
the Update Center. For more about using the Plugins manager to install the Team
plugin, see Section 2.9, "Managing Plugins in the IDE."
4.2 Working with Tasks
You can organize issues that are recorded on a registered issue tracker as tasks in the
IDE. To work with tasks in the IDE you first need to specify the issue tracker that is
used as the task repository for your project. After you register a task repository with
the IDE you can use the Tasks window to perform the following tasks in the IDE:
■
Find, update and resolve tasks
■
Create new tasks
■
Organize tasks by category
■
Create and save queries
4.2.1 About Task Repositories
A task repository is a system for tracking issues that are submitted against a project.
The IDE supports two types of task repositories:
■
■
Local. The IDE includes a local task repository that you can use to store personal
tasks. Tasks in your local repository are only stored on your local file system and
are only accessible to you from within the IDE. You store scheduling details about
tasks in your local repository.
Remote. A remote task repository is generally located on a remote server and is
accessible to other users. You can use a remote repository to submit tasks and
assign responsibility for resolving tasks to members of a team collaborating on a
project.
Remote task repositories typically use an issue tracking system. The IDE provides
support for the Bugzilla and JIRA issue tracking systems. For more details about
the supported issue tracking systems, see the following sites
–
Bugzilla: http://www.bugzilla.org/
–
Atlassian JIRA: http://www.atlassian.com/software/jira/overview
JIRA support requires the JIRA plugin available from the
NetBeans Update Center. For more about details about adding
support for JIRA, see Section 4.2.4, "How to Add Support for JIRA."
Note:
For more on the JIRA plugin, see the following FAQ:
http://wiki.netbeans.org/FaqHowToJira
4.2.2 How to Work with Tasks
You can use the Tasks window in the IDE to find, update and create tasks on a remote
repository or your local repository.
4-2 NetBeans Developing Applications with NetBeans IDE
Working with Tasks
4.2.2.1 Finding and Opening Tasks
From the Tasks window you can perform a quick search for tasks by id or a string in
the summary or open the Find Tasks form to create an advanced query. You can view a
list of tasks that match your saved queries in the Tasks window.
After you save a query the results of the search are listed under the query name in the
Tasks window. You can double-click any task in the list to open the task form in a new
window. You do not need to be online to open a task that is listed under a saved query.
You can update a task in the and save the changes when you are offline and then
submit the changes the next time that you are online.
To perform a quick search of tasks:
1. Choose Window > Tasks from the main menu to open the Tasks window.
Alternatively, choose Team > Find Tasks to open the Find Tasks form and select
the repository from the drop-down list. The drop-down list contains all remote
task repositories that are registered with the IDE.
2.
In the Repositories section of the Tasks window, click the Search task in
repository icon (
) for the repository that you want to search.
3.
Type a task id or string in the dialog box.
When you type in the text field the dialog box displays a list of possible matches
that is based on tasks that you recently viewed in the IDE.
4.
Select a task from the drop-down list.
You can choose Search online Task Repository in the drop-down list to retrieve
more results.
5.
Click Open.
When you click Open the task form opens in a window in the IDE.
4.2.2.2 Creating and Saving Task Queries
The IDE enables you to save and name search queries that you use repeatedly. You can
create and save queries using the Find Tasks form or create a query as a URL. If you
are not online you can open tasks that are listed in the Tasks window. You can also
update a task when you are not online and submit the changes later when you are
online again.
To create and save a task query:
1. Choose Window > Tasks from the main menu to open the Tasks window.
2.
In the Repositories section, click the Create New Query icon (
repository to open the Find Tasks form.
) for the
Alternatively, you can choose Team > Find Tasks in the main menu to open the
Find Tasks form
3.
Specify the search criteria.
4.
Click Search to retrieve the results of the query.
When you click Search the IDE searches the remote repository and displays the
search results in the form.
5.
Click Save Changes in the search form.
6.
Type a name for the query. Click Save.
Working in a Collaborative Environment 4-3
Working with Tasks
After you save the query the new named query is added under the repository node in
the Tasks window.You can expand the named query node to view a list of tasks that
meet the search criteria. You can double-click any task in the list to open the task form
in a new window.
You can open and update tasks in the list when you are not online. If you are not
online the Submit Changes button is disabled in the task form. You can click the Save
Changes button to save any updates that you make to the task and submit the changes
when you are online.
4.2.2.3 Reporting New Tasks
To create a new task from the IDE you need to use your local repository or register a
remote task repository with the IDE and then use the Report a New Task form to
specify the details of the task. If you are not logged in to the task repository you will be
prompted to supply the log in details when you submit the new task. If you are not
online you can create and save the task and then submit the task when you are online.
1.
Open the Tasks window and click the Create New Task icon (
repository in the Repositories section.
) for the
Alternatively, choose Team > Report Task from the main menu and choose a
repository in the Report a New Task form.
2.
Specify the details of the new task.
3.
Click Submit Task to submit a task to a remote repository or choose File > Save
from the main menu to save a task to your local repository.
If you are not online you can click Save Changes and submit the task when you are
online. You can expand the Unsubmitted Tasks node in the Tasks window to view a
list of the tasks that are not submitted. When you are online you can right-click an
unsubmitted task in the list and choose Submit in the popup menu.
4.2.2.4 Updating and Resolving Tasks
The IDE enables you to resolve tasks from within the IDE when you are logged in to a
registered remote task repository. You can also update a task to add scheduling details.
Scheduling details for the task are only stored in your local repository.
To update or resolve a task:
1. Open the task form in the IDE.
2.
Type your comment in the New Comment field.
3.
Select a new status for the task in the Status drop-down list, if applicable.
If you want to resolve the task, select Resolved in the drop-down list and select
the appropriate entry in the Resolution drop-down list.
4.
Expand the My Private Task Details section and enter a Due Date and Schedule
Date, if applicable.
5.
Click Submit Changes to submit changes to a remote repository or choose File >
Save from the main menu to save the changes to the task to your local repository.
If you are not logged in to the remote task repository you will be prompted to log
in to submit your changes. If you are not online you can click Save Changes and
submit the changes when you are online.
4-4 NetBeans Developing Applications with NetBeans IDE
Working with Tasks
4.2.3 How to Add a Task Repository
To use an issue tracker with the IDE you need to register the issue tracker as a task
repository. After the task repository is registered you can use tools in the IDE to find,
report and resolve tasks that are recorded in the task repository.
To add a task repository:
1. Choose Window > Tasks from the main menu to open the Tasks window.
2.
Click the Add Repository icon (
) in the Repositories section.
3.
Specify the connection details. Click OK.
When you click OK, a node for the task repository is added below the Task
Repositories node in the Services window.
To modify the connection properties of a task repository:
1. Choose Window > Tasks from the main menu to open the Tasks window.
2.
Right-click the repository node (
Properties in the popup menu.
) in the Repositories section and choose
3.
Modify the connection details. Click OK.
4.2.4 How to Add Support for JIRA
To enable integrated support for JIRA issue trackers in the IDE you need to install the
JIRA plugin. You can install the JIRA plugin from the NetBeans Update Center. You
need to restart the IDE to complete installation of the plugin.
If the JIRA plugin is not installed and you try to view or work with tasks that are
tracked using JIRA, the IDE prompts you to use the Plugins manager to install the
JIRA plugin.
To install the JIRA plugin from the Create Issue Tracker dialog box:
1. Choose Window > Tasks from the main menu to open the Tasks window.
2.
Click the Add Repository icon (
) in the Repositories section to open the
Create Task Repository dialog box.
3.
Select JIRA in the Connector drop-down list.
4.
Click Download JIRA plugin.
5.
Proceed through the installation process to install the plugin and restart the IDE.
To install the JIRA plugin using the Plugins Manager:
1. Open the Plugins manager by choosing Tools > Plugins from the main menu.
2.
Select the Available Plugins tab.
3.
Locate the JIRA plugin from the list of available plugins.
You can use the Search field in the Plugins manager to help you locate the plugin.
4.
Select the Install checkbox for the JIRA plugin.
5.
Click Install.
6.
Proceed through the installation process to install the plugin and restart the IDE.
For more on how to install the JIRA plugin, see the following FAQ.
Working in a Collaborative Environment 4-5
Working with the Tasks Window
http://wiki.netbeans.org/FaqHowToJira
For more information on features of the JIRA issue tracking system, see the JIRA
website:
http://www.atlassian.com/software/jira/
4.3 Working with the Tasks Window
The Tasks window provides an organized overview of tasks that are recorded in a task
repository. To use the Tasks window you can use the local task repository or register a
remote task repository with the IDE. You can add a remote task repository in the
Services window.
The Categories section of the Tasks window displays lists of tasks that are organized
by category. The Repositories section of the Tasks window displays a list of all tasks
that are the results of a saved query. You can create new categories and queries from
the Tasks window.
4.3.1 How to View Tasks
The Tasks window enables you to see lists of organized tasks. You can organize tasks
by assigning a task to a category. You can also save queries and view the results of the
query in the Tasks window. You can double-click any task entry in a list to open the
task in a new window in the IDE.
You can enter a string in the filter text field in the Tasks window to limit the tasks that
are displayed to the tasks that contain the string in the task summary.
To view tasks that are organized by category:
1. Choose Window > Tasks from the main menu to open the Tasks window.
2.
Expand a category node in the Categories section to see a list of tasks that you
assigned to that category.
3.
Double-click a task in the list to open the task in a window in the IDE.
You can move your cursor over a task entry to view a summary of the task.
To view tasks that are the result of a saved query:
1. Choose Window > Tasks from the main menu to open the Tasks window.
2.
Expand the task repository node in the Repositories section of the Tasks window
to see a list of saved queries.
3.
Expand a saved query to view a list of all tasks that are the result of that query
The entries for tasks that are new or were modified since the last time you opened
the Tasks window are displayed in green text.
4.
Double-click a task in the list to open the task in a window in the IDE.
You can move your cursor over a task entry to view a summary of the task.
To search for a task:
1. Choose Window > Tasks from the main menu to open the Tasks window.
2.
Click the Search Task in Repository icon (
to search.
4-6 NetBeans Developing Applications with NetBeans IDE
) for the repository that you want
Working with the Tasks Window
3.
In the Search Task in Repository dialog box, type the task id or part of the task
summary text, or select from recent tasks in the drop-down list.
4.
(Optional) Select a category from the drop-down list if you want to simultaneously
assign the task to your category. Click Open.
When you click Open the task opens in a window in the IDE.
4.3.2 How to Organize Tasks
You can use custom categories to group tasks in the Tasks window. After you create a
custom category you can assign any task to that category and the task remains in that
category until you explicitly remove it or you add it to a different category. A task can
only be in one custom category. By default, the Categories sections displays all tasks
that are assigned to a custom category regardless of the status of the task.
The Categories section contains three default Schedule categories that group the tasks
that have scheduling details (Today, This Week, All) and one default category for tasks
that were opened recently. To hide a Schedule category, click the filter icon (
) at
the top of the Tasks window and disable the category in the list. To hide the tasks that
are resolved, click the Filter icon and disable Show finished tasks in categories.
To organize tasks by custom category:
1. Choose Window > Tasks from the main menu to open the Tasks window.
2.
Click the Create Category icon (
Category dialog box.
) in the Tasks window to open the New
3.
Enter a name for the category in the dialog box. Click OK.
When you click OK a node for the new category is added under the Categories
section in the Tasks window.
4.
Open a task in the IDE.
5.
Click Add to Category at the top of the task window.
6.
Select a category from the drop-down list. Click OK.
When you click OK, the task is added to the list of tasks under the category node.
You can also right-click a task entry in the Repositories section and choose Set
Category to assign the task to a category.
To remove a task from a custom category:
1. Choose Window > Tasks from the main menu to open the Tasks window.
2.
Expand a category node in the Categories section to see the list of tasks that are
grouped in that category.
3.
Right-click the task entry that you want to remove and choose Remove from
Category in the popup menu.
You can remove a task from a category by assigning the task to a different category.
To remove all completed tasks from a category, click the Remove all finished tasks
from categories icon (
).
To add schedule details to a task:
1. Open the task form in the IDE
Working in a Collaborative Environment 4-7
Working with the Tasks Window
You can add scheduling information to tasks in your local or the remote repository,
however the scheduling information is only stored in your local repository.
2.
Expand the My Private Task Details section.
3.
Enter a Due Date and choose a Schedule Date option in the drop-down list.
4.
Choose File > Save from the main menu.
Tasks that have scheduling details are automatically added to one or more of the
default Schedule categories.
4.3.3 How to Configure Tasks Window Settings
You can use the Options window in the IDE to configure how often tasks are updated
in the Tasks window.
To configure settings for the Tasks window:
1. Select the Tasks tab in the Team category of the Options window.
2.
Specify how often the IDE checks the task repository to update the list of tasks in
the Tasks window.
3.
Specify the number of tasks that are displayed in each section of the Tasks
window. Click Apply.
4-8 NetBeans Developing Applications with NetBeans IDE
5
Working with NetBeans Modules
5
This chapter describes the basics of working with NetBeans Modules.
[6]
This chapter contains the following sections:
■
About NetBeans Modules
■
About the NetBeans Platform
■
Working with NetBeans Modules
■
Working with Rich-Client Applications
■
Module and Rich-Client Application Tasks: Quick Reference
■
Setting Up Modules
■
Using the NetBeans APIs
■
Bundling Supporting Items
■
Registering Modules
■
Communicating Between Modules
■
Building Modules
■
Trying Out a Module
■
About Distributing Modules
■
Branding a Rich-Client Application
■
Distributing Rich-Client Applications
5.1 About NetBeans Modules
A NetBeans module is a Java archive file which contains Java classes written to
interact with the NetBeans APIs. For more information, see Section 5.7, "Using the
NetBeans APIs".
A module identifies itself as a module by an entry in its MANIFEST.MF file. NetBeans
modules are packaged as NBM files (.nbm extension) for non-installer distribution,
usually via the Plugins manager under the Tools menu.
NetBeans modules are written with one of two aims in mind:
■
Extending the IDE - You can very easily generate skeleton code for extending the
IDE's functionality with new features. For example, you can use the skeleton code
to write modules that make your favorite cutting-edge technologies available to
the NetBeans IDE. Or, if you miss some functionality in the IDE, you can add it
Working with NetBeans Modules 5-1
About the NetBeans Platform
yourself, by using the skeleton code to write a module that provides the desired
functionality.
■
Building a rich-client application - You can use the core of the IDE as a platform
on top of which you develop standalone desktop applications. The core of the IDE
is a separate product called the NetBeans Platform. For more information, see
Section 5.2, "About the NetBeans Platform". By basing your application on the
NetBeans Platform, you can save a lot of development time, because you can reuse
the platform's existing features such as menus, toolbars, and windowing systems.
Even though it is a separate product, there is little need to download the NetBeans
Platform separately—you can develop the rich-client application in the IDE and
then exclude the modules that are specific to the IDE but that are superfluous to
your application. Only when you want to use a different version of the platform
than is included in the IDE, does it make sense to download the NetBeans
Platform and install the modules that define the application into it.
5.2 About the NetBeans Platform
The NetBeans Platform provides an application's common requirements—such as
menus, document management, and settings—right out of the box. Building an
application "on top of NetBeans" means that, instead of writing applications from
scratch, you only provide the parts of your application that the NetBeans Platform
doesn't already have. At the end of the development cycle, you bundle your
application with the NetBeans Platform, saving you time and energy and resulting in a
solid, reliable application.
5.3 Working with NetBeans Modules
A NetBeans module is a set of Java classes written to interact with the NetBeans APIs,
for extending the IDE or for creating your own application on the NetBeans Platform.
For more information, see Section 5.2, "About the NetBeans Platform" and Section 5.7,
"Using the NetBeans APIs".
The following table outlines the development cycle of NetBeans modules, from
creation to distribution.
Step
Description
1. Set up the module
1.
Begin creating your module by using the module
project template. For more information, see
Section 5.6.2, "How to Create a Module Project".
2.
Optionally, if the module will consist of a collection of
module projects, use the module suite project
template. For more information, see Section 5.6.4,
"How to Create a Module Suite Project". For example,
the collection may make use of external JAR files. If
this is the case, put the external JAR files on the
module's classpath by using one or more library
wrapper module project templates. For more
information, see Section 5.6.3, "How to Create a
Library Wrapper Module Project".
5-2 NetBeans Developing Applications with NetBeans IDE
Working with Rich-Client Applications
Step
Description
2. Develop the module
1.
Right-click a module project in the Projects window
and choose New > Other.
2.
In the New File wizard, choose the best NetBeans API
template for your programming needs. For more
information, see Section 5.7.1, "Generating Skeleton
API Implementations".
3.
After using a wizard, double-click the file that you
would like to edit. Use the Source Editor to edit the
file.
4.
Refer to the NetBeans API Javadoc.
3. Build the module
Choose Build > Build Main Project or right-click any
project and choose Build Project.
4. Try out the module
Right-click a module project node and choose Run (later
Reload in Target Platform) or Install/Reload in
Development IDE to try out the module. For more
information, see Section 5.12, "Trying Out a Module".
5. Distribute the module
1.
Right-click the module project and choose Create
NBM. For more information, see Section 5.11.2, "How
to Build an NBM File".
An NBM file is created.
2.
Distribute the NBM file for installation via the Plugins
manager.
5.4 Working with Rich-Client Applications
A rich-client application is a complete, functioning, standalone Swing application,
built on top of the NetBeans Platform. For more information, see Section 5.2, "About
the NetBeans Platform".
The following table outlines the development cycle of rich-client applications, from
creation to distribution.
To perform this task:
Follow these steps:
1. Set up the application.
1.
Begin creating your application by using the
NetBeans Platform application project template.
For more information, see Section 5.6.5, "How to
Create a NetBeans Platform Application Project".
2.
Optionally, before going further, brand the
application by providing a splash screen and other
external customizations.
Working with NetBeans Modules 5-3
Working with Rich-Client Applications
To perform this task:
Follow these steps:
2. Develop the application.
1.
Begin creating each distinct part of your application
by using the module project template. For more
information, see Section 5.6.2, "How to Create a
Module Project".
2.
Right-click a module project in the Projects window
and choose New > Other.
3.
In the New File wizard, choose the best NetBeans
API template for your programming needs. For
more information, see Section 5.7.1, "Generating
Skeleton API Implementations".
4.
After using a wizard, double-click the file that you
would like to edit. Use the Source Editor to edit the
file.
5.
Refer to the NetBeans API Javadoc.
3. Build the application.
Choose Build > Build Main Project or right-click any
project and choose Build Project.
4. Try out the application.
Right-click the application project node and choose Run
Project.
5. Brand the application.
■
■
Right-click the application node in the Projects
window and choose Properties. Use the
Application panel to brand the name of the
application launcher.
Right-click the application node again, choose
Branding, and then use the tabs Basic, Splash
Screen, Window System, and Resource Bundles to
brand these details of the application.
5-4 NetBeans Developing Applications with NetBeans IDE
Working with Rich-Client Applications
To perform this task:
Follow these steps:
6. Distribute the application. You can distribute the application in any of the
following ways:
■
Create a ZIP Distribution
■
■
■
Distribute the ZIP file.
Create a JNLP Application
■
■
■
Right-click the
application project and
choose Package as | ZIP
Distribution. For more
information, see
Section 5.15.1, "How to
Build a ZIP
Distribution". The
application's executable
and its clusters are
packaged in a ZIP
distribution.
Right-click the
application project and
choose JNLP | Build.
For more information,
see Section 5.15.2, "How
to Build a JNLP
Application". The
application's JNLP files
are created.
Put the JNLP
application on a server.
Create an installer
■
■
Right-click the
application project and
choose Project
Properties. In the
Installer panel, specify
the installers you would
like to create.
Close the Project
Properties dialog,
right-click the
application project and
choose Package as |
Installers. The installers
are created in the
application 'dist' folder,
visible in the Files
window (Ctrl-2).
Working with NetBeans Modules 5-5
Module and Rich-Client Application Tasks: Quick Reference
To perform this task:
Follow these steps:
7. Distribute updates to the
application.
1.
Right-click the application project and choose
Create NBMs. For more information, see
Section 5.11.2, "How to Build an NBM File". An
NBM file is created for each module project in the
application project. In addition, an autoupdate
descriptor is created. For more information, see
Section 5.13.2, "How to Generate an Autoupdate
Descriptor".
2.
Distribute the NBM file for installation via the
Plugins manager.
5.5 Module and Rich-Client Application Tasks: Quick Reference
This section common tasks you can perform with module projects.
To perform this task:
Follow these steps:
Create a project.
1.
Choose File > New Project (Ctrl-Shift-N).
2.
Select the right template for your project. For more
information, see Section 5.6.1, "About Module Project
Templates".
1.
Choose File > New Project (Ctrl-Shift-N).
2.
From the NetBeans Modules category, select Library
Wrapper Module. For more information, see
Section 5.6.3, "How to Create a Library Wrapper
Module Project".
3.
Follow the steps in the rest of the wizard.
Add a JAR file to a project's
classpath.
Set up deployment dependencies
between projects.
Build a project.
After making a Module Suite project, you can create
module projects in it, or add existing module projects to it.
Then you can set up dependencies among projects in the
suite by using the Libraries panel of each project's Project
Properties dialog box. You create a module suite project as
follows:
1.
Choose File > New Project (Ctrl-Shift-N).
2.
From the NetBeans Modules category, select Module
Suite. For more information, see Section 5.6.4, "How to
Create a Module Suite Project".
3.
Follow the steps in the rest of the wizard.
Choose Build > Build Main Project (F11) or right-click any
project node and choose Build Project. In addition, you
can use the IDE to build the following:
■
■
■
NetBeans Module (.nbm) file. For more information,
see Section 5.11.2, "How to Build an NBM File".
ZIP Distribution. For more information, see
Section 5.15.1, "How to Build a ZIP Distribution".
Java Web Start (.jnlp) file. For more information, see
Section 5.15.2, "How to Build a JNLP Application".
Clean a project.
Right-click the project node and choose Clean Project.
Run a project
Choose Run > Run Main Project (F6) or right-click any
project node and choose Run Project.
5-6 NetBeans Developing Applications with NetBeans IDE
Setting Up Modules
To perform this task:
Follow these steps:
Attach source code to libraries for 1.
debugging.
Add Javadoc to a project.
Set the main project.
Choose Tools > Library Manager in the main menu.
2.
If the JAR file is not already registered in the Ant
Library Manager, create a new library using the Add
Library button.
3.
Select the library in the left panel of the Ant Library
Manager.
4.
In the Classpath tab, click Add JAR/Folder and specify
the location of the JAR file containing the compiled
class files. The JAR must be the copied version in the
project's release/modules/ext/ directory, not its
original location that you picked it up from when
creating the library wrapper project. A library can
contain multiple JAR files.
5.
In the Sources tab, add the folder or archive file
containing the source code.
1.
Choose Tools > Ant Libraries in the main menu.
2.
If the JAR file is not already registered in the Ant
Library Manager, register the JAR file as described
above.
3.
In the Javadoc tab, click Add ZIP/Folder and specify
the location of the Javadoc files.
In the main menu, choose Run > Set Main Project and
choose the project name.
5.6 Setting Up Modules
The IDE contains a set of standard project templates and file templates for setting up
modules. The standard distribution of the IDE contains the following module project
templates:
■
■
■
■
Module. Use a module project as the place where you code your module.
Library Wrapper Module. Use library wrapper module projects to put one or
more library JAR files on a module's classpath.
Module Suite. Use a module suite project to group and deploy a set of
interdependent module projects and library wrapper module projects.
NetBeans Platform Application. Use a NetBeans Platform Application project as
the skeleton framework as the starting point of your own applications.
For more information, see Section 5.6.1, "About Module Project Templates".
The standard distribution of the IDE contains the following module file templates:
■
■
■
■
■
Action. Creates an action that can be invoked from a menu item, pop-up menu,
toolbar button, or keyboard shortcut.
Code Generator. Creates a new menu item in the Insert Code popup in the editor
of your choice.
File Type. Lets the IDE recognize a new type of file.
Java SE Library Descriptor. Adds a new class library to the Ant Library Manager
of the user's IDE.
JavaHelp Help Set. Creates all the files needed for building a JavaHelp help set.
Working with NetBeans Modules 5-7
Setting Up Modules
■
■
Installer/Activator. Creates a ModuleInstall class for a NetBeans module or a
BundleActivator for OSGi bundles.
Layout of Windows. Lets you design the layout of the windows in your
application.
■
Options Panel. Adds a new panel to the Options window.
■
Project Template. Adds a new template to the New Project wizard.
■
Quick Search Provider. Creates a new entry in the Quick Search field.
■
Update Center. Registers an update center in the Plugins manager. As a result, the
user does not need to manually register the Update Center via the Plugins
manager.
■
Window. Creates a new window with an Open action invoked from a menu item.
■
Wizard. Creates a new wizard for creating, for example, new files in the IDE.
■
XML Layer. Creates a layer file for registering folders and files into the central
registry, also known as the System FileSystem.
Some of the file templates are used to kickstart your work with the NetBeans APIs.
Other file templates are used for bundling supporting items, such as project samples
and JavaHelp help sets, with your modules. For more information, see Section 5.7.1,
"Generating Skeleton API Implementations" and Section 5.8, "Bundling Supporting
Items".
5.6.1 About Module Project Templates
The IDE contains a set of standard project templates for module development. The
standard distribution of the IDE contains the following module project templates:
■
■
■
■
Module. Use a module project as the place where you code your module.
Library Wrapper Module. Use library wrapper module projects to put one or
more library JAR files on a module's classpath.
Module Suite. Use a module suite project to group and deploy a set of
interdependent module projects and library wrapper module projects.
NetBeans Platform Application. Use a NetBeans Platform Application project as
the skeleton framework as the starting point of your own applications.
Important Files
Module projects, library wrapper module projects, and module suite projects have an
Important Files node where the IDE stores the Ant script, layer.xml file, and other
project data.
The following table lists the highlights of the Important Files node and whether each is
found in a module project template, a library wrapper module project template, a
module suite project, or all three:
5-8 NetBeans Developing Applications with NetBeans IDE
Setting Up Modules
Item
Description
Availability
XML Layer
The System Filesystem registration file
(layer.xml). You use this file to register new
items in the System Filesystem. When you use
file-level templates, the IDE automatically
registers items for you. For example, when you
use the Action wizard, you specify that a Java
class should be invoked as a menu item, toolbar
button, or keyboard shortcut, and the IDE
registers your specification accordingly in
thelayer.xml file.
Module Project
Build Script
The build script called by the IDE. This build
script only contains an import statement that
imports targets from
nbproject/build-impl.xml. Use the build.xml
to override targets from build-impl.xml or to
create new targets.
All
Module Manifest
The JAR manifest (MANIFEST.MF) with sections
defining attributes for the module. By default,
the MANIFEST.MF file created for a module
project specifies its name, layer.xml, localizing
bundle, and specification version.
Module Project
Project Metadata
The project.xml file. IDE-generated metadata All
file for specifying module dependencies and
classpaths. Although you can edit project.xml
manually, you generally do not need to. When
you use a file-level template to create items,
such as actions, the IDE automatically specifies
module dependencies required by the item in
question. Should you need to specify module
dependencies yourself, use the Libraries panel
in the project's Project Properties dialog box. For
more information, see Section 5.7.1, "Generating
Skeleton API Implementations".
5.6.2 How to Create a Module Project
Use a module project template to create a module project. The module project is the
place where you code your module. Module projects implement the module's features
and functionality that extend the NetBeans APIs, which you kickstart by using file
templates. In addition, module projects include the business logic that integrate the
library wrapper module projects into the module. Code housed in module projects
also provides, for example, the user interface for receiving and processing user input.
To create a module project:
1.
Choose File > New Project (Ctrl-Shift-N).
2.
From the NetBeans Modules category, select Module. Click Next.
3.
In the Name and Location panel, specify the following:
■
■
■
Project Name. Specifies the folder in which the project will be housed,
prepended by the project location, which is specified in the next field.
Project Location. Specifies the location where you want to store the project
metadata and source code.
Project Folder. Specifies the folder where you want to store the project
metadata and source code. The folder is a concatenation of the project location
and the project name.
Working with NetBeans Modules 5-9
Setting Up Modules
■
■
Standalone Module. Specifies that the module does not belong to a module
suite. In addition, you must specify which platform the module will be
compiled and deployed against. To add additional platforms to the list, click
Manage and use the NetBeans Platform Manager.
Add to Module Suite. Specifies that the module belongs to a module suite. If
the module suite is not currently open in the IDE, click Browse to locate the
module suite in your filesystem.
4.
Click Next.
5.
In the Basic Module Configuration panel, specify the following:
■
■
■
■
6.
Code Name Base. Specifies a unique name for the module. A main package
will be created with the same name as the code name base. If your code name
base is org.modules.foo, your default package structure will be
org/modules/foo.
Module Display Name. Specifies the name that will be displayed in the
Projects window.
Localizing Bundle. Specifies location of the Bundle.properties file.
Normally, the default suggestion should be appropriate.
OSGi Bundle. If the "Generate OSGi Bundle" checkbox is selected, an OSGi
bundle will be created, instead of a NetBeans module. The difference will be
visible in the Manifest file.
Click Finish.
5.6.3 How to Create a Library Wrapper Module Project
Use a library wrapper module project template to create a library wrapper module
project. Library wrapper module projects put one or more library JAR files on a
module's classpath. You have to export some or all of the packages as public, and you
need to have a regular module depend on it, or the library wrapper module becomes
useless. The wizard that you use to create the library wrapper module project
automatically exports as public any packages it finds in the JARs.
To create a library wrapper module project:
1.
Choose File > New Project (Ctrl-Shift-N).
2.
From the NetBeans Modules category, select Library Wrapper Module.
3.
In the Select Library panel, specify the following:
■
■
4.
Library. Specifies one or more JAR files that make up the library. Use
Shift-Click and Ctrl-Click to select more than one JAR file. You are encouraged
to only include more than one JAR file if their versions are likely to increment
at the same time.
License. Specifies the License of the JAR files.
In the Name and Location panel, specify the following:
■
■
Project Name. Specifies the folder in which the project will be housed,
prepended by the project location, which is specified in the next field.
Project Location. Specifies the location where you want to store the project
metadata and source code.
5-10 NetBeans Developing Applications with NetBeans IDE
Setting Up Modules
■
■
Project Folder. Specifies the folder where you want to store the project
metadata and source code. The folder is a concatenation of the project location
and the project name.
Add to Module Suite. Specifies that the module belongs to a module suite. If
the module suite is not currently open in the IDE, click Browse to locate the
module suite in your filesystem.
5.
Click Next.
6.
In the Basic Module Configuration panel, specify the following:
■
■
■
7.
Code Name Base. Specifies a unique name for the module. A main package
will be created with the same name as the code name base. If your code name
base is org.modules.foo, your default package structure will be
org/modules/foo.
Module Display Name. Specifies the name that will be displayed in the
Projects window.
Localizing Bundle. Specifies location of the Bundle.properties file. Normally,
the default suggestion should be appropriate.
Click Finish.
5.6.4 How to Create a Module Suite Project
Use a module suite project template to create a module suite. A module suite groups
and deploys a set of interdependent module projects and library wrapper module
projects. For rich-client applications, the module suite project is a skeleton application
to which you can attach a splash screen, a progress bar, a name for the application's
executable, and a title for the application's titlebar.
To create a module suite project:
1.
Choose File > New Project (Ctrl-Shift-N).
2.
From the NetBeans Modules category, select Module Suite.
3.
In the Name and Location panel, specify the following:
■
■
■
■
4.
Project Name. Specifies the folder in which the project will be housed,
prepended by the project location, which is specified in the next field.
Project Location. Specifies the location where you want to store the project
metadata.
Project Folder. Specifies the folder where you want to store the project
metadata and source code. The folder is a concatenation of the project location
and the project name.
NetBeans Platform. Specifies the platform against which the module will be
compiled and deployed. To add additional platforms to the list, click Manage
and use the NetBeans Platform Manager.
Click Finish.
5.6.5 How to Create a NetBeans Platform Application Project
Use a NetBeans Platform Application project template to create the starting point of
your application on top of the NetBeans Platform. This template project provides a
skeleton application to which you can attach a splash screen, a progress bar, a name for
the application's executable, and a title for the application's titlebar.
Working with NetBeans Modules 5-11
Using the NetBeans APIs
To create a NetBeans Platform Application project:
1.
Choose File > New Project (Ctrl-Shift-N).
2.
From the NetBeans Modules category, select NetBeans Platform Application.
3.
In the Name and Location panel, specify the following:
■
■
■
■
4.
Project Name. Specifies the folder in which the project will be housed,
prepended by the project location, which is specified in the next field.
Project Location. Specifies the location where you want to store the project
metadata.
Project Folder. Specifies the folder where you want to store the project
metadata and source code. The folder is a concatenation of the project location
and the project name.
NetBeans Platform. Specifies the platform against which the module will be
compiled and deployed. To add additional platforms to the list, click Manage
and use the NetBeans Platform Manager.
Click Finish.
5.7 Using the NetBeans APIs
The NetBeans APIs are the public interfaces and classes which are available to module
writers. They are divided into specific APIs for dealing with different types of
functionality. The contents and behavior of the Java source packages and its
subpackages, as specified in the NetBeans API List, are the NetBeans APIs.
After you register the NetBeans API sources and Javadoc, you can refer to them in the
Source Editor, while developing NetBeans modules. For more information, see
Section 5.7.3, "How to Register the NetBeans Sources and Javadoc" and Section 5.7.4,
"How to Use the NetBeans Sources and Javadoc".
For the NetBeans API List, see http://bits.netbeans.org/dev/javadoc/.
5.7.1 Generating Skeleton API Implementations
To simplify the process of working with the NetBeans APIs, the NetBeans IDE
provides several wizards that guide you through the initial phase of working with a
NetBeans API. For more information, see Section 5.7, "Using the NetBeans APIs". For
example, the New Action wizard provides the basis of an implementation of the
NetBeans Actions API, the New File Type wizard provides the basis of an
implementation of the NetBeans Datasystems API, and so on.
The NetBeans API wizards are as follows:
■
■
■
■
Module. Use a module project as the place where you code your module.
Library Wrapper Module. Use library wrapper module projects to put one or
more library JAR files on a module's classpath.
Module Suite. Use a module suite project to group and deploy a set of
interdependent module projects and library wrapper module projects.
NetBeans Platform Application. Use a NetBeans Platform Application project as
the skeleton framework as the starting point of your own applications.
Project Templates
Project templates come in two types:
5-12 NetBeans Developing Applications with NetBeans IDE
Using the NetBeans APIs
■
■
Templates that users build on when creating their own project. For example, in the
IDE a user chooses the 'Web Application' project template in the New Project
wizard, then the IDE creates a project consisting of a JSP file, a web.xml file, a
server-specific deployment file, and project metadata within a specific structure
that is useful for web application projects.
Samples that illustrate some aspect of project functionality. For example, in the
Samples directory within the New Project wizard, an Anagram Game is included
to demonstrate Java SE functionality. Samples are a kind of project template; they
have the same behavior as project templates, but they are used for a different
purpose.
A project template is made available to the IDE's New Project wizard once it has been
registered in the layer.xml file. For more information, see Section 5.9.2, "About XML
Layer Files".
You use the New Project Template wizard to create the basic files and to register the
template in the layer.xml file.
Before you can use the New Project Template wizard, you must have project in the IDE
that is structured in exactly the way that you would like it to be available in the New
Project wizard. For example, if you are going to create a new project sample, you must
first lay it out in the IDE. Then use the New Project Template wizard to add the
template to the New Project wizard.
When you make the module that contains the new project template available as an
NBM file, the user can install it via the Plugins manager and then, once it has been
successfully installed, select it from the New Project wizard.
The standard distribution of the IDE contains the following module file templates:
■
■
■
■
■
■
■
Action. Creates an action that can be invoked from a menu item, pop-up menu,
toolbar button, or keyboard shortcut.
Code Generator. Creates a new menu item in the Insert Code popup in the editor
of your choice.
File Type. Lets the IDE recognize a new file type.
Java SE Library Descriptor. Adds a new class library to the Ant Library Manager
of the user's IDE.
JavaHelp Help Set. Creates all the files needed for building a JavaHelp help set.
Installer/Activator. Creates a ModuleInstall class for a NetBeans module or a
BundleActivator for OSGi bundles.
Layout of Windows. Lets you design the layout of the windows in your
application.
■
Options Panel. Adds a new panel to the Options window.
■
Project Template. Adds a new template to the New Project wizard.
■
Quick Search Provider. Creates a new entry in the Quick Search field.
■
Update Center. Registers an update center in the Plugins manager. As a result, the
user does not need to manually register the Update Center in the Plugins manager.
■
Window. Creates a new window with an Open action invoked from a menu item.
■
Wizard. Creates a new wizard for creating, for example, new files in the IDE.
■
XML Layer. Creates a layer file for registering folders and files into the central
registry, also known as the System FileSystem.
Working with NetBeans Modules 5-13
Using the NetBeans APIs
The NetBeans API wizards create the starting point for your development activities.
Once you have worked through a wizard, you build your module's functionality on
top of the files that the wizard creates for you.
Related NetBeans API Javadoc
The NetBeans API wizards create the starting point for your development activities.
Once you have worked through a wizard, you build your module's functionality on
top of the files that the wizard creates for you.
The following table lists the Javadoc that you will need to refer to when building on
top of the skeleton API implementations:
File Template
Related NetBeans Javadoc
Action
Utilities API
File Type
Datasystems API
Module Installer
Module System API
Options Panel
Options Dialog and SPI
Project Template
Project UI API
Project API
Window
Window System API
Wizard
Dialogs API
5.7.1.1 About Actions
Actions are defined by the Actions API.
The Actions API is a standard representation of the actions a user can invoke. It
provides an interface to such IDE elements as toolbars, menus, and keyboard
shortcuts, allowing third parties to create actions that are sensitive to context and
invocable in more than one way. The Actions API offers the ability to write the action
once, and have it automatically apply as appropriate. For example, a user action might
both show up in a toolbar and be selected by a keyboard shortcut, all from the same
implementation.
Actions are typically presented in pop-up menus, or attached to a component such as a
window, node, or data object.
5.7.1.2 How to Create an Action
The New Action wizard creates a new action. For more information, see Section 5.7.1.1,
"About Actions".
To create a new action:
1.
Right-click a module project and choose New > Action.
2.
In the Action Type page, you set the type:
■
■
Always Enabled. Specifies that the action will be invoked from a menu item in
the menu bar, from a toolbar button in a toolbar, or from a keyboard shortcut
anywhere in the IDE.
Conditionally Enabled. Specifies the classes for which the action will be
created. This is normally one of your own business objects. However,
optionally, you can also include one or more of the following, which creates
the action for all classes that subclass them:
5-14 NetBeans Developing Applications with NetBeans IDE
Using the NetBeans APIs
–
DataObject
–
EditCookie
–
EditorCookie
–
OpenCookie
–
Project
3.
User Selects One Node.
4.
User May Select Multiple Nodes. Specifies the conditions under which the action
will be enabled. By default, will be enabled if one, and only one, node holding the
business object of interest is selected. If checked, it will also be enabled if multiple
nodes all holding the desired business object(s) are selected.
5.
Click Next.
6.
In the GUI Registration page, you have to specify how the user will be able to call
the new action.
■
■
■
■
Category. Specifies where the action will be displayed in the Keymap section
of the Options window.
Global Menu Item. Specifies the menu where the action will be displayed as
an item. You can also specify the position within the menu, and whether you
want a separator to appear before it, after it, or both.
Global Toolbar Button. Specifies the toolbar where the action will be
displayed as a button. You can also specify the position within the toolbar.
Global Keyboard Shortcut. Specifies a shortcut that will invoke the action.
Only if Conditionally Enabled is selected in the Action Type page can you set the
following items:
■
■
File Type Context Menu Item. Specifies the file type where the action will be
displayed in the pop-up menu.
Editor Context Menu Item. Specifies the IDE editor where the action will be
displayed in the pop-up menu.
Click Next.
7.
In the Name, Icon, and Location page, you set the following:
■
Class Name. Specifies the name of the new Action class.
■
Display Name. Specifies the action's label. (Optional)
■
■
Icon. Specifies the icon that will accompany the action. For example, if the
action will be invoked by a toolbar button, the icon specified here is displayed
on the toolbar button.
Package. Specifies the name of the package where the class will be housed.
Click Finish.
8.
After completing the wizard, you can do the following:
■
Tweak the layer.xml file to change the icon or to rearrange the position of the
action within the actions provided by the available modules. For more
information, see Section 5.9.2, "About XML Layer Files".
Working with NetBeans Modules 5-15
Using the NetBeans APIs
5.7.1.3 About Code Generators
A code generator is an action that is added to the Insert Code popup, which the user
invokes when pressing Alt-Insert. When invoked, the action is intended to insert
code into the editor. Traditionally, code generators are only found in Java documents
but, from NetBeans 6.1 onwards, they can also be found in all other types of
documents.
Via the Code Generator SPI and the accompanying Code Generator wizard, you can
quickly and easily extend the code generator popup for a specific MIME type with
new entries.
5.7.1.4 How to Create a Code Generator
A code generator is an item added to the popup that appears in an editor when
Alt-Insert is pressed. For more information, see Section 5.7.1.3, "About Code
Generators".
By default, for example, when you press Alt-Insert in a Java class, a constructor can
be generated.
To create a new code generator:
1.
Right-click a module project and choose New > Other. In the New File wizard,
choose Code Generator under the Module Development category.
2.
In the Code Generator page, set the following:
■
■
■
3.
Class Name. Specifies the name of the new code generator.
MimeType. Specifies a unique Multipurpose Internet Mail Extension (MIME)
type that enables the code generator to be registered in the layer.xml file.
Generate Code Generator Context Provider. Specifies that a class should be
created, and registered in the layer.xml file, for adding new objects to the
code generator's lookup.
Click Finish.
5.7.1.5 About File Types
Many file types are recognized by default by the IDE. For example, JSP files, Java
source files, and HTML files are recognized as such and the IDE provides functionality
specific to the file type. For example—for JSP and HTML files, the IDE provides
special syntax highlighting that is different from the syntax highlighting provided for
Java source files. In addition, the menu items provided for JSP files are different from
those provided for HTML files. For example, you can compile a JSP file but not an
HTML file.
Recognition of a file type is generally made possible via its extension. All JSP files have
a .jsp extension, while all Java source files have a .java extension. On the basis of this
distinction, the IDE provides distinct functionality for these file types. You can use the
New File Type wizard to let the IDE recognize additional file types, i.e., file types that
are not recognized by the IDE by default. For example, if you have a file type with the
file extension .xyz, you can let the IDE recognize all files with this extension and then
provide functionality specifically for this file type.
But you can also let the IDE distinguish between XML files. Whether an XML file has
an .xml extension, you can let the IDE provide different functionality for abc.xml than
for def.xml, based on the namespace defined for the XML file in question. If the
namespace of each distinguishable XML file is distinct, the namespace is used to
distinguish the file types in this case.
5-16 NetBeans Developing Applications with NetBeans IDE
Using the NetBeans APIs
When you use the New File Type wizard, the IDE creates the following files for you:
File
Purpose
xxxDataObject.java
A class that extends Class MultiDataObject.
xxxResolver.xml
Declarative resolution of MIME-type.
xxxTemplate.xxx
Dummy template, registered in the layer.xml file as a file
template.
5.7.1.6 How to Create a File Type
The New File Type wizard creates a new file type. For more information, see
Section 5.7.1.5, "About File Types".
To create a new file type:
1.
Right-click a module project and choose New > File Type.
2.
In the File Recognition page, set the following:
■
■
MIME Type. Specifies a unique Multipurpose Internet Mail Extension (MIME)
type that enables the file type to be registered in the layer.xml file. Together,
the MIME type and the filename extension or XML root element enable the
IDE to distinguish one file type from another.
by
–
Filename Extension. Specifies one or more file extensions that the IDE will
recognize as belonging to the specified MIME type. The file extension can
optionally be preceded by a dot. Separators are commas, spaces, or both.
Therefore, all of the following are valid:
.abc,.def
.abc .def
abc def
abc,.def ghi, .wow
–
XML Root Element. Specifies a unique namespace that distinguishes the
XML file type from all other XML file types.
The value that you specify is the namespace associated with the root element of your XML document. Note that this is not the same thing as the
name of the root element. For example, in the following example XML
document, the namespace is "sample":
<mydata xmlns="sample"></mydata>
3.
In the Name, Icon, and Location page, set the following:
■
■
■
■
4.
Class Name. Specifies the name of the new files that will be generated.
Icon. Specifies the icon that will accompany the new file type. For example,
when you see the new file type in the Projects window, Files window, or
Favorites window, it will be identified by the icon specified here. (Optional)
Use MultiView. Specifies that additional files should be generated as the
starting point of an extensible multiview editor.
Package. Specifies the name of the package where the class will be housed.
After completing the wizard, you can do one or more of the following:
Working with NetBeans Modules 5-17
Using the NetBeans APIs
■
■
■
■
■
■
Tweak the layer.xml file to change the icon or to rearrange the position of the
action within the actions provided by the available modules. For more
information, see Section 5.9.2, "About XML Layer Files".
Add properties to the default property sheet used by the new file type.
Use the New Action wizard to add actions to the new file type's pop-up menu.
When you do so, select Conditionally Enabled in the first page of the New
Action wizard.
Use the New Wizard wizard to create a New File wizard that the user will use
to create new files of the new type defined in the New File Type wizard.
Use the New Project Template wizard to add a sample project containing
example files of the new file type to the New Project wizard.
Add advanced support for the file type, such as syntax highlighting.
5.7.1.7 About Module Installers
A module installer is a Java class that provides hooks for running code on startup or
when a module is loaded. It can also run cleanup code when a module is uninstalled
or disabled.
Note: In general, using a module installer is not recommended, because it slows down
startup time. Before using a module installer, make sure that there is no declarative
way of doing what you are trying to do. The main declarative way of installing items
is to use the org.openide.util.lookup.ServiceProvider annotation or create an
XML layer file that declares information about the items your module is installing. For
more information, see Section 5.9.2, "About XML Layer Files".
Then, when they are needed to do actual work, your items will be instantiated.
In addition to providing a module installer class, you need to add an entry to the
MANIFEST file. The Module Installer Wizard creates a skeleton implementation of a
module installer, adds the entry to the MANIFEST file, as well as entries to the
project.xml file, which provides the module's metadata. For more information, see
Section 5.7.1.9, "How to Create a Module Installer/Activator".
5.7.1.8 Installing Modules
Applications can install modules dynamically. Any application can include the Update
Center module, to allow users of that application to download digitally-signed
upgrades and new features via the web, directly into the running application.
Installing an upgrade or a new release does not force users to download the entire
application again. And in an application with multiple modules, upgrades of specific
functionality can be incremental, further improving customer response time and
time-to-market.
5.7.1.9 How to Create a Module Installer/Activator
A module installer (for a NetBeans module) or activator (for an OSGi bundle) is a Java
class that provides hooks for running code on startup or when a module is loaded. It
can also run cleanup code when a module is uninstalled or disabled.
To create a new installer/activator:
1.
Right-click a module project and choose New > Other. In the New File wizard,
choose Installer/Activator under the Module Development category.
5-18 NetBeans Developing Applications with NetBeans IDE
Using the NetBeans APIs
2.
In the New Installer/Activator page, you have to set Package. This specifies the
name of the package where the module installer will be housed. The module
installer will always be named Installer.
5.7.1.10 About Options Panels
An Options panel is a category of the Options window. The Options window is where
the user defines settings, such as the location of the web browser used by the IDE. The
category can be displayed as a primary panel (such as the "General" panel in the IDE)
or as an addition to one of the other panels, for example, the Miscellaneous panel
(such as the "Ant" or "GUI Builder" panel in the IDE's Miscellaneous panel).
You use the Options Panel wizard to create options panels.
5.7.1.11 How to Create an Options Panel
An Options panel adds a category to the IDE's Options window. For more information,
see Section 5.7.1.10, "About Options Panels".
The category can be displayed as a primary panel (such as the "General" panel in the
IDE) or as an addition to an existing panel, for example, the Miscellaneous panel (such
as the "Ant" or "GUI Builder" panel in the IDE's Miscellaneous panel).
To create a new Options panel:
1.
Right-click a module project and choose New > Other. In the New File wizard,
choose Options Panel under the Module Development category.
2.
In the Choose Panel Type page, choose one of the following:
■
■
3.
Create Primary Panel. Specifies that the category will be displayed as a
primary panel (such as the "General" panel in the IDE).
In the Location page, you have to set the following:
■
■
4.
Create Secondary Panel. Specifies that the category will be displayed as an
addition to an existing panel, for example, the Miscellaneous panel (such as
the "Ant" or "GUI Builder" panel in the IDE's Miscellaneous panel).
Class Prefix. Specifies the prefix of the source files generated by the wizard.
Package. Specifies the name of the package where the source files will be
housed.
After completing the wizard, you can do one or more of the following:
■
■
Add a titled border to make the Options panel resemble other NetBeans
Options categories.
Use the GUI Builder to add items such as checkboxes and textfields to the
generated panel.
5.7.1.12 About Quick Search Providers
A quick search provider is a Java class that lets you plug new items into the Quick
Search feature in the IDE or any other application on top of the NetBeans Platform.
Quick search providers are registered in the layer.xml file. You can let the IDE create
and register them by means of the Quick Search Provider wizard.
5.7.1.13 How to Create Quick Search Providers
A quick search provider is a Java class that lets you plug new items into the Quick
Search feature in the IDE or any other application on top of the NetBeans Platform.
Working with NetBeans Modules 5-19
Using the NetBeans APIs
To create a new quick search provider:
1.
Right-click a module project and choose New > Other. In the New File wizard,
choose Quick Search Provider under the Module Development category.
2.
In the File Recognition page, you have to set the following:
■
■
■
■
■
Provider Class Name. Specifies the class name of the stub that the wizard will
generate.
Package. Specifies the package where the stub class will be generated.
Category Display Name. Specifies the display name of the category that the
stub will create.
Command Prefix. Specifies prefix for narrowing the search to the category
that the stub will create.
Position in Popup. Specifies the position of the new item in the within the
Quick Search feature.
5.7.1.14 About Windows
A window component creates a window (also known as 'view') for a module. For
example, the IDE's Projects window is a 'window', just as the Navigator, Output
window, Palette, and Debugger. The main class in each of the modules that define
these windows subclasses Class TopComponent.
Understanding and working with the TopComponent class is the key to creating useful
and reliable windows in the IDE. By using the Window wizard, you can be sure of the
success of the initial development phase. This is because when you use the New
Window wizard, the IDE creates a Matisse GUI Builder form that extends the
TopComponent class.
5.7.1.15 How to Create a Window
A window component creates a window (also known as 'view') for a module. For
more information, see Section 5.7.1.14, "About Windows".
The IDE provides the Window wizard to simplify the initial creation process.
To create a new window component:
1.
Right-click a module project and choose New > Window.
2.
In the Basic Settings page, you set the following:
■
Window Position. Specifies the location of the window component when
open in the IDE. Depending on the modules installed in the platform that
forms the basis of your application, you're able to choose from several window
positions, including the following:
–
bottomSlidingSide. The window component will be available as a button
on the bottom bar of the IDE.
–
commonpalette. The default position of the IDE's Palette for HTML/JSP
code snippets.
–
debugger. The default position of the IDE's Debugger.
–
editor. The default position of the IDE's Source Editor.
–
explorer. The default position of the IDE's Projects window.
–
leftSlidingSide. The window component will be available as a button
on the left sidebar of the IDE.
5-20 NetBeans Developing Applications with NetBeans IDE
Using the NetBeans APIs
■
■
■
–
navigator. The default position of the IDE's Navigator.
–
output. The default position of the IDE's Output window.
–
properties. The default position of the IDE's Properties window.
–
rightSlidingSide. The window component will be available as a button
on the right side of the Source Editor.
Open on Application Start. Specifies whether the window component is open
by default or not.
Keep preferred size when slided-in. Specifies that the size of the window
when minimized will be determined by the preferred size property of the
window. When selected, the following line is added to the TopComponent's
constructor: putClientProperty("netbeans.winsys.tc.keep_preferred_
size_when_slided_in", Boolean.TRUE);
Sliding not allowed.
Closing not allowed.
Undocking not allowed.
Dragging not allowed.
Maximization not allowed. Specify that the window should not have one or
more features that it has by default.
3.
In the Name, Icon, and Location page, you have to set the following:
■
■
■
4.
Class Name. Specifies the name of the new Action and TopComponent classes.
Icon. Specifies the icon that will accompany the window component. For
example, you will see the icon in the label of the window component.
(Optional)
Package. Specifies the name of the package where the class will be housed.
After completing the wizard, you can do one or more of the following:
■
■
■
Use the Form editor to design the window.
Place the window component in a different position. In the layer.xml file,
tweak the Modes section.
Add your own code to componentOpened() and componentClosed() to specify
what will happen when the window opens and closes.
5.7.1.16 About Wizards
Wizards are defined by the Wizard Descriptor API.
The Wizard API lets you create wizard panels that have steps, graphics, left side-bar
text, and a user panel on the right. The Wizard wizard in the IDE helps you by creating
several of the basic Java source files, containing sample code, for you.
Depending on the selections you make in the Wizard Type panel in the New Wizard
wizard, the IDE creates the following Java source files for you:
■
Registration Type: Custom
Wizard Step Sequence: Static
Created files:
–
SampleAction.java
Working with NetBeans Modules 5-21
Using the NetBeans APIs
–
VisualPanel.java (for each wizard step)
–
WizardPanel.java (for each wizard step)
These files are ideal for uncomplicated wizards that progress sequentially from
panel to panel without divergences or reversals. A menu item or toolbar button
invokes the wizard and subsequent steps are generally linear and
forward-directed.
■
Registration Type: Custom
Wizard Step Sequence: Dynamic
Created files:
–
WizardIterator.java
–
VisualPanel.java (for each wizard step)
–
WizardPanel.java (for each wizard step)
These files are for wizards that provide more flexibility to the user. A
WizardDescriptor.Iterator class guides progress from one panel to the next. The
developer has a lot more freedom in coding the wizard, but has a more complex
task since there are many more possibilities to consider. Even though the
Custom/Simple wizard type can also be extended to provide support for panel
skipping and reversals, the Custom/Dynamic type was made for this purpose. For
example, the Add Server Instance wizard offers different panels depending on the
type of server that the user wants to register.
■
Registration Type: New File
Created files:
–
WizardIterator.java
–
VisualPanel.java (for each wizard step)
–
WizardPanel.java (for each wizard step)
–
.HTML file (for the description area in the New File wizard)
These files are for wizards that are used to create new files. This wizard is
registered in the New File wizard via the layer.xml file. All the necessary entries in
the layer.xml file are created for you by the Wizard wizard. In addition, when you
make this choice, the Wizard wizard creates a WizardDescriptor.Iterator.
The iterator lets you provide the direction and sequence of the wizard. The New
File wizard can be as simple or as complex as your needs dictate. An HTML file is
created by the Wizard wizard so that you can provide a description for your new
wizard in the New File wizard.
5.7.1.17 How to Create A Wizard
The Wizard wizard helps you by creating several of a wizard's basic Java source files,
containing sample code, for you. For more information, see Section 5.7.1.16, "About
Wizards".
When you want to create a wizard, you do not always need to use the Wizard wizard.
The table below helps you to chose.
When you want to create a...
Use a...
New Project wizard
New Project Template wizard
5-22 NetBeans Developing Applications with NetBeans IDE
Using the NetBeans APIs
When you want to create a...
Use a...
New Sample wizard
New Project Template wizard
New File wizard
'New File' registration type in the New Wizard wizard
Any other type of wizard
'Custom' registration type in the New Wizard wizard
Depending on the type of wizard you want to create, do the following:
To create a New File wizard or a custom wizard:
1.
Right-click a module project and choose New > Project Template.
2.
In the Wizard Type page, you have to set the following:
■
■
Registration Type. Specifies where the user will be able to find the wizard in
the IDE. For more information, see Section 5.7.1.16, "About Wizards".
Wizard Step Sequence. Specifies whether the Wizard wizard will create an
implementation of this NetBeans API class: WizardDescriptor.Iterator.
If you choose Static, an implementation of this NetBeans API class will not be
created. The default progression from panel to panel will then be supported by
your wizard, sequential progression without divergences or reversals.
If you choose Dynamic, the Wizard wizard will create an implementation of
the WizardDescriptor.Iterator class. This class guides progress from one
panel to the next. The developer has a lot more freedom in coding the wizard,
but has a more complex task since there are many more possibilities to
consider. When you choose "Static", you can also extend the wizard to provide
support for panel skipping and reversals, but the "Dynamic" type was made
for this purpose. For example, the Add Server Instance wizard offers different
panels depending on the type of server that the user wants to register.
■
Number of Wizard Panels. For each panel, the IDE creates two files—a visual
panel (called xxxVisualPanel.java) and a wizard panel (called
xxxWizardPanel) for retrieving the current values from the visual panel. Only
if you enter an integer greater than 0, will you be able to progress to the next
panel in the Wizard wizard.
In the Name, Icon, and Location page, you have to set the following:
3.
■
Class Name Prefix. Specifies the name of the new panels and action class.
■
Package. Specifies the name of the package where the class will be housed.
Only if the wizard will be registered as a New File wizard can you set the
following items:
■
■
■
4.
Display Name. Specifies the display name for the new wizard in the New File
wizard.
Category. Specifies the New File wizard category where the new file wizard
will be located.
Icon. Specifies the icon that will be displayed in the New File wizard.
Click Finish.
After completing the wizard, you can do one or more of the following:
■
Tweak the layer.xml file to change the icon or rearrange the position of the
template in the New Project wizard.
Working with NetBeans Modules 5-23
Using the NetBeans APIs
■
Change the description that will appear in the New Project wizard's Description
box.
To create a new project template or a sample wizard:
1.
Right-click a module project and choose New > Project Template.
2.
In the Select Project page, you have to specify the project that you want to make
available as a project template or sample. You can use the Project drop-down list to
select an open project or you can click Browse to browse to a project in your
filesystem.
Click Next.
3.
In the Name, Icon, and Location page, you have to set the following:
■
■
■
■
4.
Template Name. Specifies the name of the new project template.
Display Name. Specifies the template's label. For example, you will see this
label in the Plugins manager. (Optional)
Category. Specifies the template's category. For example, this will enable the
user to find the template more easily in the New Project wizard. (Optional)
Package. Specifies the name of the package where the classes will be housed.
Click Finish.
After completing the wizard, you can do one or more of the following:
■
■
Tweak the layer.xml file to change the icon or rearrange the position of the
template in the New Project wizard.
Change the description that will appear in the New Project wizard's Description
box.
5.7.2 Extending Skeleton API Implementations
Once you have used the NetBeans API wizards, you extend the generated code by
using the NetBeans APIs. For more information, see Section 5.7.1, "Generating
Skeleton API Implementations". Several tools are provided specifically to help you at
this stage of your development cycle. Among them are the following:
■
■
■
Access to NetBeans sources and Javadoc (for more information, see Section 5.7.4,
"How to Use the NetBeans Sources and Javadoc"). After you register the NetBeans
sources and Javadoc, you can access them inside the IDE (see Section 5.7.3, "How
to Register the NetBeans Sources and Javadoc" for details). This gives you a quick
and easy reference to the API classes and methods that you are implementing.
Search facility for NetBeans APIs (for more information, see Section 5.7.5, "How to
Search for NetBeans APIs"). If you know the class that you need to use, but not the
module (API or non-API) to which it belongs, a search facility is provided to help
you. Once you have identified the module, the IDE registers it in the module
project's projext.xml file.
Code Templates for NetBeans APIs (for more information, see Section 5.7.6, "Code
Templates for NetBeans APIs"). For several common tasks, you can type an
abbreviation in the Java editor, press the registered expansion key (which is the
Tab key, by default), and then the abbreviation will expand to a full piece of code.
5-24 NetBeans Developing Applications with NetBeans IDE
Using the NetBeans APIs
5.7.3 How to Register the NetBeans Sources and Javadoc
The NetBeans Platform Manager is a tool for registering different NetBeans platforms
with the IDE. A NetBeans platform can be an installation of the NetBeans Platform
(see Section 5.2, "About the NetBeans Platform" for details) or an installation of the
NetBeans IDE. The default platform is always configured, and is the running IDE.
Even in the case that a target platform is the complete IDE, you can easily create an
application based only on the platform subset, so that there is little need to download
the NetBeans Platform separately. The NetBeans Platform Manager lists all your
registered NetBeans platforms in the left pane and lists the platform that the IDE
currently deploys to as the default.
You can open the NetBeans Platform Manager by choosing Tools > NetBeans
Platform Manager.
Using the NetBeans Platform Manager, you can:
■
Register a new platform.
■
View a registered platform's available modules.
■
■
Register source code for a platform in the Sources tab. If you register the sources,
you do not need to register Javadoc separately, because Javadoc is included in the
sources. Either the ZIP file containing the sources or the unpacked root folder can
be registered in the Sources tab. You can download the NetBeans sources from
https://netbeans.org/community/sources/.
Register Javadoc documentation for a platform in the Javadoc tab. Javadoc is
available from the Plugins manager as "NetBeans API Documentation". Choose
Tools > Plugins to access the Plugins manager.
Once you have registered a platform, you can configure a module project to use that
platform for deployment. Go to the project's Project Properties dialog box, select the
Libraries node, and choose the appropriate platform in the NetBeans Platform
drop-down list.
5.7.4 How to Use the NetBeans Sources and Javadoc
Once you have registered the NetBeans Sources and Javadoc (see Section 5.7.3, "How
to Register the NetBeans Sources and Javadoc" for details), you can use them as
follows:
■
In the Source Editor, when you use code completion (Ctrl-Space), Javadoc for the
related NetBeans API class is shown in the code completion window.
You do not need to register Javadoc for this feature to work. Just registering the
NetBeans sources suffices.
■
■
In the Source Editor, right-click on a class identifier that belongs to the NetBeans
APIs and choose Show Javadoc (Alt-F1). Javadoc for the related NetBeans API
class is shown in a separate pane in the Source Editor.
In the Source Editor, hold down the Ctrl key and move the mouse over a class
identifier belonging to the NetBeans APIs. A hyperlink appears. Click on the
hyperlink and the cursor jumps to the related NetBeans API class.
5.7.5 How to Search for NetBeans APIs
When using the NetBeans APIs, you may know the class that you need to use, but not
the API (or non-API module) to which it belongs. Until you make the API available to
your module, you are unable to make use of its classes.
Working with NetBeans Modules 5-25
Using the NetBeans APIs
To search for a NetBeans API:
1.
Right-click the Libraries node and choose Add Module Dependency.
The Add Module Dependency dialog box appears
2.
In the Add Module Dependency dialog box, in the Filter textbox, start typing the
name of the class that you need to use. The Module list narrows, showing only the
modules that satisfy the filter.
If the Show Non-API Modules checkbox is unchecked (default), the IDE excludes
any module for which the current module cannot access any packages without an
implementation dependency. These are known as "non-API modules". In other
words, only modules with public packages are included, or friend packages where
this module is a friend.
3.
When you find the module that you need to use, click OK. The IDE adds an entry
to the project.xml file.
5.7.6 Code Templates for NetBeans APIs
In the Java editor in the IDE, type an abbreviation listed below, press the expansion
key (which is Tab, by default), and then the expanded text shown below will be
generated.
■
Abbreviation: 2do
Description: Convert FileObject to DataObject
Expands to:
try {
${dobType type="org.openide.loaders.DataObject" editable="false"
default="DataObject"}
${dob newVarName default="dob"} = ${dobType}.find(${fo
instanceof="org.openide.filesystems.FileObject" default="fo"});
${cursor}
{catch (${etype type="org.openide.loaders.DataObjectNotFoundException"
default="DataObjectNotFoundException" editable="false"}
${exName newVarName default="ex" editable="false"}) {
${exctype type="org.openide.util.Exceptions" editable="false"
default=""}.printStackTrace(${exName});
}
Example:
try {
DataObject dataObject = DataObject.find(myFo);
} catch (DataObjectNotFoundException dataObjectNotFoundException) {
Exceptions.printStackTrace(dataObjectNotFoundException);
}
■
Abbreviation: 2f
Description: Convert FileObject to java.io.File
Expands to:
${fileType type="java.io.File" default="File" editable="false"}
${file newVarName default="f"} =
${FileUtilType type="org.openide.filesystems.FileUtil"
editable="false")}.toFile(${fo
instanceof="org.openide.filesystems.FileObject"
default="fo"});
${cursor}
5-26 NetBeans Developing Applications with NetBeans IDE
Using the NetBeans APIs
Example:
File file = FileUtil.toFile(myFo);
■
Abbreviation: 2fo
Description: Convert java.io.File to FileObject
Expands to:
${fileType type="org.openide.filesystems.FileObject"
default="FileObject" editable="false"}
${file newVarName default="f"}
= ${FileUtilType type="org.openide.filesystems.FileUtil"
editable="false")}.toFileObject(${FileUtilType}.normalizeFile
(${f instanceof="java.io.File" default="f"})); ${cursor}
Example:
FileObject fileObject = FileUtil.toFileObject(FileUtil.normalizeFile(myFile));
■
Abbreviation: Lka
Description: Find all implementations of a certain type registered in
META-INF/services.
Expands to:
${coltype type="java.util.Collection" default="Collection" editable="false"}
${obj newVarName default="obj"} =
${lkptype editable="false" default="Lookup"
type="org.openide.util.Lookup"}.getDefault().lookupAll(${Type}.class);
${cursor}
Example:
Collection<? extends Type> collection =
Lookup.getDefault().lookupAll(Type.class);
■
Variation: lka (i.e., the first character is lowercase)
Description: Find all implementations of a certain type from a local lookup, e.g.,
TopComponent, Node, or DataObject.
Example:
Collection<? extends Type> collection = myNode.lookupAll(Type.class);
■
Abbreviation: Lkp
Description: Find a single typed implementation registered in
META-INF/services.
Expands to:
${Type} ${obj newVarName default="obj"} = ${lkptype editable="false"
default="Lookup"
type="org.openide.util.Lookup"}.getDefault().lookup(${Type}.class);
${cursor}
Example:
Type type = Lookup.getDefault().lookup(Type.class);
Variation: lkp (i.e., the first character is lowercase)
Working with NetBeans Modules 5-27
Using the NetBeans APIs
Description: Find a single implementation of a certain type from a local lookup,
e.g., TopComponent, Node, or DataObject.
Example:
Type type = myNode.lookup(Type.class);
■
Abbreviation: Lkr
Description: Assign a single typed instance from META-INF/services to a Result
object, to which you can listen for changes.
Expands to:
${coltype type="org.openide.util.Lookup.Result" default="Lookup.Result"
editable="false"} ${obj newVarName default="res"} = ${lkptype editable="false"
default="Lookup"
type="org.openide.util.Lookup"}.getDefault().lookupResult(${Type}.class);
${cursor}
Example:
Lookup.Result<? extends Type> res =
Lookup.getDefault().lookupResult(Type.class);
Variation: lkr (i.e., the first character is lowercase)
Description: Assign a single typed instance from a local lookup to a Result object,
to which you can listen for changes.
Example:
Result<? extends Type> all = myNode.lookupResult(Type.class);
■
Abbreviation: lko
Description: Create a lookup for a local object, e.g., TopComponent, Node, or
DataObject.
Expands to:
${Type} ${obj newVarName default="obj"} = ${prov
instanceof="org.openide.util.Lookup.Provider"}.getLookup().lookup(${Type}.class
);
${cursor}
Example:
Type type = myNode.getLookup().lookup(Type.class);
■
Abbreviation: stat
Description: Create code for writing text obtained from a Bundle.properties file
into the status bar.
Expands to:
${coltype type="org.openide.awt.StatusDisplayer" default="StatusDisplayer"
editable="false"}.getDefault().setStatusText(${bundletype
type="org.openide.util.NbBundle" default="NbBundle"
editable="false"}.getMessage(getClass(), "${KEY}"));${cursor}
Example
StatusDisplayer.getDefault().setStatusText(NbBundle.getMessage(getClass(),
"KEY"));
5-28 NetBeans Developing Applications with NetBeans IDE
Bundling Supporting Items
■
Abbreviation: nb
Description: Get a text from a Bundle.properties file.
Expands to:
${coltype type="org.openide.util.NbBundle" default="NbBundle"
editable="false"}.getMessage(${classVar editable="false" currClassName
default="getClass()"}.class, "${KEY}")
Example:
NbBundle.getMessage(DemoAction.class, "KEY")
Variation: nbb (i.e., add an additional 'b' character)
Description: Pass in parameters for formatting the text.
Example:
NbBundle.getMessage(DemoAction.class, "KEY", params)
5.8 Bundling Supporting Items
The IDE provides wizards for bundling various supporting items with your module.
Using these wizards means you can simply point-and-click at the items you want to
include, and then the IDE does all the work for you.
You can use wizards to quickly and easily bundle the following items with your
module:
■
Libraries. External JARs can be included in your NetBeans Platform modules in
various ways:
–
If you are extending the IDE, you can add a new library to the Ant Library
manager, which enables the user to add the library to the classpath of their
application. For this you need a Java SE library descriptor, which the IDE can
create for you.
–
If you are creating extensions to the IDE or are creating your own applications
on the NetBeans Platform, you can include external JARs, NetBeans modules,
and OSGi bundles. You can also include groups and combinations of these
items. The IDE provides support for all of these scenarios.
For details, see Section 5.8.1, "How to Bundle a Library".
■
Project Templates. Project templates are used when users begin to create their own
project. For example, in the IDE a user chooses the 'Web Application' project
template in the New Project wizard, then the IDE creates a project consisting of a
JSP file, a web.xml file, a server-specific deployment file, and project metadata
within a specific structure that is useful for web application projects.
For details, see Section 5.8.2, "How to Bundle a Project Template or Sample".
■
Project Samples. Project samples that illustrate some aspect of project functionality
are often provided by modules that inject a new technology into the IDE. For
example, in the Samples directory within the New Project wizard, an Anagram
Game is included to demonstrate Java SE functionality. A sample is a kind of
project template; it has the same behavior as a project template, but it is used for a
different purpose.
For details, see Section 5.8.2, "How to Bundle a Project Template or Sample".
Working with NetBeans Modules 5-29
Bundling Supporting Items
■
Update Center URLs. When you bundle the URL to a update center, you help your
users, because they will not need to register your update center manually. For
more information, see Section 5.13.1, "About Update Centers".
Instead, when they install your module, your update center will automatically be
accessible via the Plugins manager. As a result, when your users go to Tools >
Plugins manager, they will immediately see your update center in the 'Select
Update Center(s) to connect' list. An update center declaration consists of the URL
to the autoupdate descriptor and a display name. For more information, see
Section 5.8.3, "How to Bundle an Update Center's URL".
■
JavaHelp Help Sets. The IDE provides a number of JavaHelp help sets. You can
add your own, or, if you are creating an application on top of the NetBeans
Platform, you can provide a help set specifically for your application. (You can
also hide help sets provided by other modules.) The files required for a JavaHelp
help set can be generated for you by the IDE. Registration of the help set in the
IDE can also be automated. As a result, you do not need to think about these
infrastructural matters, so that you can focus your time and energy on the content
of your help set.
For more information, see Section 5.8.4, "How to Bundle a JavaHelp Help Set".
■
License. With the creation of any software, there is often a need for that software to
have a software license. The IDE's support for creating modules allows you to add
a license to the module that is under creation.
For more information, see Section 5.8.5, "How to Bundle a License".
5.8.1 How to Bundle a Library
You bundle libraries with your module by using the New Java SE Library Descriptor
wizard. This wizard creates a new Java SE library descriptor, which registers the
library in the Ant Library Manager. For more information, see Section 5.8, "Bundling
Supporting Items".
Java SE Library Descriptor
A Java SE library descriptor is an XML file that, when registered in the layer.xml file,
adds a new class library to the IDE's Ant Library Manager. Whenever the module
containing the library descriptor is enabled, the library is present in the Ant Library
Manager. For example, Struts support provides the Struts libraries in the Ant Library
Manager.
To create a new Java SE Library Descriptor:
1.
Right-click a module project and choose New > Java SE Library Descriptor.
2.
In the Select Library page, you have to specify the library that you want to make
available in the Ant Library Manager via the module. You can select a library that
is available in the Ant Library Manager or you can click Manage Libraries to use
the Ant Library Manager to add the library that you want to make available via
the module.
3.
Click Next.
4.
In the Name, Icon, and Location page, set the following:
5.
■
Library Name. Specifies the name of the new library descriptor.
■
Display Name. Specifies the descriptor's label.
Click Finish.
5-30 NetBeans Developing Applications with NetBeans IDE
Bundling Supporting Items
5.8.2 How to Bundle a Project Template or Sample
The New Project Template wizard creates a new project template or project sample.
For more information, see Section 5.8, "Bundling Supporting Items".
You can create an NBM file that contains your template or sample. For more
information, see Section 5.11.1, "About NBM Files".
When the user installs the NBM file, the template or sample will be available in the
New Project wizard.
To create a new project template or sample:
1.
Right-click a module project and choose New > Project Template.
2.
In the Select Project page, you have to specify the project that you want to make
available as a project template or sample. You can use the Project drop-down list to
select an open project or you can click Browse to browse to a project in your
filesystem.
3.
Click Next.
4.
In the Name, Icon, and Location page, you have to set the following:
■
■
■
■
Template Name. Specifies the name of the new project template.
Display Name. Specifies the template's label. For example, you will see this
label in the Plugins manager. (Optional)
Category. Specifies the template's category. For example, this will enable the
user to find the template more easily in the New Project wizard. (Optional)
Package. Specifies the name of the package where the classes will be housed.
5.
Click Finish.
6.
After completing the wizard, you can do one or more of the following:
■
■
Tweak the layer.xml file to change the icon or rearrange the position of the
template in the New Project wizard.
Change the description that will appear in the New Project wizard's
Description box.
5.8.3 How to Bundle an Update Center's URL
The New Update Center wizard lets you create a module that registers a update center
in the user's Plugins manager. For more information, see Section 5.13.1, "About Update
Centers".
In effect, the module bundles the URL to the update center so that the user does not
need to register the URL manually. For more information, see Section 5.13.4, "Manually
Registering an Update Center URL".
To bundle an update center's URL:
1.
Right-click a module project and choose New > Other. In the New File wizard,
choose Update Center from the Module Development category. Click Next.
2.
In the Update Center Declaration page, you have to set the following:
■
URL to Update Descriptor. Specifies the URL to the autoupdate descriptor.
You can let the IDE generate the autoupdate descriptor for you. For more
information, see Section 5.13.2, "How to Generate an Autoupdate Descriptor".
Working with NetBeans Modules 5-31
Bundling Supporting Items
■
3.
Display Name. Specifies the name that you would like the user to see in their
Plugins manager.
Click Finish.
5.8.4 How to Bundle a JavaHelp Help Set
A JavaHelp help set provides help files that explain the features and functionality of
your module. For more information, see Section 5.8, "Bundling Supporting Items".
To create a new JavaHelp help set:
1.
Right-click a module project and choose New > Other. In the New File wizard,
choose JavaHelp Help Set under the Module Development category.
2.
In the Location page, note the files that will be created and also note that they will
be housed in a new folder called docs:
■
■
■
■
■
■
-about.html. A sample HTML file that is registered in the idx.xml file,
map.xml file, and toc.xml file.
-hs.xml. Helpset file.
-idx.xml. Index file. Using the map ID created in the map.xml file, you add
items to the idx.xml file, with the name of the topic that you want displayed in
the index.
-map.xml. Map file. Each HTML file must be registered in the map file. The
map ID that you create for the HTML file is used in the toc.xml file and
idx.xml file.
-toc.html. Table of contents file. Using the map ID created in the map.xml file,
you add items to the toc.xml file, with the name of the topic that you want
displayed in the table of contents.
-helpset.xml. The reference file that is registered in the layer.xml file.
Note: Each of the names above is prefixed by the name of the project. For example,
if the project name is myproject, the files above would be myproject-about.html,
myproject-hs.xml, etc.
Optionally, if you do not want to include the IDE's default JavaHelp help sets with
your module, you can hide them. Particularly when you are creating a rich-client
application on top of the NetBeans Platform, it is unlikely that you will want the IDE's
JavaHelp help sets to be included with your application.
To hide a JavaHelp help set:
1.
In the Projects window, expand the Important Files node.
2.
In the Important Files node, expand the XML Layer node, and then wait a moment
while the subnodes are loaded.
3.
Expand the <this layer in context> node.
4.
Within the Services/JavaHelp node, select the nodes of the JavaHelp sets that you
want to delete. Choose Delete.
In the layer.xml file, notice that tags have been added, each with a _hidden flag.
When your module is installed, the _hidden flag tells the IDE, or the application built
on the NetBeans Platform, to exclude the specified items.
5-32 NetBeans Developing Applications with NetBeans IDE
Registering Modules
5.8.5 How to Bundle a License
Especially when you want to distribute a module, bundling a license is standard
procedure. For more information, see Section 5.8, "Bundling Supporting Items".
A license is typically a plain text file.
To bundle a license:
1.
Right-click the module project node and choose Properties.
2.
In the Project Properties dialog box, click Packaging.
3.
Specify the packaging information, which includes the license.
5.9 Registering Modules
5.9.1 About the System Filesystem
The system filesystem is the central repository for configuration data in NetBeans. It is
composed at runtime of a stack of XML layer files supplied by modules in the system.
For more information, see Section 5.9.2, "About XML Layer Files".
It is a virtual filesystem that contains configuration information. NetBeans stores a
wide variety of configuration information in the system filesystem. For example, the
system filesystem contains a folder called Menu, which contains subfolders with
names such as File and Edit. These subfolders contain files that represent Java classes
which implement the actions that appear in the File and Edit menus.
When you create a module, you are free to create your own folders in the system
filesystem to store data that relate to your module. You can also add objects to existing
folders. One of the reasons to use the system filesystem is that it enables an application
to be constructed piecemeal from pluggable components (modules) without requiring
the use of a monolithic "master controller" that knows about everything.
One important aspect of a NetBeans virtual filesystem is that it can fire events to notify
the rest of the system when something in it changes. NetBeans listens for changes in
the system filesystem, and if, for example, something creates a new object in one of the
menu folders, that new item will appear in the menu.
5.9.2 About XML Layer Files
Layer files (layer.xml) are small XML files provided by modules, which define a
virtual filesystem. The layer file defines folders and files that will be merged into the
system filesystem that makes up the runtime configuration information that the
NetBeans Platform and its derivatives (such as the IDE) use. For more information, see
Section 5.9.1, "About the System Filesystem".
Layer files help to make it possible for modules to be dynamically installed. The
components of the IDE whose content is composed from folders in the system
filesystem listen for changes in folders and files in a filesystem. If a module is added at
runtime, the system filesystem fires changes; the user interface notices that the
contents of the folder has changed and updates the user interface to reflect the
changes.
New modules created using a module project template (for details, see Section 5.6.2,
"How to Create a Module Project") do not have an XML layer, but you can add one
with the New XML Layer wizard in the New File dialog. You can then expand the
Working with NetBeans Modules 5-33
Registering Modules
node for it under Important Files in your module project to see and modify its
contents. The way it is declared is simple:
■
■
In your jar, provide the layer file, for example,
com/foo/mymodule/resources/layer.xml
In your module's manifest, include the following line somewhere in the top
section:
OpenIDE-Module-Layer: com/foo/mymodule/resources/layer.xml
Just as the New XML Layer wizard creates an empty layer.xml file, so some module
file templates may add entries, creating a new layer if necessary (for details, see
Section 5.7.1, "Generating Skeleton API Implementations"). Other templates just add
Java annotations and so do not need an XML layer.
You can use the System Filesystem Browser to tweak the layer.xml file, or you can
do so manually using code completion in the Source Editor.
5.9.3 How to Edit an XML Layer File
When editing an XML layer file, you can use code completion (Ctr-Space) in the
Source Editor. Alternatively, you can use nodes in a tree view—each node represents
an item that a module makes available to the system.
To edit an XML layer file:
1.
In the Projects window, expand the Important Files node.
2.
Expand the XML Layer node. After a moment, two subnodes appear:
■
■
3.
<this layer>. The folders and files provided by the current module project's
layer file.
<this layer in context>. All the folders and files provided by all the layer files
in all modules available in the system.
Expand a subnode to explore the folders and files within it. When you right-click a
subnode, you can, for example, rename it. You can also use actions such as "Cut",
"Copy", and "Paste". In addition, you can drag a subnode and drop it elsewhere, to
reorder a folder or a file. All of these actions will result in XML entries being
added to your module project's layer file.
5.9.4 How to View the System Filesystem
The system filesystem is the general registry for publicly accessible data and objects.
For more information, see Section 5.9.1, "About the System Filesystem". It is a virtual
filesystem that contains configuration information. Layer files (layer.xml) define
folders and files that will be merged into the system filesystem. For more information,
see Section 5.9.2, "About XML Layer Files".
To view the system filesystem:
1.
Create a module project. For more information, see Section 5.6.2, "How to Create a
Module Project".
2.
In the Projects window, expand the Important Files node.
3.
Expand the XML Layer node. After a moment, two subnodes appear:
■
<this layer>. The folders and files provided by the current module project's
layer file.
5-34 NetBeans Developing Applications with NetBeans IDE
Communicating Between Modules
■
4.
<this layer in context>. All the folders and files provided by all the layer files
in all modules available in the system.
Expand a subnode to explore the folders and files within it.
When you right-click a subnode, you can, for example, rename it. You can also use
actions such as "Cut", "Copy", and "Paste". In addition, you can drag a subnode
and drop it elsewhere, to reorder a folder or a file. All of these actions will result in
XML entries being added to your module project's layer file.
5.10 Communicating Between Modules
For registration and discovery of any kind of interface or class, in any module within
the system, the NetBeans Platform supports two uniformly suitable solutions:
■
■
Lookup. One of the most fundamental classes in the NetBeans APIs is
org.openide.util.Lookup.
ServiceLoader. This is the new java.util.ServiceLoader class, introduced in
JDK 1.6. For more information, see Section 5.10.1, "About Service Providers".
Factors that might determine which approach to take:
■
■
■
■
■
Lookup is available in versions for older JDKs and thus you can use it as a
replacement of ServiceLoader when running on JDKs older than 1.6.
Lookup is ready to work inside of the NetBeans runtime container. It knows how to
discover all the modules in the system, how to effectively read its defined services,
etc.
Lookup supports listeners. Client code can attach a listener and observe changes in
lookup content. This is a necessary improvement to adapt to the dynamic
environment created by the NetBeans runtime container, where modules can be
enabled or disabled at runtime, which in turn can affect the set of registered
service providers.
Lookup is extensible and replaceable. While the ServiceLoader class in JDK 1.6 is a
final class with hard-coded behavior, the NetBeans Lookup is an extensible class
that allows various implementations. This can be useful while writing unit tests.
Or you can write an enhanced version of lookup that not only reads
META-INF/services but, for example, finds the requested service providers around
the Internet, etc.
Lookup is a general purpose abstraction. While the JDK's ServiceLoader can
de-facto have just one instance per classloader, there can be thousands of
independent Lookup instances, each representing a single place to query services
and interfaces. In fact this is exactly the way Lookup is used in NetBeans—it
represents the context of each dialog, window element, node in a tree, etc.
For a four-part tutorial series that covers Lookup, see NetBeans Selection Management
Tutorial I—Using a TopComponent's Lookup.
5.10.1 About Service Providers
In version 1.3, the JDK started to use a concept called service providers. This concept
introduces a completely declarative style of registration, which is based just on the
current classpath of a Java virtual machine and nothing else. This has an important
advantage greatly contributing to the ease of use of this registration style: in order to
change the set of registered providers, just pick up a JAR file that offers such a
Working with NetBeans Modules 5-35
Building Modules
provider and include it in application classpath. Immediately its provider will be
accessible to all code that searches for it.
The basic idea is that each JAR file (in NetBeans terminology, each module) that
wishes to provide an implementation of some interface, for example
javax.xml.parsers.DocumentBuilderFactory, can create its own implementation of
the interface, say org.sakson.MyFactory, and expose it to the system as a service by
creating a META-INF/services/javax.xml.parsers.DocumentBuilderFactory file
inside of its own JAR file. The file then contains a name of the implementation class
per line. In this example it would contain one line registering the sakson factory:
org.sakson.MyFactory.
The DocumentBuilderFactory.newInstance method then searches for all
META-INF/services/javax.xml.parsers.DocumentBuilderFactory files by using
ClassLoader.getResources("META-INF/services/javax.xml.parsers.DocumentBuil
derFactory"), reads their content, and instantiates the class(es) found there by calling
their default constructors. The first implementation of the DocumentBuilderFactory is
then returned from the newInstance method.
While you can manually create the registration of a service in your module, usually
you will use the org.openide.util.lookup.ServiceProvider annotation, which
creates such a registration for you automatically.
As already mentioned, this style has been in place since JDK 1.3 and is a standard way
to deal with service providers. Not only has NetBeans adopted this style, it is also
gaining in popularity among other Java developers. As a result, JDK 1.6 has
introduced the new utility class java.util.ServiceLoader.
5.11 Building Modules
The IDE uses an Ant build script to build your modules. The IDE generates the build
script based on the options you enter in the project's Project Properties dialog box. You
can set the module's dependencies, versioning, and packaging information in the
Project Properties dialog box. You can further customize program execution by editing
the Ant script and Ant properties for the project.
You can customize the build process by doing any of the following:
■
■
Enter basic options, like module dependencies, packaging settings and versioning
information in the Project Properties dialog box.
Customize the IDE-generated Ant targets or create new targets in build.xml.
To build a module:
1.
In the Projects window, right-click the node of the module project you want to
build.
2.
Choose Build Project.
To build all the modules belonging to a module suite project, right-click the module
suite project and choose Build All.
If the IDE does not support your desired build process, see the harness/README file.
This README file contains detailed descriptions of various file layouts and how to
edit them.
5-36 NetBeans Developing Applications with NetBeans IDE
Trying Out a Module
5.11.1 About NBM Files
An NBM file is a NetBeans module packaged for delivery via the web. For more
information, see Section 5.1, "About NetBeans Modules". The principal differences
between NBM files and module JAR files are:
■
■
■
■
An NBM file can contain more than one JAR file—modules can package any
libraries they use into their NBM file.
An NBM file contains metadata that NetBeans will use to display information
about it in the Plugins manager, such as the manifest contents, the license, etc.
An NBM file may be signed for security purposes.
NBM files are just ZIP files with a special extension. They use the JDK's
mechanism for signing JAR files. Unless you are doing something unusual, you
need not worry about the contents of an NBM file—just let the standard Ant build
script for NBM creation take care of it for you.
5.11.2 How to Build an NBM File
An NBM file is a NetBeans module in binary format, packaged for delivery via the
web. For more information, see Section 5.11.1, "About NBM Files".
To build an NBM file:
1.
In the Projects window, right-click the node of the module project you want to
build.
2.
Choose Create NBM.
To build all NBM files in a module suite:
1.
In the Projects window, right-click the node of the module suite project you want
to build.
2.
Choose Create NBMs.
When you choose Create NBMs in a module suite's contextual menu, an
autoupdate descriptor is generated by the IDE. The autoupdate descriptor
describes all the NBM files. When you put the autoupdate descriptor on a server,
your users can access it and retrieve your NBM files via the autoupdate descriptor.
For more information, see Section 5.13.2, "How to Generate an Autoupdate
Descriptor".
5.12 Trying Out a Module
When you test your module, it is advisable to deploy it to a different instance of the
IDE. This way, if there are problems with your module that cause the IDE to crash, you
will not lose unsaved work or need to restart the IDE.
However, if you are confident of your module or if you are demonstrating module
development, you may want to see the effect of your module more quickly. In these
cases, it is worth taking the risk that you will lose unsaved files and have the
inconvenience of being required to restart the IDE, if bugs in your module cause the
IDE to crash.
To install a module project in a new instance of the IDE:
1.
Choose a target platform. For more information, see Section 5.7.3, "How to
Register the NetBeans Sources and Javadoc".
2.
Right-click the module project and choose Run.
Working with NetBeans Modules 5-37
About Distributing Modules
The target platform starts up and installs the module project. By default, the target
platform is the IDE in which you are developing your module project.
3.
If you wish to test changes to the module without restarting the target platform,
right-click the module project and choose Reload in Target Platform.
To install a module project in the current instance of the IDE:
1.
Save your work.
2.
Right-click the module project and choose Install/Reload in Development IDE.
5.12.1 Deploying Modules
When an application based on a NetBeans Platform is run, the NetBeans Platform's
Main class is run. It then finds the available modules and builds an in-memory registry
of them, and performs any tasks they specify for startup. Generally, a module's code is
loaded into memory as it is needed.
5.13 About Distributing Modules
You can distribute a module in one or more of the following ways:
■
■
Contribute to the Plugin Portal. This is the central location where you can upload
your NetBeans modules so that they may be easily found, all in the same place.
For more information, see http://plugins.netbeans.org/PluginPortal/.
Create your own update center. With your own update center, you can distribute
modules that are specific to your application, as well as modules that are not
appropriate for distribution via the Plugin Portal. For more information, see
Section 5.13.1, "About Update Centers".
For quick updates to your modules or for making modules available to a smaller
subset of end users, creating your own update center might be a good idea.
■
Other. You can simply zip up a module's sources and transfer them via e-mail or
upload them onto a server. Alternatively, you can use the IDE to create a binary
NBM file, which you can then transfer via e-mail or upload to a server, instead of
transferring the sources.
5.13.1 About Update Centers
An update center is nothing more than an XML file that is known as the “autoupdate
descriptor”, together with the modules that it describes. The autoupdate descriptor
lists all the modules that you would like to make available. For each module, the
autoupdate descriptor provides information such as a name, a description, and a list of
modules that it depends on.
Most importantly, the autoupdate descriptor specifies a URL for each module that it
describes. Each module, in binary NBM file format, must live on a server. For more
information, see Section 5.11.1, "About NBM Files".
The autoupdate descriptor itself must also live on a server. The server where the
autoupdate descriptor lives need not be the same server as where the modules live.
The modules can live together on the same server or be spread across different servers.
After the autoupdate descriptor and its associated modules are on a server, you must
let your end users know that they are there. The URL to the autoupdate descriptor
must be registered in the end users' IDEs. This can be done in one of two ways:
5-38 NetBeans Developing Applications with NetBeans IDE
About Distributing Modules
■
■
Automatically. You can provide a module that registers the URL to the update
center for them. This module can be generated in the IDE, without any coding on
your part.
Manually. You must tell your end user what the URL to your autoupdate
descriptor is. Then, the end users need to register the URL to your autoupdate
descriptor. They must then do so manually in the Plugins manager.
Once the URL to the update center is registered, your end users can access your
modules via the Plugins manager, which they can find under the Tools menu. Not only
new modules, but new versions of existing modules can be distributed in this way.
5.13.2 How to Generate an Autoupdate Descriptor
An autoupdate descriptor is an XML file that describes the NBM files that you want to
make available to your users. For more information, see Section 5.11.1, "About NBM
Files".
For example, an autoupdate descriptor specifies a name, a description, and a URL for
each module that it describes.
When you put an autoupdate descriptor on a server, and make its URL available to
your users, your users are able to register the URL in your IDE. After registering the
URL, they can access your NBM files via the Plugins manager, under the Tools menu.
To generate an autoupdate descriptor:
1.
If you have not already done so, create a module suite project. For more
information, see Section 5.6.4, "How to Create a Module Suite Project".
2.
In the Projects window, right-click the node of the module suite project you want
to build.
3.
Choose Create NBMs.
The IDE builds the NBM files in the module suite project. The IDE also creates a
file called updates.xml, which is the autoupdate descriptor. To see it, look in the
Files window (Ctrl-2).
4.
Tweak the autoupdate descriptor, if needed. For example, customize the
distribution element for each module, so that the URL to the NBM file is correct.
5.13.3 How to Bundle an Update Center's URL
The New Update Center wizard lets you create a module that registers a update center
in the user's Plugins manager. For more information, see Section 5.13.1, "About Update
Centers". In effect, the module bundles the URL to the update center so that the user
does not need to register the URL manually. For more information, see Section 5.13.4,
"Manually Registering an Update Center URL".
To bundle an update center's URL:
1. Right-click a module project and choose New > Other. In the New File wizard,
choose Update Center from the Module Development category. Click Next.
2.
In the Update Center Declaration page, you have to set the following:
■
URL to Update Descriptor. Specifies the URL to the autoupdate descriptor.
You can let the IDE generate the autoupdate descriptor for you; for details, see
Section 5.13.2, "How to Generate an Autoupdate Descriptor".
Working with NetBeans Modules 5-39
Branding a Rich-Client Application
■
3.
Display Name. Specifies the name that you would like the user to see in their
Plugins manager.
Click Finish.
5.13.4 Manually Registering an Update Center URL
If you have not been provided with a module that bundles an update center's URL,
you need to register the update center manually. For more information, see
Section 5.8.3, "How to Bundle an Update Center's URL".
Once you have registered the update center, you can access its modules via the Plugins
manager, which you can access under the Tools menu.
To manually register an update center's URL:
1.
Choose Tools > Plugins.
The Plugins manager opens.
2.
Click the Settings tab at the top of the Plugins manager.
3.
Click Add.
4.
Type the name and URL of the autoupdate center. The name can be anything you
want it to be. Click Finish.
5.
Click Close.
You have now manually registered the update center's URL.
5.14 Branding a Rich-Client Application
Once the functionality of an application built on top of the NetBeans Platform is
complete, the appearance of the application still closely resembles the default
NetBeans Platform. You can use the IDE to personalize your application. In particular,
you can do the following:
■
Replace the application's splash screen.
■
Replace the strings in the NetBeans Platform's bundle files.
■
Define a progress bar.
■
Define the application's title bar.
■
Disable one or more of the window system's default features.
To brand a rich client application:
1.
Right-click the application project in the Projects window and choose Branding.
2.
In the Branding editor, click the tab related to your branding needs:
3.
■
Basic. Brand the title bar and the application icons.
■
Splash Screen. Brand the splash screen and progress bar.
■
Window System. Remove features from the window system.
■
Resource Bundles. Customize the strings provided by the NetBeans Platform.
Click OK to confirm your changes and exit the editor.
5-40 NetBeans Developing Applications with NetBeans IDE
Branding a Rich-Client Application
5.14.1 How to Brand the Window System
You can brand an application's window system by disabling the following of its
default features:
■
■
Window Drag and Drop. The ability to reorganize the window layout by
dragging windows to new positions.
Floating Windows. The ability for windows to be undocked into a standalone
frames.
■
Sliding Windows. The ability to minimize (slide out) a window.
■
Maximized Windows. The ability to maximize a window by clicking its header.
■
Closing Windows. The ability to close a document/non-document window.
■
■
Window Resizing. The ability to adjust the width and height of windows by
dragging splitter bars.
Respect Minimum Size When Resizing Windows. The ability to resize internal
windows to zero width/height using splitter bars.
To brand the window system:
1.
Right-click the application project in the Projects window and choose Branding.
2.
In the Branding editor, click Window System.
3.
Deselect the items listed above, depending on your needs.
4.
Click OK to confirm your choices and exit the Branding editor.
5.14.2 How to Add a Splash Screen
1.
Right-click the application project in the Projects window and choose Properties.
2.
In the Project Properties dialog box, click Splash Screen. Do the following:
3.
■
Define the progress bar.
■
Choose a splash screen.
Click OK to confirm your choices and exit the Project Properties dialog box.
5.14.3 How to Remove Unwanted Modules
You can exclude unwanted modules from a standalone application, leaving only those
you really need. By default, all the modules that the IDE uses are included.
To remove unwanted modules:
1.
Right-click a module-suite project and choose Properties.
2.
In the Project Properties dialog box, click Libraries.
3.
Uncheck all the clusters that you want to exclude from the standalone application.
The only cluster that all standalone applications need is platformNNN.
4.
Expand the nodes of the clusters that you want to keep, and uncheck any module
that you want to exclude from the cluster.
5.
Click OK.
When you brand a standalone application (for details, see Section 5.14, "Branding a
Rich-Client Application"), the IDE asks you whether it should exclude IDE-related
Working with NetBeans Modules 5-41
Distributing Rich-Client Applications
modules for you. If you do not let the IDE exclude IDE-related modules, you can do so
manually using the steps above.
5.15 Distributing Rich-Client Applications
Rich-client applications are complete, functioning, standalone Swing applications. The
Swing libraries provide a rich collection of user interface elements. However, the
Swing libraries do not provide a mechanism for joining the user interface elements
together into an application. For this purpose, NetBeans provides the NetBeans
Platform, which is the application framework on top of which you build your
application. For more information, see Section 5.2, "About the NetBeans Platform".
Each distinct part of a rich-client application is provided by a separate module, several
of which serve to provide the user interface elements from the Swing libraries. For
example, if your rich-client application is an editor, you might have one module that
provides syntax highlighting, while another provides file templates.
Branding
Before you distribute a rich-client application, you need to consider whether you want
to leave it resembling NetBeans. For example, your rich-client application uses the
NetBeans splash screen by default. Branding, the final stage before creating
distribution packages, involves making decisions such as what the splash screen
should look like and whether the application will include a progress bar during
startup. In the module suite project's Project Properties dialog box, you define such
settings. For more information, see Section 5.14, "Branding a Rich-Client Application".
While branding, also consider whether your rich-client application needs all the
modules that the IDE uses. For example, if your rich-client application is not an editor,
you will not need the modules that relate to editor functionality. Similarly, it is unlikely
that all of the IDE's menu items and toolbar buttons are needed by your application.
Releasing
Once a rich-client application is branded, you can distribute it over the web as a
web-startable JNLP application. Alternatively, you can distribute the ZIP file. See
Section 5.15.2, "How to Build a JNLP Application" and Section 5.15.1, "How to Build a
ZIP Distribution" for details. Updates to the modules that make up a rich-client
application can be distributed via the Update Center.
5.15.1 How to Build a ZIP Distribution
Once your rich-client application is complete, one way to distribute it is via a ZIP file.
The IDE can create the ZIP file for you, containing the application.
To build a ZIP distribution:
1.
In the Projects window, right-click the node of the application.
2.
Choose Package as | ZIP Distribution.
5.15.2 How to Build a JNLP Application
Java Web Start is a helper application that becomes associated with a Web browser.
When a user clicks on a link that points to a special launch file (JNLP file), it causes the
browser to launch Java Web Start, which then automatically downloads, caches, and
runs the given Java Technology-based application. The entire process is typically
completed without requiring any user interaction, except for the initial single click.
To build a JNLP application:
5-42 NetBeans Developing Applications with NetBeans IDE
Distributing Rich-Client Applications
1.
In the Projects window, right-click the node of the module suite project you want
to build.
2.
Choose JNLP | Build.
3.
Depending on whether you have set up the module suite project as a standalone
application, do the following:
■
■
If you have already set up the module suite project as a standalone project, the
IDE builds a jnlp folder in your build folder and adds a master.jnlp file in
your main project folder. Open the Files window to see the JNLP file and the
folder within the build folder.
If you have not set up the module suite project as a standalone application, the
IDE will not be able to build the JNLP application. The IDE will tell you this
by means of a dialog box.
–
Click Configure Application in the dialog box. The Project Properties
dialog box opens. Click Build.
–
Select the Create Standalone Application radio button. Click OK.
–
In the Projects window, right-click the node of the module suite project
you want to build.
–
Choose Build JNLP Application.
The IDE builds a jnlp folder in your build folder and adds a master.jnlp
file in your main project folder. Open the Files window to see the JNLP file
and the folder within the build folder.
5.15.3 How to Run a Rich-Client Application
Unless your NetBeans modules are designed to be deployed as standalone modules,
you should always deploy them by deploying the application (the module suite
project) that contains them. If you run the Run Project command on an individual
module that is part of an application built on top of the NetBeans Platform, the IDE
only deploys that module itself.
To deploy a standalone application:
■
In the Projects window, right-click the module suite project and choose one of the
following:
–
Run Project. Starts the target platform, undeploys the standalone application
if it is already deployed, deploys the standalone application to the target
platform, starts the platform and loads the application as one unit.
–
Run JNLP Applications. Builds and runs the application as a JNLP
application. For more information, see Section 5.15.2, "How to Build a JNLP
Application".
5.15.4 How to Use the NetBeans Shared JNLP Repository
By default, the JNLP application generated for a module suite project always contains
all the module suite project's modules as well as all the modules that the module suite
project depends on. This may be useful for intranet usage, but it is a bit less practical
for wide internet use. When on the internet, it is much better if all the applications
built on the NetBeans Platform refer to one repository of NetBeans modules, which
means that such modules are shared and do not need to be downloaded more than
once.
Working with NetBeans Modules 5-43
Distributing Rich-Client Applications
There is such a repository for NetBeans modules. It does not contain all the modules
that NetBeans IDE has, such as, for example, the ant module, which is not JNLP-ready,
but it contains enough to make many JNLP applications possible.
To use the shared JNLP repository:
1.
In the Projects window, expand the Important Files node.
2.
Double-click NetBeans Platform Config.
3.
Add the jnlp.platform.codebase property with, as its value, the URL of the 5.0
JNLP Repository:
jnlp.platform.codebase=http://www.netbeans.org/download/5_0/jnlp
5-44 NetBeans Developing Applications with NetBeans IDE
6
Creating Java Projects
6
This chapter describes creating and working with standard and free-form Java
projects, including using projects using templates.
[7]
This chapter contains the following sections:
■
About Creating Java Projects
■
Using Java Project Templates
■
Importing an Eclipse or JBuilder Project
■
Setting the Main Project
■
Adding Multiple Sources Roots to a Project
■
Sharing a Library with Other Users
■
Adding a Javadoc to a Project
■
Setting the Target JDK
■
Moving, Copying, and Renaming a Project
■
Deleting a Project
6.1 About Creating Java Projects
A project is a group of source files and the settings with which you build, run, and
debug those source files. In the IDE, all Java development has to take place within a
project. For applications that involve large code bases, it is often advantageous to split
your application source code into several projects
The IDE includes several project templates designed to support different types of
development including web applications, general Java applications, and so forth. The
IDE's set of standard project templates automatically generate an Ant script and
properties. The IDE also contains free-form project templates that you can use to base a
project on an existing Ant script. In addition to Ant, the IDE also supports Maven, an
open source build management tool. Maven uses a project object model (POM) that
describes a set of standards that all projects using Maven follow allowing for
consistency between projects. You can easily create a Maven project by choosing a
Maven project template and providing a few project details.
You do not need an in-depth understanding of Ant or Maven
to work with the IDE as the provided set of standard project templates
automatically generate an Ant script or Maven POM files based on the
options you enter in the IDE.
Note:
Creating Java Projects 6-1
Using Java Project Templates
For more information about Ant, see http://ant.apache.org/.
This chapter focuses primarily on the use of Ant scripts to build a project. For
information on using Maven to build and manage a project in JDeveloper, see
"Working with Maven in the IDE" and "Working with Maven Repositories." For more
information about Maven, see http://maven.apache.org/.
When you finish creating a project, it opens in the IDE with its logical structure
displayed in the Projects window and its file structure displayed in the Files window:
■
■
The Projects window is the main entry point to your project sources. It shows a
logical view of important project contents such as Java packages and Web pages.
You can right-click any project node to access a context menu of commands for
building, running, and debugging the project, as well as opening the Project
Properties dialog box. The Projects window can be opened by choosing Window
> Projects.
The Files window shows a directory-based view of your projects, including files
and folders that are not displayed in the Projects window. From the Files window,
you can open and edit your project configuration files, such as the project's build
script and properties file. You can also view build output like compiled classes,
JAR files, WAR files, and generated Javadoc documentation. The Files window
can be opened by choosing Window > Files.
If you need to access files and directories that are outside of
your project directories, you can use the Favorites window. You open
the Favorites window by choosing Window > Favorites. You add a
folder or file to the Favorites window by right-clicking in the
Favorites window and choosing Add to Favorites.
Note:
6.2 Using Java Project Templates
You can facilitate creating a Java application by using one of the available templates
provided by the IDE. For each type of Java application, the IDE provides two types of
project templates:
■
■
Standard templates. Templates in which the IDE controls all source and classpath
settings, compilation, running, and debugging.
Free-form templates. Templates in which your own Ant script controls all
classpath settings, compilation, running, and debugging.
6.2.1 Standard Project Templates
With standard project templates, the IDE controls all aspects of how your application
is built, run, and debugged. You set a project's source folder, classpath, and other
project settings when creating the project and in the Project Properties dialog box. The
IDE generates an Ant build script in which all of your settings are stored.
The IDE comes with the following standard templates:
Standard Java Applications:
■
■
–
Java Application - An empty Java SE project with a main class.
–
Java Class Library - An empty Java class library with no main class.
–
Java Project with Existing Sources - A Java SE project with existing sources.
JavaFX Applications:
6-2 NetBeans Developing Applications with NetBeans IDE
Using Java Project Templates
–
JavaFX Application (without FXML) - An empty JavaFX application with no
main class.
–
JavaFX Application With FXML - An empty JavaFX FXML-enabled
application.
–
JavaFX Preloader - A JavaFX application with a preloader to facilitate loading
the application particularly in applet or webstart mode.
–
JavaFX Swing Application - A JavaFX application enabled with Swing and a
main class containing sample JavaFX-n-Swing code.
Web Applications:
■
–
Web Application - An empty web application.
–
Web Application with Existing Sources - A web application with existing
sources.
EJB Modules:
■
–
EJB Module - An empty EJB module.
–
EJB Module with Existing Sources - An EJB module with existing sources.
Enterprise Applications:
■
–
Enterprise Application - An empty enterprise application.
–
Enterprise Application with Existing Sources - An enterprise application with
existing sources that conform to the Sun Java BluePrints Guidelines.
Enterprise Application Clients:
■
–
Enterprise Application Client - An empty enterprise application client.
–
Enterprise Application Client with Existing Sources - An enterprise
application client with existing sources.
NetBeans Modules:
■
–
Module Project - An empty module with a layer.xml file and a
Bundle.properties file. You use a module to implement the logic that
integrates the library wrappers into the platform and provides a user interface
for receiving user input.
–
Module Suite Project - A library wrapped in a module project and a
Bundle.properties file. You use a library wrapper to put a library JAR file on
a module's classpath and export some or all of the JAR file's packages from the
module as public packages.
–
Library Wrapper Module Project - An empty module suite. You use a module
suite to group and deploy a set of interdependent modules and library
wrappers.
Depending on what modules you have installed, your IDE may contain additional
templates. Consult the help for your additional modules for more information.
For information on creating an Web Application Project, see Chapter 12, "Developing
Web Applications."
For information on creating an Enterprise Application Project, see Chapter 14,
"Developing Enterprise Applications."
For information on creating an EJB Module Project, see Chapter 16, "Developing with
Enterprise Beans."
Creating Java Projects 6-3
Using Java Project Templates
6.2.1.1 Source Folders
In standard projects, you can have multiple source folders and multiple JUnit test
folders for each Java SE, web, and EJB project.
Right-click the Source Packages node of a project and choose Properties to add or
remove source folders. A single source folder cannot, however, be added to more than
one project. If you need a source folder to be part of several projects, you should create
a separate project for the source folder and add it to the classpath of each of your
projects.
For information on add multiple sources to a project, see Section 6.5, "Adding Multiple
Sources Roots to a Project."
6.2.1.2 Project Settings
When you create a project from a standard project template, the IDE generates an Ant
script that controls all aspects of program compilation, execution, and debugging.
Right-click a project node in the Projects window and choose Properties to set basic
project settings in the Project Properties dialog box. All changes are immediately
registered in the project's Ant script. You can also set more complex options by editing
the project's Ant script and properties file directly.
For information on editing Ant build scripts, see Section 6.2.3.3, "Editing
IDE-Generated Ant Scripts."
6.2.1.3 Switching a Java SE Project to a JavaFX Deployment Model
If you have an existing standard Java SE project and you want to take advantage of the
JavaFX deployment model, you can quickly switch your current project by choosing
Properties from the project’s context menu, selecting the Deployment category, and
clicking Switch Project to JavFX Deployment Model. This feature saves you the time
consuming effort of creating a new JavaFX application and manually copying over the
project artifacts to the new project and resetting options, removing the main class, and
so on.
Instead of a main class, JavaFX projects use an extension to the Application class.
When you switch the project, the IDE creates a project_nameFX.java class and
automatically adds it to the Source Packages folder of your SE project. You then have
the option of using JavaFX customizations, such as specifying a JavaFX runtime
version or adding custom manifest entries through the Project Properties dialog box.
Be aware that once a Java SE project has been switched to a
JavaFX deployment model, it cannot be automatically reverted.
Note:
6.2.1.4 Adding a JavaFX Class to a Java SE Project
You can add a JavaFX class to a Java SE project without having to manually add a
JavaFX runtime dependency. This feature is particularly advantageous for making a
Java class library project usable for JavaFX development. When you select the Keep
JavaFX RT artifacts on Compile Classpath if not present by default option from the
Deployment category of the Project Properties dialog box, the IDE automatically
updates the jfxrt.jar file dependency. If you later change the project platform, the
dependency is corrected for you.
6-4 NetBeans Developing Applications with NetBeans IDE
Using Java Project Templates
6.2.1.5 Project Folders
Each standard project has a project folder where the IDE stores the Ant script, project
metadata, and output folders. In projects with existing sources, you can place the
project source directories in the same location as the project folder or in a separate
location. In empty projects, the source root is always in the same location as the project
directory.
Table 6–1
Standard Project Folder Contents
Item
Description
build.xml
The build script called by the IDE. This build script only
contains an import statement that imports targets from
nbproject/build-impl.xml. Use the build.xml to override
targets from build-impl.xml or to create new targets.
nbproject
The directory that contains the project Ant script and other
metadata.This directory contains:
■
■
■
build-impl.xml. The IDE-generated Ant script. You should
never edit build-impl.xml directly. Always override its
targets in build.xml.
project.properties. Ant properties used by the IDE to
configure the Ant script. Although you can edit this file
manually, you generally do not have to, as it is
automatically updated by the IDE when you configure the
project's properties.
project.xml and genfiles.properties. IDE-generated
metadata files. Although you can edit project.xml
manually, for standard projects it is generally not necessary.
Never edit genfiles.properties.
nbproject/private
The directory that holds properties that are defined for you only.
If you are sharing the project over VCS, any properties you
define in private.properties are not checked in with other
project metadata and are applied only to your installation of the
IDE.
build
The output directory for compiled classes.
dist
The output directory of packaged build outputs (JAR files and
WAR files). Standard Java projects produce one build output per
project. The dist directory also contains generated Javadoc
documentation.
For information on setting the classpath for standard projects, see Section 6.2.3.1,
"Managing the Classpath."
6.2.2 Free-Form Templates
With free-form project templates, the IDE relies on your existing Ant script for
instructions on how to compile, run, and debug your applications. The settings you
configure in the New Project wizard when creating a project as well as in the Project
Properties dialog box are used to tell the IDE how your Ant script manages your
source code and must be consistent with the settings in your Ant script.
For example, all classpath elements are handled by your Ant script. When you declare
the classpath for a free-form project, you are only telling the IDE which classes to make
available for code completion and refactoring. These settings do not affect the actual
classpath used when compiling or running your source code.
Creating Java Projects 6-5
Using Java Project Templates
Free-form projects can contain as many source folders as your Ant script is configured
to handle. If your Ant script does not contain targets for all IDE actions, like
debugging and running your project, you can easily write Ant targets for these actions.
The standard distribution of the IDE contains the following
templates:
■
■
free-form Java project
Java Free-Form Project. A free-form project containing one or more Java source
roots.
Web Free-Form Project. A free-form project containing a web application and
optionally other Java source roots.
6.2.2.1 Source Folders
Free-form Java projects can contain multiple source folders. The classpath
relationships and handling instructions for your source directories must be handled in
your Ant script.
6.2.2.2 Project Settings
In the project's properties, you declare the source folders, classpath, and output files
for your project. Each source root can have a unique classpath and output file. These
settings do not affect the actual contents or classpath of your application. The settings
only tell the IDE how to handle the code. For example, the classpath settings tell the
IDE which classes to make available for code completion.
6.2.2.3 IDE Commands and Ant Targets
In free-form projects, the IDE relies on your Ant script to provide targets for all IDE
actions, such as running, debugging, and generating Javadoc. If your Ant script does
not contain targets for these commands, the commands are disabled.
You can write debug targets in your Ant script or in a supplementary Ant script. You
can also add a shortcut to any of your Ant script's targets to the contextual menu of
your project's node in the Projects window.
6.2.2.3.1 Creating a Target to Compile a Single File If you want to be able to select files in
the IDE and compile them individually, you need an Ant target for the Compile File
command. The IDE offers to generate a target the first time you choose the command.
The generated target looks something like this:
<?xml version="1.0" encoding="UTF-8"?>
<project basedir=".." name="MyProjectName">
<!-- TODO: edit the following target according to your needs -->
<!-- (more info: https://netbeans.org/kb/archive/index.html) -->
<target name="compile-selected-files-in-src">
<fail unless="files">Must set property 'files'</fail>
<!-- TODO decide on and define some value for ${build.classes.dir} -->
<mkdir dir="${build.classes.dir}"/>
<javac destdir="${build.classes.dir}" includes="${files}" source="1.5"
srcdir="src"/>
</target>
</project>
In the generated target, you need to specify the directory where to put the compiled
class or classes. You can do so by specifying a value for the build.classes.dir
property in the generated target. For example, you might add the following line to the
line above the <target name="compile-selected-files-in-src"> entry:
<property name="build.classes.dir"
6-6 NetBeans Developing Applications with NetBeans IDE
value="build"/>
Using Java Project Templates
Alternatively, you can replace the value of the provided build.classes.dir or rewrite the
target entirely.
The value of the includes parameter is the value of the generated files property. The
IDE uses this property to store the name of the currently selected file (or files).
You can configure multiple compile.single actions to
overload the F9 shortcut and menu command with different
functionality depending on what file is selected. For example, you
could set up a separate compile-selected-files target for JUnit test
classes, then map compile.single to that target for all sources in JUnit
test directories. Or you could change the pattern to \.xml$ and map
F9 to a Validate XML target for all XML files.
Note:
6.2.2.3.2 Writing a Target for the Apply Code Changes Command The Apply Code Changes
command allows you to make changes to your code during a debugging session and
continue debugging with the changed code without restarting your program. The IDE
contains a nbjpdareload task that you can use to write a target for the Apply Code
Changes command.
A typical target for the fix command looks something like this:
<target name="debug-fix">
<javac srcdir="${src.dir}" destdir="${classes.dir}" debug="true" >
<classpath refid="javac.classpath"/>
<include name="${fix.file}.java"/>
</javac>
<nbjpdareload>
<fileset dir="${classes.dir}">
<include name="${fix.file}.class"/>
</fileset>
</nbjpdareload>
</target>
■
■
The target compiles the currently selected file using the ${fix.file} property. (In
the next section you will set up the IDE to store the name of the currently selected
file in this property.)
The nbjpdareload task reloads the corrected file in the application.
To hook this target up to the Apply Code Changes command (the same as the Fix
command in previous versions of the IDE), define the following action in
<ide-actions> in project.xml:
<action name="debug.fix">
<target>debug-fix</target>
<context>
<property>fix.file</property>
<folder>${src.dir}</folder>
<pattern>\.java$</pattern>
<format>relative-path-noext</format>
<arity>
<one-file-only/>
</arity>
</context>
</action>
■
■
<property> now stores the context in the fix.file property.
Since you can only run the Fix command on one file at a time, you set <arity> to
<one-file-only>.
Creating Java Projects 6-7
Using Java Project Templates
■
You have to pass the full path to the .java file to the javac task and the full path
to the .class file to the nbjpdareload task. You therefore set the <format> to
rel-path-noext, then append .class or .java in the debug-fix target as
necessary.
The IDE does not define the ${src.dir} property for you. You
have to define the property or import the .properties file that the
Ant is using in project.xml. See Section 6.2.4.9.1, "Using Properties in
the project.xml File" for more information.
Note:
For information on creating free-form projects in the IDE, see Section 6.2.4, "Creating
Free-Form Projects."
6.2.3 Creating Standard Projects
You can facilitate creating a Java application by using one of the available templates
provided by the IDE.
To create a Java project:
1. Choose File > New Project (Ctrl+Shift+N).
2.
Select the appropriate template for your project.
3.
Follow the steps in the remainder of the application wizard.
Once you create your project, you can configure the classpath and add a JAR file,
library, or an IDE project to the classpath as needed. Set your project as the main
project to build it and then run it. If necessary, set the main class and any arguments
for your project prior to running it. Afterwards, you can debug your project by setting
breakpoints or watches and running the IDE’s debugging tool.
Maven uses repositories that contain build artifacts and project
dependencies. To create a Maven project, you need to configure
Maven settings at both the IDE level and at the project level. For
information on creating a Maven project, see Section 8.12, "Working
with Maven in the IDE."
Note:
6.2.3.1 Managing the Classpath
Adding a group of class files to a project's classpath tells the IDE which classes the
project should have access to during compilation and execution. The IDE also uses
classpath settings to enable code completion, automatic highlighting of compilation
errors, and refactoring.
Source roots must only exist in a single project and cannot be shared with other
projects, regardless of whether they are opened or not. If you have to use a library in
several projects, create a special project within which to store it.
6.2.3.1.1
Classpath and Standard Projects
For standard projects, the IDE maintains separate classpaths for compiling and
running your project, as well as compiling and running unit tests. The IDE
automatically adds everything on your project's compilation classpath to the project's
runtime classpath. Also the project's compiled test files and everything on the tests'
compilation classpath are added to the test runtime classpath.
6-8 NetBeans Developing Applications with NetBeans IDE
Using Java Project Templates
Whenever you build a standard project for which a main class is specified, the IDE
automatically copies any JAR files on the project's classpath to the dist/lib folder.
The IDE also adds each of the JAR files to the Class-Path element in the application
JAR's manifest.mf file. This simplifies running the application outside the IDE. For
more information, see Section 8.9, "Preparing a JAR File for Deployment Outside the
IDE."
To edit a standard project’s classpath:
1. Expand the project node, right-click the Libraries node, and choose Properties.
2.
In the Project Properties dialog box, add the necessary elements to the project's
compilation classpath by clicking the appropriate button. You can add any of the
following:
■
■
Project. The JAR file or WAR file produced by another project, as well as the
associated source files and Javadoc documentation.
Library. A collection of JAR files or folders with compiled classes, which can
optionally have associated source files and Javadoc documentation.
If you have attached Javadoc and source files to a JAR file in
the Library Manager, the IDE automatically adds the Javadoc and
source files to the project when you register the JAR file on a project's
classpath. You can step into classes and look up Javadoc pages for the
classes without configuring anything else.
Note:
■
JAR/Folder. A JAR file or folder that contains compiled classes.
3.
(Optional) In web applications, click the Deploy checkbox if you do not want to
package an element in the web application. By default, all classpath elements are
included in the web application.
4.
(Optional) Click the Build Projects on Classpath checkbox if you do not want to
rebuild all projects on the classpath whenever you build the current project. By
default, all projects on the classpath and, in web applications, projects listed in the
Packaging page, are rebuilt when you build the current project.
5.
(Optional) Click the Move Up and Move Down buttons to alter the classpath
priority.
6.
(Optional) Click the Run, Compile Tests, or Run Tests tabs to make any changes
to the these classpaths.
6.2.3.1.2
Classpath and Free-form Projects
In free-form projects, your Ant script handles the classpath for all of your source
folders. The classpath settings for free-form projects only tell the IDE what classes to
make available for code completion and refactoring. To change a free-form project's
actual compilation or runtime classpath you must edit your build.xml file directly. For
information on setting runtime arguments, see Section 10.6, "Setting the Main Class
and Runtime Arguments."
Free-form projects do not have Library nodes nor do free-form project's Project
Properties dialog boxes include a Libraries panel. For more information, see
Section 6.2.4.5, "Declaring the Classpath in a Free-Form Project."
Creating Java Projects 6-9
Using Java Project Templates
The project's classpath declaration must exactly match the
classpath used by your Ant script.
Note:
Adding a free-form project to the classpath of a standard project does nothing unless
you also declare the free-form project's build outputs in the Output page of its Project
Properties dialog box.
For information on specifying the target JDK to use for your project, see Section 6.8,
"Setting the Target JDK."
6.2.3.1.3
Adding Annotation Processors to the Classpath
In addition to other libraries, you can add annotation processors to the classpath or the
processor path of your project. The annotation processors are specified as either a
library, a JAR file, or another NetBeans IDE project. You can add annotation processors
on the following tabs: Compile and Processor. Additionally, you can specify the FQN
(fully qualified name) of the annotation processor on the Compile tab.
To add an annotation processor to the classpath:
1. Right-click the project node and choose Properties.
2.
Select the Libraries category in the Project Properties window.
3.
Select one of the following tabs in the Libraries panel and add the project, library
or JAR that contains the annotation processor to the project’s classpath.
■
■
Compile tab. When an annotation processor is packaged together with its
annotations as a single JAR file, specify this JAR file on the Compile tab. In
this case, there is no need to add it to the Processor tab. The resources added
on the Compile tab correspond to the –classpath option of the Java compiler.
Processor tab. When an annotation processor and its annotations are packaged
into separate JAR files, add the JAR file with the processor on the Processor
tab and the JAR file with the annotations on the Compile tab. The resources
added on the Processor tab correspond to the -processor path option of the
Java compiler.
4.
Select the Compiling node under the Build category and select Enable
Annotation Processing and Enable Annotation Processing in Editor.
5.
Click Add and type the fully-qualified name of the annotation processor in the
Add Annotation Processor dialog box.
6.2.3.2 Creating Dependencies Between Projects
When creating Java applications you typically set up a single main project, which
contains both the project main class and any required projects. Whenever you create
separate standard project for each of a project's source roots, you have to set up the
classpath dependencies between the main project and the required projects. A required
project is a project that has been added to another project's classpath.
For standard projects that have a main class specified, the IDE automatically copies
any JAR files on the project's classpath to the dist/lib folder when you build the
project. The IDE also adds each of the JAR files to the Class-Path element in the
application JAR's manifest.mf file. This simplifies running the application outside the
IDE. For more information, see Section 8.9, "Preparing a JAR File for Deployment
Outside the IDE."
6-10 NetBeans Developing Applications with NetBeans IDE
Using Java Project Templates
Whenever you clean and build a project, the IDE also cleans and builds its required
projects. The required project's attached Javadoc and source code are also made
available to the project that you are building. For information on adding Javadoc, see
Section 6.7.1, "How to Add a Javadoc to a Project."
If you want to add a free-form project to the classpath of a standard project, you have
to declare all of the JAR files that are produced when the free-form project is built.
Right-click the free-form project's node in the Projects window and choose Properties.
Then specify those JAR files in the Output page of the dialog box.
To configure project dependencies:
1. In the Projects window, expand the node of the project to which you want to add a
dependent project.
2.
Right-click the Libraries node and choose Add Project.
3.
Select the directory containing the project whose JAR files you want to add to the
classpath. When you select the project directory, the project name and project JAR
files are displayed in the dialog's right pane.
The file chooser depicts IDE project directories using
4.
project folder icons.
Click Add Project JAR Files.
The IDE adds the dependent project to the primary project's classpath and display
a node for it within the Projects window's Library node.
In free-form projects, the classpath is defined in your Ant script. For more information,
see Section 6.2.4.5, "Declaring the Classpath in a Free-Form Project."
For information on modifying the runtime classpath, see Section 10.5, "Setting the
Runtime Classpath."
6.2.3.3 Editing IDE-Generated Ant Scripts
If you are working with a standard project and want to set more project options than
are available in the Project Properties dialog box, you can edit the project's Ant script
and Ant properties. The Ant targets and properties are defined in the following files in
your project folder:
■
■
■
■
nbproject/build-impl.xml. The Ant script that contains all of the instructions for
building, running, and debugging the project. Never edit this file. However, you
can open it to examine the Ant targets that are available to be overridden.
build.xml. The main Ant script for the project. The IDE calls targets in this Ant
script whenever you run IDE commands. build.xml contains a single import
statement that imports targets from build-impl.xml. In build.xml, you can
override any of the targets from build-impl.xml or write new targets.
nbproject/project.properties. The Ant properties file that contains important
information about your project, such as the location of your source and output
folders. You can override the properties in this file.
nbproject/private/private.properties. The Ant properties file that contains
properties specific to your installation of the IDE. For example, if you are sharing
the project over VCS, any properties you set in private.properties are not
checked into the repository. You can copy a property from project.properties
into private.properties and give the property different definitions in each file.
The definitions in private.properties take precedence over those in
project.properties.
Creating Java Projects 6-11
Using Java Project Templates
In a free-form project, there is no build-impl.xml. The IDE
directly calls targets in the project's Ant script.
Note:
For NetBeans Plugin Module projects, build-impl.xml imports
targets from the suite.xml in your target platform's harness folder.
For information on editing and running an Ant script, see Section 8.2.2, "How to Edit
an Ant Script" and Section 8.2.3, "How to Run an Ant Script," respectively.
6.2.3.4 Customizing the IDE-Generated Ant Script
You can edit the Ant scripts generated for standard projects to fine tune the way your
project is built and run.
To override a target from an IDE-generated build script:
■
Copy the target from build-impl.xml or suite.xml to build.xml and make any
changes to the target.
Note: You might need to disable the Compile on Save option in
project properties, because when enabled it causes some commands to
skip calling the ant targets. To disable the Compile on Save option,
right-click your project in the Projects window, select Properties, and
clear the Compile on Same checkbox in the Compiling category.
To add instructions to be processed before or after an Ant target is run:
■
Override the -pre or -post target for the target.
For example, to insert an obfuscator after compilation, type the following in
build.xml:
<target name="-post-compile">
<obfuscate>
<fileset dir="${build.classes.dir}"/>
</obfuscate>
</target>
To add a new target to the build script:
1. Create the new target in build.xml.
2.
Optionally, add the new target to the dependencies of any of the IDE's existing
targets. Override the existing target in build.xml then add the new target to the
existing target's depends property.
For example, the following adds the new-target target to the run target's
dependencies:
<target name="run" depends="new-target,init,compile"/>
Copy the dependencies exactly as they exist in build-impl.xml or suite.xml.
Notice that you do not have to copy the body of the run target into build.xml.
6-12 NetBeans Developing Applications with NetBeans IDE
Using Java Project Templates
The output folder is deleted every time you clean your project.
Therefore, never set the output folder to the same location as your
source folder without first configuring the clean target to not delete
the output folder.
Note:
For information on editing and running an script, see Section 8.2.2, "How to Edit an
Ant Script" and Section 8.2.3, "How to Run an Ant Script," respectively.
For information on setting JVM arguments and system properties, see Section 10.7,
"Setting JVM Arguments."
6.2.3.5 Working with a JavaFX Project
To work with JavaFX in NetBeans IDE, you must have the following:
■
Installed JavaFX 2 SDK and Runtime
■
A JavaFX-enabled Java Platform within the IDE
6.2.3.5.1
JavaFX Application and JavaFX FXML Applications
In a JavaFX Application without FXML, graphic layout and actions are both defined in
Java classes. By default, both are defined in the main Application class.
In a JavaFX FXML application, graphic layout is defined in an FXML file and actions
are defined in a controller Java class. The controller class implements the interface
javafx.fxml.Initializable.
6.2.3.5.2
JavaFX Preloaders
A preloader is a small application that is started before the main application to
customize the startup experience. You can create JavaFX preloaders either by running
the New JavaFX Preloader wizard or by selecting Create Custom Preloader in the
New JavaFX Application wizard.
6.2.3.5.3
Editing JavaFX Applications
Edit JavaFX Java source code as you edit any other Java source code in the IDE. For
more information, see Section 7.2, "Editing Java Code."
Edit FXML files in one of two ways, depending on whether you have SceneBuilder
installed:
■
■
If SceneBuilder is installed, go to the Projects window and either double-click the
FXML file's node or right-click the FXML file's node and select Open. SceneBuilder
opens automatically, focused on that FXML file. For information about installing
and using SceneBuilder, see the JavaFX SceneBuilder documentation at
http://docs.oracle.com/javafx/index.html.
If SceneBuilder is not installed, edit the FXML file as you edit any XML document
in the IDE. If SceneBuilder is installed, you can choose to use the IDE's XML editor
instead by right-clicking the FXML file's node and selecting Edit. For more
information, see Section 18.2, "Creating and Editing XML Documents."
6.2.3.5.4
Building and Running JavaFX Applications
Build and run a JavaFX application as you build and run a standard Java application,
with the difference that you can configure a JavaFX project to run in the following
ways:
Creating Java Projects 6-13
Using Java Project Templates
■
■
■
Standalone application. Project builds and runs as a standard Java desktop
application.
Java Web Start. Application uses JNLP. The IDE generates the JNLP page when it
builds the application.
In Browser. The IDE embeds the application in a browser, using an HTML page
that calls a JNLP page. The IDE can generate the HTML page or you can use your
own web page. If you run the application from the IDE, the IDE opens a browser
page that points to the HTML page on your local file system.
To set how a JavaFX application is run, open the Project Properties and go to the Run
category. To open Project Properties, right-click the project's node in the Projects
window and select Properties from the context menu. For more information on
packaging a JavaFX application, see the chapter Packaging Basics in the JavaFX
Documentation at:
http://docs.oracle.com/javafx/2/deployment/packaging.htm
6.2.3.5.5
Debugging JavaFX Applications
Debug JavaFX applications as you would debug Java applications. In addition, you
can use the Java GUI visual debugger with JavaFX applications. For more information
on JavaFX, see the JavaFX 2 documentation at http://docs.oracle.com/javafx/.
6.2.4 Creating Free-Form Projects
Free-form projects do not produce an Ant script or hold project metadata in another
form. Instead, these projects rely on your existing Ant script to provide instructions for
handling your project source.
To create a free-form project:
1. Choose File > New Project (Ctrl+Shift+N).
2.
Select the appropriate template for your project.
3.
Follow the steps in the remainder of the application wizard.
6.2.4.1 Source Folders
Free-form Java projects can contain multiple source folders. The classpath
relationships and handling instructions for your source directories must be handled in
your Ant script.
6.2.4.2 Project Settings
In the project's properties, you declare the source folders, classpath, and output files
for your project. Each source root can have a unique classpath and output file. These
settings do not affect the actual contents or classpath of your application. The settings
only tell the IDE how to handle the code. For example, the classpath settings tell the
IDE which classes to make available for code completion.
For information on how to declare a classpath, see Section 6.2.4.5, "Declaring the
Classpath in a Free-Form Project."
6.2.4.3 IDE Commands and Ant Targets
In free-form projects, the IDE relies on your Ant script to provide targets for all IDE
actions, such as running, debugging, and generating Javadoc. If your Ant script does
not contain targets for these commands, the commands are disabled.
6-14 NetBeans Developing Applications with NetBeans IDE
Using Java Project Templates
You can write debug targets in your Ant script or in a supplementary Ant script. You
can also add a shortcut to any of your Ant script's targets to the contextual menu of
your project's node in the Projects window.
For information on mapping an Ant target to a command in the IDE, see
Section 6.2.4.6, "Mapping an Ant Target to an IDE Command."
For information on setting the IDE to read targets from a separate Ant script, see
Section 6.2.4.8, "Storing IDE Targets in a Separate Ant Script."
6.2.4.4 Adding a Source Directory to a Free-Form Project
Free-form projects can contain multiple source directories, as long as the project's Ant
script contains instructions on handling those source directories. To make project
sources available to Ant, you need to specify the classpath for the project sources. If
you have any custom tasks, you also need to add these tasks to Ant's classpath.
To add a source directory to a free-form project:
1. Build the project so that all of the project's build outputs (JAR files and WAR files)
exist on your computer.
2.
In the Projects window, right-click the project node and choose Properties.
3.
Click Sources in the right panel of the Project Properties dialog box and add the
source folder.
4.
Click Classpath in the right panel of the Project Properties dialog box and set the
classpath for the source directory.
You do this because by default the IDE ignores your environment's CLASSPATH
variable whenever it runs Ant.
Note: The classpath variable you set in the Project Properties dialog
box does not affect the actual classpath of the project, which is
specified in the Ant script. Declaring the classpath in the Project
Properties dialog box does not change the actual compilation or
runtime classpath of the source folders. However, the project classpath
variable must match the classpath used by your Ant script in order to
provide the correct information for code completion, error
highlighting, and refactoring commands. You have to set an explicit
classpath in your build scripts because the IDE ignores your
environment's CLASSPATH variable whenever it runs Ant. If you
change the classpath of one, you must change the class path of the
other.
5.
Click Output in the right panel of the Project Properties dialog box and specify
the source folder's build output.
6.
Click OK.
Specifying the Classpath for Custom Tasks
In free-form projects, you can call up and run custom Ant tasks in your build script.
For your Ant script to use customs tasks, you must include the tasks in the Ant script's
classpath. For example, you may add a task to your build script to format your code
with Jalopy. In order to do this, however, you have to add the Jalopy JAR file to Ant's
classpath.
Creating Java Projects 6-15
Using Java Project Templates
You can add custom tasks to Ant's classpath within the IDE by doing either of the
following:
■
Providing an explicit classpath to the tasks in your build script. This is the
recommended method for specifying the location of JAR files that contain custom
tasks used by your Ant script, as it ensures that your build scripts will be fully
portable. You can write your tasks and include instructions to compile them and
produce a JAR file in the build file. To use these tasks, include the long form of
taskdef, which includes a classpath. Here is a simple example of such a task:
<project name="test" default="all" basedir=".">
<target name="init">
<javac srcdir="tasksource" destdir="build/taskclasses"/>
<jar jarfile="mytasks.jar">
<fileset dir="build/taskclasses"/>
</jar>
<taskdef name="customtask" classname="com.mycom.MyCustomTask">
<classpath>
<pathelement location="mytasks.jar"/>
</classpath>
</taskdef>
</target>
</project>
The advantage of this method is that no special preparation is needed to begin
using the script. The script is entirely self-contained and portable. This method
also makes it easier to develop your tasks within the IDE, as the script compiles
them for you automatically.
To make your build scripts even more robust, use a property instead of a
hard-coded location to specify the classpath to your tasks. You can store the
property in the build script itself or in a separate ant.properties file. You can then
change the classpath setting throughout your script by simply changing the value
of the specified property.
■
Configuring the Ant Classpath property in the Options window. If you cannot
declare a classpath in your build script, or you are using third-party build scripts
which you cannot alter, you can add tasks to Ant's classpath in the IDE in the
Options window.
Note: If you modify the Ant classpath in the Options window, the
task is on Ant's classpath for all projects when you run Ant in the IDE.
6.2.4.5 Declaring the Classpath in a Free-Form Project
In a free-form project, all classpath relationships between your source folders are
handled by your Ant script. In order for the IDE to know which classes to include in
code completion and refactoring, you have to declare the classpath in the project
settings.
You first declare the classpath in the New Project wizard when creating the project.
You can edit all classpath declarations for an existing project in the Project Properties
dialog box.
Declaring the classpath in the Project Properties dialog box does not change the actual
compilation or runtime classpath of the source folders. The project's classpath
declaration must exactly match the classpath used by your Ant script.
6-16 NetBeans Developing Applications with NetBeans IDE
Using Java Project Templates
To declare the classpath for a project:
1. Build the project so that all of the project's build outputs (JAR files and WAR files)
exist on your computer.
2.
In the Projects window, right-click the project node and choose Properties.
3.
Click Java Sources Classpath in the Categories panel of the Project Properties
dialog box.
4.
Declare the classpath for the project.
■
■
■
To set a common classpath for all source folders, unselect the Separate
Classpath for Each Source Package Folder checkbox. Then add or remove
classpath elements with the buttons on the right of the dialog box.
To set a separate classpath for each source folder, leave the Separate Classpath
for Each Source Package Folder checkbox selected. Select a source folder in
the drop-down list and add or remove classpath elements for the source
folder.
To add the build output of source folder A to source folder B, select the source
folder B in the drop-down list and click Add JAR/Folder. Then navigate to the
output folder of source folder A and select its build output. You must have a
separate classpath for each source package folder to set up relational classpath
dependencies between source package folders.
If you have attached Javadoc and source files to a JAR file in the Ant Library
Manager, the IDE automatically adds the Javadoc and source files to the project
when you register the JAR file on a project's classpath. You can step into classes
and look up Javadoc pages for the classes without configuring anything else.
For information on how to add multiple source directories to a free-form project, see
Section 6.2.4.4, "Adding a Source Directory to a Free-Form Project."
For information on adding Javadoc documentation associated with a JAR file, see
Section 6.7.1, "How to Add a Javadoc to a Project."
For information on adding source code to a JAR file or a compiled classes folder, see
Section 10.9.3, "Attaching Source Code to a JAR File."
6.2.4.6 Mapping an Ant Target to an IDE Command
In a free-form project, IDE commands must be mapped to targets in your Ant script.
These mappings are recorded in the project.xml file in your project folder.
There are three ways to map an IDE command to a target in an Ant script:
■
By adjusting the settings in the Build and Run page of a project's Project
Properties dialog box
You can use the Project Properties dialog box to add a shortcut to any Ant target
to the project node's context menu. For example, if you have several runnable
classes that you have to run often, you can write targets to run these classes and
then run them using the links. Right-click the project node, choose Properties, and
register the shortcuts in the Build and Run page of the dialog box.
■
■
By having the IDE generate a target for you and then customizing this target to
your needs. This works for the Debug Project and Compile File commands. The
IDE offers to generate these targets the first time you run those commands in the
project.
By manually editing the project's project.xml file.
Creating Java Projects 6-17
Using Java Project Templates
Mappings are recorded in the project.xml file automatically in the following cases:
■
■
■
■
When you specify a target for a command in the Build and Run Actions page of
the New Project wizard.
When you specify a target for a command in the Build and Run panel of the
Project Properties dialog box for a project.
When you create a mapping for a command after having chosen the command
from the Build menu or Run menu and having been prompted to create the
mapping.
When you have had the IDE generate a target. (The IDE offers to generate a target
for the Debug Project and Compile File commands the first time you choose these
commands in a free-form project.)
To map commands for a project:
1. In the Projects window, right-click the project node and choose Properties.
2.
Click Build and Run in the right panel of the Project Properties dialog box.
Note: The Project Properties dialog box is the main tool for
configuring free-form projects in the IDE.
3.
For each command (Build Project, Clean Project, Generate Javadoc, Run Project
(free-form Java projects), Deploy Project (free-form Web projects), and Test
Project), choose an Ant target from the combo box. The combo box contains each
of the targets in your Ant script.
If your Ant script uses an import statement to import targets
from another Ant script, the targets only appear if the <import> target
specifies the full path to the secondary Ant script. If the <import>
target uses a property to reference the secondary Ant script, the
targets do not show up in the drop-down lists. In this case, you have
to type the name of the projects in the drop-down list for the
command.
Note:
4.
Use the Custom Menu Items list to add shortcuts to Ant targets to the project's
contextual menu.
Each IDE project has a project.xml file that contains important metadata about your
project's contents, the location of the project's Ant script, which targets to run for IDE
commands, and other information. If you want to map commands that work on the
presently selected files in the IDE, or if you want to map a command to a target in a
separate Ant script, you have to edit the project.xml file by hand.
To map IDE commands in project.xml:
1. In the Files window, expand the node for your project folder and expand the
nbproject folder.
2.
Double-click project.xml to open it in the Source Editor.
3.
Enter the following in <ide-actions>:
<action name="action_name">
<target>target_name</target>
</action>
6-18 NetBeans Developing Applications with NetBeans IDE
Using Java Project Templates
Note: The <ide-actions> element holds the mappings for IDE
commands. You enter an action element with the name for any of the
standard IDE actions and define the script and target to which you
want to map the command.
If you want to map an action to a target in a separate Ant script, add the following
before the <target> declaration:
<script>path_to_Ant_script</script>
You can map any of the following IDE actions:
■
build. Build project.
■
rebuild. Clean and build project.
■
compile.single. Compile selected file.
■
clean. Clean project
■
run. Run project.
■
run.single. Run the currently selected file.
■
redeploy. For Web application projects, build project, undeploy project from
server, and deploy project to server.
■
test. Run tests for project.
■
test.single. Run the test file for the currently selected file.
■
debug.test.single. Run the test file for the currently selected file in the
debugger.
■
debug. Debug project.
■
debug.single. Compile the currently selected file.
■
■
debug.fix. Run the Apply Code Changes command on the currently selected
file.
debug.stepinto. Execute one line of the project main class in the debugger
and pause.
■
profile.test.single. Profile the JUnit test for the selected file.
■
profile. Run project in the profiler.
■
profile.single. Profile the selected file.
■
javadoc. Generate Javadoc for project.
Note that actions that run on the currently selected files in the IDE require
additional configuration in project.xml.
4.
If you also want the command to appear in the project's contextual menu, enter the
following in <context-menu>:
<ide-action name="action_name"/>
For example, the following maps the Debug Project to the debug-nb target of the
project's Ant script:
<action name="debug">
Creating Java Projects 6-19
Using Java Project Templates
<target>debug-nb</target>
</action>
The Ant targets for NetBeans IDE commands do not have to live in the same Ant script
that you use to build and run the project. This is useful for users who cannot alter their
Ant script. The following maps the Debug Project to the debug-nb target in a separate
Ant script:
<action name="debug">
<script>path/to/my/nbtargets.xml</script>
<target>debug-nb</target>
</action>
Note:
<script> must precede <target>.
You can also configure a command to run multiple targets. The targets are run in the
order they appear in the action. For example, the mapping for the Clean and Build
Project command looks like this:
<action name="rebuild">
<target>clean</target>
<target>compile</target>
</action>
Adding Shortcuts to Project Node Contextual Menu
project.xml also has a context-menu element that controls the contents of a project
node's contextual menu. If you manually add an action that is run on the project, make
sure you register the action name in <context-menu> as well. If you use the Project
Properties dialog box to configure a standard project command, the IDE automatically
adds the command to the project's contextual menu.
For information on creating a debug target for a free-form project’s build script, see
Section 10.8.1.1, "How to Create a Debug Target for a Free-form Java Project."
6.2.4.7 Debugging Free-Form Projects
Similar to commands for compiling and running, debugging commands rely on
various information, such as the location of your sources, the location of the compiled
classes and other items on the classpath, and name of the project's main class.
In free-form projects, the IDE is not aware of any of these things. When you run a
command in the IDE (such as Build), the IDE simply calls a target in your build script
and lets the script handle the command. Therefore, for debugging to work, you also
have to have a build script target for debugging. The IDE provides some custom Ant
tasks to work with the debugger and also can generate a basic debug target, which
attempts to fill in important details based on other targets in your script.
For more information on debugging free-form projects, see Section 10.8.1, "Debugging
Free-form Projects."
6.2.4.8 Storing IDE Targets in a Separate Ant Script
When using a free-form project, you sometimes have to write Ant targets for IDE
actions. For example, you have to write an Ant target to run a program in the
debugger or to compile the currently selected file in the IDE.
If you are not able to write these IDE targets in your project's Ant script, you can set
the IDE to read these targets from a separate Ant script.
6-20 NetBeans Developing Applications with NetBeans IDE
Using Java Project Templates
To map an IDE command to an Ant target in a separate Ant script:
1. Write the target in a separate Ant script.
2.
In the Files window, expand your project folder node and the nbproject node.
3.
Double-click project.xml to open it in the Source Editor.
4.
Enter the following in <ide-actions>:
<action name="action_name">
<script>path_to_Ant_script</script>
<target>target_name</target>
</action>
Note that <script> must precede <target>.
5.
If the command also appears in the project's contextual menu, enter the following
in <context-menu>:
<ide-action name="action_name"/>
For information on mapping Ant targets to IDE commands, see Section 6.2.4.6,
"Mapping an Ant Target to an IDE Command."
6.2.4.9 Editing the project.xml File
Each IDE project has a project.xml file that includes important information about the
project, such as:
■
■
■
Information about what the project's type (free-form or standard, Web application
or standard Java SE application)
Mappings between project commands and targets in an Ant script
Information about the project's contents, classpath, and target Java platform. This
information is used to visualize the project and enable code completion and
refactoring.
For standard projects, there is usually no need to edit the project.xml file. In
free-form projects, you often have to edit the project.xml file to hook up Ant targets
to IDE commands and make other customizations.
6.2.4.9.1
Using Properties in the project.xml File
Like all XML files, you can define properties inside the XML file itself or store them in
a separate .properties file. One way of keeping your project.xml page synchronized
with the information in your Ant script is to import properties into project.xml from
the same .properties file that is used by your Ant script.
All file paths in project.xml are by default relative to the
project folder. If your Ant script is not located in the project folder, a
classdir property that points to build/classes/ does not point to
the same directory for the Ant script and for the project.xml file. (The
project folder is the folder that contains your nbproject folder, not the
nbproject folder itself. By default, the new free-form project wizard
makes your Ant script's parent folder the project folder.)
Note:
You can solve this problem by defining properties for important paths
(like project.dir) and using these properties to be more exact (for
example, classdir=${project.dir}/build/classes).
Creating Java Projects 6-21
Using Java Project Templates
To create and import properties in project.xml
1. In the Files window, double-click project.xml.
2.
Enter the following between the <name> element and the <folders> element:
<properties>
<property name="name">value</property>
<property-file>my-properties-file.properties</property-file>
<property-file>another-properties-file.properties</property-file>
</properties>
The syntax is different than the syntax used in Ant scripts.
While you can add properties in any order, properties can only
refer to other properties that have been defined previously in the file.
The properties file path itself can also use property substitutions.
Note:
6.2.4.9.2
Validating the project.xml File
The IDE comes bundled with the XML schemas for free-form project.xml files and
automatically validates a free-form project.xml file every time you edit and save it.
You can view the XML schemas for the free-form project.xml file at the following
locations:
■
■
■
http://netbeans.org/ns/freeform-project/1.xsd. Controls the main section of
the free-form project.xml (<general-data>).
http://netbeans.org/ns/freeform-project-java/1.xsd. Controls the
<java-data> section.
http://netbeans.org/ns/freeform-project-web/1.xsd. Controls the
<web-data> section (if you have one).
6.2.5 Setting Up a Java Project Based on Existing Sources
For Java projects developed outside of NetBeans, you use an Existing Sources template
in the New Project wizard to make a NetBeans project. In the wizard, you identify the
location of the sources and specify a location for the NetBeans project metadata. You
then use the Project Properties dialog box to configure the project.
To set up a NetBeans project for an existing Java application:
1. Choose File > New Project.
2.
Choose Java > Java Project with Existing Sources. Click Next.
3.
In the Name and Location page of the wizard, follow these steps:
■
Type a project name.
■
(Optional) Change the location of the project folder.
■
■
(Optional) Change the name of the build script used by the IDE. This might be
desirable if there is already a build script called build.xml that is used to build
the sources.
(Optional) Select the Use Dedicated Folder for Storing Libraries checkbox
and specify the location for the libraries folder.
6-22 NetBeans Developing Applications with NetBeans IDE
Importing an Eclipse or JBuilder Project
■
(Optional) Select the Set as Main Project checkbox. When you select this
option, keyboard shortcuts for commands such as Clean and Build Main
Project apply to this project.
4.
Click Next to advance to the Existing Sources page of the wizard.
5.
In the Source Packages Folder pane, click Add Folder. Then navigate to your
sources and select the source roots, click Open.
When you add a folder containing source code, you must add
the folder that contains the highest folder in your package tree. For
example, for the com.mycompany.myapp.ui package, you add the
folder that contains the com folder.
Note:
6.
(Optional) In the Test Package Folders pane, click Add Folder to select the folder
containing the JUnit package folders.
7.
Click Next to advance to the Includes & Excludes page of the wizard.
8.
(Optional) In the Includes & Excludes page of the wizard, enter file name patterns
for any files that should be included or excluded from the project. By default, all
files in your source roots are included.
9.
Click Finish.
6.3 Importing an Eclipse or JBuilder Project
You can import projects created in other IDEs, such as Eclipse or JBuilder, into the
NetBeans IDE.
The functionality to import Eclipse projects is included into the standard NetBeans
IDE distribution. For Eclipse projects, you can import a set of dependent projects from
an Eclipse Workspace or import a single project ignoring dependencies.
For JBuilder projects, you must install the JBuilder Project Importer plugin from the
NetBeans Update Center. For JBuilder projects, you can import a standard Java SE
project with dependencies.
To import an Eclipse project into the NetBeans IDE:
1. Make sure that you have copy of the project that you want to import on your
system.
Typically, this project would already be in an Eclipse workspace on your system.
2.
Choose File > Import Project > Eclipse Project.
3.
In the Workspace Location page of the wizard, select the Import Projects from
Workspace radio button, and specify the workspace location. Click Next.
4.
In the Projects to Import page, select the projects that you want to import.
5.
Choose one of the following two options for storing the NetBeans project files:
■
■
Store NetBeans project data inside Eclipse project folders. NetBeans adds
folders and files within the top-level folder of the original project.
Create imported NetBeans projects in a separate location. NetBeans uses the
sources and libraries in the original Eclipse project folder but creates a
separate folder to hold NetBeans project metadata and build outputs.
Creating Java Projects 6-23
Importing an Eclipse or JBuilder Project
Typically, it is better to store NetBeans project data inside
Eclipse project folders. In most cases, this means that the NetBeans
project metadata will refer to sources and libraries with the same
paths that are used by the Eclipse metadata. Therefore, checking out
the project from a version control system on different machines should
result in similar behavior both in NetBeans and Eclipse.
Note:
6.
(Applicable when web applications are being imported only.) Click Next. In the
Servers page, register any servers that your projects need with NetBeans IDE.
7.
Click Finish.
After you have completed the wizard, the following dialog boxes might appear:
■
Import Issues. The Import Issues dialog box provides information about
discrepancies between the project structure in Eclipse and in NetBeans and points
out actions that you might need to take to correct the discrepancies.
You can copy the information from this dialog and paste it elsewhere for future
reference.
In most cases, you use the project's Project Properties dialog box to resolve those
issues. See Resolving Import Problems for a guide to resolving the most common
problems.
■
■
Resolve Reference Problems. The Resolve Reference Problems dialog box alerts
you to a specific reference problem with one of your project libraries. You can
solve this problem after dismissing this dialog box by right-clicking the project's
node and choosing Resolve Reference Problems.
Resolve Missing Server. The Resolve Missing Server dialog box alerts you that
the project cannot find a necessary server. You can solve this problem after
dismissing this dialog box by right-clicking the project's node and choosing
Resolve Missing Server.
After you have completed the wizard and have closed any of the above informational
dialog boxes, nodes for the projects will appear in the Projects window.
If there are references in your project metadata to servers or other resources that
NetBeans cannot resolve, the node for the project will appear in red. You can resolve
these references immediately by right-clicking the project node and choosing Resolve
Reference Problems or Resolve Missing Server.
For other types of project configuration adjustments, you use the Project Properties
dialog box. You open the Project Properties dialog box by right-clicking the project's
node and choosing Properties.
After you have imported the project, you will find the following folder and files on
your system:
■
■
build.xml file or nb-build.xml file. The main NetBeans build script for the
project. You can customize this script according to the needs of your project. By
default, this file is called build.xml. If such a file already exists in the project
folder, the script is called nb-build.xml.
nbproject folder. Contains most of the NetBeans project metadata, including
resources that are called by the main NetBeans build script. If you check this folder
and the build.xml file or nb-build.xml into your version control system, other
users will be able to open the project in NetBeans. This folder also contains the
private folder, which contains data specific to your system. This folder should not
6-24 NetBeans Developing Applications with NetBeans IDE
Importing an Eclipse or JBuilder Project
be checked in to the version control system since its contents will vary between
users. See Version Control Considerations below.
■
■
nbbuild folder. When you build or run your project in NetBeans, the project's
sources are compiled into this folder.
nbdist folder. When you build your project in NetBeans, the project's distributable
outputs are created and placed in this folder. Such outputs might be JAR files and
WAR files.
Version Control Considerations
If the project is checked out of a version control system, the build (or nbbuild), dist
(or nbdist), and the nbproject/private folders should not be checked into that
version control system.
If the project is under the CVS, Subversion, or Mercurial version control systems, the
appropriate "ignore" files are created or updated for these directories when the project
is imported.
Note: Though nbproject/private should be ignored, nbproject
should be checked into the version control system. nbproject
contains project metadata that enables others users to open the project
in NetBeans without having to import the project first.
Building and Running an imported Project
Once you have the project imported into NetBeans, you can build and run the project.
All artifacts created from NetBeans build and run commands are created in the build
and dist folders. NetBeans does not over-write output created from Eclipse build
actions. If the Eclipse project already has build and dist folders, the NetBeans project
creates folders called nbbuild and nbdist and uses those for the build outputs.
The following are some of the build and run commands are available from the Run
menu:
■
■
■
■
Run Project. Test runs the application in the IDE.
Clean and Build Project. Deletes the contents of the build (or nbbuild) and dist
(or nbdist) folders and rebuilds all of the project's outputs. Uses the NetBeans
build script. Similar to the Clean command in Eclipse.
Clean. Deletes the contents of the nbbuild and nbdist folders.
Build. Rebuilds the project's outputs. If the Compile on Save feature is enabled,
the Build command is disabled.
Resynchronizing a Project
The project importer features synchronization capabilities. If the classpath in the
Eclipse has changed since you initially imported it, you can use the Resynchronize
Eclipse Projects feature to update the classpath in the corresponding NetBeans project.
Project resynchronization is one-way from Eclipse projects to NetBeans projects. If you
make changes to the project structure in NetBeans, those changes are not propagated
to the Eclipse project with the resynchronization feature. If you intend to keep both
Eclipse and NetBeans projects, use the Eclipse project as the "master" project.
The IDE also resynchronizes the projects automatically if the changes to the Eclipse
configuration are unambiguous and do not require your input. This automatic
Creating Java Projects 6-25
Importing an Eclipse or JBuilder Project
resynchronization occurs shortly after you open the project. If the resynchronization
requires your input, you need to manually resynchronize the project.
To manually resynchronize NetBeans projects with Eclipse projects:
■
Choose File > Import Project > Resynchronize Eclipse Projects.
When you resynchronize a project, the resynchronization is
performed on all projects that you have imported from the workspace.
Note:
Resolving Import Problems
When you import a project into NetBeans, there might be some things that can not be
automatically resolved in NetBeans IDE. For some of these problems, a menu item,
such as Resolve Missing Server Problem, appears in the contextual menu for the
project. Other problems can be resolved in the Project Properties dialog box for the
imported project in NetBeans IDE.
Here is a list of common import problems and their solutions.
Problem Message
Solution
Resolve Missing Server Problem
Right-click the project node and choose
Resolve Missing Server Problem. Then
navigate to the file or folder that contains
the server.
Resolve Reference Problem
Right-click the project's node and choose
Resolve Reference Problem. Then navigate
to the file or folder that contains the
resource that is referred to from the project.
Eclipse platform for project ProjectName
cannot be used. It is a JRE and the
NetBeans project requires a JDK. NetBeans
will use the default platform.
If you would like to change the platform
that NetBeans uses for the project, choose
Tools > Platforms and specify a different
platform.
Eclipse project ProjectName claims to use
JDK from the "{1}" directory. But this
directory does not exist. NetBeans will use
the default platform.
If you would like to change the platform
that NetBeans uses for the project, choose
Tools > Platforms and specify a different
platform.
NetBeans does not support source
includes/excludes per source root as
Eclipse does. They were merged and it is
recommended that you double check them
in project's properties in Source panel.
In NetBeans, includes and excludes are
declared in one place for the whole project.
To check the includes and excludes in the
NetBeans project, right-click the project's
node and the Projects window and choose
Properties. In the Project Properties dialog
box, select the Sources tab and then click
the Includes/Excludes button.
Import failed due to .... More details can be
found in IDE's log file.
You can open the IDE's log file by choosing
View > IDE Log.
Unknown project type - it cannot be
imported.
You can only import the following Eclipse
project types: Java Project, Java Project from
Existing Ant File, Static Web, Dynamic
Web, and JPA Project.
To install the JBuilder Project Importer plugin:
1. Choose Tools > Plugins from the main menu.
2.
Click the Available Plugins tab and select JBuilder Project Importer.
6-26 NetBeans Developing Applications with NetBeans IDE
Adding Multiple Sources Roots to a Project
3.
Click Install.
To import a JBuilder project:
■
Choose the JBuilder project type from the File > Import Project menu.
For information on how to create a Java project, see Section 6.1, "About Creating Java
Projects."
For information on adding dependent projects, see Section 6.2.3.2, "Creating
Dependencies Between Projects."
6.4 Setting the Main Project
When you develop a large application consisting of numerous source directories, it is
common to split up your code into separate projects. Of these projects, one is typically
the entry point for your application and contains the application's main class.
To tell the IDE which of your projects is the main entry point for your application, you
set one project to be the main project. The IDE provides commands that act on the
main project. For example, running the Build Main Project command builds both the
main project and all of its required projects, thereby ensuring that you all of your
compiled classes are up-to-date. Only one project can be the main project at any time.
After you set a project as the main project, the keyboard shortcuts for Run (F6), Build
(F11) and Clean and Build (Shift+F11) apply to the main project regardless of which
project is selected in the Projects window. Keyboard shortcuts for Debug and Profile
also apply to the main project.
To make a project the main project:
■
Choose Run > Set Main Project from the main menu and select a project from the
list of open projects.
Alternatively, you can right-click the project node in the Projects window and
choose Set as Main Project.
If you create separate projects for each source root, you must
set the classpath dependencies between the main project and the
required projects. For more information, see Section 6.2.3.2, "Creating
Dependencies Between Projects."For information on setting and
modifying a project’s classpath, see Section 6.2.3.1, "Managing the
Classpath."
Note:
6.5 Adding Multiple Sources Roots to a Project
You can add multiple sources roots to either standard or free-form projects that require
them. However, never add the same source root to more than one project because this
is not supported in the IDE.
In Standard projects, it is sometimes advantageous to add additional source roots to
your project's classpath such as when the project uses sources stored in a separate
resources folder. Because all source directories on a standard project's classpath form a
single compilation unit, they are also packaged into the application's JAR when the
project is built. In Standard projects, you add source roots to the classpath using the
project wizard and properties dialog.
In free-form projects, each source root can be assigned to independent compilation
units providing you maximum flexibility when structuring your applications.
Creating Java Projects 6-27
Sharing a Library with Other Users
Free-form projects, however, require that you manage the classpath by editing your
build.xml file directly. For more information, see Section 6.2.3.1, "Managing the
Classpath."
For both standard and free-form projects, source roots must
only exist in a single project and cannot be shared with other projects,
regardless of whether they are opened or not. If you have to use a
library in several projects, create a special project within which to
store it.
Note:
If you want to add a library to multiple projects, you must create a special project
within which to store the library's compiled source that you want to use.
For more information on using project templates, see Section 6.2, "Using Java Project
Templates."
6.6 Sharing a Library with Other Users
As the NetBeans IDE project system is Ant-based, NetBeans projects are generally
portable between different users, whether or not they use the IDE. However, by
default, the project build script's way of referring to libraries is dependent on factors
specific to each user, particularly in the case of libraries defined in the Library
Manager dialog box.
A potential inconvenience is that libraries are stored in a variety of locations, based on
where they originate. Libraries that come with the IDE are stored in various different
folders within the IDE's installation. Examples of these include the libraries for the
Swing Layout Extensions, beans binding, and database drivers.
You can configure most standard Java SE, Web, and Enterprise projects in a way that
makes it easy to share libraries with other users. You can specify a location for libraries
on which the project relies. You can also specify how the libraries are referenced from
your project.
These options make it easy for you to handle the following situations:
■
■
You create a project and need to make it available and buildable to other users,
whether they use the IDE or not. They must be able to access the project through a
version control checkout or by unpacking a ZIP file that you have provided them.
Then they should be able to build the application without extra configuration.
You must start working on an existing project and adhere to a strict set of
conventions concerning where project libraries are stored (and whether your build
script accesses them with a relative reference or absolute reference). Other users on
the team are not using NetBeans and have no plans to switch.
6.6.1 How to Share a Library
You can make a project's libraries sharable when you create the project in the New
Project wizard. You can convert an existing project to be sharable in the Libraries tab of
the Project Properties dialog box.
To make a general Java project's libraries sharable upon project creation:
1. Choose File > New Project.
2.
In the Java category of the wizard, select one of the standard templates and click
Next.
6-28 NetBeans Developing Applications with NetBeans IDE
Sharing a Library with Other Users
3.
In the Name and Location page of the wizard, select the Use Dedicated Folder for
Sharing Libraries checkbox.
4.
In the Libraries field, select the location for the libraries to be stored.
If the libraries are already included in the IDE, those libraries are copied to the
folder that you have designated.
To make a web or enterprise project's libraries sharable upon project creation:
1. Choose File > New Project.
2.
Select one of the standard templates in the Web or Enterprise category and click
Next.
3.
In the Name and Location page of the wizard, select the Use Dedicated Folder for
Sharing Libraries checkbox.
4.
In the Libraries field, select the location for the libraries to be stored.
If the libraries are already included in the IDE, those libraries are copied to the
folder that you have designated.
5.
(Optional) On the Server and Settings page, select the Copy Server JAR Files to
Libraries Folder radio button.
To make an existing project's libraries sharable:
1. Right-click the project's node and choose Properties.
2.
In the Project Properties dialog box, select the Libraries node.
3.
In the Libraries panel, click Browse to open the New Libraries Folder wizard.
4.
In the Library Folder page of the wizard, enter a location for the libraries and click
Next.
You can enter the location as a relative reference or an absolute reference.
5.
In the Actions panel of the wizard, verify the selected action for each listed library.
In most cases, the IDE detects the most appropriate action for that library.
The following actions are available:
■
■
■
■
Copy Library JAR Files to New Libraries Folder. Use this option if the library
is not in the folder that you have selected and you want to have the library
JAR files placed there.
Use Relative Path to Library JAR Files. Use this option if the library is not in
the libraries folder and you have to access the library in its existing location
using a relative path. An entry with a relative reference is added for the library
in the libraries folder's nblibraries.properties file.
Use Absolute Path to Library JAR Files. Use this option if the library is not in
the libraries folder and you need to access the library in its existing location
using an absolute path. An entry with an absolute reference is added for the
library in the libraries folder's nblibraries.properties file.
Use Existing Library in Libraries Folder. Use this option if there is already a
copy of the library in the libraries folder and you want to use that copy of the
library.
6.
Click Finish to exit the Make Project Sharable wizard.
7.
Click OK to exit the Project Properties dialog box.
Creating Java Projects 6-29
Adding a Javadoc to a Project
You can also use the Libraries node of the Project Properties dialog box to change the
location of the libraries folder. If you have already specified a libraries folder, click
Browse to open a file chooser instead of the New Libraries Folder wizard.
Free-form project libraries cannot be sharable in the ways
described in this topic.
Note:
For information on creating standard Java projects, see Section 6.2.3, "Creating
Standard Projects."
For information on creating free-form projects, see Section 6.2.4, "Creating Free-Form
Projects."
6.7 Adding a Javadoc to a Project
You can make Javadoc documentation for a JAR file's class available in the IDE by
associating that documentation with the JAR file.
If you want to have access to compiled JDK documentation through the IDE, see
Section 2.15.2, "How to Add the JDK Javadoc to the IDE."
6.7.1 How to Add a Javadoc to a Project
When you add a required project to a project's classpath, the required project's Javadoc
and sources are automatically added to the project as well.
To add Javadoc for a JAR file:
1. Choose Tools > Libraries from the main menu.
2.
In the left pane of the Ant Library Manager, select the project library within which
the JAR file you want to add Javadoc documentation to is located.
Only libraries already registered with the IDE are listed in the Ant Library
Manager's Class Libraries list.
3.
If the JAR file for which you want to add Javadoc documentation has not already
been added to a registered library, create a new empty library using the New
Library button. Next, in the Classpath tab click Add JAR/Folder and specify the
location of the JAR file containing the compiled class files.
You can also associate the Javadoc with a JAR file using the
project's Project Properties window. However, doing so creates the
association only for that project. Open the Project Properties dialog
box by right-clicking the project node and choosing Properties. Select
the Libraries node in the Categories pane. Then select the JAR with
which you want to associate the Javadoc and click Edit. You can then
specify the sources to be associated.
Note:
A class library can contain multiple JAR files as well as their Javadoc
documentation and source code.
4.
In the Javadoc tab, click Add ZIP/Folder and specify the location of the Javadoc
files.
5.
Click OK to exit the Ant Library Manager.
6-30 NetBeans Developing Applications with NetBeans IDE
Setting the Target JDK
The IDE adds the selected JAR files and Javadoc documentation ZIP files to the
specified library and automatically registers the documentation in every project
that has that JAR file on its classpath.
When you create a Java class library for a single JAR file, you can simply add the
JAR file to the project's classpath to make the associated Javadoc and source code
available. If your Java library contains multiple JAR files, however, you must add
the library itself to the classpath. Adding the library to the classpath also makes it
easier to share the project with other developers.
For information on setting the classpath for standard projects, see Section 6.2.3.1,
"Managing the Classpath."
For information on adding source code to a JAR file or a compiled classes folder, see
Section 10.9.3, "Attaching Source Code to a JAR File."
For information on how to view Javadoc in the IDE, see Section 2.15.3, "How to View
Javadoc Documentation."
6.8 Setting the Target JDK
By default, the IDE uses the version of the Java SE platform (JDK) with which the IDE
runs as the default Java platform for compilation, execution, and debugging. You can
view your IDE's JDK version by choosing Help > About and clicking the Detail tab.
The JDK version is listed in the Java field.
You can run the IDE with a different JDK version by starting the IDE with the
--jdkhome jdk-home-dir switch on the command line or in your
IDE-HOME/etc/netbeans.conf file. For more information, see Section 2.7, "Setting
Startup Parameters."
You cannot enable JavaFX for the default registered Java platform. However, you can
use the same JDK sources as the default platform in a new registered Java platform
and enable JavaFX in the new platform.
6.8.1 How to Register a New Java Platform
In the IDE, you can register multiple Java platforms and attach Javadoc and source
code to each platform. For example, if you want to work with the new features
introduced in JDK 7, you would either run the IDE on JDK 7 or register JDK 7 as a
platform and attach the source code and Javadoc to the platform. You can also enable
JavaFX for multiple platforms.
To register a new Java platform:
1. Choose Tools > Java Platforms from the main window.
2.
Click Add Platform and select the directory that contains the Java platform. Java
platform directories are marked with a
icon in the file chooser. Click Next.
If support for Java ME is enabled in the IDE you must select to add either a Java
Standard Edition platform or one of the Java ME platforms. For information on
adding a new Java ME platform, see Section 22.9, "Using Java ME Emulator
Platforms."
3.
Specify the display name for the platform and the location of the sources for the
Java platform and the Javadoc. Click Finish.
To register a new Java SE Embedded platform:
1. Choose Tools > Java Platforms from the main window.
Creating Java Projects 6-31
Setting the Target JDK
2.
Click Add Platform and select the Remote Java Standard Edition option. Click
Next.
3.
Specify the display name for the platform, the details of the remote device where
an application is executed, your authentication details, and the path to the JRE on
the remote device. Click Finish.
6.8.2 How to Set the Target JDK
In standard projects, you can switch the target JDK in the Project Properties dialog box.
In free-form projects, you have to set the target JDK in the Ant script itself, then specify
the source/binary format in the Project Properties dialog box.
To set the default Java platform for a standard project:
1. Right-click the project's root node in the Projects window and choose Properties.
2.
In the Project Properties dialog box, select the Libraries node in the left pane.
3.
Choose the desired Java platform in the Java Platform combo box.
Switching the target JDK for a standard project does the following:
■
Offers the new target JDK's classes for code completion.
■
If available, displays the target JDK's source code and Javadoc documentation.
■
■
Uses the target JDK's executables (javac and java) to compile and execute
your application.
Compiles your source code against the target JDK's libraries.
4.
Click Manage Platforms to register additional Java platforms with the IDE.
5.
Click Add Platform and navigate to the desired platform
To switch the target JDK of a standard project:
1. Right-click the project's node and choose Properties.
2.
Select the Libraries panel.
3.
Change the Java Platform property.
To set the target Java platform for a free-form project:
1. In your Ant script, set the target JDK as desired in the javac, java, and javadoc
tasks.
2.
Right-click the project's root node in the Projects window and choose Properties.
3.
In the Sources panel, set the level of JDK you want your application to be run on in
the Source/Binary Format combo box.
When you access Javadoc or source code for JDK classes, the IDE searches the Java
platforms registered in the Java Platform Manager for a platform with a matching
version number. If no matching platform is found, the IDE's default platform is
used instead.
For information on setting the classpath for standard projects, see Section 6.2.3.1,
"Managing the Classpath."
For information on how to declare a classpath, see Section 6.2.4.5, "Declaring the
Classpath in a Free-Form Project."
6-32 NetBeans Developing Applications with NetBeans IDE
Deleting a Project
6.8.3 How to Upload Java SE Embedded JRE to a Remote Device
When no JRE is installed on a remote device, new embedded JRE must be uploaded
and deployed.
To upload and deploy an embedded JRE on a remote device:
1. Choose Tools > Java Platforms from the main window.
2.
Click Add Platform and select the Remote Java Standard Edition option. Click
Next.
3.
In the Add Java Platform dialog, specify the display name for the platform, the
details of the remote device where an application is executed and your
authentication details. Click Create.
4.
In the Create Java SE Embedded JRE dialog, click Browse and browse for the
directory with JRE create on your hard drive.
5.
Specify the path to the directory on a remote device where JRE must be installed
and the required options. Click Create.
6.9 Moving, Copying, and Renaming a Project
When you create a project, the IDE bases much of its project metadata on the name and
location of the project. These values are used in the project build scripts, the project
properties, and the names and locations of the project folders.
6.9.1 How to Move, Copy, or Rename a Project
To safely move, copy, and rename a project, you must use the commands provided by
the IDE.
To move, copy, or rename a project:
■
Right-click the project's node in the Projects window and choose one of the
following commands:
–
Rename Project
–
Move Project
–
Copy Project
When moving or copying a project to a new location, the new
folder must already exist on the computer. You can create the folder
with the Browse button.
Note:
Moving and renaming a project can break compilation dependencies
between projects. To fix the project dependencies, remove the renamed
or moved project from the classpath of any other projects, then add
the project again
6.10 Deleting a Project
Deleting a project is a simple procedure and you have the option of deleting all project
files or only the build scripts and metadata.
Creating Java Projects 6-33
Deleting a Project
To delete a project:
1. Right-click the project's node in the Projects window and choose Delete Project.
2.
Specify whether to also delete the source folders under the project folder. If you do
not select this option, the IDE only deletes the generated build scripts and project
metadata.
The IDE does not offer to delete any source folders that are outside of the project
folder.
6-34 NetBeans Developing Applications with NetBeans IDE
7
Working with Java Code
7
[8This
]
chapter describes how to take advantage of the NetBeans editing tools and search
features that help you create and modify the code for your Java applications.
This chapter contains the following sections:
■
About Working with Java Code
■
Editing Java Code
■
Navigating in Java Code
■
Finding and Replacing Text
■
Using Regular Expressions
■
Using Special Code Templates
■
Using Java Editor Shortcuts
7.1 About Working with Java Code
Use the Java Source Editor to write or edit Java code. The Java Source Editor is a
full-featured text editor that is integrated with the GUI Builder, the compiler, the
debugger, and other parts of the IDE. It contains a set of features to enhance your
coding experience. For example, you can navigate to specific areas in the source code
using accelerator keys or menu commands in the Java Source Editor. You can find and
replace regular expressions, Java objects such as methods and interfaces.
In addition, you can use code templates to facilitate coding commonly used sequences
of reserved words and common code patterns.
7.2 Editing Java Code
The IDE's built-in Source Editor enables you to view, create, and edit your Java source
code. Open the Source Editor window by double-clicking a node in the Projects
window, Files window, or Navigator window. Alternatively, you can open the Source
Editor by choosing File > New to create a new file.
If a file is open in the GUI Builder, click Source in the editor's
toolbar to open the Source Editor.
Note:
The IDE has many features to simplify coding of Java files such as:
■
Code completion. After you press Ctrl+Space, a dialog box appears and offers
possible ways of completing the expression you are typing.
Working with Java Code 7-1
Editing Java Code
■
■
■
■
■
■
■
■
■
■
■
■
Code templates. You can enter common code snippets by typing abbreviations for
those snippets and then pressing Tab.
Editor hints. For some common coding mistakes, the Source Editor provides hints
for adding the missing code and offers to add the code for you automatically. To
display hints, choose Source > Fix Code (Alt+Enter).
Insert Code. You can generate getters, setters, properties, and so on. Right-click in
the Source Editor and choose Insert Code (Alt+Insert) to get a list of items that
you can generate.
BeanInfo Editor. You can generate a BeanInfo class for a bean class by
right-clicking the bean class in the Project window and choosing BeanInfo Editor.
You can then visually edit the BeanInfo class by clicking the Designer tab in the
Source Editor.
Word match. After you type the beginning characters of a word used elsewhere in
your code and then press Ctrl+K, the Source Editor generates the rest of the word.
GUI Builder. Visually design Java GUI applications.
Refactoring. Change the structure of your code without changing the
functionality.
Navigation Shortcuts. Include keyboard shortcuts that enable you to navigate to a
source file, declaration statement, or Javadoc documentation based on the location
of the insertion point.
Code Folding. Enables you to hide sections of code, such as Javadoc comments
and method bodies.
Pair Completion, Smart Enter, and Smart Semicolons. When you type a
quotation mark, bracket, brace, or parenthesis, the Source Editor automatically
inserts the closing character. The matching is "smart", so the closing characters are
not duplicated if you type them yourself.
Macros. Record macros by choosing Edit > Start Recording Macro.
Import Management. The Ctrl+Shift+I keyboard shortcut helps you generate
missing import statements for the file. See
You can find information about other Source Editor features in help topics that are
specific to the type of application you are developing.
For information on working with GUI source code, see Section 11.2.11, "How to
Modify GUI Source Code."
For information on working with code formatting in the editor, see Section 2.13.2,
"How to Specify Editor Formatting Options."
7.2.1 How to Identify Java Source Files
The IDE uses various icons to identify different types of source files. The following
table shows some of the high-level icons used in the Projects and Files windows to
indicate Java files and objects. In general, you can find out what an icon represents by
holding your cursor over the icon to display the node's tool tip.
7-2 NetBeans Developing Applications with NetBeans IDE
Editing Java Code
Icon
Description
Java source file. The following file types are represented by this icon:
■
Classes, Entity Classes, Interfaces, Exceptions
■
Beans, Filters, Listeners, Servlets
■
Tag Handlers, Service Locators
■
Applets, JApplets
Java main class file
JAR file or WAR file
Java packages root
Java package
Private Java package
Empty Java package
Library packages root
Package library
Generic information file. This node icon can represent the following file
types:
■
Java Enum files
■
Java Annotation Type files
■
Java Package Info files
■
Empty files
Swing GUI form object. This includes:
■
JPanel Forms
■
Bean Forms
Swing JInternational Frame form object
Swing and AWT GUI form object. This includes:
■
Frame Forms
■
JFrame Forms
Swing and AWT GUI dialog form object. This includes:
■
Dialog Forms
■
JDialog Forms
Swing and AWT GUI applet form object. This includes:
■
Applet Forms
■
JApplet Forms
Persistence Unit file
Database schema file
Working with Java Code 7-3
Navigating in Java Code
Icon
Description
JUnit file. This includes:
■
JUnit Tests
■
Tests for Existing Class
■
Test Suites
Badge icons can be affixed to other file icons to indicate a particular state of the object.
The following table lists some of the badges used in the Projects (Ctrl+1) and Files
(Ctrl+2) windows.
Icon
Description
The file needs to be compiled. Either the file has not been compiled or
the source has changed since the last compilation.
The file cannot be parsed. The file might contain an unrecoverable
syntactic error, or there might have been a problem reading the file.
7.3 Navigating in Java Code
NetBeans provides many editing features that you can use to improve your
productivity. These include features for locating and moving to the source code for
your projects' classes and interfaces and their members. NetBeans provides keyboard
accelerators to step from member to member in a class definition in the Java Source
Editor.
For Java files, you can see a list of constructors, methods, and fields. For some kinds of
XML files, you can use the Navigator to view the structure of the file. The Navigator
window works with standard XML documents, XML schema files, and Ant scripts.
Choose Window > Navigator (Ctrl+7) to open this window.
To display a source file in the Navigator window:
■
Select the file in the Source Editor, the Projects window, the Files window, or the
Favorites window.
Once a file is displayed, you can use the Navigator window to focus on a specific
nodes contained in the document. To do so, click on a given node in the Navigator
window, and your cursor automatically relocates to the node's position in the
document.
7.3.1 Browsing Java Files
When a Java file is selected, a drop-down list appears at the top of the Navigator
window to enable you to choose between the following two views:
■
■
Members view that lists, alphabetically, the selected source file's members
(constructors, methods, and fields).
Bean Patterns that lists of a class's bean properties and event listeners.
You can display the Javadoc documentation for a member by hovering the mouse over
the member's node. Right-click a node in the Members view to choose the following
commands:
■
Go to Source. Opens the class in the Source Editor and places the insertion point
at the beginning of the constructor, method, or field that the node represents.
7-4 NetBeans Developing Applications with NetBeans IDE
Navigating in Java Code
■
■
■
Sort by Name. Displays the members in alphabetical order.
Sort by Source. Displays the members in the order in which they appear in the
code.
Filters. Opens a submenu that enables you to select some common filters for the
types of members to display:
–
Show Inherited Members. Displays members that come from classes that the
current class extends
–
Show Fields. Displays the class's fields.
–
Show Static Members. Displays static fields and methods.
–
Show Non Public Members. Displays members that do not provide public
access.
You can also activate and disable filters using the buttons at the bottom of the
Navigator window.
The icons in the following table represent elements and bean patterns within the Java
hierarchy. These icons are visible from the Navigator window (Ctrl+7).
Icon
Description
Java class or inner class
Category node for constructors
Constructor with default access
Private constructor
Public constructor or nonstatic initializer
Constructor with protected access
Static initializer
Category node for methods
Method with default access (nonstatic)
Private method (nonstatic)
Public method (nonstatic)
Method with protected access (nonstatic)
Method with default access (static)
Private method (static)
Public method (static)
Method with protected access (static)
Category node for fields
Working with Java Code 7-5
Navigating in Java Code
Icon
Description
Field with default access (nonstatic)
Private field (nonstatic)
Public field (nonstatic)
Field with protected access (nonstatic)
Field with default access (static)
Private field (static)
Public field (static)
Field with protected access (static)
7.3.2 Browsing XML Files
For XML files, the Navigator view displays a tree of elements. Right-click an element
node to choose the following options for the level of detail to have displayed:
■
Show Attributes. Displays the attributes of each element.
■
Show Content. Displays the text content of each element.
7.3.3 Browsing Ant Scripts
When an Ant build script is selected, a drop-down list appears at the top of the
Navigator window to enable you to choose between the following two views:
■
Ant Targets. Displays an alphabetical list of build targets.
■
XML View. Displays a hierarchical tree view XML elements in the build script
Select the Ant Targets view and right-click a node and to choose one of the following
commands:
■
■
■
■
Open. Opens the file in the Source Editor and places the insertion point at the
beginning of the selected target's line.
Run Target. Runs the selected target.
Create Shortcut. Opens a wizard that enables you to create a menu item, a toolbar
item, a keyboard shortcut, and custom code for running the target.
Properties. Displays properties for the target in a property sheet. These properties
are not editable.
7.3.4 Browsing an XML File
When you select the XML View, right-click a node to choose one of the following
options for the level of detail to have displayed:
■
Show Attributes. Displays the attributes of each element.
■
Show Content. Displays the text content of each element
7-6 NetBeans Developing Applications with NetBeans IDE
Navigating in Java Code
7.3.5 How to Navigate Within Your Code
While working in NetBeans, you can navigate within your source code and browse
source and Javadoc documentations.
To go to the Java source for the identifier the insertion point is on:
■
Press Alt+O.
Alternatively, you can choose Navigate > Go to Source. The class is opened in the
Source Editor and the insertion point is placed at the beginning of the constructor,
method, or field that the node represents.
To go to a Java file, JSP file, or tag file using hyperlinks:
Hold down the Ctrl key and move your over one of the following identifiers and click
on it:
■
■
Java identifier (package, class, method, or variable)
JSP identifier (include directive, <jsp:include> element, <jsp:forward> element,
or tag file reference).
To jump to the declaration for the Java method or field the insertion point is on:
■
Press Alt+G.
Alternatively, right-click and choose Go To > Declaration from the context menu.
To go directly to a Java class:
■
Press Alt+Shift+O.
Alternatively, you can choose Navigate > Go To Class.
To display Javadoc documentation for the entity that the insertion point is on:
■
Press Alt+F.
Alternatively, right-click and choose Show Javadoc from the context menu.
Note that to locate the documentation, the appropriate Javadoc library must be
included in the Library manager.
To display Javadoc documentation for the method that corresponds to the
method signature that you are using in your code:
1. Place the insertion point between the closing parenthesis of the method call and
the semicolon.
2.
Press Alt+F1.
Alternatively, right-click and choose Show Javadoc from the context menu.
If the insertion point is elsewhere in the line when you press Alt+F1, the
documentation for the method with no parameters is displayed.
To go to a specific method or field in the currently displayed Java class:
■
Double-click the method or field in the Navigator window.
To switch Source Editor tabs:
■
Press Alt+Right or Alt+Left.
Working with Java Code 7-7
Finding and Replacing Text
To jump back and forth among areas of code in which you have been working:
■
Use the Alt+K and Alt+L jump list keyboard shortcuts.
To bookmark a line of code:
■
Click anywhere in the line that you want to bookmark and press Ctrl+Shift+M.
Press Ctrl+Shift+Period or Comma to cycle forward or backwards, respectively,
through your bookmarks.
Press Ctrl+Shift+M on a bookmarked line to remove the bookmark.
To go to a specific line number:
■
Press Ctrl+G.
To select the Projects window node for the current file in the Source Editor:
■
Press Ctrl+Shift+1.
7.4 Finding and Replacing Text
From the source editor, you can search for and replace text and expressions in your
Java source code quickly and efficiently.
7.4.1 How to Find and Replace Text
You can search for text with the option of replacing it across your source file.
To search a source file currently open in the source editor, with the option to
replace text:
1. In the Source Editor, press Ctrl+F to display the Search panel, at the bottom of the
editor, or Ctrl+H to display the Replace dialog box.
2.
Type the text to find and replace in the appropriate text fields.
Use the Find combo box or the Replace combo box to select from recent entries.
You can open the combo box with the Alt+down arrow and close it with the
Alt+up arrow.
3.
Use any combination of the following options:
■
■
■
■
Match Case. Limits the search to text that has the same capitalization.
Whole Words. Matches the search text only to whole words in the file. Does
not match words that contain but do not exactly equal the search text. Text
separated by periods (for example, javax.swing.jPanel) is considered to be
separate whole words. For example, if the search word is add and the Match
Whole Words Only option is not selected, jPanel.add and
blueSlider.addChangeListener both contain matches. If Match Whole
Words Only is selected, only jPanel.add contains a match.
Regular Expressions. Enables you to search for and replace patterns based on
regular expression constructs. For more information, see Section 7.5, "Using
Regular Expressions."
Wrap Around. Continues the search from the beginning of the file when the
end is reached.
■
Search Selection. Limits the search to the selected block of text.
■
Search Backwards. Searches back to the top of the file.
7-8 NetBeans Developing Applications with NetBeans IDE
Using Regular Expressions
■
■
■
4.
Wrap Around. Continues the search from the beginning of the file when the
end is reached.
Highlight Results. Highlights all occurrences of the search text in the file. To
unhighlight the text, do another search on the same text without this option
selected, or press Alt+Shift+H in the Source Editor. Alt+Shift+H toggles
between highlighting and unhighlighting the text.
Incremental Search. Tries to find the text as you type it (instead of waiting
until you click the Find button).
After the using the Find operation or Replace operation, use these keyboard
shortcuts in the Source Editor:
Shortcut
Action
F3
Finds the next occurrence of the search text.
Shift+F3
Finds the previous occurrence of the search text.
Alt+Shift+H
Switches the highlight function on or off.
Ctrl+F3
Searches for the word the insertion point is on, using the last settings
specified in the Find dialog box.
For Java classes, use the Find Usages command to display usages of a class, method,
or field throughout your source code. For information on the Find Usages command,
see Section 8.11.2, "How to Find Class, Methods, and Field Usages."
7.5 Using Regular Expressions
You can use regular expressions to add flexibility to searches in the IDE. Regular
expressions are composed of a special syntax that enables you to express a wide range
of search patterns.
In the Find in Projects dialog box, you can use regular expressions to match file names
or file text. In the Find dialog box and the Replace dialog box, you can use regular
expressions to help you perform search and replace operations.
7.5.1 Regular Expression Constructs
Table 7–1 describes some of the special characters in regular expressions:
Table 7–1
Regular Expression Constructs
Construct
Description
|
Or.
^
Matches text beginning with the subsequent characters.
$
Matches text ending with the preceding characters.
\
Escape character. Necessary if you want to match to a period (.), bracket ([),
brace (() or other special character.
\n
New-line character.
\r
Carriage-return character.
[]
Used to delimit a set of characters.
*
Zero or more occurrences of the previous character or set of characters.
Working with Java Code 7-9
Using Special Code Templates
Table 7–1 (Cont.) Regular Expression Constructs
Construct
Description
+
One or more occurrences of the previous character or set of characters.
.*
Wildcard.
For a more complete list of regular expression constructs and further discussion of
regular expressions, see
http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html#sum.
7.5.1.1 Sample Regular Expressions
Table 7–2 lists some examples of regular expressions that you might use in file
searches:
Table 7–2
Regular Expressions
Regular Expression
Matches
"[^"\r\n]*"
Matches (quoted) strings in the document.
\{[^\{\}]*\}
Inner block of code between braces ({}). Blocks with nested
braces are not matched.
[ \t]+$
All white space at the end of lines.
When using regular expressions in the Replace dialog box, you can use scalers in the
Replace With field to refer to groups (constructs within parentheses) in the Find What
field. $1 is the scaler assigned to the first group, $2 is assigned to the second group,
and so on.
For information on finding classes, methods, and fields, see Section 8.11.2, "How to
Find Class, Methods, and Field Usages."
For information on finding and replacing text, see Section 7.4.1, "How to Find and
Replace Text."
7.6 Using Special Code Templates
Use code templates to speed up the entry of commonly used sequences of reserved
words and common code patterns. For example, if you enter forc and press the Tab
key, it expands into the following:
for (Iterator it = col.iterator(); it.hasNext();) {
Object object = it.next();
When you create code templates, there are several constructs that you can use to
customize the way the code template behaves. You can look at the default IDE code
templates in the Options window, under the Tools menu, for examples from which
you can learn.
In general, a code template parameter can be specified by its name and a set of
optional hints. Hints serve as guidance when computing the values assigned by the
infrastructure to the parameters on template expansion. Syntax for parameter
definition is as follows:
${param_name hint=value hint=value ...}
However, boolean hints that can be written without the value part:
7-10 NetBeans Developing Applications with NetBeans IDE
Using Java Editor Shortcuts
${param_name hint} translates to ${param_name hint=true}
Some parameter names are reserved by the code template infrastructure:
■
■
${cursor} defines the position where the caret will be located after the editing of
the code template values finishes.
${selection} defines the position for pasting the content of the editor selection,
which is used by the 'selection templates' that appear as hints whenever the user
selects text in the editor.
Similarly, some of the hint names are reserved by the code template infrastructure:
■
■
■
■
■
■
■
■
■
■
■
${param_name default="value"} defines the parameter's default value.
${param_name editable=false} can be used to disable user's editing of the
parameter.
${param_name instanceof="java.util.Collection"} requires the parameter
value to be an instance of the given type.
${param_name array} requires the parameter value to be of an array type
(including arrays of primitive data types).
${param_name iterable} requires the parameter value to be of an array type or an
instance of "java.lang.Iterable". Can be used in 'for-each' cycles.
${param type="java.util.Iterator"} requires the parameter value to be the
given type. The infrastructure tries to use short name Iterator and import
java.util.Iterator if possible.
${param_name iterableElementType} requires the parameter value to be the type
of the iterable element. Can be used in 'for-each' cycles.
${param_name leftSideType} requires the parameter value to be the type of the
expression on the assignment's left side.
${param_name rightSideType} requires the parameter value to be the type of the
expression on the assignment's right side.
${param_name cast} defines that the parameter value would be a type cast if
necessary.
${param_name newVarName} defines that the parameter value should be a 'fresh'
unused variable name in the given context.
7.7 Using Java Editor Shortcuts
Table 7–3 lists the keyboard shortcuts you can use to perform the following Java
Source Editor operations:
Table 7–3
Java Editor Keyboard Shortcuts
Keys
Action
Ctrl+Shift+B
Goes to the source of the item the insertion point is on.
Ctrl+B
Goes to the method or variable declaration for method or variable the
insertion point is on.
Ctrl+Q
Goes to the line in the file where the last change took place.
Ctrl+/
Comments/uncomments the current line or selected lines.
Alt+Shift+F
Formats the selected code or the entire file if nothing is selected.
Working with Java Code 7-11
Using Java Editor Shortcuts
Table 7–3 (Cont.) Java Editor Keyboard Shortcuts
Keys
Action
Alt+Shift+Left
Moves the selected line or lines one tab to the left.
Alt+Shift+Right
Moves the selected line or lines one tab to the right.
Alt+Shift+Up
Moves the selected line or lines one line up.
Alt+Shift+Down
Moves the selected line or lines one line down.
Ctrl+Shift+Up
Copies the selected line or lines one line up.
Ctrl+Shift+Down
Copies the selected line or lines one line down.
Ctrl+Slash
Toggles the commenting out of the current line or selected lines.
Ctrl+Space
Shows code completion box.
Alt+Insert
Pops up a context aware menu that you can use to generate common
structures such as constructors, getters, and setters
Alt+Enter
Displays editor hints. The IDE informs you when a hint is available
when the light bulb is displayed.
Ctrl+Shift+I
Generates the import statements required by all classes specified in the
file.
Alt+Shift+I
Generates the import statements required by the class under the cursor.
Ctrl+P
Selects the next parameter. You must have a parameter selected
(highlighted) for this shortcut to work.
Ctrl+Shift+Space
Shows documentation for item under the cursor.
Ctrl+Shift+K
Generates the next word used elsewhere in your code as you type its
beginning characters.
Ctrl+K
Generates the previous word used elsewhere in your code as you type its
beginning characters.
Ctrl+R
In place rename.
7-12 NetBeans Developing Applications with NetBeans IDE
8
Building Java Projects
8
This chapter provides an overview of the building features in NetBeans.
[9]
This chapter contains the following sections:
■
About Building Java Projects
■
Working with Ant
■
Working with Builds
■
Building a Java Project
■
Using a Build Server
■
Compiling a Single Java File
■
Building a JAR File
■
Packaging an Application as a Native Installer
■
Preparing a JAR File for Deployment Outside the IDE
■
Using the Output Window
■
Refactoring Java Projects
■
Working with Maven in the IDE
■
Working with Maven Repositories
8.1 About Building Java Projects
NetBeans provides both Ant and Maven for building your Java applications. With Ant,
if you are using a standard Java project, the IDE generates an Ant build script based on
the options you enter in the project's Project Properties dialog box. If you are using a
free-form Java project, the IDE uses your existing Ant build script.
With standard Java projects, you can customize the build process by doing any of the
following:
■
■
Enter basic options, such as classpath settings and JAR filters, in the Project
Properties dialog box.
Override IDE-generated Ant targets or create new targets in build.xml.
By default, the IDE compiles the classes in a standard project when you save them.
This compile-on-save feature enables you to run or debug your applications in the IDE
without having to wait for the projects to be built. However, the compile-on-save
feature does not build your application JAR file. Before delivering your application to
Building Java Projects 8-1
Working with Ant
users, use the Clean and Build command to generate fresh versions of the project's
distributable files.
For standard projects that have a main class specified, the IDE automatically copies
any JAR files on the project's classpath to the dist/lib folder when you build the
application. The IDE also adds each of the JAR files to the Class-Path element in the
application JAR's manifest.mf file. This simplifies running the application outside the
IDE. For more information, see Section 8.9, "Preparing a JAR File for Deployment
Outside the IDE."
For information on how to customize an Ant build script, see Section 6.2.3.4,
"Customizing the IDE-Generated Ant Script."
For information on how to modify a build JAR file, see Section 8.7, "Building a JAR
File."
Maven is a framework that provides help with managing the project lifecycle,
including building and managing dependencies. Maven projects follow a set of
standards that are described with a Project Object Model (POM) file. You build the
project using its POM and a set of plugins that are shared by all projects using Maven
to ensure consistency between projects.
When you build, the IDE executes the plugin goals, builds the project and adds the
project artifacts to the local repository. Maven uses repositories (local or remote) to
contain a project’s build artifacts and dependencies.
By adhering to convention, Maven frees you from having to explicitly specify every
build action, configure the path to source files, and so on as it uses a default setup.
Even though Maven is based on convention, you can customize a project by creating a
custom configuration where you can map IDE actions to Maven goals enabling you to
load the project in the IDE with a specific set of dependencies and trigger specific
actions.
For information on using Maven in the IDE, see Section 8.12, "Working with Maven in
the IDE."
For information on configuring Maven settings, see Section 8.12.2, "How to Configure
Maven Settings."
For more information on Maven repositories, see Section 8.13, "Working with Maven
Repositories."
8.2 Working with Ant
Apache Ant is a Java-based build tool used to standardize and automate build and run
environments for development. Ant build scripts are XML files that contain targets,
which in turn contain tasks. Ant tasks are executable bits of code that handle the
processing instruction for your source code. For example, you use the javac task to
compile code, the java task to execute a class, and so forth. You can use Ant's built-in
tasks, use tasks written by third parties, or write your own Ant tasks.
For more information about Ant, see http://ant.apache.org/.
For information on installing Ant documentation, see Section 8.2.9, "How to Install Ant
Documentation in the IDE."
8.2.1 Using Ant with the IDE
The IDE's project system is built directly on top of Ant version 1.9.0. All of the project
commands, like Build Project or Run File in Debugger, call targets in the project's Ant
8-2 NetBeans Developing Applications with NetBeans IDE
Working with Ant
script. Therefore, you can build and run your project outside the IDE exactly as it is
built and run inside the IDE. For information on mapping Ant targets to debugger
commands, see Section 6.2.4.6, "Mapping an Ant Target to an IDE Command."
You do not need to be familiar with Ant to work with the IDE. You can set all the basic
compilation and runtime options in your project's Project Properties dialog box and
the IDE automatically updates the project's Ant script. If you know how to work with
Ant, you can customize a standard project's Ant script or write your own Ant script for
your project. For more information on customizing an Ant script, see Section 8.2.8,
"Ant Classpaths and Custom Tasks."
Though the IDE is built directly on top of Ant, the parsers that
usually come with Ant are not necessarily bundled with the IDE. If
you require parsers not included with the IDE distribution, you can
add them to Ant's classpath using the Ant Settings > Additional
Classpath property in the Options window.
Note:
For more help with the IDE's Ant support, see the NetBeans Ant FAQ at
http://wiki.netbeans.org/.
For information on modifying the classpath for a project, see Section 6.2.3.1,
"Managing the Classpath."
8.2.2 How to Edit an Ant Script
In standard projects the IDE generates the build script based on the options you enter
in the New Project wizard and the project's Project Properties dialog box. You can set
all the basic compilation and runtime options in the project's Project Properties dialog
box and the IDE automatically updates your project's Ant script. If you have
additional requirements for the build process that cannot be handled in the Project
Properties dialog box, you can modify the build script directly.
The main Ant script for a standard project is build.xml. The IDE calls targets in
build.xml whenever you run IDE commands. This file contains an import statement
that imports nbproject/build-impl.xml, which contains build targets that are
generated by the IDE. In build.xml, you can override any of the targets from
nbproject/build-impl.xml or write new targets. Do not edit
nbproject/build-impl.xml directly, because that file is regenerated based on changes
that you make in the Project Properties dialog box.
In addition, the build script uses the nbproject/project.properties which you can
edit manually.
Editing an Ant script is much like editing any other XML file. All of the applicable
Source Editor shortcuts are available. Double-click any of the Ant script's subnodes in
the Files window to jump to that target's location in the Source Editor.
The IDE provides code completion for all standard Ant tasks. To enter an end tag for
any empty beginning tag, type </.
With standard projects, you can customize the build process by doing any of the
following:
■
Entering basic options, like classpath settings and JAR filters, in the New Project
wizard when you create a project, or afterwards in the Project Properties dialog
box.
Building Java Projects 8-3
Working with Ant
■
■
Editing properties in nbproject/project.properties. This file stores Ant
properties with important information about your project, such as the location of
your source and output folders. You can override the properties in this file. Be
careful when editing this file. For example, the output folder is deleted every time
you clean your project. You should therefore never set the output folder to the
same location as your source folder without first configuring the clean target to
not delete the output folder.
Customizing existing or creating new Ant targets by doing any of the following:
–
Add instructions to be processed before or after an Ant target is run. Each of
the main targets in nbproject/build-impl.xml also has a -pre and -post
target that you can override in build.xml. For example, to get RMI working
with regular projects, type the code from Example 8–1 in build.xml.
Example 8–1
<target name="-post-compile">
<rmic base="${build.classes.dir}" includes="**/Remote*.class"/>
</target>
–
Change the instructions in an Ant target. Copy the target from
nbproject/build-impl.xml to build.xml and make any changes to the target.
–
Create new targets in build.xml. You can also add the new target to the
dependencies of any of the IDE's existing targets. Override the existing target
in build.xml and then add the new target to the existing target's depends
property. For example, code from Example 8–2 adds the new-target target to
the run target's dependencies.
Example 8–2
<target name="new-target">
<!-- target body... -->
</new-target>
<target name="run" depends="new-target,myprojname-impl.run"/>
You do not need to copy the body of the run target into build.xml.
The following table lists some common tasks for redefining a JAR file that you may
find useful.
To perform this task
Follow these steps
Specify which files are added
to a JAR file.
Right-click the project node in the Projects window and
choose Properties. Click the Packaging subnode (under
Build) and configure the filter and compression
settings using the Exclude from JAR File field.
Change a JAR file's name and
location.
In the Files window, double-click the project's
nbproject/project.properties file to open it in the
Source Editor. Enter the full path to the JAR file in the
dist.jar property.
Specify the manifest file for a
JAR file.
In project.properties, type the name of the manifest
file in the manifest.file property. The file name must
be specified relative to the project's build.xml file. Note
that if you are using the Java Application template, the
IDE creates a manifest file for you.
8-4 NetBeans Developing Applications with NetBeans IDE
Working with Ant
To perform this task
Follow these steps
Disable the generation of a JAR In the Files window, open your project folder and open
file for a project.
build.xml. Override the jar target to have no contents
and no dependencies. For example, add the following
to build.xml:
<target name="jar" />
The IDE automatically recognizes Ant scripts and displays them as Ant script nodes
( ) rather than as normal XML files. You can right-click Ant scripts in the Projects
window, Files window, or Favorites window to access a context menu of commands.
You can also expand the Ant script node to see an alphabetical list of subnodes
representing the Ant script's targets. Each of these subnodes also has a context menu of
commands.
In the Projects, Files, and Favorites windows, an Ant script's subnodes are flagged in
the following ways:
Icon
Meaning
Emphasized Ant target. These targets include a
description attribute, which is displayed as a tooltip.
You define the target's description attribute in the
Source Editor.
Normal Ant target. A target without a description
attribute.
Double-click any of the Ant script's subnodes to jump to that target's location in the
Source Editor. All of the normal XML search tools, selection tools, and keyboard
shortcuts are available for editing Ant scripts, and the IDE provides code completion
for all standard Ant tasks.
When you create a target that you want to run from the command line, give the target
a description attribute. Then, if you forget the names of the targets or what they do,
you can run the ant -projecthelp <script> command from the command line. With
this command, Ant lists only those targets that have a description attribute, together
with their descriptions. Especially when there are many targets in your Ant build
script, emphasizing some and de-emphasizing others can be a useful way to
distinguish between those that you use a lot and those that you use less often.
The font style of a subnode's label in the Projects, Files, and Favorites windows
indicates the following:
■
Normal. A target that is defined within the current Ant script.
■
Italics. A target that is imported from another Ant script.
■
■
Greyed out. An internal target that cannot be run directly. Internal targets have
names beginning with -.
Bold. The default target for the script, if there is one. The default target is declared
as an attribute of the project, together with other project attributes, such as its
name. You define the project's default attribute in the Source Editor.
Targets that are imported from another script but are overridden in the importing
script are not listed. Only the overriding target is listed.
Building Java Projects 8-5
Working with Ant
8.2.2.1 Writing Custom Ant Tasks
You can use custom Ant tasks to expand on the functionality provided by Ant's
built-in tasks. Custom tasks are often used to define properties, create nested elements,
or write text directly between tags using the addText method.
To create a custom Ant task in the IDE:
1. Right-click the package where you would like to place the task and choose New >
Other.
2.
Select the Other category and the Custom Ant Task file type.
3.
Complete the wizard.
When you create the custom Ant task file, the template opens in the Source Editor. The
template contains sample code for many of the common operations performed by Ant
tasks. After each section of code, the template also shows you how to use the task in an
Ant script.
8.2.3 How to Run an Ant Script
The IDE runs targets in your project's Ant script any time you run commands on your
project. You can also manually run a target in any Ant script from the Ant script's node
in the Files window or Favorites window.
To run a target in an Ant script:
■
Right-click the Ant script node and choose the target you want to run from the
Run Target submenu.
Targets are sorted alphabetically. Only emphasized targets are listed.
Choose Other Targets to run a target that has not been emphasized with a
description attribute. Internal targets are excluded from these lists because they
cannot be run independently.
■
Select the Ant script node to display its targets in the Navigator window. Then
right-click the target node and choose Run Target.
The Output window displays compilation errors generated by Ant scripts as normal
Java code compilation errors. You can double-click any error message to jump to the
location in the source where the error occurred.
For free-form projects, you need to modify the Ant script to
map IDE commands to Ant targets. For more information, see
Section 6.2.4.6, "Mapping an Ant Target to an IDE Command."
Note:
To stop a running Ant script:
■
Choose Run > Stop Build/Run from the main menu.
For resources on learning Ant, see http://ant.apache.org/resources.html.
To install the Ant manual into the IDE help system by using the Plugins
Manager:
■
Choose Tools > Plugins and install the Ant Documentation module.
8-6 NetBeans Developing Applications with NetBeans IDE
Working with Ant
8.2.4 How to Debug an Ant Script
You can run an Ant script in the IDE's debugger like you would a Java class.
Debugging an Ant script is handy when you need to diagnose a problem in the Ant
script's execution or examine how the script works.
To debug an Ant script:
■
Right-click the Ant script node in the Projects window, Files window, or Favorites
window and choose any target from the Debug Target menu.
When you start debugging an Ant script, the IDE opens the Debugger windows, goes
to the first line of the target, and stops. You can perform all of the following
operations:
■
Use the Step Into (F7), Step Over (F8), Step Out (Ctrl+F7) commands to go
through the Ant script one line at a time.
■
View the values of instantiated properties in the Local Variables window.
■
Set a watch on a property by choosing Run > New Watch (Ctrl+Shift+F7).
■
Set a line breakpoint by clicking in the Source Editor's left margin and use the
Continue (F5) command to run the Ant script to the line.
■
Set a conditional breakpoint by choosing Run > New Breakpoint (Ctrl+Shift+F8).
■
See the hierarchy of nested calls in the Call Stack window.
For information on using the debugger window, see Chapter 10, "Running and
Debugging Java Application Projects."
8.2.5 How to Create a Shortcut to a Target
You can create a mini-script that serves as a shortcut to a commonly used target in an
Ant script. You can also customize the way the target is run. The shortcut can be saved
as a menu item, toolbar button, or keyboard shortcut.
To create a shortcut to a target:
1. Select the build script node in the Files or Favorites window to display its targets
in the Navigation window.
2.
Right-click the target node and choose Create Shortcut.
3.
Specify where you want to place the shortcut and whether you want to customize
its Ant code and click Next.
4.
Use the remaining pages of the wizard to assign the shortcut to a toolbar, menu, or
keyboard shortcut. The wizard only shows those steps that you selected in Step 3.
To ensure you do not overwrite any existing keyboard shortcuts, you can view
existing keyboard shortcuts by choosing Tools > Options and clicking Keymap.
5.
In the Customize Script page, add or change any of the shortcut script's elements,
such as tasks or properties. This page only appears if you selected the Customize
generated Ant code checkbox in Step 3.
6.
When you have specified all of the necessary information, click Finish. The
shortcut is created in the specified locations.
Building Java Projects 8-7
Working with Ant
8.2.6 How to Configure Ant Settings
You can use the Options window to configure Ant Settings that effect the behavior of
Ant in the IDE.
To configure Ant Settings:
1. From the main window, choose Tools > Options.
2.
Click the Miscellaneous category and then click the Ant tab.
3.
Modify the properties as desired.
You can set the following properties:
■
Ant Home. Displays the installation directory of the Ant executable used by the
IDE. You can change Ant versions by typing the full path to a new Ant installation
directory in this property. You can only switch between versions 1.5.3 and higher
of Ant.
The Ant installation directory must contain a lib/ subdirectory which contains the
ant.jar binary. For example, for the standard Ant 1.5.4 release, the Ant
installation directory is ant/lib/apache-ant-1.5.4. If you enter a directory that
does not match this structure, the IDE gives you an error.
■
■
■
■
■
Save Files. If selected, saves all unsaved files in the IDE before running Ant. It is
recommended to leave this property selected because modifications to files in the
IDE are not recognized by Ant unless they are first saved to disk.
Verbosity Level. Sets the amount of compilation output. You can set the verbosity
lower to suppress informational messages or higher to get more detailed
information.
Always Show Output. If selected, fronts the Output window tab if the Ant output
requires user input or contains a hyperlink. Output that contains hyperlinks
usually denotes an error or warning. If not selected, the IDE always fronts the
Output window for all Ant processes.
Reuse Output Tabs. If selected, writes Ant output to a single Output window tab,
deleting the output from the previous process. If not selected, opens a new tab for
each Ant process.
Properties. Configures custom properties to pass to an Ant script each time you
call Ant. Click the ellipsis button to open the property editor. This property is
similar to the Ant command-line option, -Dkey=value.
The default property, ${build.compiler.emacs}, is available. If you are compiling
using Jikes (build.compiler=jikes), setting this property to true enables
Emacs-compatible error messages. It is recommended that you leave this property
set to true even if you are not using Jikes, since the IDE prefers Emacs-compatible
error messages.
■
Classpath. Contains binaries and libraries that are added to Ant's classpath. For
more information, see Chapter 8.2.8, "Ant Classpaths and Custom Tasks."
8.2.7 How to Switch Versions of Ant
The IDE comes bundled with Ant version 1.9.0 and uses this installation to run Ant
scripts. You can change the version of Ant that the IDE uses by switching the Ant
installation directory in Ant Settings. You can only switch between versions 1.5.3 and
higher of Ant.
8-8 NetBeans Developing Applications with NetBeans IDE
Working with Ant
To switch the IDE's Ant version:
1. Choose Tools > Options from the main window.
2.
Click Miscellaneous in the left panel of the window and expand the Ant node. The
Ant Home section displays the current Ant location and version.
3.
Click Manage Ant Home and select a new Ant installation folder.
The Ant installation directory must contain a lib/ subdirectory which contains the
ant.jar binary. If you enter a directory that does not match this structure, the IDE
gives you an error.
8.2.8 Ant Classpaths and Custom Tasks
By default, the IDE ignores your environment's CLASSPATH variable whenever it runs
Ant. For your build script to use custom tasks, you must add the tasks to Ant's
classpath in the IDE.
To add custom tasks to Ant's classpath within the IDE:
■
Configure the Ant classpath settings in the Options window.
■
Provide an explicit classpath to the tasks in your build script. This is the
recommended method.
8.2.8.1 Adding Binaries to Ant's Classpath in the IDE
If you cannot declare a classpath in your build script, or you are using third-party
build scripts that you cannot alter, you can add the tasks to Ant's classpath in the IDE.
Open the Options window, click Miscellaneous in the left panel of the window, and
expand the Ant node. Use the Classpath section to manage the Ant classpath.
Only add items to the Ant classpath that are needed to run custom tasks. Do not use
the Classpath settings to manage the compilation or runtime classpath of your project
source folders. For information on managing the project classpath, see Chapter 6.2.3.1,
"Managing the Classpath." For free-form projects, you must declare the classpath in
the project settings as the IDE is unaware of project metadata. For more information,
see Chapter 6.2.4.5, "Declaring the Classpath in a Free-Form Project."
8.2.8.2 Build Scripts With an Explicit Classpath
Using an explicit classpath is the recommended method as it ensures that your build
scripts are fully portable. You can write your tasks and include instructions to compile
them and produce a JAR file in the build file. To use these tasks, include the long form
of taskdef, which includes a classpath. Here is a simple example of such a task:
Example 8–3 Sample of a Task with an Explicit Classpath
<project name="test" default="all" basedir=".">
<target name="init">
<javac srcdir="tasksource" destdir="build/taskclasses"/>
<jar jarfile="mytasks.jar">
<fileset dir="build/taskclasses"/>
</jar>
<taskdef name="customtask" classname="com.mycom.MyCustomTask">
<classpath>
<pathelement location="mytasks.jar"/>
</classpath>
</taskdef>
</target>
</project>
Building Java Projects 8-9
Working with Builds
The advantage of this method is that no special preparation is needed to begin using
the script. The script is entirely self-contained and portable. This method also makes it
easier to develop your tasks within the IDE as the script compiles them for you
automatically.
To make the your build scripts even more robust, use a property instead of a
hard-coded location to specify the classpath to your tasks. You can store the property
in the build script itself or in a separate ant.properties file. You can then change the
classpath setting throughout your script by simply changing the value of the specified
property.
For information on customizing Ant scripts, see Chapter 6.2.3.4, "Customizing the
IDE-Generated Ant Script."
8.2.9 How to Install Ant Documentation in the IDE
Use the Ant documentation plugin to install the Ant manual in the IDE.
To install the Ant documentation plugin:
1. Choose Tools > Plugins from the main window.
2.
Select the Available Plugins tab and locate the Ant documentation plugin.
3.
Select the Install checkbox for the Ant documentation plugin and click Install.
4.
Follow the wizard instructions to complete the installation of the plugin.
If you receive the Unable to Connect to the Update Center Server error message,
click OK in the dialog box to close it. Click the Proxy Settings button in the Settings
tab of the Plugin manager and set make sure the proxy settings are correct. Click OK
and try to connect to the update center again.
The official release of the Ant documentation plugin does not always coincide with the
release of the IDE. If you do not see the Ant documentation plugin on the NetBeans
Update Center, it may be posted on the NetBeans Beta Update Center.
8.3 Working with Builds
Before building a project, set the compilation classpath (for details, see Section 6.2.3.1,
"Managing the Classpath." After the project is built, fix any build errors that occurred.
Build errors are displayed in the IDE’s Output window. Once all errors in the code
have been corrected, clean the build and dist directories by deleting their contents.
You can examine the build output by viewing compiled classes in the project’s build
directory and the Javadoc files and built libraries, such as JAR and WAR files, in the
project’s dist directory from the Files window.
8.4 Building a Java Project
When you build a project, the IDE calls the corresponding target in the project's Ant
build script. The IDE compiles the source files and generates the packaged build
output, such as a JAR file or WAR file. You can build a project and all of its required
projects, or build any project individually.
You do not need to build the project or compile individual classes to run the project in
the IDE. By default, the IDE automatically compiles classes when you save them.
These incrementally compiled files are stored in a cache in your user directory and are
copied to your project's build folder when you run or debug your project. This
8-10 NetBeans Developing Applications with NetBeans IDE
Building a Java Project
incremental compilation can save you a lot of time when you are editing and testing
your project. However, you need to build the project to generate distributable files for
the project, such as JAR files.
8.4.1 How to Build a Java Project
By default, the Build Project command is not enabled since most of that command's
functions are handled by the incremental compilation. However, you can use the
Clean and Build command to create a fresh build. When you clean and build a project,
all previous build outputs are deleted and new versions of the build outputs are
created.
To build a project and its required projects:
1. Select the project that you want to build in the Projects window.
2.
Choose Run > Clean and Build Project (Shift+F11).
Alternatively, right-click the project's node in the Projects window and choose
Clean and Build.
The IDE displays the Ant output and any compilation errors in the Output
window. Double-click any error to go to the location in the source code where the
error occurred.
If you are building a project often, you can set it as the main
project by right-clicking on it in the Projects window and choosing Set
as Main Project or by choosing Run > Set Main Project from the main
menu and selecting the project in the sub-menu. After you set a
project as the main project, the keyboard shortcuts for Run (F6), Build
(F11) and Clean and Build (Shift+F11) apply to the main project
regardless of which project is selected in the Projects window.
Keyboard shortcuts for Debug and Profile also apply to the main
project.
Note:
To stop building a project:
■
Choose Run > Stop Build/Run from the main menu.
For standard projects that have a main class specified, the IDE automatically copies
any JAR files on the project's classpath to the dist/lib folder when you build the
project. The IDE also adds each of the JAR files to the Class-Path element in the
application JAR's manifest.mf file. This simplifies running the application outside the
IDE. For more information, see Section 8.9, "Preparing a JAR File for Deployment
Outside the IDE."
To turn off incremental compilation for a project:
1. Right-click the project's node and choose Properties.
2.
In the Project Properties dialog box, select the Compiling node and clear the
Compile On Save checkbox.
You can compile individual files as well entire project files. For information on
compiling individual files, see Section 8.6, "Compiling a Single Java File."
If you need to modify the main class or specify runtime arguments, see Section 10.6,
"Setting the Main Class and Runtime Arguments."
Building Java Projects 8-11
Using a Build Server
8.5 Using a Build Server
The IDE supports creating and starting build jobs using the Hudson build server.
Hudson is an open-source server that you can use to build your applications. You can
use the Hudson server as part of your continuous integration (CI) process for
automated building, verification and testing.
For more information about setting up and using a Hudson build server, see the
following documents: http://hudson-ci.org and
http://wiki.hudson-ci.org/display/HUDSON/Meet+Hudson.
The Jenkins build server also works with the IDE, though this is not as well tested.
To add a Hudson instance:
1. Right-click the Hudson Builders node in the Services window and choose Add
Hudson Instance.
2.
Type the name for the instance to be displayed under the Hudson Builders node.
3.
Specify the server URL, the auto-refresh setting.
4.
Click Add.
After you add a Hudson instance, a node for the instance is added below the Hudson
Builders node. You can expand the node to view the status of builds on that instance.
8.5.1 Creating a Build
You can specify the application that you want the server to build by creating a new
build. When you create the build, you specify the repository containing the sources for
the application. A node for the build is added under the node of the target Hudson
instance in the Services window. To view additional details about the status of builds,
right-click the node for the build and choose Open in Browser.
To set up a new build job:
1. Choose Team > Create Build Job from the main menu.
Alternatively, in the Services window, right-click the Hudson instance you want to
use and choose New Build.
2.
Select the build server instance from the dropdown list.
3.
Specify the name for the build job.
4.
Select the project from the dropdown list.
The build server will use the sources in the project's repository.
5.
Click Create.
After you supply the details for the build, you can start the build process on the server
by right-clicking the build that you want to start and choosing Start Job. When a job is
building, the node for the job is displayed as running. You can expand the node for the
job to view past builds and build artifacts.
To create builds and start jobs you must have access to a
Hudson server.
Note:
8-12 NetBeans Developing Applications with NetBeans IDE
Building a JAR File
8.6 Compiling a Single Java File
By default, you do not need to manually compile the files to run your application in
the IDE. Files in a standard Java project are compiled automatically when you save the
files.
If you have turned off the Compile on Save feature for a project, you can compile files
by building the project or by compiling individual files.
To compile an individual file:
■
Select the file in the Projects window, Files window, or in the Source Editor and
choose Run > Compile File (F9).
If you are using a free-form project, you need an Ant target for this command. The IDE
offers to generate a target the first time you choose the command. In the generated
target, specify the directory where to put the compiled class. You can do so by
specifying a value for the build.classes.dir property in the generated target. For
example, you might add the following line to the line above the <target
name="compile-selected-files-in-src"> entry:
<property name="build.classes.dir"
value="build"/>
Alternatively, you can replace the value of the provided build.classes.dir or rewrite
the target entirely.
For information on managing the classpath, see Section 6.2.3.1, "Managing the
Classpath."
8.7 Building a JAR File
In standard project, the IDE builds a JAR file from your project sources every time you
run the Build command or the Clean and Build command. The JAR file is generated
to the dist directory of your project folder.
For standard projects where the main class is specified, the IDE automatically copies
any JAR files on the project's classpath to the dist/lib folder when you build the
project. The IDE also adds each of the JAR files to the Class-Path element in the
application JAR's manifest.mf file. This simplifies running the application outside the
IDE. For more information, see Section 8.9, "Preparing a JAR File for Deployment
Outside the IDE."
When you create a JAR file or a WAR file, you usually want to include just the
compiled .class files and any other resource files located in your source directory,
such as resource bundles or XML documents. The default filter does this for you by
excluding all .java, .nbattrs, and .form files from your output file.
In addition to the default expressions, you can create additional filters using regular
expressions to control the output files.
Regular Expression
Description
\.html$
Exclude all HTML files
\.java$
Exclude all Java files
(\.html$)|(\.java$)
Exclude all HTML and Java files
(Key)|(\.gif$)
Exclude all GIF files and any files with Key in their name
Building Java Projects 8-13
Packaging an Application as a Native Installer
To specify which files are added to the JAR file:
1. Right-click the project node in the Projects window and choose Properties.
2.
Select the Packaging node in the dialog's left pane.
3.
Specify the files to exclude and any additional settings in the right pane.
To disable generation of a JAR file for a project:
1. In the Files window, open your project folder and open build.xml.
2.
Override the jar target to have no contents and no dependencies. For example, add
the following to build.xml:
<target name="jar" />
Alternatively, if you deselect the Build JAR after Compiling option in the Packaging
category of the Properties window the Java compiler will produce only.class files,
without building JAR files.
In free-form projects, JAR file creation is controlled by your
Ant script.
Note:
See Section 6.2.3.3, "Editing IDE-Generated Ant Scripts" for a description of standard
project Ant scripts and properties files. For information on customizing an Ant build
script, see Section 6.2.3.4, "Customizing the IDE-Generated Ant Script."
8.8 Packaging an Application as a Native Installer
NetBeans IDE supports native packaging for standard Java SE and JavaFX projects. A
native package is a wrapper for your project that turns the project into a
self-contained, platform-specific installation package. The package contains all the
artifacts (source code, Javadoc, Java Runtime and/or JavaFX runtime, a native
application launcher, and so on) needed to install and run the application.
Native packaging does not affect the deployment model of a Java SE or a JavaFX
project. It enables your project to be packaged with the Java runtime to produce an
installer that is common for the operating system you are working in.
Some of the benefits to using native packaging are:
■
Negates runtime version conflicts since the specific JRE is included in the bundle
■
Allows for easy deployment of the application using enterprise deployment tools
■
Can be distributed as a .zip file or packaged as a platform-specific installer
Before opting for native packaging, however, be aware of the following considerations:
■
■
■
■
Users might have to go through several steps to download and install the package
Due to the inclusion of the Java runtime (JavaFX runtime for JavaFX applications),
the size of the application is significantly larger than a standard packaged
application
Application formats are platform-specific (to create a bundle for different
operating systems, you must build your project on each platform)
No autoupdate support exists for bundled applications
The following types of packages can be built for the following platforms:
8-14 NetBeans Developing Applications with NetBeans IDE
Packaging an Application as a Native Installer
■
■
■
Windows
–
bundle image
–
EXE installer (requires Inno Setup 5 or later)
–
MSI installer (requires WiX 3.0 or later)
MAC OS X:
–
bundle image
–
DMG installer
Linux:
–
bundle image
–
rpm installer (requires rpmbuild)
Note that native packaging might require external tools. For instance, if you want to
package a Java application to distribute to a non-Windows environment, you need the
appbundler tool, which is not included in JDK7update 6.
Deployment of a Java SE applet (or application) intended to be launched from a web
browser and deployment of a JavaFX application are similar in that when a Java SE
applet or a JavaFX application are built, both a Java Network Launching Protocol
(JNLP) file and a sample html version of the applet are generated. The WebStart engine
reads the JNLP file and executes the applet accordingly. The html file defines how the
applet is embedded in the web page.
For web page deployment, Java SE and JavaFX applications require the following
packaging tools:
■
■
bin/javafxpackager (command-line utility to produce Java SE or JavaFX
packages)
lib/ant-javafx.jar (set of Ant tasks to produce Java SE or JavaFX packages)
These packaging tools are available with JDK version 7 update 6 and later.
For more information on deploying a Java Web Start Application, see Deploying a Java
Web Start Application at
http://docs.oracle.com/javase/tutorial/deployment/deploymentInDepth/create
WebStartLaunchButtonFunction.html.
For information on using JavaFX packaging tools, see Deploying JavaFX Applications:
http://docs.oracle.com/javafx/2/deployment/jfxpub-deployment.htm.
For information on creating native packaging of a Java SE project in NetBeans, see
Packaging a Distributable JavaApp at
http://wiki.netbeans.org/PackagingADistributableJavaApp.
For more information on native packaging, see the Native packaging for JavaFX page
at the following URL:
https://blogs.oracle.com/talkingjavadeployment/entry/native_packaging_for_
javafx
To enable native packaging actions in the project context menu:
1. Right-click the project node in the Projects window and select Properties from the
context menu.
2.
In the Project Properties dialog, choose the Deployment category.
3.
Select the Enable Native Packaging Actions option.
Building Java Projects 8-15
Preparing a JAR File for Deployment Outside the IDE
4.
Click OK.
A Package as command is added to the project's context menu. When you are ready to
package your application, right-click the project, choose Package as, and select one of
the packaging types:
■
■
All Artifacts - Creates a package that contains only the project artifacts
All Installers - Creates a package that contains the application image and all
applicable installers
■
Image Only - Creates a package that contains the application image only
■
EXE Installer - (Windows only) Creates a package as an executable.exe installer
■
MSI Installer - (Windows only) Creates a package as an executable.msi installer
Contents of the package types is dependent on the platform on
which the IDE is running.
Note:
When you select a packaging type, a subdirectory is created under the project’s dist
directory where the package is stored.
Be aware that the packaging process can take some time to complete and, depending
on the tools you are using, progress might not be indicated.
Note that the contents of the submenu are dependent on the operating system you are
running on. For example, if running on Linux, an RPM installer is available instead of
EXE or MSI. If running on MAC OS, a DMG installer is available.
8.9 Preparing a JAR File for Deployment Outside the IDE
Whenever you build a standard Java project for which a main class is specified, the
IDE automatically copies any JAR files on the project's classpath to the dist/lib
folder. The IDE also adds each of the JAR files to the Class-Path element in the
application JAR's manifest.mf file. This simplifies running the application outside the
IDE.
Though the IDE copies the necessary files to the dist/lib directory automatically, the
following special cases should be kept in mind:
■
■
■
If two JAR files on the project classpath have the same name, only the first JAR file
is copied to the lib folder.
If you added a folder of classes or resources to the classpath (as opposed to a JAR
file or project), none of the classpath elements are copied to the dist folder.
If a library on the project's classpath also has a Class-Path element specified in its
manifest, the content of the Class-Path element must be on the project's runtime
path.
8.9.1 Running an Application JAR Outside of the IDE
Once you have distributed the archive of your application, the application can be run
outside of the IDE from the command line.
To run an application JAR file from the command line:
1. Navigate to the project's dist folder.
2.
Type the following:
8-16 NetBeans Developing Applications with NetBeans IDE
Refactoring Java Projects
java -jar <jar_name>.jar
When you run the jar command, the JAR tool uses the JAR manifest to determine the
application entry point and the paths to the dependent binaries that are specified in
the manifest.mf file.
8.10 Using the Output Window
The Output window is a multi-tabbed window that displays messages from the IDE.
This window is displayed automatically when you encounter compilation errors,
debug your program, generate Javadoc documentation, and so on. You can also open
this window by choosing Window > Output (Ctrl+4).
One function of the Output window is to notify you of errors found while compiling
your program. The error message is displayed in blue underlined text and is linked to
the line in the source code that caused the error. The Output window also provides
links to errors found when running Ant build scripts and when checking and
validating XML documents. For information on validating XML documents, see
Section 18.2.5, "How to Validate an XML Document."
If the file that contains the error is open, the Source Editor jumps to the line containing
each error as you move the insertion point into the error in the Source Editor. You can
also use the F12 and Shift+F12 keyboard shortcuts to move to the next and previous
error in the file.
Every action that is run by an Ant script, such as compiling, running, and debugging
files, sends its output to the same Output window tab. If you need to save some
output, you can copy and paste it to a separate file.
To set Ant to print the command output for each new target to a new Output
window tab:
1. Choose Tools > Options.
2.
Click Miscellaneous in the left panel of the window, expand the Ant node, and
select the checkbox in the Reuse Output Tabs property.
When you run a program that requires user input, a new tab appears in the Output
window. This tab includes a cursor. You can enter information in the Output window
as you would on a command line.
8.11 Refactoring Java Projects
Refactoring is the use of small transformations to restructure code without changing
any program behavior. Just as you factor an expression to make it easier to understand
or modify, you refactor code to make it easier to read, simpler to understand, and
faster to update. And just as a refactored expression must produce the same result, the
refactored program must be functionally equivalent with the original source.
Some common motivations for refactoring code include:
■
Making the code easier to change or easier to add a new feature.
■
Reducing complexity for better understanding.
■
Removing unnecessary repetition.
■
Enabling use of the code for other needs or more general needs.
■
Improving the performance of your code.
Building Java Projects 8-17
Refactoring Java Projects
The IDE's refactoring features simplify code restructuring by evaluating the changes
that you want to make, showing you the parts of your application that are affected,
and making all necessary changes to your code. For example, if you use the Rename
operation to change a class name, the IDE finds every usage of that name in your code
and offers to change each occurrence of that name for you.
For information on how to refactor an Enterprise Bean, see Section 8.11.22, "How to
Refactor an Enterprise Bean."
8.11.1 How to Undo Refactoring Changes
You can undo any changes that you made using the commands in the Refactor menu.
When you undo a refactoring, the IDE rolls back all the changes in all the files that
were affected by the refactoring.
To undo a refactoring command:
1. Go to the Refactor menu in the main menu bar.
2.
Choose Undo.
The IDE rolls back all the changes in all the files that were affected by the
refactoring.
If any of the affected files have been modified since the refactoring took place, the
Refactoring Undo is not available.
8.11.2 How to Find Class, Methods, and Field Usages
Use the Find Usages command to determine everywhere a class, method, or field is
used in your project's source code.
To find where a class, interface, method, or field is used in your project:
1. In the Projects window or the Source Editor window, right-click the code element
and choose Find Usages (Alt+F7).
2.
3.
In the Find Usages dialog box, select options for the scope of the search:
■
Classes and interfaces
■
Methods
■
Fields
Click Find.
The Usages window displays the file name and the line of code for each usage
found in that file.
To jump to a specific occurrence of the code element:
■
Double-click a file name in the Usages window to open the file.
■
Double-click a line of code to open the file and to position the cursor on that line of
code.
8.11.2.1 Classes and Interfaces
For classes and interfaces, the Find Usages command displays all the code lines that:
■
Use the type, such as creating a new instance, importing, extending,
implementing, casting, or throwing.
8-18 NetBeans Developing Applications with NetBeans IDE
Refactoring Java Projects
■
Use the type's members and static variables
After you choose the Find Usages command on a class or interface, the Find Usages
dialog box might give you additional options:
■
■
Find All Subtypes checkbox. If selected, only usages of subtypes of the class are
displayed.
Find Direct Subtypes Only checkbox. If selected, only usages of direct subtypes
are displayed. Subtypes of those subtypes are ignored.
8.11.2.2 Methods
For methods, the Find Usages command displays the code lines that:
■
Call the method
■
Override the method
After you choose the Find Usages command on a method, the Find Usages dialog box
might give you additional options:
■
■
Include overloaded methods checkbox. If selected, any occurrences of overloaded
methods are displayed.
Search from Base Class checkbox. If selected, the output shows every usage of
that base method. This option only appears if the method that you are finding
usages for overrides another method.
8.11.2.3 Fields
For fields, the Find Usages command displays the code lines that:
■
Set the field to a value
■
Get the value of a field
8.11.2.4 Additional Find Mechanisms
Other IDE tools that enable you to search for all the places where specific text is used
in a project include:
■
■
Finding and Replacing Text. Searches for all the places where specific text is used
in a source file that is open in the Java Editor. Choose Edit > Find to open the Find
dialog box, or choose Edit > Replace to open the Replace dialog box. These
commands finds all matching strings, regardless of whether the string is a Java
element.
Find in Projects. As with the Find command, the Find in Projects command
searches for matching strings, regardless of whether the string is a class name.
Choose Edit > Find in Projects to open the Find in Projects dialog box and then
type the string of text that you are looking for.
To find where a method is declared in a source file, you can
either double-click the method in the Projects window or Navigator
window. If the method is declared in a different source file, right-click
the method and choose Go To > Declaration from the context menu.
Note:
8.11.3 How to Rename a Class or Interface
Use the refactoring Rename command to rename a class or interface. When you
rename a class or interface through refactoring, all instances of that class or interface
Building Java Projects 8-19
Refactoring Java Projects
are renamed throughout the project. If you do not want to enact a global change, you
can simply select the desired class or interface and edit its name.
To rename a class or interface and update references to it throughout your
project:
1. In the Projects window or the Source Editor window, right-click the class or
interface and choose Refactor > Rename from the contextual menu.
2.
In the Rename dialog box, type the new name of the class or interface.
3.
Click Next.
4.
In the Refactoring window, review the lines of code that are affected by the change
and clear the checkbox of any code that you do not want changed.
5.
Click Do Refactoring to apply the selected changes.
Always perform a clean build after completing any refactoring commands. Clean a
build by right-clicking the project's node in the Projects window and choosing Clean
and Build Project.
To rename the class or interface without refactoring:
1. In the Projects window, rename the class's node inline.
You can rename a class this way by selecting the node of the class and then
pressing F2 to make the name editable.
2.
In the Rename dialog box, select the Rename Without Refactoring checkbox.
3.
Click Next.
If you need to back out a refactoring change, see Section 8.11.1, "How to Undo
Refactoring Changes."
8.11.4 How to Rename a Field or Method
Use the refactoring Rename command to rename a field or method. As with renaming
a class or interface, the scope of a renaming operation is the full scope of the element in
the project. Field and method usages are replaced everywhere they appear in the
project. Parameters and variables are renamed only in the lexical scope of their
definitions. Other elements with the same name are not modified.
To rename a field or method and update references to it throughout your project:
1. In the Source Editor, right-click the field or method and choose Refactor >
Rename from the context menu
2.
In the Rename dialog box, type the new name of the field or method.
3.
(Optional) Click Preview. In the Refactoring window, at the bottom of the Source
Editor, review the lines of code that are affected by the change and clear the
checkbox of any code that you do not want changed.
4.
Click Do Refactoring to apply the selected changes.
For quick in-place renaming, place the cursor in the item that you want to rename, and
press Ctrl+R. Type the new name. Press Escape to finish renaming.
Always perform a clean build after completing any refactoring commands. You can do
a clean build by right-clicking the project's node in the Projects window and choosing
Clean and Build Project.
8-20 NetBeans Developing Applications with NetBeans IDE
Refactoring Java Projects
For information on how to undo refactoring, see Section 8.11.1, "How to Undo
Refactoring Changes."
8.11.5 How to Move a Class to Another Java Package
Use the refactoring Move command to move a class to another package. All references
to the class are updated the next time you build the project.
To move a class to another package and to change the code that references that
class:
1. In the Projects window or the Source Editor window, right-click the class and
choose Refactor > Move from the context menu.
2.
In the Move Class dialog box, select the package from the To Package drop-down
list or type the fully qualified package name, such as com.myCom.myPkg.
3.
Click Refactor or Preview.
If you click Refactor, the IDE applies the changes automatically and skips the
remaining steps.
If you click Preview, the Refactoring window displays the lines of code that are
affected. Review the list and clear the checkbox of any code that you do not want
changed. If the class that you are pushing members from has multiple subclasses
and you do not want the members to be pushed to all of them, be sure to clear the
checkboxes for the corresponding subclasses. Click Do Refactoring to apply the
selected changes.
You can also initiate the moving of a class by dragging a class's node in the Projects
window to another package's node or by cutting and pasting a class's node.
Always perform a clean build after completing any refactoring commands. Clean a
build by right-clicking the project's node in the Projects window and choosing Clean
and Build Project.
To move a class without doing refactoring:
1. In the Projects window, manually move the class to another package.
You can cut and paste the class or drag and drop it into another package.
2.
In the Move Class dialog box, select the Move Without Refactoring checkbox.
3.
Click Next.
You can also use the Move command to move the methods and fields of a selected
class to another package.
To move the members of a class:
1. In the Projects window or the Source Editor window, right-click the method and
choose Refactor > Move from the context menu.
2.
In the Move Members dialog box, select the package from the drop-down list or
type the fully qualified package name, such as com.myCom.myPkg.
3.
Enter the class name or select the target class from the drop-down list.
4.
Select the members you want to move.
5.
Select the visibility level.
6.
Select whether to keep the Javadoc as it is or update it.
Building Java Projects 8-21
Refactoring Java Projects
7.
Check the option if you want to keep the original method signatures in the source
class and let them call the new methods in the target class.
8.
Check the option if you want the original methods in the source class to be
deprecated.
9.
Click Refactor or Preview.
If you click Refactor, the IDE applies the changes automatically and skips the
remaining steps.
If you click Preview, the Refactoring window displays the lines of code that are
affected. Review the list and clear the checkbox of any code that you do not want
changed. If the class that you are pushing members from has multiple subclasses
and you do not want the members to be pushed to all of them, be sure to clear the
checkboxes for the corresponding subclasses. Click Do Refactoring to apply the
selected changes.
8.11.6 How to Move an Inner Class One Level Up
Use the Move Inner to Outer Level command to do move an inner class one level up
in hierarchy. For example, if the selected class is directly nested in a top-level class, a
new top-level class is created. If the selected class is nested in an inner class, the
selected class is moved to the level of the inner class in which it was nested.
To use the Move Inner to Outer Level operation:
1. In the Source Editor, place the insertion point in the inner class that you want to
convert.
2.
Choose Refactor > Move Inner to Outer Level.
The Move Inner to Outer Level dialog box appears.
3.
In the Class Name field, change the name of the class, if necessary.
4.
(Optional) Select the Declare Field for the Current Outer Class checkbox if you
want to generate an instance field for the current outer class and pass the outer
class to the constructor. If you select this checkbox, type a name for the outer class'
instance field.
5.
Click Refactor or Preview.
If you click Refactor, the IDE applies the changes automatically and skips the
remaining steps.
If you click Preview, the Refactoring window displays the lines of code that are
affected. Review the list and clear the checkbox of any code that you do not want
changed. If the class that you are pushing members from has multiple subclasses
and you do not want the members to be pushed to all of them, be sure to clear the
checkboxes for the corresponding subclasses. Click Do Refactoring to apply the
selected changes.
Always perform a clean build after completing any refactoring commands. You
can do a clean build by right-clicking the project's node in the Projects window
and choosing Clean and Build Project.
8.11.7 How to Move a Class Member to a Superclass
Use the Pull Up command to move methods and fields to a class that their current
class inherits from.
8-22 NetBeans Developing Applications with NetBeans IDE
Refactoring Java Projects
To move a class member to a superclass:
1. In the Source Editor or Projects window, select the class that contains members
that you want to move.
2.
Choose Refactor > Pull Up.
The Pull Up dialog box appears and displays a list of the class's members and any
interfaces that the class implements.
3.
In the Destination Supertype drop-down list, select the class to which you want to
move the members.
4.
Select the checkbox for the member or members that you want to move.
If the current class implements any interfaces, there are checkboxes for these
interfaces. If you select a checkbox for an interface, the implements statement for
that interface is moved to the superclass.
5.
(Optional) If you want to make a method abstract, select the Make Abstract
checkbox for the method. If you select this checkbox, the method will be declared
in the superclass as an abstract method and overridden in the current class. The
method will be assigned the protected access modifier.
6.
Click Refactor or Preview.
If you click Refactor, the IDE applies the changes automatically and skips the
remaining steps.
If you click Preview, the Refactoring window displays the lines of code that are
affected. Review the list and clear the checkbox of any code that you do not want
changed. If the class that you are pushing members from has multiple subclasses
and you do not want the members to be pushed to all of them, be sure to clear the
checkboxes for the corresponding subclasses. Click Do Refactoring to apply the
selected changes.
Always perform a clean build after completing any refactoring commands. You
can do a clean build by right-clicking the project's node in the Projects window
and choosing Clean and Build Project.
8.11.8 How to Move a Class Member to a Subclass
Use the Push Down command to move inner classes, methods, and fields to all
subclasses of their current class.
To move a class member to a subclass:
1. In the Source Editor or Projects window, select the class member or class members
that you want to move.
2.
Choose Refactor > Push Down.
The Push Down dialog box appears and displays a list of the class's members.
Make sure the checkbox for the member that you want to move is selected.
3.
(Optional) Select the Keep Abstract checkbox for any abstract methods that you
want to keep defined in the current class and have implemented in the subclass.
The checkbox in the left column must also be checked for the class definition to be
copied to the subclass.
4.
Click Refactor or Preview.
If you click Refactor, the IDE applies the changes automatically and skips the
remaining steps.
Building Java Projects 8-23
Refactoring Java Projects
If you click Preview, the Refactoring window displays the lines of code that are
affected. Review the list and clear the checkbox of any code that you do not want
changed. If the class that you are pushing members from has multiple subclasses
and you do not want the members to be pushed to all of them, be sure to clear the
checkboxes for the corresponding subclasses. Click Do Refactoring to apply the
selected changes.
Always perform a clean build after completing any refactoring commands. You
can do a clean build by right-clicking the project's node in the Projects window
and choosing Clean and Build Project.
8.11.9 How to Copy a Class
Use the refactoring Copy command to copy a class.
To copy a class, either to the same or to another package, and to change the
code that references that class:
1. In the Projects window or the Source Editor window, right-click the class and
choose Refactor > Copy from the contextual menu.
2.
In the Copy Class dialog box, select the package from the To Package combo box
or type the fully qualified package name, such as com.myCom.myPkg.
3.
Click Refactor or Preview.
If you click Refactor, the IDE applies the changes automatically and skips the
remaining steps.
If you click Preview, the Refactoring window displays the lines of code that are
affected. Review the list and clear the checkbox of any code that you do not want
changed. If the class that you are pushing members from has multiple subclasses
and you do not want the members to be pushed to all of them, be sure to clear the
checkboxes for the corresponding subclasses. Click Do Refactoring to apply the
selected changes.
You can also initiate the copying of a class by dragging a class's node in the Projects
window to another package's node or by cutting and pasting a class's node.
Always perform a clean build after completing any refactoring commands. You can do
a clean build by right-clicking the project's node in the Projects window and choosing
Clean and Build Project.
To copy a class without doing refactoring:
1. In the Projects window, manually copy the class to another package.
You can cut and paste the class, or you can use drag and drop.
2.
In the Copy Class dialog box, select the Copy Without Refactoring checkbox.
3.
Click Next.
8.11.10 How to Encapsulate a Field
Field encapsulation is the act of restructuring your code so that a field is accessed only
by a pair of accessor methods. Accessor methods are also referred to as read/write
methods or getters and setters.
Typically when you encapsulate a field, you change the field's access modifier to
private so that the field can not be directly referenced from outside of the class. For
other classes to reference the field, they have to use the accessor methods.
8-24 NetBeans Developing Applications with NetBeans IDE
Refactoring Java Projects
Use the Encapsulate Fields command to:
■
■
■
Generate accessor methods for fields. The names of these methods take the form of
getfield-name and setfield-name.
Adjust the access modifier for the fields.
Replace direct references in your code to the fields with calls to the accessor
methods.
To encapsulate a field:
1. In the Source Editor, right-click a field or a reference to the field and choose
Refactor > Encapsulate Fields from the context menu.
2.
In the List of Fields to Encapsulate table in the Encapsulate Fields dialog, make
sure the checkbox for the field that you want to encapsulate is selected. You can
select multiple fields.
3.
(Optional) Set the field's visibility.
4.
(Optional) Set the accessors' (getter and setter) visibility.
5.
(Optional) If you do not want the IDE to replace code to use the accessor methods,
clear the Use Accessors Even When Field is Accessible checkbox.
This option only has an impact if both of the following are true:
■
■
6.
You have direct references to the field in your code.
You have set the field's accessor modifier so that the field is visible to the
classes with these references.
Click Refactor or Preview.
If you click Refactor, the IDE applies the changes automatically and skips the
remaining steps.
If you click Preview, the Refactoring window displays the lines of code that are
affected. Review the list and clear the checkbox of any code that you do not want
changed. If the class that you are pushing members from has multiple subclasses
and you do not want the members to be pushed to all of them, be sure to clear the
checkboxes for the corresponding subclasses. Click Do Refactoring to apply the
selected changes.
Always perform a clean build after completing any refactoring commands. You can do
a clean build by right-clicking the project's node in the Projects window and choosing
Clean and Build Project.
8.11.11 How to Change a Method’s Signature
Use the Change Method Parameters command to alter the signature of a method and
have those changes propagated in all of the code that calls this method. Specifically,
you can:
■
Add parameters to a method.
■
Reorder the parameters in a method signature.
■
Change the access modifier for the method.
To add a parameter to a method:
1. Right-click the method in the Source Editor and choose Refactor > Change
Method Parameters from the contextual menu.
Building Java Projects 8-25
Refactoring Java Projects
2.
In the Change Method Parameters dialog, click the Add to add a parameter.
3.
In the Parameters table, modify the name and type of the parameter that you have
added. Then add a default value for the parameter in the Value column. You need
to double-click a cell to make it editable.
4.
Click Refactor or Preview.
If you click Refactor, the IDE applies the changes automatically and skips the
remaining steps.
If you click Preview, the Refactoring window displays the lines of code that are
affected. Review the list and clear the checkbox of any code that you do not want
changed. If the class that you are pushing members from has multiple subclasses
and you do not want the members to be pushed to all of them, be sure to clear the
checkboxes for the corresponding subclasses. Click Do Refactoring to apply the
selected changes.
Always perform a clean build after completing any refactoring commands. You
can do a clean build by right-clicking the project's node in the Projects window
and choosing Clean and Build Project.
To reorder a parameter in a method signature:
1. Right-click the method in the Source Editor and choose Refactor > Change
Method Parameters from the context menu.
2.
Select a parameter that you want to move and click Move Up or Move Down to
change its position in the list.
3.
Click Next.
If you click Refactor, the IDE applies the changes automatically and skips the
remaining steps.
4.
The Refactoring window displays the lines of code that are affected.
Review the list and clear the checkbox of any code that you do not want changed.
5.
Click Do Refactoring to apply the selected changes.
To change a method's access modifier:
1. Right-click the method in the Source Editor and choose Refactor > Change
Method Parameters from the contextual menu.
2.
Choose a modifier from the Visibility Modifier combo box.
3.
Click Refactor or Preview.
If you click Refactor, the IDE applies the changes automatically and skips the
remaining steps.
If you click Preview, the Refactoring window displays the lines of code that are
affected. Review the list and clear the checkbox of any code that you do not want
changed. If the class that you are pushing members from has multiple subclasses
and you do not want the members to be pushed to all of them, be sure to clear the
checkboxes for the corresponding subclasses. Click Do Refactoring to apply the
selected changes.
Always perform a clean build after completing any refactoring commands. You
can do a clean build by right-clicking the project's node in the Projects window
and choosing Clean and Build Project.
8-26 NetBeans Developing Applications with NetBeans IDE
Refactoring Java Projects
8.11.12 How to Invert a Boolean Method or Variable
When testing for a logical condition, it can be helpful to replace a Boolean method or
variable with an opposite definition.
To invert a Boolean method or variable:
1. Select the method or variable in the Source Editor.
2.
Choose Refactor > Invert Boolean.
3.
Modify the name of the method or variable in the New Name field.
4.
Click Refactor.
If you click Refactor, the IDE applies the changes automatically and skips the
remaining steps.
If you click Preview, the Refactoring window displays the lines of code that are
affected. Review the list and clear the checkbox of any code that you do not want
changed. If the class that you are pushing members from has multiple subclasses and
you do not want the members to be pushed to all of them, be sure to clear the
checkboxes for the corresponding subclasses. Click Do Refactoring to apply the
selected changes.
Always perform a clean build after completing any refactoring commands. You can do
a clean build by right-clicking the project's node in the Projects window and choosing
Clean and Build Project.
8.11.13 Replacing a Constructor
You can replace a public constructor with references to a newly created builder class.
Use the Replace Constructor With Builder command to introduce a builder class that
calls the hidden constructor and replaces existing calls to the constructor with calls to
the builder class.
To replace a constructor with a builder class:
1. Select a constructor in the Source Editor.
2.
Choose Refactor > Replace Constructor with Builder
3.
Edit the setter name and default value as needed by double-clicking the
appropriate column.
4.
Check the Optional Setter option if you want to omit a setter method in the builder
invocation if the default value of a field matches the parameter value in the
constructor invocation.
5.
Specify the name of the builder class.
6.
Click Do Refactoring.
You can also replace a public constructor with a factory method. Use the Replace
Constructor with Factory command to introduce a new static factory method that calls
the constructor and replaces existing calls to the constructor with calls to the new
factory method. After replacing a public constructor with a factory method, the
constructor is made private.
To convert a constructor into a factory method:
1. Select a constructor in the Source Editor.
2.
Choose Refactor > Replace Constructor with Factory.
Building Java Projects 8-27
Refactoring Java Projects
3.
Specify a factory method name.
4.
Click Do Refactoring.
For either operation, you can preview the changes before initiating refactoring. Click
Preview and check the items displayed in the Refactoring window. Clear the
checkboxes for the parts of the code the you do not want changed. Click Do
Refactoring to make the changes.
8.11.14 How to Introduce a Variable, Constant, Field, or Method
When you introduce a variable, constant, field, or method in the IDE, you change a
selected code fragment into a variable, constant, field, or method. Typically you do this
when you want to separate a piece of code into smaller, more meaningful fragments.
Creating smaller fragments can increase the reusability of your code as you can
separate the parts of your code that may need to be updated more often. By giving
your new method a meaningful name, you can increase the comprehensibility of your
code.
For example, when you introduce a method in the IDE, you replace statements in a
class with a call to a method. Before statements are replaced, the IDE opens the
Introduce Method dialog box where you specify the parameters and modifiers for the
method. The IDE searches your open projects for occurrences of the statements you
specified and replaces the occurrences with the method call.
To introduce a variable, constant, field, parameter, or method:
1. In the Source Editor, select the statements you want to introduce as a new variable,
constant, field, or method.
2.
Choose Refactor > Introduce.
Choose the appropriate menu item, such as Introduce Method.
3.
Type the name for your new item in the Name field and choose the access type.
4.
Provide the information required for the item.
For example, to introduce a method, you must choose an access type.
5.
Select the Replace Also Other Occurrences to replace all occurrences of the
selected item with the new reference
6.
Click OK to apply the changes to the selected files.
In situations where you need to add multiple methods to a class but cannot modify the
class, you can create a new class that contains these methods. You can this class as a
local extension that is either a subclass or wrapper of the original class.
To introduce a local extension:
1. In the Source Editor, select the class for which you want an extension.
2.
Choose Refactor > Introduce > Local Extension.
The project and source folder name are automatically entered in the dialog box.
Use the drop-down list to change the values if needed.
3.
Change the name of the new class to be easily identified.
4.
Specify the name of package to store the extension class.
5.
Select whether the extension class is a wrapper or subclass of the original class.
6.
Select the Equality type if the wrapper option is chosen.
8-28 NetBeans Developing Applications with NetBeans IDE
Refactoring Java Projects
7.
(Optional) Replace all usages of the original class with the extension class
throughout the source code.
Troubleshooting
If you encounter an error message when introducing a method, check to see that the
statements you selected meet the following criteria:
■
■
■
Selections cannot have more than one output parameter.
Selections cannot contain a break or continue statement if the corresponding
target is not part of the selection.
Selections cannot contain a return statement that is not the last statement of the
selection. The selected code is not allowed to return conditionally.
8.11.15 How to Inline a Variable, Method, or Constant
Inline refactoring allows you to replace references to a variable, method, or constant
with the values assigned to the variable, the implementation of the method, or the
constant, respectively.
To inline a variable, constant, or method:
1. Select a local variable (temp) method, or constant in the Source Editor.
2.
Choose Refactor > Inline.
3.
Click Do Refactoring in the Refactoring window.
Inline Temp replaces all references to a local variable with its initial value and removes
the declaration.
Inline Method replaces all method calls with the method's body and removes the
declaration.
Inline Constant replaces all constant references with its defined value and removes the
declaration.
8.11.16 How to Extract a Superclass
Use the refactoring Extract Superclass command to extract the common features of
classes to create a new superclass. When you extract a superclass, the IDE does the
following operations:
■
Creates a new class with the selected methods and fields in the selected class. You
can also have the new class implement interfaces that are implemented in the
selected class.
If the selected class extends a class, the new class also extends the same class.
■
■
The selected class is modified so that it extends the new superclass. All selected
interfaces are removed from the implements clause.
Removes the selected public and protected fields from the base class.
Click Preview in the Extract Interface dialog box to preview the files that are affected.
A list of the files to be modified is displayed in the Refactoring window. If you do not
want certain occurrences to be changed, you can clear the checkbox for that occurrence
in the Refactoring window. Double-clicking on an occurrence opens that file in the
Source editor, and the caret is placed in the line containing the occurrence.
Building Java Projects 8-29
Refactoring Java Projects
To extract a superclass:
1. Open the class containing the methods or fields you want to move to the new
superclass.
2.
In the Source editor, right-click in the file and choose Refactor > Extract
Superclass.
The Extract Superclass dialog box opens.
3.
Type the name for your new superclass in the Superclass Name text field.
4.
Select the members you want to extract to the new superclass.
5.
(Optional) If you want to make a method abstract, select the Make Abstract
checkbox for the method. If you select this checkbox, the method is declared in the
superclass as an abstract method and overridden in the current class. The method
will be assigned the protected access modifier.
6.
Click Refactor or Preview.
If you click Refactor, the IDE applies the changes automatically and skips the
remaining steps.
If you click Preview, the Refactoring window displays the lines of code that are
affected. Review the list and clear the checkbox of any code that you do not want
changed. If the class that you are pushing members from has multiple subclasses
and you do not want the members to be pushed to all of them, be sure to clear the
checkboxes for the corresponding subclasses. Click Do Refactoring to apply the
selected changes.
Always perform a clean build after completing any refactoring commands. You
can do a clean build by right-clicking the project's node in the Projects window
and choosing Clean and Build Project.
8.11.17 How to Extract an Interface
Use the Extract Interface command to create a new interface from the selected public
non-static methods in a class or interface. Because an interface does not restrict how its
methods are implemented, interfaces can be used in classes that have different
functions. Creating interfaces can increase the reusability of your code as you can have
multiple classes implementing the same interface. If necessary, you can then modify
the interface instead of making modifications in multiple classes.
When you extract an interface, the IDE does the following things:
■
■
Creates a new interface with the selected methods in the same package as the
current class or interface.
Updates the implements or extends clause of the current class or interface to
include the new interface. Any interfaces that the new interface extends are
excluded.
To extract an interface:
1. Open the class or interface containing the methods you want to move to an
interface.
2.
In the Source editor, right-click in the file and choose Refactor > Extract Interface.
The Extract Interface dialog box opens.
3.
Type the name for your interface in the Interface Name text field.
8-30 NetBeans Developing Applications with NetBeans IDE
Refactoring Java Projects
4.
In the Members to Extract list, select the members that you want to extract to the
new interface.
If the class from which you are extracting an interface already implements an
interface, there is also an item for that implemented interface. If you select the
checkbox for that interface, the implements clause for that new interface is moved
to the new interface that you are extracting.
5.
Click Refactor or Preview.
If you click Refactor, the IDE applies the changes automatically and skips the
remaining steps.
If you click Preview, the Refactoring window displays the lines of code that are
affected. Review the list and clear the checkbox of any code that you do not want
changed. If the class that you are pushing members from has multiple subclasses
and you do not want the members to be pushed to all of them, be sure to clear the
checkboxes for the corresponding subclasses. Click Do Refactoring to apply the
selected changes.
Always perform a clean build after completing any refactoring commands. You
can do a clean build by right-clicking the project's node in the Projects window
and choosing Clean and Build Project.
8.11.18 How to Use a Supertype Where Possible
Use the Use Supertype Where Possible command to replace references to a type with
references to one of the type's supertypes. Before replacing those references, the IDE
checks to make sure that supertype and its members are accessible to all of the code
that would be changed to reference them.
To initiate the Use Supertype Where Possible operation:
1. In the Source Editor or Projects window, select the type to which you want to
apply the operation. The type can be a class, interface, or enumeration.
2.
Choose Refactor > Use Supertype Where Possible.
3.
In the Select Supertype to Use list, select the supertype that you want to be
referenced in place of the type your code currently uses.
4.
Click Refactor or Preview.
If you click Refactor, the IDE applies the changes automatically and skips the
remaining steps.
If you click Preview, the Refactoring window displays the lines of code that are
affected. Review the list and clear the checkbox of any code that you do not want
changed. If the class that you are pushing members from has multiple subclasses
and you do not want the members to be pushed to all of them, be sure to clear the
checkboxes for the corresponding subclasses. Click Do Refactoring to apply the
selected changes.
Always perform a clean build after completing any refactoring commands. You
can do a clean build by right-clicking the project's node in the Projects window
and choosing Clean and Build Project.
8.11.19 How to Convert an Anonymous Inner Class to a Regular Inner Class
Use the Convert Anonymous Class to Inner command to convert an anonymous class
to an inner class that contains a name and constructor. When you use this operation, a
Building Java Projects 8-31
Refactoring Java Projects
new inner class is created and the anonymous inner class is replaced with a call to the
new inner class.
To use the Convert Anonymous Class to Inner operation:
1. In the Source Editor, place the insertion point in the anonymous inner class that
you want to convert.
2.
Press Alt+Enter and choose Convert Anonymous Class to Inner from the menu
that appears.
8.11.20 How to Safely Delete Java Code
Use the Safely Delete command to have the IDE check for references to a code
element before you delete that code element. You can use this command on classes,
methods, and fields.
When you apply the Safely Delete command to a code element, the Safe Delete dialog
box opens and helps walk you through the process.
To initiate the Safely Delete operation:
1. Select the code element that you want to delete and choose Refactor > Safely
Delete.
2.
In the Safe Delete dialog box, make sure that the IDE has identified the right
element to be deleted and click Next.
■
■
If the code element is not referenced by other code, the Safe Delete dialog box
closes and the code element is deleted.
If the code element to be deleted is referenced by other code, a warning and a
Show Usages button appear in the Safely Delete dialog box. See the following
section for information on completing or canceling the operation.
8.11.20.1 Handling Deletions When The Code Element is Referenced
When the message beginning with References to selected elements were found
appears in the Safely Delete window, you can proceed in one of the following ways:
■
■
Remove the references to the code to be deleted and then continue the Safely
Delete operation.
Click Cancel to cancel the command.
If you mistakenly delete a code element that is still referenced by other code, you can
reverse the deletion with the Refactor > Undo command.
To remove references to code and continue with the deletion of the class
element:
1. In the Safely Delete dialog box, click Show Usages.
A list of the references to the code that you want to delete is displayed in the
Usages window.
2.
Double-click a node for code that references the class to be deleted.
The referencing class opens in the Source Editor.
3.
Remove the reference to the code that you want to delete.
8-32 NetBeans Developing Applications with NetBeans IDE
Refactoring Java Projects
Use the Safely Delete command to remove this reference. If there are references to
that code as well, you can click Show Usages to open a new tab in the Usages
window.
4.
Repeat steps 2 and 3 until all references to the code that you want to delete are
removed.
5.
In the Usages window, click Rerun Safe Delete.
The Safely Delete command is run again. If there are any references that you have
not removed, a warning appears and you can click Show Usages to resume the
process of resolving the references.
6.
Click Preview in the Safe Delete window, then click Next.
7.
Click Do Refactoring in the Refactoring window to proceed with the deletion.
8.11.21 Using Hints in Source Code Analysis and Refactoring
In the Source Editor, a hint is displayed when the IDE performs source code analysis
and detects common syntax errors or problems.
An editor hint is available if a light bulb icon appears in the left margin of the Source
Editor while you are developing your code. Click the light bulb icon or press
Alt+Enter to read the hint. Click the hint or press Enter to generate the code suggested
by the hint.
You can select which hints to display when you type in the
Source Editor in the Hints tab of the Editor panel in the Options
dialog box. You can access it by choosing Tools > Options from the
main IDE's menu, and then clicking the Editor category.
Note:
You can use hints when running source code inspections on a selected file, package, or
project and refactoring your sources.
To initiate the Inspect operation:
1. Choose Source > Inspect from the main IDE's menu.
2.
In the Scope drop-down list of the Inspect dialog box, select a file, package, or
project(s) to be inspected.
3.
Select either of the following:
■
In the Configuration drop-down list, select NetBeans Java Hints to choose all
hints available in the IDE to be used in the source code analysis.
Alternatively, click Manage to open the Configurations dialog box and specify
a set of hints to be used in the source code analysis. Click OK.
■
4.
Select Single Inspection and choose a single hint to be used in the source code
analysis.
Click Inspect to perform the source code analysis.
After the Inspect operation is completed, the hints that can be applied to your code
are displayed in the Inspector Window below the Source Editor.
To initiate the Inspect and Transform operation:
1. Choose Refactor > Inspect and Transform from the main IDE's menu.
Building Java Projects 8-33
Working with Maven in the IDE
2.
In the Inspect drop-down list of the Inspect and Transform dialog box, select a file,
package, or projects to be inspected.
Alternatively, click the button to the right to open the Custom Scope dialog box
and specify the custom code to be inspected.
3.
Select either of the following to use:
■
In the Configuration drop-down list, select a predefined configuration of hints
available in the IDE (for example, Convert to JDK 7) to be used in the source
code analysis.
Alternatively, click Manage to open the Manage Inspections dialog box and
group a set of hints into a configuration to be used in the source code analysis.
Click OK.
■
4.
Select Single Inspection and choose a single hint to be used in the source code
analysis.
Click Refactor to run the source code analysis.
After the Inspect and Transform operation is completed, the results are displayed
in the Inspect and Transform dialog box. Click Preview to display the source code
refactorings proposed by the IDE upon conducting the source code analysis with
the hints you specified.
Check the complete list of hints available in the IDE at the Java Hints wiki page at
http://wiki.netbeans.org/Java_Hints.
For information on how to create a NetBeans module that provides one or more Java
hints, see the NetBeans Java Hint Module Tutorial at
https://platform.netbeans.org/tutorials/nbm-java-hint.html.
8.11.22 How to Refactor an Enterprise Bean
Refactoring is especially useful in EJB modules, since changing the name of one
method often means you have to update the name in all of the related interfaces,
deployment descriptors, and dependent classes and servlets.
To refactor an EJB module:
■
Right-click a piece of code in the Source Editor and choose from the Refactor
submenu in the pop-up menu.
You cannot move an enterprise bean or any of its classes and interfaces to a different
project. The Move Class command only lets you move bean classes and interfaces to
different packages in the same EJB module.
You cannot rename mandatory EJB infrastructure methods such as ejbCreate.
When you rename a Web service endpoint interface, the IDE updates the
corresponding WSDL file.
When deleting a code element, you can use the Safely Delete refactoring command to
help check for references to that element before making the changes.
8.12 Working with Maven in the IDE
When using Maven as the build infrastructure for Java projects, Maven uses
conventions and patterns to provide a uniform build system. All Maven projects use a
shared set of plugins that are retrieved from the Maven repository and Maven
executes a defined series of tasks as part of the lifecycle when building the project.
8-34 NetBeans Developing Applications with NetBeans IDE
Working with Maven in the IDE
Unlike Ant, you do not need to explicitly specify all the tasks required for building a
project.
Maven support in the IDE includes the following features:
■
Maven is bundled with IDE and is used to run builds
■
Project creation from archetypes in the New Project wizard
■
Repository browser for managing Maven repositories
■
Code-completion for POM in editor
■
Configuring of custom Maven goals
For information about developing projects in the IDE using Maven, see the Maven best
practices page at http://wiki.netbeans.org/MavenBestPractices.
For more information about using Maven, see the Maven documentation at
http://maven.apache.org.
8.12.1 How to Create a New Maven Project
The New Project wizard enables you to create a new Maven project (referred to as an
artifact) based on an archetype in your local or a remote repository. An archetype is a
Maven project template. When you create the new artifact, the wizard prompts you to
specify the project coordinates (artifactId, groupId, versionId).
To create a new Maven project:
1. Choose File > New Project from the main menu to open the New Project wizard.
2.
Choose the Maven category and then choose a Maven project template.
3.
Click Next.
4.
Specify the project name, location and project details. Click Finish.
The IDE creates the Maven project and displays the node for the project in the Projects
window.
When using Maven, be aware of the following considerations:
■
■
■
■
■
If you have only recently installed Maven, the first time you create a project the
IDE might need to download the most recent artifacts into your local repository.
This process can take some time.
If you choose an Enterprise Application template, the IDE automatically creates an
assembly module for packaging the web application module and EJB module. You
can select the modules that you want to create in the New Project wizard.
If you choose a NetBeans Application template, you can choose to use OSGI
bundles if the version of NetBeans you are using supports it and whether you
want the IDE to create a NetBeans module and configure it as dependency of the
project.
If you choose the Project from Archetype project template, you need to choose an
archetype. The wizard displays the available archetypes contained in your local or
registered remote repository.
If you have an existing Maven project that contains a pom.xml file, you do not need
to use the New Project wizard. You can open the project by choosing Open Project
(Shift+Ctrl+O) from the main menu.
Building Java Projects 8-35
Working with Maven in the IDE
After you create the project, you can configure additional project properties by
right-clicking the project node in the Projects window and choosing Properties.
8.12.2 How to Configure Maven Settings
Configure Maven settings at the IDE level and at the project level. At the IDE level,
you can configure Maven installation and repository details and define global Maven
goals. At the project level, you can create configurations to activate Maven profiles and
bind IDE actions to Maven goals for a project.
8.12.2.1 Configuring Maven Settings for the IDE
Configure Maven settings that affect the behavior of Maven in the IDE in the Options
window. You can specify a local Maven installation, the location of the local Maven
repository, and settings for updating the repository.
To modify Maven settings in the IDE:
1. From the main window, choose Tools > Options.
2.
Click the Java option and then click the Maven tab.
3.
Modify the properties as desired.
4.
Click OK.
8.12.2.2 Configuring Maven Settings for Projects
By using the project's Properties window, you can configure Maven settings for an
individual project. You can create custom configurations and then bind IDE actions to
Maven goals and assign the binding to a configuration.
To configure Maven settings for a project:
1. Right-click the project node in the Projects window and choose Properties.
2.
Click the category in the left pane and modify the properties in the right pane.
8.12.2.3 Using Project Configurations
The Configurations category of the Project Properties window of a Maven project
enables you to create and select custom configurations for your project. For example,
you can create custom configurations to do the following:
■
Load the project in the IDE with a customized set of dependencies or submodules.
■
Trigger actions and activate any associated profiles.
■
Customize IDE actions to map to Maven goals.
To create a custom configuration for a project:
1. Open the Configurations category of the Properties window by right-clicking the
project node in the Projects window and choosing Set Configuration >
Customize.
Alternatively, right-click the project node and choose Properties and select
Configurations in the Project Properties window.
2.
Click Add to open the Add Configuration dialog box.
Alternatively, select an existing configuration and click Clone to create a copy of
the configuration. The name of the clone configuration is the name of the original
8-36 NetBeans Developing Applications with NetBeans IDE
Working with Maven in the IDE
configuration with the suffix _clone. You cannot rename the clone but you can set
profiles and properties.
3.
Type a name for the new configuration.
4.
Select Keep private to this IDE instance if you do not want to share the
configuration with other instances of the IDE.
By default this option is deselected and configurations are shared between
instances of the IDE when the project is opened, for example when you open the
project in an updated version of the IDE.
5.
Type any profiles or settings that you want to enable for the configuration. Click
OK to close the Add Configuration dialog box.
6.
Select the new configuration in the list of configurations and click Activate.
The name of the configuration that is currently active is in bold.
7.
Modify additional options for the configuration in the other categories in the
Properties window.
8.
Click OK.
When you click OK the IDE creates a configuration file in the root directory of the
project with the name nbactions-myconfigurationname.xml.
To activate a configuration for a project, right-click the project node and choose Set
Configuration and then choose the configuration name in the context menu. You can
also use the drop-down list in the toolbar to switch between configurations for the
project that is currently selected in the Projects window. If a project is set as the main
project, the dropdown list displays the configurations for the main project.
8.12.2.4 Binding IDE Actions to Maven Goals
Use the Actions category in the Properties window to customize IDE actions by
binding the action to Maven goals. The Actions pane lists the IDE's default project
actions that can be mapped to Maven goals. Assign the mapping to a project
configuration if you activated configurations for the project.
After you select an IDE action, modify the Maven goals and properties of the action by
typing in the textfield. Actions are displayed in bold if the default values for the action
have been modified. The following textfields display the goals and properties
associated with the selected action:
■
■
■
Execute Goals. This field displays the Maven goals that are associated with the
selected IDE action.
Activate Profiles. This field displays any profiles that are activated when the
action is invoked.
Set Properties. This field displays the properties that are set on the command line.
Properties are generally used to customize the behavior of the executed goal.
Type in the text area to add a property or click the Add button to view and add
one of the default properties.
When you select an action you can select the Build with Dependencies checkbox if
you want to run the Build with Dependencies command as part of the action.
8.12.2.5 Creating Custom Actions
Click Add Custom in the Actions category of the Properties window to create custom
actions for a project. After you create the new action, specify the goals or properties for
Building Java Projects 8-37
Working with Maven in the IDE
the new action. Right-click the project node in the Projects window and choose the
action under Custom in the context menu to invoke the new action.
Click Edit Global Custom Goal Definitions in the Maven tab in the Options window
to create global custom goals for Maven projects. The global goal is then listed in the
context menu under Custom when you right-click a Maven project in the Projects
window.
8.12.3 How to Work with the Maven POM
The Project Object Model (POM) is the basic unit of work in Maven. The POM is
described in the pom.xml XML file and contains project and configuration details, such
as the artifact coordinates, project dependencies, and build profiles that Maven uses to
execute goals and build the project.
For more information about POM elements, see Introduction to POM at
http://maven.apache.org/guides/introduction/introduction-to-the-pom.html.
When you use the New Project wizard to create an artifact, the IDE automatically
generates the pom.xml file and adds the artifact details. Open pom.xml in the XML
editor to edit the file. The following features are available in the XML editor to help
you edit pom.xml:
■
■
Code completion. The IDE's code completion can help you add and modify
elements. The code completion hints offered in the editor are based on the contents
of the repository.
Insert Code. The IDE can generate XML elements for you based on the details you
specify in a dialog box. When you right-click in the editor window and choose
Insert Code (Ctrl-+), a context menu appears where you can choose to add any of
the following types of elements to the POM:
–
Dependency
–
Dependency Exclusion
–
Plugin
–
Profile
–
License
After you select the type of element a dialog box opens that enables you to specify the
details about the code that you want the IDE to insert into the POM:
■
■
Dependency Graph. The Maven Dependency Graph is a visual representation of
the direct and transitive dependencies specified in pom.xml. Click the Graph tab in
the XML editor toolbar to open the graph. You can select any element in the graph
to view a representation of the dependencies of that element. You can right-click in
the graph view and choose different layout schemes in the popup menu.
Effective POM. The Effective POM tab displays a read-only version of the POM
that Maven uses to build the project after other factors that affect the build such as
any active profiles and inherited parent POMs are incorporated. The left column of
the tab displays the source that generates each line in the effective POM when the
source can be determined. Right-click the source and choose Go to Source to
navigate to the line in the source where the element is specified.
In the Effective POM tab you can click Show Diff in the toolbar to compare the
effective POM to a POM for an alternate project configuration or profile. Click
Show Diff to open a dialog box where you can select the alternate POM. The diff of
the POMs opens in a new tab in the IDE.
8-38 NetBeans Developing Applications with NetBeans IDE
Working with Maven in the IDE
8.12.4 How to Manage Maven Project Dependencies
To make libraries and projects available to your project during compilation, testing,
and execution, you need to declare the projects or libraries as dependencies. All
dependencies need to be available as artifacts in your local repository when you build
the project.
You declare a dependency by modifying the POM to add the coordinates of the artifact
you want to declare as a dependency. All Maven artifacts are defined by a unique
coordinate that consists of a group identifier (groupId), artifact identifier (artifactId)
and version. Adding a dependency to the POM is similar to adding libraries to the
classpath in an Ant-based project.
To add a dependency to a Maven project:
■
Edit the POM in the editor. Open pom.xml in the XML editor and use code
completion to help you write the dependency elements and artifact coordinates.
■
Use the Add Dependency dialog. Type or search for the artifact in the Add
Library dialog and click OK. When you click OK, the IDE adds the dependency
elements and artifact coordinates to pom.xml.
To open the Add Dependency dialog:
■
Right-click the Dependencies node in the Projects window and choose Add
Dependency.
■
■
Right-click in pom.xml in the editor and choose Insert Code (Ctrl+I) and choose
Dependency.
Right-click an artifact under the Maven Repositories node in the Services window
and choose Add as Dependency and select a project in the Add Dependency
dialog box.
After you add a dependency to pom.xml, a node for the artifact ( ) appears under the
project's Dependencies node. Artifacts that are not in your local repository are marked
with a badge. You need to have a copy of the artifact in your local repository if you
want to use it in your project. This applies to libraries and to other projects that are
described as dependencies.
If a required artifact is available in a remote repository, Maven
automatically downloads the artifact and any transitive dependencies
from the repository when you build the project. Maven uses the latest
available version of the artifact if no version is specified. If the
required artifact is not available in a remote repository, right-click the
artifact node and install the artifact manually.
Note:
It is recommended that you store Maven software library JARs and project artifacts in
a local repository and keep the source code for projects under a version control system.
8.12.5 How to Work with Maven Artifacts
The project dependencies that are displayed under a project's Dependencies node are
Maven artifacts. Each Maven artifact has a unique coordinate (groupId, artifactId and
version) that is used to identify the artifact in a project's POM. An artifact can also
have dependencies. The artifacts available to a project can be viewed under the Maven
Repositories node in the Services window.
Building Java Projects 8-39
Working with Maven in the IDE
Right-click an artifact in the Projects window or the Services window to invoke a
popup menu with commands for downloading the sources and Javadoc of an artifact,
finding usages and viewing artifact details. Use the Artifact Viewer to view details
about individual artifacts.
To open the Artifact Viewer, perform either of the following steps.
■
In the Projects window, right-click an artifact under the Dependencies node and
choose View Artifact Details.
■
In the Services window, expand the Maven Repositories node, right-click an
artifact and choose View Details.
The Artifact Viewer displays details in the following tabs:
■
■
■
■
■
Basic. Displays the artifacts coordinates and version details.
Project. Displays metadata contained in the artifact's POM such as the description
of the artifact, the URL for the project and issue tracking and version control
details.
Classpath. Displays the artifact's compilation, runtime and test dependencies.
Graph. Displays a visualization of the artifact's primary and secondary
dependencies.
POM. Displays the pom.xml file of the artifact.
Table 8–1 describes the commands available from the toolbar of the Artifact Viewer:
Table 8–1
Artifact Viewer Toolbar Commands
Command
Description
Add as Dependency
Opens the Add Dependency dialog box from which you can
choose a project.
Checkout Sources
Opens the Checkout Sources wizard in which you can specify a
location for a local repository for the sources.
Use this command only if the sources of the artifact are
available in a repository
Create Library
Creates a NetBeans library from the artifact. The new library is
available in the Ant Library Manager.
8.12.5.1 Visualizing Dependencies
The Graph tab of the Artifact Viewer enables you to easily visualize dependencies. The
visualizer also provides tools to help you find and resolve potential problems resulting
from dependency version conflicts.
To use the graph view to resolve dependency conflicts:
1. Open the artifact in the Artifact Viewer and click the Graph tab.
Alternatively, you can open pom.xml file in the editor and click the Graph tab.
2.
Locate any artifact boxes that have a red background.
In the dependency graph, a dependency with a red background indicates a
potential version conflict.
3.
Click the suggestion icon to open a dialog box with a description of the conflict
and options for resolving the conflict.
8-40 NetBeans Developing Applications with NetBeans IDE
Working with Maven in the IDE
8.12.6 How to Build a Maven Project
The Maven build lifecycle has defined phases with goals that are executed when
building and distributing the project. When you execute a goal, Maven will also
execute all the preceding goals in the build lifecycle. You can invoke phase goals and
plugin goals by mapping the goals to IDE actions, or you can create custom goals and
invoke the goals individually. When you execute a goal, the Maven output with the
plugin and goal identifiers are displayed in the Output window.
When you want to generate distributable files for the project, such as JAR files or WAR
files, you need to build the project. When you build a Maven project using the IDE's
Build command, by default the IDE executes the plugin goals in the install phase of the
Maven lifecycle (builds the project and adds the artifact to the local repository).
Note: The IDE can automatically compile classes when you save
them if you enable the Compile on Save option in the Compile
category of the project's Properties window. When Compile on Save
is enabled, you do not need to build the project or compile individual
classes to run or test the project in the IDE. The incrementally
compiled files are stored in a cache in your user directory and are
copied to your project's build folder when you run or debug your
project.
Compile on Save is enabled by default for WAR, EJB and EAR projects.
To build a Maven project:
1. Select the project node in the Projects window.
2.
Choose Run > Build Project (F11).
When you build a project the IDE displays the Maven output and any compilation
errors in the Output window. You can double-click any error to go to the location in
the source code where the error occurred.
You can click Show Build Overview (
) in the Output window sidebar to open the
Build Execution Overview window to view additional details about the executed goal
or goals. Click Show Phase in the Build Execution Overview window to view the goals
organized by the phase in the build lifecycle. You can right-click a goal in the Build
Execution Overview window to open a popup menu where you can choose to view
the goal definition in the POM, the source code of the plugin or to debug the plugin.
You can modify the goals that are executed by the Build command and other IDE
commands by modifying the Maven settings in the project's Properties window.
To build an individual project and its required projects:
■
Right-click the project's node in the Projects window and choose Build with
Dependencies.
Note: You can change the default Build action to Build with
Dependencies by selecting the Build action in the Actions category of
the project's Properties window and then selecting the Build with
Dependencies checkbox.
Modify the project dependencies by adding libraries in the Projects window or by
editing pom.xml in the editor.
Building Java Projects 8-41
Working with Maven Repositories
8.12.6.1 Executing Maven Goals in the IDE
IDE actions in the popup menu are mapped to Maven phases and goals. For example,
by default the Build action in the IDE is mapped to the install phase in the Maven
lifecycle. When you right-click the project node and choose Build, the IDE executes the
goals described in the install phase to package the project and executes all the goals in
the preceding phases in the build lifecycle.
You can modify the mapped Maven goals that are invoked by IDE actions by
configuring actions in the project's Properties window or in the Maven tab in the
Options window. For more information, see Section 8.12.2, "How to Configure Maven
Settings."
8.12.6.2 Customizing the Build Process
To customize the build for a Maven project, modify the POM to add or reconfigure
plugins and dependencies. You can use the code completion in the editor to help you
when adding details to pom.xml.
To customize a build:
1. Open pom.xml in the XML editor.
2.
Choose Source > Insert Code (Ctrl+I) from the main menu and select Plugin from
the popup menu to open the Add New Plugin dialog box.
3.
Type a query term to search for the plugin.
4.
Select the plugin from the list of available plugins.
5.
Select the goals that you want to be executed. Click OK.
When you click OK, the IDE adds the plugin description to pom.xml and the goals to
run as part of the build process. If you add a plugin that is not in the local repository,
the required artifact will be automatically downloaded from a remote repository when
required.
8.12.6.3 Executing Individual Goals
If you select the project node or pom.xml in the Projects window you can execute goals
that are defined in the pom.xml from the Navigator window.
To execute a goal:
1. Open the Navigator window.
2.
Select the project node in the Projects window.
Alternatively, select pom.xml in the Projects window and choose Related goals in
the drop-down list at the top of the Navigator window.
3.
Right-click a goal in the Navigator window and choose Execute Goal.
Alternatively, select Execute Goal with Modifiers to open the Run Maven dialog
box and modify the default run settings for the goal.
You can view the results of the goal in the Output window.
8.13 Working with Maven Repositories
Software library archives (JARs), build artifacts and dependencies that are used to
build Maven projects are stored in repositories. There are two types of repositories:
8-42 NetBeans Developing Applications with NetBeans IDE
Working with Maven Repositories
■
■
Local repositories. A cache of a remote repository that is stored on the local
machine. Maven projects are built against the local repository. The local repository
usually only stores a subset of the files available in the remote repository and any
temporary build artifacts.
Remote repositories. A repository that contains all the Maven artifacts and
plugins. The remote repository may be a third-party repository (for example,
http://repo.maven.apache.org/), or it may be a private internal repository.
8.13.1 How to Work with Maven Repositories
The IDE indexes the contents of local and remote Maven repositories using the Nexus
indexing engine. The IDE uses the repository indexes for some Maven-related
functions such as code completion. You can browse and manage Maven repository
indexes in the Services window.
To browse Maven repositories:
■
Choose Window > Services from the main menu and expand the Maven
Repositories node to view the contents of the repositories.
The Maven Repositories node in the Services window lists the Maven repositories
registered with the IDE and enables you to add, remove and update Maven
repositories. The local Maven repository is indicated by a yellow repository node (
and remote repositories are indicated by blue repository nodes (
).
)
By default, the IDE includes the central Maven repository in the list of remote
repositories. When a project requires build artifacts that are not stored in the local
repository, Maven downloads the required artifacts to the local repository from a
remote repository. The files in the local Maven repository are then shared by all of
your Maven projects.
Expand the repository nodes to view the indexed artifacts grouped by GroupId and
ArtifactId, the version of the sources, and the type of packaging. Depending on the
metadata available, right-click an artifact to perform the following actions:
■
■
■
View Details. Opens the Artifact Viewer tab in the editor window.
Add As Dependency. Adds the library to an open project as a dependency. The
IDE automatically modifies the project's POM.
Find Usages. Displays open projects and repository artifacts that use the selected
library as a dependency.
■
View JavaDoc. Displays the downloaded JavaDoc in a browser.
■
Open. Opens the project POM in the IDE.
■
Download. Downloads the artifact to the local Maven repository.
■
■
■
Download Sources. Downloads the source JAR for the binary. After downloading,
if you click on a class file, the Java file is displayed.
Download JavaDoc. Downloads the Javadoc.
Copy. Copies the dependency.xml snippet of the artifact to the clipboard, which
you can paste into the project pom.xml file.
To locate artifacts in the repositories:
1. Right-click the Maven Repositories node and choose Find.
2.
Enter the search term for the artifact in the Find in Repositories dialog box (a
groupID, for example) and select any additional criteria.
Building Java Projects 8-43
Working with Maven Repositories
3.
Click OK.
When you click OK the IDE creates a node for the search term (
) under the Maven
Repositories node. Expand the search node to view a list of the artifacts that matched
your search. Remove a search node by right-clicking the node and choosing Delete.
To add a repository:
1. Right-click the Maven Repositories node and choose Add Repository.
2.
Specify the details for the new repository and click Add.
To update the index of a repository:
■
Expand the Maven Repositories node, right-click the repository node you want to
update and choose Update Index.
8-44 NetBeans Developing Applications with NetBeans IDE
9
Testing and Profiling Java Application Projects
9
[10This
]
chapter describes how to use the tools provided by the IDE to run unit tests and
to profile Java applications.
This chapter contains the following sections:
■
About Testing and Profiling Java Application Projects
■
Testing Java Application Projects with Unit Tests
■
Creating a Unit Test
■
Running a Unit Test
■
Debugging a Unit Test
■
Configuring Unit Test Settings
■
Creating a Selenium Test
■
Configuring Selenium Server Settings
■
Starting a Profiling Session
■
Selecting a Profiling Task
■
Attaching the Profiler
■
Attaching the Profiler to a Remote Application
■
Profiling a Free-form Project
■
Taking and Accessing Snapshots of Profiling Data
■
Taking a Heap Dump
■
Setting a Profiling Point
■
Profiling Telemetry
■
Profiling Methods
■
Profiling Objects
■
Profiling Threads
■
Profiling Locks
■
SQL Queries Profiling
■
Additional Functions when Running a Profiling Session
Testing and Profiling Java Application Projects
9-1
About Testing and Profiling Java Application Projects
9.1 About Testing and Profiling Java Application Projects
The IDE provides tools for creating and running unit tests and for profiling Java
applications. Unit tests enable you to test the code in Java applications. Profiling is the
process of examining an application to locate memory or performance-related issues.
When profiling a Java application, you can monitor the Java Virtual Machine (JVM)
and obtain data about application performance, including method timing, object
allocation and garbage collection. You can use this data to locate potential areas in
your code that can be optimized to improve performance.
You can use the IDE to test and to profile the following types of Java applications:
■
Java SE projects
■
Java EE and Web applications
■
Java Free-form projects
■
NetBeans Modules and Module suites
The following profiling capabilities are available:
■
■
■
Telemetry—profiles CPU, memory usage, number of threads and loaded classes.
See Section 9.17, "Profiling Telemetry"
Methods—profiles methods execution times and invocation count, including call
trees. See Section 9.18, "Profiling Methods."
Objects—profiles size and count of allocated objects including allocation paths.
See Section 9.19, "Profiling Objects."
■
Threads—profiles threads time and state. See Section 9.20, "Profiling Threads."
■
Locks—profiles locks content data. See Section 9.21, "Profiling Locks."
9.2 Testing Java Application Projects with Unit Tests
The IDE provides built-in support for generating and executing unit tests based on the
JUnit, TestNG, Mocha frameworks and Selenium tool suite.
The IDE supports JUnit 3 and JUnit 4 unit testing. For more information about JUnit,
see http://www.junit.org
For more information about TestNG, see http://testng.org/doc/index.html
For more information about Mocha, see http://mochajs.org/
The IDE supports Selenium 2.0 testing. For more information about Selenium, see
http://www.seleniumhq.org/docs/index.jsp
9.2.1 Test Types in the IDE
You can use the IDE to create the following:
■
■
■
Empty Tests. Test skeletons without testing methods, for which no class has been
designated to be tested.
Tests for Existing Classes. Classes containing the actual testing methods which
mirror the structure of the sources being tested.
Test Suites. Groups of test classes clustered to permit testing of an entire
application or project.
9-2 NetBeans Developing Applications with NetBeans IDE
Creating a Unit Test
You can generate tests and test suites by selecting any class or package node in the
Projects window and choosing Tools > Create/Update Tests from the main menu.
9.2.2 Unit Test Structure
The IDE represents unit tests as subtrees which mirror the project's Java package
structure. By default, when the IDE generates tests each test class has the name of the
class it is testing appended by the word Test (for example, MyClassTest.java).
Each standard project has a default test folder that is used to store the unit tests and
test suites. This folder is displayed as the Test Packages node in the Projects window.
You can add any number of test folders to your project. Test files and the source files
they test cannot be located in the same source tree.
9.3 Creating a Unit Test
The unit test generator enables you to create unit test suites and compilable test classes
for use as skeletons in your unit tests. You can create unit tests for single classes and
entire packages, as well as empty test skeletons to be used with sources you create
later.
JUnit 4.x is backwards-compatible with JUnit 3.x. If you decide to downgrade from
JUnit 4.x to JUnit 3.x, tests using unsupported features such as annotation descriptions
and static imports are ignored.
The JUnit 4.x option is only available if your project is running
on the Java 5.0 platform or higher.
Note:
9.3.1 Changing the JUnit Version
You can update support for the JUnit versions by updating the JUnit libraries in the
project's Test Libraries node. View the project's JUnit libraries by expanding the
project's Test Libraries node in the Projects window.
To add a new library, right-click the Test Libraries node in the Projects window and
choose Add Library and select the library in the Add Library dialog box. To remove a
library, right-click the library and choose Remove.
9.3.2 How to Create a Unit Test
Generated tests are distinguished by appending Test to the tested classes' names (for
example, MyClassTest.java).
Depending on the version of the unit testing framework you
are using, the name of the test class is not required to end with Test.
Note:
To create a test, the project must have a test directory for the tests. The IDE creates a
Test Packages directory by default when you create a project. If no test directory exists
in your project or you want to specify a different directory for your test, you can
specify a test directory in the project properties dialog.
To create a test for a single class:
1. Right-click the class in the Projects window and choose Tools > Create/Update
Tests (Ctrl+Shift+U) to open the Create Tests dialog box.
Testing and Profiling Java Application Projects
9-3
Creating a Unit Test
You can modify the default name of the test class, but some of the navigation in
the IDE between classes and test classes might not function if the name of the test
class does not contain the name of the class that is tested.
2.
Select a unit test framework.
3.
Select the desired code generation options and click OK.
Alternatively, you can create a test by choosing File > New File, selecting the Unit
Tests category, and selecting JUnit Test or TestNG Test Case in the File Types pane.
To create a test suite:
1. Right-click the package node containing the source files for which you want to
generate the test suite in the Projects window and choose Tools > Create Tests
(Ctrl+Shift+U) from the context menu.
2.
Select a unit test framework.
3.
Select the Generate Test Suites checkbox.
4.
Select the desired code generation options and click OK.
The IDE generates test classes for all enclosed classes and stores them in the project's
Test Packages node. If any of the test classes already exist, those classes are updated.
By default the IDE includes all the test classes as part of the generated test suite.
Alternatively, you can create a test suite by choosing File > New File, selecting the
Unit Test category, and selecting Test Suite or TestNG Test Suite in the File Types pane.
To create an empty test:
1. Choose File > New File from the main menu.
2.
In the New File wizard, select the Unit Test category and JUnit Test or TestNG Test
Case in the File Types pane. Click Next.
3.
Specify the test class name, folder and package.
4.
Select the desired code generation options and click Finish.
When you create an empty test the IDE generates a test class that does not contain any
skeleton methods. The IDE creates the test suite class based on the parameters you
have specified and opens the class in the editor. The test suite class then appears in the
Projects window under the package-name node in the test folder.
To create a new test for an existing class:
1. Choose File > New File from the main menu.
2.
In the New File wizard, select the Unit Test category and Test for Existing Class in
the File Types pane. Click Next.
3.
Specify the test class name and folder.
4.
Select the desired code generation options and click Finish.
When you create a test for an existing class, you specify the class that you want to test
and the IDE generates a test class that contains skeleton methods based on the
methods in the specified class. The IDE opens the class in the editor. The test class then
appears in the Projects window in the test folder. The IDE creates the test class under
the package-name node that replicates the package structure of the tested class.
To specify a test directory:
1. Right-click the project node in the Projects window and choose Properties.
9-4 NetBeans Developing Applications with NetBeans IDE
Running a Unit Test
2.
In the Properties window, select Sources in the Categories pane.
3.
Define the properties of the test packages folder in the Test Package Folders list.
You can add or remove the folders that are used for test packages and modify the
names of the test packages folder as it appears in the Projects window.
4.
Click Close.
Your project must have a test package folder to generate unit tests. If the test packages
folder for your project is missing or unavailable, create a new folder in your project
and then designate the new folder as the test packages folder in the project's Properties
window.
9.4 Running a Unit Test
Once you have created a test or test suite, use the Run Test command to initiate
execution of the test. Run Test commands are available on source nodes only. After
you run a test, you can rerun individual test methods executed during the test and
displayed in the Test Results window.
9.4.1 How to Run a Unit Test
You can run unit tests for a specific class or method or for a project.
To run tests for an entire project:
1. Select any node or file in the project you want to test in the Projects or Files
window.
2.
From the main menu, choose Run > Test Project project_name (Alt+F6).
The IDE executes all of the project's tests.
If you want to run a subset of the project's tests or run the tests in a specific order, you
can create test suites that specify the tests to run as part of that suite. After creating a
test suite you run the suite in the same way you run a single test class.
You can select multiple projects in the Projects window and run tests for them at once
by choosing Run > Test number_of_selected_projects Projects (Alt+F6) from the main
IDE's menu. If you want to run a subset of the project's tests or run the tests in a
specific order, you can create test suites that specify the tests to run as part of that
suite. After creating a test suite you run the suite in the same way you run a single test
class.
To run a test for a single class:
1. Select the node of the class for which you want to run a test in the Projects or Files
window.
2.
From the main menu, choose Run > Test File (CtrlF6).
You can also run a class's test by right-clicking the test class node itself in the Projects
window and choosing Test File (Ctrl+F6).
To run a single test method:
1. Run the test class or suite containing the test method.
2.
In the Test Results window, right-click the test method and choose Run Again.
To run a single test method the method must be listed in the Test Results window.
Testing and Profiling Java Application Projects
9-5
Debugging a Unit Test
9.4.2 Working with Unit Test Output
When you run a test, the IDE shows the following test results in two panes in the Test
Results window:
■
■
A summary of the passed and failed tests and the description of failed tests are
displayed in the left pane of the window. You can use the filter icons in the left
side of the window to filter the test results.
The textual output from the unit tests themselves is displayed in the right pane of
the window.
The output from the process that builds and runs the test is displayed in the Output
window. you can double-click any error to jump to the line in the code where the error
occurred.
After you run a test class, you can right-click any test method displayed in the Test
Results window and choose Run Again from the context menu to run the individual
test method again or Debug to debug the test.
9.5 Debugging a Unit Test
You can debug a test class as you would any class. After you set your breakpoints in
the test class you can run your unit test in the debugger and step through the code to
locate problems in your test classes.
To debug a unit test:
1. Place your breakpoints in your test class.
2.
Select the node for the class whose test you wish to debug.
3.
Choose Debug > Debug Test File (Ctrl+Shift+F6) from the main menu.
When you choose Debug Test File the IDE starts the test in the debugger and opens
the Debugging window. For information on using the Debugging window, see
Section 10.9, "Using the Debugger Windows."
9.6 Configuring Unit Test Settings
The IDE enables you to customize the process of test generation as you create tests.
You can also edit the list of sources the IDE references when compiling tests.
9.6.1 How to Edit Unit Test Settings
Modify the test settings to create a custom tests.
To edit unit test settings as you create tests:
1. Right-click the sources for which you wish to create tests.
2.
Choose Tools > Create Tests (Ctrl+Shift+U).
3.
Select a unit test framework.
4.
In the Create Tests dialog box, select the Code Generation options you require for
the tests.
The IDE creates the tests with the specified options.
9-6 NetBeans Developing Applications with NetBeans IDE
Configuring Selenium Server Settings
9.6.2 How to Edit the Classpath for Compiling or Running Tests
Edit the classpath as needed to include specific projects, libraries, or JAR files.
To edit the classpath for compiling or running tests:
1. Right-click the project's Test Libraries node and choose one of the following:
■
2.
Add Project. The build output, source files, and Javadoc files of another IDE
project.
■
Add Library. A collection of binary files, source files, and Javadoc files.
■
Add JAR/Folder. A JAR file or folder somewhere on your system.
Click OK.
The IDE adjusts and stores the classpath priorities based on the new settings. For
information on setting the classpath for a project, see Section 6.2.3.1, "Managing the
Classpath."
9.7 Creating a Selenium Test
You can create a Selenium test by choosing File > New File, selecting the Selenium
Tests category, and selecting Selenium Test Case in the File Types pane.
To create a Selenium Test:
1. Choose File > New File from the main menu.
2.
Select the Selenium Tests category.
3.
Select Selenium Test Case in the File Types pane.
4.
Click Next.
5.
Provide the required information in the Name and Location panel of the wizard.
6.
Click Finish.
A Selenium Mocha/Protractor test case with a default test method is created.
To create a Selenium Test for a single class (applies to Maven java related
project types only):
1. Right-click the class in the Projects window and choose Tools > Create/Update
Tests to open the Create Tests dialog box.
Note: You can modify the default name of the test class, but some of
navigation between classes and test classes might be disabled in the
IDE if the name of the test class does not contain the name of the class
that is tested.
2.
Select Selenium as the test framework.
3.
Click OK.
9.8 Configuring Selenium Server Settings
Configure the Selenium server settings as needed to test.
Testing and Profiling Java Application Projects
9-7
Starting a Profiling Session
To configure Selenium server:
1. Right-click the Selenium Server node in the Services tab.
2.
Provide the required information.
3.
Click OK.
9.9 Starting a Profiling Session
If you have a project that is targeted to run on your local machine, you can profile the
project without any additional configuration. When you profile a local project, you
launch the project and start the profiling session from within the IDE.
If you want to profile a local application but you cannot or do not want to start the
application from the IDE, you can profile the application by attaching the IDE to the
application.
To profile a local project, the project must be open in the IDE. You can start the
profiling session after you select the profiling task.
Table 9–1
Profiling Commands
Command
Description
Profile > Profile Project
The selected task is run on the project that is selected in the
Projects window or on the main project if a main project is set.
Profile > Profile File
The profiling task is run on the selected file. The selected file
must have a main method.
Profile > Profile Test File
If a test file is selected the profiling task is run on the test file. If
the selected file is not a test file, the profiling task is run on the
test file associated with the selected file.
Profile > Attach to Project
Opens the Profile window. In the Profile window, you select the
profiling task.
Profile > External Process
Opens the Profile window. In the Profile window, you select the
profiling task to profile remote applications or applications that
you start outside the IDE.
Before you can use the profiler in the IDE, you must calibrate
the profiler. You only have to calibrate the profiler once. For
information, see Section 9.9.2, "How to Calibrate the Profiler."
Note:
9.9.1 How to Profile a Project
To profile an individual project:
1. Right-click a project in the Projects window and choose Profile.
Alternatively, you can select a project in the Projects window and choose Profile >
Profile Project from the main menu.
2.
On the main window click the Configure Session button and select a profiler
mode by clicking on it. You can change the profiler mode at any point by clicking
the Profile drop-down arrow.
3.
On the main window, click the Profile button. The application and the profiling
session are started.
9-8 NetBeans Developing Applications with NetBeans IDE
Starting a Profiling Session
If a project is set as the main project, the Profile Project command in the Profile menu
always profiles the main project.
To profile a specific class:
1. In the Projects window, select the class that you want to profile. (This class must
contain a runnable method.)
2.
Choose Profile > Profile File from the main menu.
3.
On the main window, click the Profile button. The profiling session is started.
For information on profiling an application that you started outside the IDE, see
Section 9.11, "Attaching the Profiler."
For information on monitoring an application thread activity, see Section 9.20,
"Profiling Threads". For information on examining CPU performance and memory
usage, see Section 9.17, "Profiling Telemetry".
9.9.2 How to Calibrate the Profiler
You must calibrate the IDE before you can use the IDE to profile an application. You
must run the calibration process for each JDK that you use for profiling. You do this
because instrumenting the bytecode of the application imposes some overhead, and
the time spent in code instrumentation needs to be "factored out" to achieve more
accurate results.
You only have to calibrate the IDE once for each JDK that you use. However, you
should run the calibration process again when anything changes on your local or
remote configuration that could affect system performance. The following could affect
system performance:
■
Any hardware upgrade
■
Any significant change or upgrade of the operating system
■
An upgrade of the Java platform used for profiling
To calibrate the IDE to the local system:
1. Close any other programs that are running.
The IDE runs the calibration if other applications are running, but running any
CPU-intensive programs when performing the calibration might affect the
accuracy of profiling results.
2.
Go to Tools > Options > Java > Profiler.
3.
Select the General category and click Manage in the Profiling specific options. The
Manage Calibration Data dialog box displays.
4.
Select the Java Platform to be used for profiling. Click Calibrate.
You can click Java Platforms to open the Java Platform Manager to add a new Java
platform. The Manage Calibration Data dialog box displays the date that the most
recent calibration was performed.
When you click Calibrate, the IDE collects calibration data on the selected Java
platform. When the calibration process is complete you can start using the IDE to
profile your applications.
Do not share calibration data between various computers or systems.
Testing and Profiling Java Application Projects
9-9
Starting a Profiling Session
You cannot perform a calibration of a remote platform from the Manage Calibration
Data dialog box. Calibration of a remote platform is performed the first time that you
profile an application on the remote platform.
To calibrate the IDE to a remote system:
■
To calibrate the IDE to a remote system, see the NetBeans FAQ at
http://wiki.netbeans.org/wiki/view/FaqProfilerCalibration.
9.9.3 Understanding the Toolbar Icons
Table 9–2 contains the various icons used when profiling. These icons are available
from areas in the NetBeans user interface, including Profile window with Methods,
Profile window with Threads, Profile window with Objects, Profile window with
Telemetry, and Profile window with Locks.
Table 9–2
Icon
Profiling Methods Icons
Name
Description
Pause live results
Allows to stop updating live results.
Pressed automatically when a context
menu is displayed for the profiling results.
Update live results
Is enabled when the Pause live results
button is pressed, allows to manually
update paused live results.
Show delta/absolute values
Controls switching between absolute and
incremental values.
Forward calls
Shows or hides the Forward calls view
(visible by default).
Hot spots
Shows or hides the Hot spots view (hidden
by default).
Reverse calls
Shows or hides the Reverse calls view
(visible by default).
Select threads
Shows a list of threads to be included or
excluded from the displayed results.
Take snapshot
Saves the currently available profiling data
to a file which can be reopened later for
offline analysis or compared with another
snapshot.
Reset results
Clears the currently available profiling
data, enabling to start collecting new data
from a defined point.
Take thread dump
Takes snapshot of all threads in the profiled
JVM including their call stacks and
displays it in a separate view.
Take heap dump
Saves a snapshot of all objects currently
stored in the heap memory in a .hprof
format and optionally opens it in a heap
viewer.
Request garbage collection
Requests garbage collection in the profiled
JVM. There's no guarantee when or if at all
the garbage collection will be performed.
To make sure GC will be run, the action
should be invoked several times.
9-10 NetBeans Developing Applications with NetBeans IDE
Selecting a Profiling Task
9.10 Selecting a Profiling Task
When you start a profiling session, you first select and configure the profiling task.
You choose the profiling task according to the type of profiling results you want to
obtain from the session.
Each profiling task has default settings that are sufficient in most situations. You can
configure the basic settings of each profiling task to modify the profiling results that
are returned.
Table 9–3 describes the profiling tasks and the profiling results obtained from running
the task.
Table 9–3
Profiling Tasks and Results
Profiling Task
Results
Telemetry
Choose this to monitor CPU, memory usage, number of threads
and loaded classes.
Methods
Choose this to profile methods execution times and invocation
count, including call trees.
Objects
Choose this to profile size and count of allocated objects
including allocation paths.
Threads
Choose this to profile threads time and state.
Locks
Choose this to profile locks content data.
9.10.1 How to Select a Profiling Task
Each time you start or modify a profiling session, you first select a profiling task. You
cannot run more than one profiling session at one time. You can profile a project or an
individual file if the file has a runnable method. You can also profile test classes.
To select a profiling task:
1. Select a project or file in the Projects window and choose Profile > Profile Project
from the main menu.
Alternatively, you can right-click a project node in the Projects window and choose
Profile, or right-click a file and choose Profile File or Profile Test File.
2.
(Required when you run a profiling session for the first time only.) Select a
profiling task by clicking one of the tasks in the Configure Section drop-down list.
3.
Click Profile.
9.10.2 Using a Load Generator Script
The IDE supports using a load generator to replay previously saved load testing
scripts. By using a load testing script, you can simulate a heavy load on your server or
application to achieve more accurate results when testing application performance.
The IDE supports the Apache JMeter load testing tool. To work with the Apache
JMeter load testing tool in the IDE, use the Plugins manager download and install the
JMeter plugin from the Update Center by choosing Tools > Plugins from the main
menu. This plugin installs additional Load Generator and Profiler/Load Generator
Bridge plugins. A sample JMeter script is downloaded as a part of the JMeter plugin.
The sample script is available in userdir/modules/jmeter/extras/Test.jmx.
Testing and Profiling Java Application Projects
9-11
Attaching the Profiler
Once you install the JMeter integration, a new Plugins section with a Load Generator
item appears in the Profile or Attach drop-down menu. Choose Load Generator to
start a JMeter script when starting the profiling session.
To create a new load testing script:
1. Choose File > New File from the main menu.
2.
Select Load Testing Scripts > JMeter Plans in the Categories list and New JMeter
Plan in the New File dialog and click Next.
3.
In the Name and Location panel of the dialog specify the name of the new test jmx
file and its location. Click Finish.
For more about using Apache JMeter, see
http://jakarta.apache.org/jmeter/index.html.
9.11 Attaching the Profiler
The easiest way to profile your application is to use the Profile Project command.
However, if you must start your application outside of the IDE, you can use the attach
mode to profile an application. For example, you might want to use the attach mode in
the following cases:
■
Your application needs to be started from the command line or uses a complex
launch script
■
You want to obtain profiling data on the startup of the application or target JVM
■
You want to profile the application without restarting the application
You must use the attach mode in the following cases:
■
■
You want to profile an application running on a remote JVM, such as a remote
application server
You want to profile a Java EE or web application and the target server is not
Tomcat, GlassFish, WebLogic or JBoss
The Attach mode enables you to attach the profiling tool to an application that is
already running, or just about to start on a local or remote machine. Using the attach
mode is useful for profiling long-running applications, and in particular for profiling
web or enterprise applications running on top of an application server. You can also
use the Attach mode to profile the code of the application server itself.
9.11.1 How to Configure the Attach Settings
Before you can attach to an application, the startup options for the target application
or server must be configured. You use the Attach Settings dialog box to specify the
attachment settings for a project. You only have to configure the attachment settings
once. The attachment settings are project specific, which means that each project has its
own settings. You can open the Attach Settings dialog box at any time if you want to
review or modify any of the attachment settings.
To configure the attach settings:
1. Choose Profile > Attach to Project or Profile > Attach to External Process (
from the main menu to open the Profile window.
2.
)
Click the Attach button to display the Attach Settings dialog box and make the
appropriate selections.
9-12 NetBeans Developing Applications with NetBeans IDE
Attaching the Profiler
Based on the attach mode you choose in the Profile drop-down list, the Attach
Settings dialog box provides you with a set of instructions on how to configure
the application so that you can attach the profiler.
3.
Click OK.
The attach mode you choose depends on the type of profiling data you want to obtain
and the details of the target JVM platform. Table 9–4 provides an overview of the
attach modes:
Table 9–4
Attach Modes
Attach Mode
Description
Already running local Java
process
Use this mode if you want to obtain profiling data on a local
application. To use this mode, the application needs to be
running on JDK 1.6, 1.7, or 1.8.
When you use this mode, you can attach to and detach from the
application without restarting application.
Manually started local Java
process
Use this mode if you want to obtain profiling data on the startup
of a local application.
When you use this mode, the target JVM and application wait
until you attach the profiler before starting. After you detach
from the application, you must restart the application to start
another profiling session.
Manually started remote
Java process
Use this mode if you want to obtain profiling data on an
application running on a remote JVM. To use this mode, you
must install the Profiler Remote Pack on the remote target
machine. You specify the details of the remote system and
generate the Profiler Remote Pack using the Attach Settings
dialog box.
When you use this mode, the remote application starts after the
profiler is attached. This mode enables you to obtain profiling
data on the startup of the target JVM.
To profile an applet using the Local Direct or Remote attach mode:
■
Specify the agent parameters in the Java Control Panel and restart the browser.
9.11.2 How to Attach the Profiler to a Local Application
Use the attach mode to profile a local application when you must start the application
outside of the IDE. For example, you may want to use the attach mode in the following
cases:
■
■
■
Your application needs to be started from the command line or uses a complex
launch script.
You want to obtain profiling data on the startup of the application or target JVM.
You want to profile the application without restarting the application (Already
running local Java process attach mode, requires JDK 1.6, 1.7, or 1.8).
To attach to a local application, you must first configure the attachment settings using
the Attach Settings dialog box. These settings are associated with the project you are
profiling. You only have to configure the attach settings for your project once, but you
can modify the settings at any time in the Attach Settings dialog box.
When you configure the settings for attaching to a local application, you can choose
from the following attachment modes:
Testing and Profiling Java Application Projects
9-13
Attaching the Profiler to a Remote Application
■
■
Already running local Java process. This mode allows you to detach from and
attach to the application at any time without stopping the application. This mode
requires JDK 1.6, 1.7, or 1.8 but does not require any additional configuration.
Manually started local Java process. This mode enables you to obtain profiling
data on the startup of the local application. This mode requires you to modify the
startup script and start the application when you want to attach the profiler.
Once the connection is established and the profiler is attached to the target application,
you can change the profiling task you are running on the target application without
stopping or restarting the application.
To attach to a local application:
1. Choose Profile > Attach to Project (
window.
) from the main menu to open the Profile
2.
Click the Attach button to open the Attach Settings dialog box.
3.
Select either Already running local Java process or Manually started local Java
process as the attach mode.
4.
Follow the instructions in the Attach Settings dialog box for configuring the
application, if necessary. Click OK.
A profiling session tracking the running application is started.
To finish profiler session:
■
Choose Profile > Finish Profiler Session from the main menu or click the Finish
profiler button in the Profiler window.
When you finish profiler session, the connection to the target JVM is closed. You can
re-attach to the application by choosing Profile > Attach to Project from the main
menu.
To change the profiling task without finishing profiler session:
Click the Attach drop-down arrow to change the profiling mode at any point.
The target application is instrumented again without starting or stopping the
application.
9.12 Attaching the Profiler to a Remote Application
You can profile an application that is running on a remote system by attaching the
profiling tool to the application. When you use this attach mode, the remote
application starts after the profiler is attached. This mode enables you to obtain
profiling data on the startup of the target JVM.
To attach the profiling tool, you use the Attach Settings dialog box to specify the
attachment settings for your project. In the Attach Settings dialog box, specify the
location, OS and JVM of the remote target. Based on the details that you provide, the
Attach Settings dialog box provides you with a set of instructions on how to configure
the remote application to support profiling.
9.12.1 How to Attach to a Remote Application
To attach the profiler to a remote application you must configure the application to
load some profiler libraries on startup to enable the profiling tool to attach to the
application. You use the Attach Settings dialog box to specify the details of the remote
9-14 NetBeans Developing Applications with NetBeans IDE
Attaching the Profiler to a Remote Application
system and to generate a Remote Profiler Pack archive that contains the necessary
profiler libraries. You must copy the contents of the Remote Profiler Pack archive to
the remote system and then configure the remote application to load the profiler
libraries.
After you configure the remote application according to the instructions, you can start
the remote application and attach the profiler. You only have to configure the attach
mode once. The attachment settings are associated with that project. You can open the
Attach Settings dialog box at any time to change the attachment settings.
To attach to a remote application:
1. Choose Profile > Attach to External Project from the main menu. The Profile
External Process window displays.
2.
Select the Configure Session button and select Setup Attach to Process. The
Attach Settings dialog box displays.
3.
Set the profiler mode to Manually started remote Java process in the Profile
drop-down list.
4.
Specify the Hostname and select the OS and JVM from the drop-down list.
5.
Follow the detailed instructions in the Attach Settings dialog to start profiling.
6.
Click OK.
After the IDE is attached to the remote application you can do the following:
■
Detach from the remote application.
When you detach from the remote application, the remote application does not
stop but you stop receiving profiling data about the remote application. To attach
to the remote application, use the startup options provided by the Attach Settings
dialog box and start the remote application again.
■
Modify the profiling session.
You can modify the profiling session without detaching from the remote
application. For example, you can change the profiling task to monitoring to
reduce the profiling overhead, and then modify the task again later. This way you
do not have to re-attach and restart the remote application.
9.12.2 Attaching to a Remote Server
Similar to attaching the profiler to a remote application, you must copy the profiler
libraries in the Remote Profiler Pack to the remote system to attach the profiling tool to
a remote server. You must also modify the server configuration files to specify the path
to the JDK and to specify the path to the profiler agent. When you start the server
using the modified startup script, the server waits until the profiler attaches to the
server.
You can retrieve the path to the profiler agent when you use the Attach Settings dialog
box to configure your attach settings. The path to the profiler agent is similar to the
following path.
-agentpath:<remote>\lib\deployed\jdk16\windows\profilerinterface.dll=\lib,
5140
The placeholder <remote> refers to the full path to the root directory containing the
profiler libraries that you copied to the remote system. The number 5140 is the
Communication Port that the profiling tool uses to connect to the application. Modify
the port number in the Profiler tab in the Java category in the Options window.
Testing and Profiling Java Application Projects
9-15
Profiling a Free-form Project
Table 9–5 identifies the startup scripts and the parameters that must be modified to
specify the paths to the JDK and the profiler libraries:
Table 9–5
Startup Scripts
Server
File
Modification
Tomcat 7.x and 8.0.27 catalina.bat/catalina.sh
Set JAVA_HOME path to JDK
For server, modify CATALINA_OPTS to include profile
-agentpath parameter
GlassFish Server
Open Source Edition
4.1.1
asenv.bat/asenv.conf domain.xm
WebLogic 12c
startWebLogic.cmd/startWebLogic.sh
Set AS_JAVA path to JDK
For server, add jvm-options to include profile -agentpath
parameter
Set JAVA_HOME path to JDK
For server, modify JAVA_OPTIONS to include profile
-agentpath parameter
JBoss AS 7.x
standalone.conf.bat/standalone.con
Set JAVA_HOME path to JDK
For server, modify JAVA_OPTS to include profile
-agentpath parameter
For the GlassFish server, set the path to the JDK in the asenv.bat/asenv.conf file and
the path to the profiler agent in domain.xml.
For more details about configuring the servers for attaching the profiler tool, see the
following NetBeans FAQ:
http://wiki.netbeans.org/wiki/view/FaqProfilerAttachRemoteServer
For more details about modifying server startup scripts, consult the documentation for
the server.
9.13 Profiling a Free-form Project
In a free-form project, you have to create Ant targets to be able to profile a file or
project. You generally want one target in your free-form project's build script for
profiling a project and one target for profiling individual files.
If you do not have a profile target written for your project the IDE will offer to
generate a basic target for you when you first try to profile the project. You can then
inspect the target and customize it according to the specific requirements of the
project.
The first time that you choose the Profile Project or Profile File command on a
free-form project you must create the targets. The IDE can create the targets for you
based on the information for the target that is mapped to the Run command for the
project. You only have to generate the targets once.
Before the profile target is generated it is recommended that
you first confirm that you have a target mapped to the Run Project
command. When the IDE generates a profile target the IDE looks for
the information in the target that is mapped to the Run Project
command to determine details such as the run classpath and the
project's main class. If a target is already mapped to the Run Project
command there is a good chance that the generated profile target will
work without further customization.
Note:
9-16 NetBeans Developing Applications with NetBeans IDE
Profiling a Free-form Project
To profile a free-form project:
1. Set the free-form project as the main project by choosing Run > Set Main Project
in the main menu and selecting the project.
2.
Choose Profile > Profile Main Project in the main menu.
3.
Click the Configure Session button and select the required profiling mode.
4.
Click the Profile button to start profiling.
Before profiling your free-form project, be aware of the following conditions:
■
■
■
The project output must be set before you can profile a free-form application.
If you click Generate in the Profile Project dialog box to generate the targets the
IDE creates a build script named ide-targets.xml and generates a target named
profile-nb. Verify that the generated profile-nb target properly takes into
account all of the elements of your project. In some cases, you might have to
modify the classpath argument in the target if it does not include all of the items in
your run classpath.
The IDE also modifies project.xml to map the profile-nb target to the Profile
Project command in the IDE. If you write the target from scratch, you must also
create this mapping yourself.
For example, the profile-nb target that the IDE generates in ide-targets.xml
might look similar to the following example:
Example 9–1 Sample profile-nb Target
<?xml version="1.0" encoding="UTF-8"?>
<project basedir=".." name="YourProjectName">
<import file="../build.xml"/>
<target name="-profile-check">
<startprofiler freeform="true"/>
</target>
<!-- TODO: edit the following target according to your needs -->
<target name="profile-nb" if="profiler.configured"
depends="-profile-check">
<java classname="${mainclass}" dir="." fork="true">
<classpath>
<pathelement path="ClasspathSpecifiedInYourRunTarget"/>
</classpath>
<jvmarg line="${agent.jvmargs}"/>
</java>
</target>
</project>
In this example the IDE attempted to guess the runtime classpath for the project.
■
If you do not have a run target mapped or the IDE otherwise cannot determine the
project's classpath or main class, the generated profile target includes "TODO"
placeholders for you to fill in these values.
9.13.1 Profiling Free-form Web Projects
Typically the server is started using a startup script, not the java command directly.
Therefore you cannot use the <jvmarg .../> element to pass additional argument to
it. Instead, you have to modify the server startup script to configure it for profiling.
The recommended approach is to create a new script for starting the server for
profiling and use it in the profile target. The Attach Settings dialog box can provide
Testing and Profiling Java Application Projects
9-17
Profiling a Free-form Project
steps to help you modify the startup script. If your target server does not support
automatic integration, you can create the script by following the integration steps
described in the Attach Settings dialog box. You always have to set up the integration
for Local Direct attach.
The other steps for profiling a free-form web project are the same as those above for
profiling a standard J2SE projects.
9.13.1.1 A Typical Free-Form Project Profile Target
The generated Ant target does the following:
■
■
■
■
Starts the profiler with the startprofiler task. Setting the freeform attribute to true
will force displaying the profiling session configuration dialog.
The previous task sets the profiler.configured to true if the configuration was
confirmed. It also stores the profiler agent JVM arguments in the agent.jvmargs
property.
Establishes the runtime classpath. If the IDE is not able to determine your runtime
classpath the IDE adds placeholders to the script which you need to fill in
yourself.
Runs the application in profile mode. Setting fork="true" ensures the process is
launched in a separate virtual machine.
You can add any additional JVM arguments or program
arguments in the java task as well.
Note:
A generated profile target where the IDE is able to guess the runtime classpath will
look similar to the following (where the italicized items would have values specific to
your project).
<?xml version="1.0" encoding="UTF-8"?>
<project basedir=".." name="YourProjectName">
<import file="../build.xml"/>
<target name="-profile-check">
<startprofiler freeform="true"/>
</target>
<!-- TODO: edit the following target according to your needs -->
<!-- (more info:
https://netbeans.org/kb/articles/freeform-config.html#profilej2se) -->
<target name="profile-nb" if="profiler.configured"
depends="-profile-check">
<java classname="${mainclass}" dir="." fork="true">
<classpath>
<pathelement path="ClasspathSpecifiedInYourRunTarget"/>
</classpath>
<jvmarg line="${agent.jvmargs}"/>
</java>
</target>
</project>
If you do not have a run target mapped or the IDE otherwise cannot determine the
project's classpath or main class, the generated profile target includes "TODO"
placeholders for you to fill in these values as in the example below.
<?xml version="1.0" encoding="UTF-8"?>
<project basedir=".." name="YourProjectName">
<target name="-profile-check">
<startprofiler freeform="true"/>
9-18 NetBeans Developing Applications with NetBeans IDE
Profiling a Free-form Project
</target>
<!-- TODO: edit the following target according to your needs -->
<!-- (more info:
https://netbeans.org/kb/articles/freeform-config.html#profilej2se) -->
<target depends="-profile-check" if="profiler.configured"
name="profile-nb">
<path id="cp">
<!-- TODO configure the runtime classpath for your project here:
-->
</path>
<!-- TODO configure the main class for your project here: -->
<java classname="some.main.Class" fork="true">
<classpath refid="cp"/>
<jvmarg line="${agent.jvmargs}"/>
</java>
</target>
</project>
To specify the runtime classpath, insert pathelement elements within the path element
and point them to the directories that contain the items in your classpath. For example,
you can use the location attribute of pathelement to specify the location of the
classpath items relative to your project directory. The project directory is usually the
directory that contains the project's build.xml file. Below is an example of using the
pathelement attributes.
<path id="cp">
<pathelement location="libs">
<pathelement location="build">
</path>
9.13.1.2 Writing a Target to Profile a Selected File
The process is basically the same for writing targets to debug and run a single file. The
profile-selected-files target looks similar to the following:
<target name="-profile-check">
<startprofiler freeform="true"/>
</target>
<!-- TODO: edit the following target according to your needs -->
<!-- (more info: https://netbeans.org/kb/articles/freeform-config.html#profile_
sing) -->
<target depends="-profile-check" if="profiler.configured"
name="profile-selected-file-in-src">
<fail unless="profile.class">Must set property 'profile.class'</fail>
<path id="cp">
<pathelement location="build"/>
</path>>
<java classname="${profile.class}" fork="true">
<classpath refid="cp"/>
<jvmarg line="${agent.jvmargs}"/>
</java>
</target>
■
This is basically the same as the profile target. Instead of passing the program
main class to java you pass the profile.class property, which is set by the IDE to
the currently selected file.
Then you map the profile-selected-files target to the profile.single action.
<action name="profile.single">
<target>profile-selected-files</target>
<context>
<property>profile.class</property>
Testing and Profiling Java Application Projects
9-19
Taking and Accessing Snapshots of Profiling Data
<folder>${src.dir}</folder>
<pattern>\.java$</pattern>
<format>java-name</format>
<arity>
<one-file-only/>
</arity>
</context>
</action>
■
<property> now stores the context in the profile.class property.
■
Because java can only take a single file, you set <arity> to <one-file-only>.
■
Setting <format> to java-name and making it relative to src.dir creates a
fully-qualified class name for the currently selected file.
The IDE does not define the ${src.dir} property for you. You
need to define the property or import the .properties file that Ant is
using in project.xml. See Section 6.2.4.9.1, "Using Properties in the
project.xml File" for more information.
Note:
9.14 Taking and Accessing Snapshots of Profiling Data
A snapshot captures profiling data at a specific point in time and allows you to access
them via the Snapshot window. See Section 9.14.4, "Accessing Snapshots".
A snapshot differs from live profiling results in the following ways:
■
Snapshots can be examined when no profiling session is running.
■
Snapshots can be easily compared.
There are two options for taking snapshots:
■
■
While the profiling session is in progress. See Section 9.14.1, "Taking Snapshots
During a Profiling Session"
At the end of the profiling session. See Section 9.14.2, "Taking Snapshots at the End
of a Profiling Session"
9.14.1 Taking Snapshots During a Profiling Session
You may take a snapshot of the profiling data at any time during the profiling session
by clicking the Snapshot icon shown in the figure below.
To control how the snapshots functionality behaves during a session, go to Tools >
Options > Java > Snapshots > Profiler and click the When taking snapshots
drop-down menu to see the following options:
Open Snapshot—it opens the snapshot right after clicking the Snapshot icon
Save Snapshot—it saves a new snapshot every time you click the Snapshot Icon
Save and open snapshot—it saves and opens a snapshot right after clicking the
Snapshot icon.
You may take multiple snapshots during a profiling session and you will also be
prompted to save a "final" snapshot at the end of the session.
You can only take a snapshot while a profiling session is in progress. You can take a
snapshot manually or set a profiling point to take a snapshot automatically at a precise
point in your application. When you use a profiling point to take a snapshot, you
9-20 NetBeans Developing Applications with NetBeans IDE
Taking and Accessing Snapshots of Profiling Data
locate the point in your source code where you want to take a snapshot. For example,
you may want to take a snapshot when a thread enters a specific method.
Perform the following steps to take a snapshot manually:
1. Start a profiling session.
For information, see Section 9.9, "Starting a Profiling Session."
2.
Do one of the following:
■
Click the Take Snapshot of Collected Results button in the Profiler window.
■
Select Profile > Take Snapshot of Collected Results from the main menu.
When you take a snapshot, the snapshot opens in the main editor window. You can
then save the snapshot to your project.
To take a snapshot using a profiling point:
1. Open the source file containing the code where you want to place the profiling
point.
2.
Right-click in the line of code and choose Profile > Insert Profiling Point.
3.
Select one of the snapshot options in the New Profiling Point wizard and click
Next.
4.
Modify any of the profiling point properties in the Customize Properties page of
the wizard. Click Finish.
If you use a profiling point to take a snapshot, you can choose from the following
snapshot options:
■
■
■
■
■
■
Load Generator. Choose this if you want the IDE to take a snapshot to start and
stop a load generator script at the given source code location.
Reset Results. Choose this if you want the IDE to take a snapshot to reset
currently collected profiling results.
Stopwatch. Choose this if you want the IDE to take a snapshot to measure time
between start and stop locations to obtain the execution time of a method
fragment.
Take Snapshot. Choose this if you want the IDE to take a snapshot when an
application thread enters or leaves the specified line of code.
Timed Take Snapshot. Choose this if you want the IDE to take a snapshot at a
specific time and date. You can also configure the IDE to take snapshots at a
specified interval.
Triggered Take Snapshot. Choose this if you want the IDE to take a snapshot
when the specified condition is met. You specify the condition by choosing one of
the available triggers.
For each snapshot option you can choose to save the snapshot to your project or you
can specify a location.
To save a snapshot;
■
Click Save Snapshot to Project in the snapshot toolbar.
You can also use the Options window to configure the IDE behavior when taking
a snapshot.
Testing and Profiling Java Application Projects
9-21
Taking a Heap Dump
You can save a snapshot to your project or you can save the snapshot to a location on
your local file system. When you save a snapshot to your project, the snapshot is listed
under Snapshots in the Snapshots window.
To distinguish a snapshot from other profiling snapshots you have taken of the project,
you can rename it. Select a snapshot in the Snapshots section of the Snapshots window
and click Rename selected snapshot to open the Rename Snapshot dialog box and
enter a new name.
9.14.2 Taking Snapshots at the End of a Profiling Session
When closing a profiled application, or if it finishes on its own, while the profiling
session is in progress, the profiler asks you whether to take a snapshot of the results
collected so far by displaying the Application Finished dialog.
Click Yes to save the snapshot.
9.14.3 Starting and Stopping the Application Finished Dialog
When the Application Finished dialog appears at the end of the profiling session, if
you select the Do not show this message again checkbox the dialog would not display
again. If at a later time you want to reactivate the display of this dialog, go to Tools
Options > Java > Snapshots > Profiler > General > Miscellaneous and click the Reset
button.
9.14.4 Accessing Snapshots
You may access you profiling session snapshots by going to Window > Profiling >
Snapshots. The Snapshots window appears.
At the bottom of the Snapshots window there are icons that allow you to export, open,
rename, and delete selected snapshots.
9.15 Taking a Heap Dump
A heap dump captures profiling data at a specific point in time. You can take a heap
dump when a profiling session is in progress. When you take a heap dump, you are
prompted to save the heap to your project or local file system. After you save a heap
dump you can load the heap dump at any time and browse the objects on the heap,
locate references to individual objects and compare heap dumps to view the
differences between the snapshots. It is not necessary to run a profiling session to load
and browse the heap dump.
To take a heap dump, the application must be running on a
version of JDK 1.5.0_12 or later.
Note:
9.15.1 How to Take a Heap Dump
You can take a heap dump manually or set a profiling point to take a heap dump
automatically at a certain point in your application. In the Options window, you can
also set the IDE to automatically take a heap dump on OutOfMemory error.
To take a heap dump manually:
1. Start a profiling session.
2.
Choose Profile > Take Heap Dump in the main menu.
9-22 NetBeans Developing Applications with NetBeans IDE
Taking a Heap Dump
When you take the heap dump, you are prompted to specify where you want to save
the heap dump. You can save the heap dump snapshot to your project or to any
location on your local file system.
To take a heap dump using a profiling point:
1. Open the source file containing the code where you want to place the profiling
point.
2.
Right-click in the line of code where you want to place the profiling point and
choose Profile > Insert Profiling Point.
3.
In the New Profiling Point wizard, select one of the following snapshot options
and click Next.
4.
■
Take Snapshot
■
Timed Take Snapshot
■
Triggered Take Snapshot
In the Customize Properties page of the wizard, select Heap Dump as the type of
snapshot and modify any additional settings. Click Finish.
When you use a profiling point to take a heap dump, you specify the point in your
source code where you want to place the profiling point. For example, you may want
to take a heap dump when a thread enters a specific method.
To take a heap dump on OutOfMemory error:
1. Choose Tools > Options from the main menu, click the Java category and then
click the Profiler tab.
2.
Choose the Snapshots category.
3.
In the On OutOfMemoryError list, select an option from the drop-down list to
specify what the IDE does when an OutOfMemoryError is encountered.
The default behavior is to save the heap dump to the profiled project.
9.15.2 How to Analyze a Heap Dump Using Object Query Language (OQL)
OQL is a SQL-like query language to query a Java heap that enables you to
filter/select information wanted from the Java heap. While pre-defined queries such as
"show all instances of class X" are already supported by the tool, OQL adds more
flexibility. OQL is based on JavaScript expression language.
When you load a Java heap in the Heap window, you can click the OQL Console tab of
the window to open the OQL editor. The OQL Console contains an OQL editor, a
saved OQL queries window and a window that displays the query results. You can
use any of the sample OQL queries or create a query to filter and select heap data to
locate the information that you want from the Java heap. After you choose or write a
query, you can run the query against the Java heap and view the results.
An OQL query is of the following form:
select <JavaScript expression to select>
[ from [instanceof] <class name> <identifier>
[ where <JavaScript boolean expression to filter> ] ]
where class name is fully qualified Java class name (example: java.net.URL) or array
class name. char[] (or [C) is char array name, java.io.File (or [Ljava.io.File;) is
name of java.io.File[] and so on. Note that fully qualified class name does not always
uniquely identify a Java class at runtime. There may be more than one Java class with
Testing and Profiling Java Application Projects
9-23
Taking a Heap Dump
the same name but loaded by different loaders. So, class name is permitted to be id
string of the class object. If instanceof keyword is used, subtype objects are selected. If
this keyword is not specified, only the instances of exact class specified are selected.
Both from and where clauses are optional.
In select and (optional) where clauses, the expression used in JavaScript expression.
Java heap objects are wrapped as convenient script objects so that fields may be
accessed in natural syntax. For example, Java fields can be accessed with obj.field_
name syntax and array elements can be accessed with array[index] syntax. Each Java
object selected is bound to a JavaScript variable of the identifier name specified in from
clause.
9.15.2.1 OQL Examples
Select all Strings of length 100 or more:
select s from java.lang.String s where s.count >= 100
Select all int arrays of length 256 or more:
select a from int[] a where a.length >= 256
Show content of Strings that match a regular expression:
select {instance: s, content: s.toString()} from java.lang.String s
where /java/(s.toString())
Show path value of all File objects:
select file.path.toString() from java.io.File file
Show names of all ClassLoader classes:
select classof(cl).name
from instanceof java.lang.ClassLoader cl
Show instances of the Class identified by given id string:
select o from instanceof 0xd404b198 o
0xd404b198 is id of a Class (in a session). This is found by looking at the id shown in
that class's page.
9.15.2.2 OQL built-in objects and functions
Heap object
The heap built-in object supports the following methods:
■
heap.forEachClass - calls a callback function for each Java Class
heap.forEachClass(callback);
■
heap.forEachObject - calls a callback function for each Java object
heap.forEachObject(callback, clazz, includeSubtypes);
clazz is the class whose instances are selected. If not specified, defaults to
java.lang.Object. includeSubtypes is a boolean flag that specifies whether to
include subtype instances or not. Default value of this flag is true.
■
heap.findClass - finds Java Class of given name
heap.findClass(className);
where className is name of the class to find. The resulting Class object has
following properties:
–
name - name of the class.
9-24 NetBeans Developing Applications with NetBeans IDE
Taking a Heap Dump
–
superclass - Class object for super class (or null if java.lang.Object).
–
statics - name, value pairs for static fields of the Class.
–
fields - array of field objects. field object has name, signature properties.
–
loader - ClassLoader object that loaded this class.
Class objects have the following methods:
■
–
isSubclassOf - tests whether given class is direct or indirect subclass of this
class or not.
–
isSuperclassOf - tests whether given Class is direct or indirect superclass of
this class or not.
–
subclasses - returns array of direct and indirect subclasses.
–
superclasses - returns array of direct and indirect superclasses.
heap.findObject - finds object from given object id
heap.findObject(stringIdOfObject);
■
heap.classes - returns an enumeration of all Java classes
■
heap.objects - returns an enumeration of Java objects
heap.objects(clazz, [includeSubtypes], [filter])
clazz is the class whose instances are selected. If not specified, defaults to
java.lang.Object. includeSubtypes is a boolean flag that specifies whether to
include subtype instances or not. Default value of this flag is true. This method
accepts an optional filter expression to filter the result set of objects.
■
■
heap.finalizables - returns an enumeration of Java objects that are pending to be
finalized.
heap.livepaths - return an enumeration of paths by which a given object is alive.
This method accepts optional second parameter that is a boolean flag. This flag
tells whether to include paths with weak reference(s) or not. By default, paths with
weak reference(s) are not included.
select heap.livepaths(s) from java.lang.String s
Each element of this array itself is another array. The later array is contains an
objects that are in the 'reference chain' of the path.
■
heap.roots - returns an Enumeration of Roots of the heap.
Each Root object has the following properties:
–
id - String id of the object that is referred by this root
–
type - descriptive type of Root (JNI Global, JNI Local, Java Static, etc.)
–
description - String description of the Root
–
referrer - Thread Object or Class object that is responsible for this root or null
Examples
■
Access static field 'props' of class java.lang.System
select heap.findClass("java.lang.System").statics.props
select heap.findClass("java.lang.System").props
■
Get number of fields of java.lang.String class
Testing and Profiling Java Application Projects
9-25
Taking a Heap Dump
select heap.findClass("java.lang.String").fields.length
■
Find the object whose object id is given
select heap.findObject("0xf3800b58")
■
Select all classes that have name pattern java.net.*
select filter(heap.classes(), "/java.net./(it.name)")
Functions on individual objects
■
allocTrace function
Returns allocation site trace of a given Java object if available. allocTrace returns
array of frame objects. Each frame object has the following properties:
■
–
className - name of the Java class whose method is running in the frame.
–
methodName - name of the Java method running in the frame.
–
methodSignature - signature of the Java method running in the frame.
–
sourceFileName - name of source file of the Java class running in the frame.
–
lineNumber - source line number within the method.
classof function
Returns class object of a given Java object. The resulting object supports the
following properties:
–
name - name of the class
–
superclass - class object for super class (or null if java.lang.Object)
–
statics - name, value pairs for static fields of the class
–
fields - array of field objects. Field objects have name, signature properties
–
loader - ClassLoader object that loaded this class.
Class objects have the following methods:
–
isSubclassOf - tests whether given class is direct or indirect subclass of this
class or not
–
isSuperclassOf - tests whether a given class is direct or indirect superclass of
this class or not
–
subclasses - returns array of direct and indirect subclasses
–
superclasses - returns array of direct and indirect superclasses
Examples
■
Show class name of each Reference type object
select classof(o).name from instanceof java.lang.ref.Reference o
■
Show all subclasses of java.io.InputStream
select heap.findClass("java.io.InputStream").subclasses()
■
Show all superclasses of java.io.BufferedInputStream
show all superclasses of java.io.BufferedInputStream
9-26 NetBeans Developing Applications with NetBeans IDE
Taking a Heap Dump
■
forEachReferrer function
Calls a callback function for each referrer of a given Java object.
■
identical function
Returns whether two given Java objects are identical or not, for example:
select identical(heap.findClass("Foo").statics.bar,
heap.findClass("AnotherClass").statics.bar)
■
objectid function
Returns String id of a given Java object. This id can be passed to heap.findObject
and may also be used to compare objects for identity. For example:
select objectid(o) from java.lang.Object o
■
reachables function
Returns an array of Java objects that are transitively referred from the given Java
object. Optionally accepts a second parameter that is comma separated field names
to be excluded from reachability computation. Fields are written in class_
name.field_name pattern.
Examples
–
Print all reachable objects from each Properties instance.
select reachables(p) from java.util.Properties p
–
Print all reachables from each java.net.URL but omit the objects reachable via
the fields specified.
select reachables(u, 'java.net.URL.handler') from java.net.URL u
■
referrers function
Returns an enumeration of Java objects that hold reference to a given Java object.
This method accepts optional second parameter that is a boolean flag. This flag
tells whether to include weak reference(s) or not. By default, weak reference(s) are
not included.
Examples
–
Print number of referrers for each java.lang.Object instance
select count(referrers(o)) from java.lang.Object o
–
Print referrers for each java.io.File object
select referrers(f) from java.io.File f
–
Print URL objects only if referred by 2 or more
select u from java.net.URL u where count(referrers(u)) > 2
■
referees function
Returns an array of Java objects to which the given Java object directly refers to.
This method accepts optional second parameter that is a boolean flag. This flag
tells whether to include weak reference(s) or not. By default, weak reference(s) are
not included. For example, to print all static reference fields of java.io.File class:
select referees(heap.findClass("java.io.File"))
Testing and Profiling Java Application Projects
9-27
Taking a Heap Dump
■
refers function
Returns whether first Java object refers to second Java object or not.
■
root function
If the given object is a member of root set of objects, this function returns a
descriptive Root object describing why it is so. If given object is not a root, then
this function returns null.
■
sizeof function
Returns size of the given Java object in bytes, for example:
select sizeof(o) from int[] o
■
retainedsize function
Returns size of the retained set of the given Java object in bytes. Note: Using this
function for the first time on a heap dump may take significant amount of time.
The following is an example usage of the retainedsize function:
select rsizeof(o) from instanceof java.lang.HashMap o
■
toHtml function
Returns HTML string for the given Java object. Note that this is called
automatically for objects selected by select expression. But, it may be useful to
print more complex output. For example, to print a hyperlink in bold font:
select "<b>" + toHtml(o) + "</b>" from java.lang.Object o
9.15.2.3 Selecting Multiple Values
Multiple values can be selected using JavaScript object literals or arrays.
For example, show the name and thread for each thread object
select { name: t.name? t.name.toString() : "null", thread: t }
from instanceof java.lang.Thread t
array/iterator/enumeration manipulation functions
These functions accept an array/iterator/enumeration and an expression string [or a
callback function] as input. These functions iterate the array/iterator/enumeration
and apply the expression (or function) on each element. Note: JavaScript objects are
associative arrays. So, these functions may also be used with arbitrary JavaScript
objects.
■
concat function
Returns whether the given array/enumeration contains an element the given
boolean expression specified in code. The code evaluated can refer to the following
built-in variables.
–
it - currently visited element
–
index - index of the current element
–
array - array/enumeration that is being iterated
For example, to select all Properties objects that are referred by some static field
some class:
9-28 NetBeans Developing Applications with NetBeans IDE
Taking a Heap Dump
select p from java.util.Properties p
where contains(referrers(p), "classof(it).name == 'java.lang.Class'")
■
count function
Returns the count of elements of the input array/enumeration that satisfy the
given boolean expression. The boolean expression code can refer to the following
built-in variables.
–
it - currently visited element
–
index - index of the current element
–
array - array/enumeration that is being iterated
For example, print the number of classes that have a specific name pattern:
select count(heap.classes(), "/java.io./(it.name)")
■
filter function
Returns an array/enumeration that contains elements of the input
array/enumeration that satisfy the given boolean expression. The boolean
expression code can refer to the following built-in variables.
–
it - currently visited element
–
index - index of the current element
–
array - array/enumeration that is being iterated
–
result -> result array/enumeration
Examples
–
Show all classes that have java.io.* name pattern
select filter(heap.classes(), "/java.io./(it.name)")
–
Show all referrers of URL object where the referrer is not from java.net
package
select filter(referrers(u), "! /java.net./(classof(it).name)")
from java.net.URL u
■
length function
Returns number of elements of an array/enumeration.
■
map function
Transforms the given array/enumeration by evaluating given code on each
element. The code evaluated can refer to the following built-in variables.
–
it - currently visited element
–
index - index of the current element
–
array - array/enumeration that is being iterated
–
result -> result array/enumeration
Map function returns an array/enumeration of values created by repeatedly calling
code on each element of input array/enumeration.
For example, show all static fields of java.io.File with name and value:
select map(heap.findClass("java.io.File").statics, "index + '=' + toHtml(it)")
Testing and Profiling Java Application Projects
9-29
Taking a Heap Dump
■
max function
Returns the maximum element of the given array/enumeration. Optionally
accepts code expression to compare elements of the array. By default numerical
comparison is used. The comparison expression can use the following built-in
variables:
–
lhs - left side element for comparison
–
rhs - right side element for comparison
Examples
–
Find the maximum length of any string instance
select max(map(heap.objects('java.lang.String', false), 'it.count'))
–
Find string instance that has the maximum length
select max(heap.objects('java.lang.String'), 'lhs.count > rhs.count')
■
min function
Returns the minimum element of the given array/enumeration. Optionally
accepts code expression to compare elements of the array. By default numerical
comparison is used. The comparison expression can use the following built-in
variables:
–
lhs - left side element for comparison
–
rhs - right side element for comparison
Examples
–
Find the minimum size of any vector instance
select min(map(heap.objects('java.util.Vector', false),
'it.elementData.length'))
–
Find vector instance that has the maximum length
select min(heap.objects('java.util.Vector'), 'lhs.elementData.length <
rhs.elementData.length')
■
sort function
Sorts a given array/enumeration. Optionally accepts code expression to compare
elements of the array. By default numerical comparison is used. The comparison
expression can use the following built-in variables:
–
lhs - left side element for comparison
–
rhs - right side element for comparison
Examples
–
Print all char[] objects in the order of size.
select sort(heap.objects('char[]'), 'sizeof(lhs) - sizeof(rhs)')
–
Print all char[] objects in the order of size but print size as well.
select map(sort(heap.objects('char[]'), 'sizeof(lhs) - sizeof(rhs)'),
size: sizeof(it), obj: it }')
■
top function
9-30 NetBeans Developing Applications with NetBeans IDE
'{
Taking a Heap Dump
Returns top N elements of the given array/enumeration. Optionally accepts code
expression to compare elements of the array and the number of top elements. By
default the first 10 elements in the order of appearance is returned. The
comparison expression can use the following built-in variables:
–
lhs - left side element for comparison
–
rhs - right side element for comparison
Examples
–
Print 5 longest strings
select top(heap.objects('java.lang.String'), 'rhs.count - lhs.count', 5)
–
Print 5 longest strings but print size as well.
select map(top(heap.objects('java.lang.String'),
5), '{ length: it.count, obj: it }')
■
'rhs.count - lhs.count',
sum function
Returns the sum of all the elements of the given input array or enumeration.
Optionally, accepts an expression as second param. This is used to map the input
elements before summing those.
For example, return the sum of sizes of the reachable objects from each Properties
object:
select sum(map(reachables(p), 'sizeof(it)'))
from java.util.Properties p
// or omit the map as in ...
select sum(reachables(p), 'sizeof(it)')
from java.util.Properties p
■
toArray function
Returns an array that contains elements of the input array/enumeration.
■
unique function
Returns an array/enumeration containing unique elements of the given input
array/enumeration.
The following example selects a unique char[] instances referenced from strings.
Note that more than one string instance can share the same char[] for the content.
// number of unique char[] instances referenced from any String
select count(unique(map(heap.objects('java.lang.String'), 'it.value')))
// total number of Strings
select count(heap.objects('java.lang.String'))
9.15.2.4 Other Examples
The following example prints a histogram of each class loader and number of classes
loaded by it.
java.lang.ClassLoader has a private field called classes of type java.util.Vector
and Vector has a private field named elementCount that is number of elements in the
vector. The query selects multiple values (loader, count) using JavaScript object literal
and map function. It sorts the result by count (i.e., number of classes loaded) using sort
function with comparison expression.
Testing and Profiling Java Application Projects
9-31
Setting a Profiling Point
select map(sort(map(heap.objects('java.lang.ClassLoader'),
'{ loader: it, count: it.classes.elementCount }'), 'lhs.count < rhs.count'),
'toHtml(it) + "<br>"')
The following example shows the parent-child chain for each class loader instance.
select map(heap.objects('java.lang.ClassLoader'),
function (it) {
var res = '';
while (it != null) {
res += toHtml(it) + "->";
it = it.parent;
}
res += "null";
return res + "<br>";
})
Note that the parent field of java.lang.ClassLoader class is used and the example
walks until the parent is null using the callback function to map call.
The following example prints the value of all System properties. Note that this query
(and many other queries) may not be stable - because private fields of the Java
platform classes may be modified or removed without any notification
(implementation detail). But using such queries on user classes may be safe, given that
you have control over the classes.
select map(filter(heap.findClass('java.lang.System').props.table, 'it != null &&
it.key != null && it.value != null'),
function (it) {
var res = it.key.toString() + ' = ' + it.value.toString();
return res;
});
■
■
■
■
java.lang.System has static field by name 'props' of type java.util.Properties.
java.util.Properties has field by 'table' of type java.util.Hashtable$Entry
(this field is inherited from java.util.Hashtable). This is the hashtable buckets
array.
java.util.Hashtable$Entry has key, value and next fields. Each entry points the
next entry (or null) in the same hashtable bucket.
java.lang.String class has a value field of type char[].
9.16 Setting a Profiling Point
A profiling point is a marker in your source code that can invoke specific profiling
actions. You set a profiling point in your code by using the context menu in the Source
Editor or by using the toolbar in the Profiling Points window.
You can set the following types of profiling points:
■
Reset Results
■
Stopwatch
■
Take Snapshot
■
Load Generator
■
Timed Take Snapshot
■
Triggered Take Snapshot
9-32 NetBeans Developing Applications with NetBeans IDE
Setting a Profiling Point
You can use a profiling point to reset profiling results, take a snapshot or record the
timestamp or execution time of a code fragment.
You can also use a profiling to stop and start a load generator script (requires the load
generator plugin).
9.16.1 How to Set Profiling Points
Once you set a profiling point it becomes part of the project until you delete it. You can
view, modify and delete the Profiling Points in your projects in the Profiling Points
window. The Profiling Points window displays all profiling points in open projects.
You can select a profiling point and then use the toolbar to edit, remove, enable and
disable the profiling point.
To open the New Profiling Points window:
■
Choose Profile > Insert Profiling Points in the main menu
To set a profiling point:
1. Locate the class where you want to add the profiling point and open the class in
the Source Editor.
2.
In the Source Editor, right-click in the line where you want to add the profiling
point and choose Profiling > Insert Profiling Point to open the New Profiling
Point wizard.
3.
Select a profiling point type and the project and click Next.
4.
Customize the properties of the profiling point, if necessary and click Finish.
When you click Finish, an icon representing the profiling point type appears in the
sidebar of the Source Editor next to the line where you inserted the profiling point.
To enable and disable a profiling point:
1. Locate the class containing the profiling point and open the class in the Source
Editor.
2.
In the Source Editor, right-click in the left margin of the line containing the
profiling point and choose Profiling Point > Disabled or Enabled.
To enable, disable, or customize the settings of a profiling point:
■
Choose Window > Profiling > Profiling Points.
To view details about a profiling point:
You can view information about a profiling point in the Profiling Points Report
window. The information displayed is dependent on the profiling point type.
Right-click a profiling point in the Profiling Points window and choose Show Report
in the context menu to open this window.
9.16.2 How to Reset Profiling Results
You can use a profiling point to reset the collected profiling results each time that a
thread in the application hits the profiling point. You can then use this profiling point
to gather results deltas when combined with the Take Snapshot profiling point.
To reset a profiling point:
1. Click Add Profiling Point or Edit Profiling Point in the Profiling Points window.
Testing and Profiling Java Application Projects
9-33
Profiling Telemetry
2.
Select the Reset Results profiling point type and select the desired project.
3.
Click Next.
4.
Specify a name that identifies that profiling point.
5.
Specify the line number containing the profiling point and whether the profiling
point is hit when a thread hits the beginning or end of that line (the file name is
automatically filled in).
6.
Click Finish.
9.16.3 How to Set a Stopwatch Profiling Point
You can obtain a timestamp each time that a profiling point is hit instead of calling the
System.currentTimeMillis() method. Setting a Stopwatch profiling point lets you
measure the time between the start and stop locations to obtain the execution time of a
method fragment.
To set a Stopwatch profiling point:
1. Choose Window > Profiling > Profiling Points.
2.
Click Add Profiling Point in the Profiling Points window.
3.
Select the Stopwatch profiling point type and select the desired project.
4.
Click Next.
5.
Specify a name that identifies that profiling point.
6.
Select whether you want to obtain a timestamp or a timestamp and the execution
duration.
7.
Specify the file in which to set the profiling point.
8.
Specify the line number containing the profiling point at which point time
measurement begins (the file name is automatically filled in).
9.
If you selected Timestamp and duration, specify the line at which to stop the
measurement (the file name is automatically filled in).
10. Click Finish.
9.17 Profiling Telemetry
The telemetry mode provides the following metrics:
■
CPU and GC—displays the CPU and GC percentage of use at a given time
■
Memory—displays in MB the heap size and used heap at a given time
■
■
Surviving Generations —displays the number of surviving generations at a given
time. It also displays indicates the GC intervals
Threads and Classes—displays number of loaded classes and threads at a given
time
To start a profiling telemetry session, see Section 9.9, "Starting a Profiling Session".
Figure 9–1 shows a snapshot of a telemetry session.
9-34 NetBeans Developing Applications with NetBeans IDE
Profiling Methods
Figure 9–1 Telemetry Session
When running in the Telemetry mode the profiler monitors the target application with
a very low overhead. A Thread Dump or Heap Dump can be taken from the profiled
application. The garbage collection in the target VM can be requested using a toolbar
button.
Each graph displays the full data for a profiling session and can be zoomed and
panned separately by the control buttons and mouse wheel. A graph can be
maximized to display more details by hiding the other graphs using the toolbar
buttons.
For the description of the toolbar buttons see Section 9.9.3, "Understanding the Toolbar
Icons".
For more information on profiling methods in NetBeans IDE, see
http://wiki.netbeans.org/ProfilerTelemetry.
9.18 Profiling Methods
The methods profiling mode tracks methods call trees, execution times and
invocations count if configured, enabling to measure and optimize application
performance. Use this profiling mode if experiencing slow responses or optimizing
algorithms for speed of execution.
Figure 9–2 shows a snapshot of a methods session.
Testing and Profiling Java Application Projects
9-35
Profiling Methods
Figure 9–2 Methods Session
For the description of the toolbar buttons see Section 9.9.3, "Understanding the Toolbar
Icons".
To start a profiling methods session, see Section 9.9, "Starting a Profiling Session".
9.18.1 Basic Methods Profiling Mode
The methods mode is designed to provide profiling data from all classes and methods
without any initial setup. The methods mode provides metrics for methods and
classes. The methods report allows you to view the data by Forward Calls, Hot Spots,
and Reverse Calls by clicking on the appropriate icons.
Table 9–6 lists three different views on the methods data collected by the profiler.
Table 9–6
Methods Views
Methods View Name
Description
Forward calls
Shows the methods execution tree, from a thread down to single
method calls. The Self time node represents execution time of the
method, without any outgoing calls.
Hot spots
Shows a flat list of methods without the incoming/outgoing
context. If sorted by the Self Time, it can immediately uncover an
obvious performance bottleneck.
Reverse calls
Shows a flat list of methods for each thread and a tree of all
execution points of these methods, transitively. It helps to
discover the right call tree affected by a slowdown.
You may also choose to Show Delta Values and Select Threads.
■
Show Delta Values. Switches from absolute values to incremental values. The
values displayed prior to switching the view are remembered but the new view
displays changes starting at the moment the new selection was made. Clicking this
icon again resets the results back to absolute values.
9-36 NetBeans Developing Applications with NetBeans IDE
Profiling Methods
■
Select Threads. Shows threads available in live results or a saved snapshot and
allows you to select specific threads for displaying results. This feature is useful
when tracking EDT slowness in desktop applications or analyzing worker threads
in server applications. This feature merges results from the selected threads to a
single tree.
Additionally, you may select the columns to be displayed; the options are Total Time,
Total Time (CPU), Selected, and Hits/Invocations (depending on the session
configuration).
9.18.1.1 Selecting Threads
By default results for all threads are displayed. By clicking the Select threads button
it's possible to select just some threads and the methods executed by other threads
won't be displayed in the results.
Initially the Show all threads option is selected, which means that results of all
threads including any new threads started in future are displayed. Deselecting this
option clears all selected threads, enabling to quickly select one desired thread.
Clicking a thread in the Select thread table also deselects the option, but keeps the
other threads selected, which makes it easier to remove just one thread from the
results.
When the Show all threads option is deselected, the Merge selected threads becomes
enabled. This option allows to merge methods executed from different threads into
single call tree, simplifying analysis of profiling data from multiple worker threads.
9.18.1.2 Searching And Filtering Results
To find a method in results, either:
■
■
use the Find stripe which opens by invoking the Find action in results context
menu or in the Edit menu
use the Ctrl - F keyboard shortcut
To filter collected results, either:
■
■
use the Filter stripe which opens by invoking the Filter action in the results context
menu
use the Ctrl - G keyboard shortcut
For more information on profiling methods in NetBeans IDE, see
http://wiki.netbeans.org/ProfilerMethods.
9.18.2 Advanced Methods Profiling Mode
To change the profiling modes and settings in the Settings pane, press the Settings
switch in the Profiler window toolbar.
Table 9–7 lists the profiling modes the profiler offers with different profiling
techniques and settings.
Table 9–7
Methods Profiling Modes
Name
Description
All classes
Uses sampling and collects profiling data from methods of all
classes. This mode is selected by default and doesn't require any
additional configuration.
Testing and Profiling Java Application Projects
9-37
Profiling Methods
Table 9–7 (Cont.) Methods Profiling Modes
Name
Description
Project classes
Uses sampling and collects data from methods of projects
classes. This mode doesn't require any additional configuration.
Selected classes
Uses bytecode instrumentation and collects data from methods
of the defined classes. To use this mode, at least one class has to
be selected for profiling.
Selected methods
Uses bytecode instrumentation and collects data from the
defined methods. To use this mode, at least one method has to
be selected for profiling.
For more information on profiling methods in NetBeans IDE, see
http://wiki.netbeans.org/ProfilerMethods.
9.18.3 Selecting Classes And Methods For Profiling
Selected classes or methods instruct the profiler from where to start collecting the
profiling data. Once a JVM executes a selected method or the method of a selected
class, the profiler starts collecting data of this method and all methods called by this
method, transitively.
A class or method for instrumented profiling can be selected via:
■
■
■
■
Select Class or Select Method dialog. Allows to select one or several classes or
methods from a project or .class/.jar file. Can be opened directly from the Methods
Settings pane.
Code editor context menu. Provides Profile | Profile Class and Profile | Profile
Method actions.
Navigator context menu. Provides Profile | Profile Class and Profile | Profile
Method actions.
Profiling results. Live or saved Methods results provide Profile Class and Profile
Method actions in the context menu. The Selected column is available to select
methods for profiling. The column can be displayed using the right corner button
in the view header by clicking the drop-down arrow (or right clicking the header
on Mac OS X).
For more information on profiling methods in NetBeans IDE, see
http://wiki.netbeans.org/ProfilerMethods.
9.18.4 Configuring Additional Options
Additional options define where to stop collecting the profiling data in order to lower
the overhead and keep the profiling data clear and focused.
By default the profiler offers a limited subset of customizable options for an
instrumented profiling session.
To enable the expert mode:
1.
Choose Tools > Options > Java > Profiler > General from the main menu.
2.
Select the Enable manual setup for Methods and Objects (expert users)
checkbox.
For more information on the expert mode of profiling methods in NetBeans IDE, see
http://wiki.netbeans.org/ProfilerExpertFeatures.
9-38 NetBeans Developing Applications with NetBeans IDE
Profiling Objects
9.19 Profiling Objects
The objects mode provides a list of classes allocated to a project including live
instances and bytes allocation.
Figure 9–3 shows a snapshot of an objects session.
Figure 9–3 Objects Session
To select the classes to be profiled, click the Settings icon in the top-right corner and
choose the required option in the drop-down menu:
■
All Classes. Shows all classes and object that are live on the Virtual Machine heap.
■
Project Classes. Allows to view only the classes defined in the project.
To start a profiling objects session, see Section 9.9, "Starting a Profiling Session".
For the description of the toolbar buttons see Section 9.9.3, "Understanding the Toolbar
Icons".
For more information on profiling objects in NetBeans IDE, see
http://wiki.netbeans.org/ProfilerObjects.
9.19.1 Basic Profiling
The Objects mode provides profiling data from all classes without any initial setup.
Click the Profile or Attach button in the toolbar to start a profiling session.
9.19.1.1 Results View
The default results view shows a histogram of the classes currently live in the heap
memory with instance numbers and sizes. The view provides data columns listed in
Figure 9–8.
Testing and Profiling Java Application Projects
9-39
Profiling Objects
Table 9–8
Default Results View
Column
Description
Name
Shows name of the class with live instances on heap.
Live Bytes
Shows the size of all instances of the class currently live on heap.
Live Objects
Shows the number of all instances of the class currently live on
heap.
The columns can be displayed or hidden using the right corner
button in the view header by clicking the drop-down arrow (or right
clicking the header on Mac OS X).
Note:
9.19.1.2 Searching And Filtering Results
A class can be found in results using the Find stripe which opens by invoking the Find
action in results context menu or IDE Edit menu or using the Ctrl-F keyboard shortcut.
Values of the Name column are searched for the entered substring, optionally
matching case if selected. Once a search has been performed, it can be repeated using
the F3 or Shift+F3 shortcuts. Next appearance of the currently selected value of Name
column can be found using the Ctrl+F3 shortcut.
Collected results can be filtered using the Filter stripe which opens by invoking the
Filter action in results context menu or using the Ctrl-G keyboard shortcut. Values of
the Name column are filtered by the entered substring depending on the selected filter
mode (Contains, Does Not Contain, Regular Expression), optionally matching case if
selected. When collecting the allocation stack traces, the top level class nodes are
always displayed, only the allocating methods are filtered.
9.19.2 Advanced Profiling
To cover various use cases of objects profiling the profiler offers three profiling modes
with different profiling techniques and settings. The modes and settings can be
changed in the Settings pane which is displayed by pressing the Settings switch in
Profiler window toolbar.
9.19.2.1 Objects Profiling Modes
Table 9–9 lists objects profiling modes.
Table 9–9
Objects Profiling Modes
Name
Description
All classes
Uses sampling and shows histogram of live objects of all classes
allocated on the heap, including instance numbers and sizes.
Project classes
Uses sampling and shows histogram of live objects of project
classes allocated on the heap, including instance numbers and
sizes.
Selected classes
Uses bytecode instrumentation and shows allocated or live
instances of the defined classes including allocations stack traces
if configured. To use this mode, at least one class has to be
selected for profiling.
9-40 NetBeans Developing Applications with NetBeans IDE
Profiling Objects
9.19.2.2 Selecting Classes For Profiling
Selected classes instruct the profiler to track instances of these classes only, keeping the
profiling overhead low. You can select a class or method for instrumented profiling by
either:
■
■
■
■
Using the Select Class dialog. The dialog allows to select one or several classes
from a project or .class/.jar file. It can be open directly from the Objects Settings
pane.
From the code editor. Java code editor provides Profile > Profile Class action in its
context menu.
From Navigator. Java Navigator provides Profile > Profile Class action in its
context menu.
From profiling results. Live or saved Objects results provide Profile Class actions
in its context menu. Also a special column Selected is available to select classes for
profiling. The column can be displayed using the right corner button in the view
header by clicking the drop-down arrow (or right-clicking the header on Mac OS
X).
9.19.2.3 Configuring Additional Options
Based on the additional settings, the profiler can track either all allocated objects or
just the objects currently live on the heap. It can also record allocation stack traces to
visualize from where in the source code are the objects being created. The following
options are available:
■
■
Track only live objects controls whether the profiler tracks all allocated objects
from the beginning of the profiling session or last results reset (deselected) or
whether the profiler tracks just the objects currently live in the heap memory
(selected). When tracking only live objects, the profiler also provides a special
metric Surviving Generations which helps to easily discover certain types of
memory leaks.
Limit allocations depth controls whether the profiler collects allocation stack traces
and sets the depth limit for the stacks. If deselected, the profiler collects full
allocation stack traces. If selected, the value controls the maximum depth of
allocation stacks. Zero value means no allocation stack traces are being collected.
The Objects profiling mode, selected Classes and additional options can be changed at
any time during a running profiling session. The changes are applied by clicking the
Apply button on the right side of the settings area.
9.19.2.4 Objects Views
In case the Track only live objects option is not selected, the following data columns
are available:
■
■
■
Name column shows name of the class with allocated instances.
Allocated Bytes column shows the size of all allocated objects from the beginning
of the profiling session or last results reset.
Allocated Objects column shows the number of all allocated objects from the
beginning of the profiling session or last results reset.
In case the Track only live objects option is selected, the following data columns are
available:
■
Name column shows name of the class with live instances.
Testing and Profiling Java Application Projects
9-41
Profiling Threads
■
■
■
■
■
Live Bytes column shows the size of all instances of the class currently live on
heap.
Live Objects column shows the number of all instances of the class currently live
on heap.
Allocated Objects column shows the number of all allocated objects from the
beginning of the profiling session or last results reset.
Avg. Age average object age of all instances of the class currently live on heap
measured by the number of survived garbage collections.
Surviving Generations column shows the number of different generations
measured by the number of survived garbage collections.
To provide more control of which methods are to be profiled
there is a special mode with fully manual setup of profiled classes and
instrumentation filter.
Note:
9.19.2.5 Expert Mode of Objects Profiling
Bytecode instrumentation is a powerful tool to analyze Java applications performance
and memory management. However, the profiling overhead and amount of collected
data is heavily dependent on the profiler configuration. Misconfigured settings may
cause extreme slowdown of the profiled process or OutOfMemoryErrors being thrown
by the NetBeans JVM due to too many data.
By default the profiler offers just a limited subset of customizable options for an
instrumented profiling session to prevent the above mentioned problems. While this
makes the instrumenting profiler a safe choice for most of the users, it doesn't provide
the full power of the profiler engine to expert users. That's why there's a special mode
Defined classes which allows detailed definition of the classes to be instrumented.
The expert mode needs to be enabled using Tools > Options > Java > Profiler >
General > Enable manual setup for Methods and Objects. The currently opened
profiler window needs to be closed and reopened after changing this option to enable
the expert mode. The mode can be set by opening the Settings pane by the rightmost
Settings button in the profiler window toolbar and selecting Defined classes.
For more information about defined classes mode of the objects profiling in NetBeans
IDE, see http://wiki.netbeans.org/ProfilerExpertFeatures.
9.20 Profiling Threads
The threads mode allows you to view detailed information about application thread
activity.
Figure 9–4 shows a snapshot of a threads session.
9-42 NetBeans Developing Applications with NetBeans IDE
Profiling Locks
Figure 9–4 Threads Session
To start a profiling threads session, see Section 9.9, "Starting a Profiling Session".
For the description of the toolbar buttons see Section 9.9.3, "Understanding the Toolbar
Icons".
Additionally, you may customize the threads you monitor by accessing the Live
Threads drop-down list and choosing from the available options: All Threads, Live
Threads (Default), Finished Threads, and Selected Threads.
For more information on profiling Threads in NetBeans IDE, see
http://wiki.netbeans.org/ProfilerThreads.
9.21 Profiling Locks
The locks mode allows you to view details about locked threads and the threads that
are monitoring and holding locks.
Figure 9–5 shows a snapshot of a locks session.
Testing and Profiling Java Application Projects
9-43
SQL Queries Profiling
Figure 9–5 Locks Session
The Locks view displays threads and locks of the profiled process and their relation
(thread T has been blocked by lock L owned by another thread X) and information
about time spent by waiting and number of waits to acquire a lock.
To start a profiling lock session, see Section 9.9, "Starting a Profiling Session".
For the description of the toolbar buttons see Section 9.9.3, "Understanding the Toolbar
Icons".
In the session window you can choose Threads or Monitors in the Threads
drop-down list. Choose Threads to view locked threads. Expand the nodes to view the
owners of the locks. Choose Monitors to view the threads that are locking other
threads.
For more information on profiling locks in NetBeans IDE, see
http://wiki.netbeans.org/ProfilerLocks.
9.22 SQL Queries Profiling
SQL queries profiling enables profiling calls from Java processes to databases using a
JDBC connection. It allows you to analyze which queries have been invoked, how
many times they have been initiated, and how long they took to run. SQL queries
profiling helps you to see which SQL query causes the most contention within an
application.
Table 9–6 shows a snapshot of a SQL Query session.
9-44 NetBeans Developing Applications with NetBeans IDE
SQL Queries Profiling
Figure 9–6 SQL Query Session
The SQL Query view displays a live list of executed SQL queries with their duration
and execution counts, including the invocation paths. You can sort the content of each
column by clicking a column heading and reorder columns by dragging and droping
column headings.
To start a profiling lock session, see Section 9.9, "Starting a Profiling Session".
For the description of the toolbar buttons see Section 9.9.3, "Understanding the Toolbar
Icons".
In the SQL Query session window you can perform the following actions:
■
View SQL Query. Displays the text of a query in the SQL Query Viewer window.
■
Copy Row. Copies the content of the row to the clipboard.
■
Copy SQL Query. Copies the content of the query to the clipboard.
■
Copy Total Time. Copies the total time of the query execution to the clipboard.
■
Copy Invocations. Copies the number of the selected query invocations to the
clipboard.
■
Copy Statement Type. Copies the type of a SQL query to the clipboard.
■
Copy Command Type. Copies the type of a SQL command to the clipboard.
■
Copy Tables. Copies the name of a database table to the clipboard.
■
Find. Searches for the specified query content.
To switch between different profiling modes:
1. Click the Settings button in the toolbar.
2.
Select the required option in the Profile drop-down list.
3.
If the Defined queries option is selected, specify the text that the query must
contain.
4.
Click Apply.
Testing and Profiling Java Application Projects
9-45
Additional Functions when Running a Profiling Session
To filter the collected queries in live results or snapshots:
1. Specify the filtering options - Statements, Commands, Tables - below the live
results area.
2.
Click Apply.
To visually filter out profiling results by coloring:
1. Choose Tools > Options from the main menu.
2.
In the Options dialog box, select Java > Profiler.
3.
In the Filters category, select the Use defined filters for coloring results option
and click the Add new filter button.
4.
In the Add Filter dialog window, specify the name and value of the new filter.
5.
(Optional) Select the Color checkbox to define custom color for your filter results.
6.
Click OK.
To display a hidden column:
1. Click the pointing down triangle icon to the right of the table.
2.
Select the name of the column to be displayed in the displayed menu.
9.23 Additional Functions when Running a Profiling Session
While the profiler session is in progress, additional actions related to the actual profiler
mode are available in the toolbar of the profiler window. The following actions are
always available:
Thread dump — creates a textual dump of all active threads and monitors of the
profiled application. It shows what methods have been executed at the point of
capturing the dump, thread by thread. This information is useful to view what the
application is currently doing. The thread dump also contains information about locks,
threads holding the locks, and threads waiting to acquire a lock. This data is essential
when debugging deadlocks. To capture a Thread Dump, click the Thread Dump icon
during the profiling session. To learn more about taking snapshots, see Appendix 9.14.
Heap dump — saves an image of the current heap content of the profiled process in
.hprof format and optionally opens it in heap browser. For more information, see
Capturing Heap Dump Data.
GC — requests the JVM of the profiled process to invoke garbage collection. The JVM
behavior for garbage collection is not defined in the JVM specification. It should do the
garbage collection at some point, but there is no guarantee it will do it immediately or
at all.
Additionally, when profiling Methods or Objects, the following actions are available:
Snapshot — creates a snapshot of all currently collected profiling data related to
methods or objects. The snapshot opens in a separate window and can be saved to the
project or to an external file. For more information, see Taking and Accessing
Snapshots of Profiling Data.
Reset collected results — clears all currently collected profiling data related to
methods or objects.
The other actions displayed in the toolbar of the profiler window are specific to the
actual profiling mode. If multiple profiling modes are active in a profiling session, the
toolbar displays actions available for the currently displayed modes.
9-46 NetBeans Developing Applications with NetBeans IDE
10
Running and Debugging Java Application
Projects
10
[1This
]
chapter describes how you can use the running and debugging features in
NetBeans to create and perfect your projects.
This chapter contains the following sections:
■
About Running Java Application Projects
■
Working with Project Execution
■
Running an Application
■
Running a Single File
■
Setting the Runtime Classpath
■
Setting the Main Class and Runtime Arguments
■
Setting JVM Arguments
■
Debugging Applications
■
Using the Debugger Windows
10.1 About Running Java Application Projects
As you are developing your application, you can run the application in the IDE to test
the application's behavior. When you run a project in the IDE, the IDE runs the
application from the files in the project's build/classes folder.
Typically, the project that contains the program's main class is set as the main project.
You can then run the entire application with the Run Main Project command (F6). You
can also run any executable class by choosing Run > Run File > Run my_class
(Shift+F6). Alternatively, you can run any project that has a main class by
right-clicking its project node in the Projects window and choosing Run Project.
When you run the project the IDE displays any compilation errors and output in the
Output window.
Running and Debugging Java Application Projects 10-1
Working with Project Execution
If Compile on Save is enabled for a project, the Run Project
command operates on class files that have been created when you
have saved those files. The Ant build script is not used. If you have
defined custom steps in the build script, those steps are not followed.
If you would like the full build process to occur when you use Run
Project, Debug Project, and Profile Project, disable Compile on Save.
The Compile on Save feature can be toggled from the Run category in
the Project Properties window.
Note:
10.1.1 Running Standard Projects
For standard projects, the IDE uses settings that you specify in project's Project
Properties dialog box. You can set the project's main class, runtime arguments, VM
arguments, and working directory.
To run the application outside of the IDE, you must first use the Clean and Build
command so that the project's JAR file is built or updated. For standard projects that
have a main class specified, the IDE automatically copies any JAR files on the project's
classpath to the dist/lib folder. The IDE also adds each of the JAR files to the
Class-Path element in the application JAR's manifest.mf file. This simplifies running
the application outside the IDE. For more information, see Section 8.9, "Preparing a
JAR File for Deployment Outside the IDE."
10.1.2 Running Free-form Projects
For free-form projects, the IDE uses an existing Ant script to run your class. You can
write a target that executes the currently selected file in the IDE and map it to the Run
File command.
10.2 Working with Project Execution
Once you have created and built your project, you must perform the following
operations to configure the run process for your project:
■
Set your project as the main project in the IDE.
■
Set the project’s main class.
■
■
Modify the runtime classpath, as needed, to include any special libraries, project
dependencies, or specific JAR files.
Specify any runtime and Java VM arguments the project requires.
When you have the runtime configurations set, you can either run individual project
files or run the entire the project. Each of these operations is discussed in more detail
in the following sections.
10.3 Running an Application
With standard projects, you typically have one project that contains the application
main class and several projects containing class libraries. You can run the project or
run any individual project that contains an executable class. For information on setting
the main class, see Section 10.6, "Setting the Main Class and Runtime Arguments."
To run a project:
1. Select the project that you want to run in the Projects window.
10-2 NetBeans Developing Applications with NetBeans IDE
Running a Single File
2.
Choose Run > Run Project (F6).
When running an application, be aware of the following considerations:
■
■
■
■
If you have the Compile on Save option selected in the Compiling section of the
Project Properties window, the project is run directly from the build/classes
directory of your project. If Compile on Save is not selected, the project is run
using the project's build script.
If you run a project for which you have not specified a main class, the IDE
prompts you for the main class. You can change this setting in the Run panel of the
project's Project Properties dialog box. Each project can contain only one main
class. For information on setting the classpath, see Section 10.5, "Setting the
Runtime Classpath."
If you are running a project often, you can set a project as the main project by
choosing Run > Set Main Project from the main menu and selecting the project in
the submenu or by right-clicking the project node in the Projects window and
choosing Set as Main Project.
You can select multiple projects in the Projects window and run them at once by
choosing Run > Run (number of selected projects) Projects (F6) from the main IDE's
menu.
10.4 Running a Single File
You might have a file in your project that you want to test before running the entire
project. You can run a single file in the IDE and see any warning or error messages that
might occur during the run in the Output window.
To run a single file:
1. Select the file in the Source Editor or Projects window.
2.
Choose Run > Run File > Run my_class.
The IDE initiates execution of the selected file.
Note: In free-form projects, this command is disabled by default. To
enable this function, you have to write an Ant target for running the
file in the IDE and map it to the IDE's Run Class command. This
command is not available for EJB projects.
10.4.1 Writing a Target to Run/Debug/Test a Single File
The IDE does not generate targets for the Run File, Debug File, Test File, and Debug
Test for File commands, but you can create your own targets and map them to the
following predefined actions:
■
run.single - Run selected file
■
debug.single - Debug selected file
■
test.single - Run the JUnit test for selected file
■
debug.test.single - Debug the JUnit test for selected file
Each of these actions contains a context element that gets a reference to the currently
selected files and stores it in a property of your choice. You use this property in your
Ant targets to specify which files to process.
Running and Debugging Java Application Projects 10-3
Running a Single File
10.4.1.1 Running the Selected File
Let's demonstrate how this works when you run a class. A typical target for running a
project looks something like the following:
<target name="run2" depends="...">
<java fork="true" classname="MyMainClass" classpath="MyRunClasspath" />
</target>
The target runs the file specified by classname. To run the currently selected file in the
IDE, you need to modify the above target to something like the following:
<target name="run-selected-file" depends="compile" description="Run Single File">
<fail unless="runclass">Must set property 'classname'</fail>
<java classname="${runclass}">
<classpath refid="run.classpath"/>
</java>
</target>
10.4.1.2 Getting a Reference to the Currently Selected File in the IDE
Once you have an Ant target for running the selected file, you have to get a reference
to that file in the IDE and store it in a property. For example, the run-selected-file
target above looks for the currently selected file in the runclass property.
You store this reference in the same place where you map the build target
(run-selected-file) to the IDE action. First we will look at how to do this and then
we will explain it in detail:
<action name="run.single">
<target>run-single</target>
<context>
<property>runclass</property>
<folder>${src.dir}</folder>
<pattern>\.java$</pattern>
<format>java-name</format>
<arity>
<one-file-only/>
</arity>
</context>
</action>
The runclass property is a newly defined property that holds the file that you want to
run and is referenced by the java task.
Now let's take a look at the following lines to see how it works.
<action name="run.single">
<target>run-selected-file</target>
<context>
<property>runclass</property>
■
■
■
■
<action name="run.single"> maps the Run File command and the F9 shortcut to
the run-selected-file target.
<context> sets the context on which the Ant target is executed. In this case, it is
the name of file that you want to run.
runclass is the name of the property that holds the context. You can choose any
unique name for this property. This property must be set by the IDE before the
target can be run.
<arity> specifies that runclass can hold only one file. If you want the property to
be able to hold more than one file (such as for the Compile File target), you can use
the following, where the comma (,) is the separator between file names:
<arity>
10-4 NetBeans Developing Applications with NetBeans IDE
Running a Single File
<separated-files>,</separated-files>
</arity>
■
■
<format>java-name</format> specifies that the IDE should pass the relative file
name to the target but delimited by periods (.) and without an extension. Other
formatting options include the following:
–
relative-path - specifies that the IDE should pass the relative file name to the
target
–
relative-path-noext - Same as relative-path, but the file's extension is
removed
–
absolute-path - Absolute file name
–
absolute-path-noext - Same as absolute-path, but the file's extension is
removed
<folder>${src.dir}</folder> specifies that the file name should be relative to
the src.dir directory and that this action is only enabled for the src.dir
directory.
The IDE does not define the ${src.dir} property for you. You
have to define the property or import the .properties file that the
Ant is using in project.xml. See Using Properties in the project.xml
File for more information.
Note:
■
<pattern>\.java$</pattern> is the regular expression which the file names must
pass. You use <pattern> to limit which files can be passed to the Ant target. In this
case, you want the target be executed only with files that end in .java.
10.4.1.3 Debugging the Selected File
The process is basically the same for writing targets to debug and run a single file. The
debug-selected-files target looks something like this:
<target name="debug-selected-files" depends="compile" if="netbeans.home"
description="Debug a Single File">
<fail unless="classname">Must set property 'classname'</fail>
<nbjpdastart name="${classname}" addressproperty="jpda.address"
transport="dt_socket">
<classpath refid="run.classpath"/>
<!-- Optional - If source roots are properly declared in project, should
work without setting source path.
<sourcepath refid="debug.sourcepath"/> -->
</nbjpdastart>
<java classname="${classname}" fork="true">
<jvmarg value="-Xdebug"/>
<jvmarg value="-Xnoagent"/>
<jvmarg value="-Djava.compiler=none"/>
<jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
<classpath refid="run.classpath"/>
</java>
</target>
■
This is basically the same as the debug target. Instead of passing the program main
class to java, you pass the classname property, which is set by the IDE to the
currently selected file.
Then you map the debug-selected-files target to the debug.single action:
<action name="debug.single">
Running and Debugging Java Application Projects 10-5
Setting the Runtime Classpath
<target>debug-selected-files</target>
<context>
<property>classname</property>
<folder>${src.dir}</folder>
<pattern>\.java$</pattern>
<format>java-name</format>
<arity>
<one-file-only/>
</arity>
</context>
</action>
■
<property> now stores the context in the classname property.
■
Since java can only take single file, you set <arity> to <one-file-only>.
■
Setting <format> to java-name and making it relative to src.dir creates a
fully-qualified class name for the currently selected file.
The IDE does not define the ${src.dir} property for you. You
have to define the property or import the .properties file that the Ant
is using in project.xml. See Section 6.2.4.9.1, "Using Properties in the
project.xml File" for more information.
Note:
10.5 Setting the Runtime Classpath
By default, the runtime classpath of each standard project contains the project's
compiled classes and everything in the project's compilation classpath. For
information on viewing the compilation classpath, see Section 6.2.3.1, "Managing the
Classpath."
If your project uses special libraries dynamically at runtime through an indirect
interface or reflection (like JDBC drivers or JAXP implementations), you have to add
these libraries to the runtime classpath.
For standard projects that have a main class is specified, the
IDE automatically copies any JAR files on the project's classpath to the
dist/lib folder. The IDE also adds each of the JAR files to the
Class-Path element in the application JAR's manifest.mf file. This
simplifies running the application outside the IDE. For more
information, see Section 8.9, "Preparing a JAR File for Deployment
Outside the IDE."
Note:
You also have to adjust your runtime classpath if the runtime dependencies between
your projects do not match the compilation dependencies between the projects. For
example, imagine that project A compiles against project B, and project B compiles
against project C, but project A does not compile against project C. This means that
project A only has project B on its runtime classpath. If project A requires both project
B and project C during execution, you have to add project C to project A's runtime
classpath.
To set the runtime classpath:
1. Right-click the project node in the Projects window and choose Properties.
2.
In the Project Properties dialog box, select the Libraries node in the Categories
pane.
10-6 NetBeans Developing Applications with NetBeans IDE
Setting the Main Class and Runtime Arguments
3.
Select the Run tab in the dialog's right pane.
4.
Add the necessary elements to the project's runtime classpath by clicking the
appropriate button. You can add any of the following:
■
5.
Project. The build output, source files, and Javadoc files of another IDE
project. Adding a project to the classpath makes it dependent on the present
project. Whenever you clean or build the project, all of its dependent projects
are also cleaned or built.
■
Library. A collection of binary files, source files, and Javadoc files.
■
JAR/Folder. A JAR file or folder somewhere on your system.
(Optional) Click Move Up and Move Down to alter to the classpath priority.
In free-form projects, your Ant script handles the classpath for
all of your source folders. The classpath settings for free-form projects
only tell the IDE what classes to make available for code completion
and refactoring. For more information, see Section 6.2.4.5, "Declaring
the Classpath in a Free-Form Project."
Note:
10.6 Setting the Main Class and Runtime Arguments
By default, the IDE specifies neither a main class nor runtime arguments. The runtime
classpath of each standard project contains the project's compiled classes and
everything in the project's compilation classpath.
Indicate which class in your project is the entry point for the application by setting a
main class.
To set the main class and runtime arguments:
1. Right-click the project node in the Projects window and choose Project Properties.
2.
Select the Run node in the Categories pane of the dialog box.
3.
Type the fully qualified name of the main class in the Main Class field (for
example, org.myCompany.myLib.MyLibClass). The main class must exist in the
project or in one of the JAR files or libraries on the project's runtime classpath.
If you use the Browse button to choose the project main class,
the file chooser only displays classes in your project source directory.
If you want to specify a class in one the libraries on the classpath, you
have to type the fully-qualified name of the class in the Main Class
field.
Note:
4.
Enter any runtime arguments you require in the Arguments field.
The IDE sets the project's main class and stores any newly-added arguments.
Running and Debugging Java Application Projects 10-7
Setting JVM Arguments
For standard projects that have a main class is specified, the
IDE automatically copies any JAR files on the project's classpath to the
dist/lib folder. The IDE also adds each of the JAR files to the
Class-Path element in the application JAR's manifest.mf file. This
simplifies running the application outside the IDE. For more
information, see Section 8.9, "Preparing a JAR File for Deployment
Outside the IDE."
Note:
If you use the Browse button to choose the project main class, the file chooser only
shows classes in your project source directory. If you want to specify a class in one the
libraries on the classpath, you have to type the fully-qualified name of the class in the
Main Class field.
To change project runtime options:
1. Right-click the project node in the Projects window and choose Properties.
2.
In the Project Properties dialog box, select the Libraries node in the Categories
pane.
3.
Click the Run tab in the right pane of the dialog box.
To access settings for the main class, program arguments, the
working directory for program execution and VM options, you have
to select the Run node.
Note:
10.7 Setting JVM Arguments
JVM arguments and system properties can be set through the project’s properties file
through the IDE.
To set JVM arguments:
1. Right-click the project node in the Projects window and choose Project Properties.
2.
Select the Run node in the Categories pane of the dialog box.
3.
Type a space-separated list of JVM arguments in the VM Options field.
To set system properties:
■
Specify the system property and its value in the VM Options field:
-Dname=value
10.8 Debugging Applications
Debugging is the process of examining your application for errors. The process of
debugging is accomplished by setting breakpoints and watches in your code and
running it in the debugger. This enables you to execute your code one line at a time
and examine the state of your application to discover any problems.
When you start a debugging session the Debugging window opens in the left pane of
the IDE. Additional debugger windows also appear automatically at the bottom of
your screen.
You can also debug applications that are running on a remote machine by attaching
the debugger to the application process.
10-8 NetBeans Developing Applications with NetBeans IDE
Debugging Applications
You can customize the Java debugger by choosing Tools > Options and clicking the
Java Debugger tab. From this tab you can perform the following:
■
set custom breakpoint commands
■
set step filters to specify language constructs that are filtered while stepping
■
create and edit variable formatters
■
modify options for the Visual Debugger
10.8.1 Debugging Free-form Projects
Similar to commands for compiling and running, debugging commands rely on
various information, such as the location of your sources, the location of the compiled
classes and other items on the classpath, and name of the project's main class (for more
information, see Section 10.5, "Setting the Runtime Classpath").
In free-form projects, the IDE does not "know" about any of these things. When you
run a command in the IDE (such as Build), the IDE simply calls a target in your build
script and lets the script handle the command. Therefore, for debugging to work, you
also have to have a build script target for debugging. The IDE provides some custom
Ant tasks to work with the debugger and also can generate a basic debug target, which
attempts to fill in important details based on other targets in your script.
To set up debugging in a free-form project:
■
Make sure that your classes are compiled with debugging information included.
For example, you might accomplish this in the compile target of your build script
by including the argument debug="true" in the <javac> task.
■
■
■
Set the output of the free-form project. If the output of a free-form project is on the
classpath of another project, map the free-form project's source packages to their
outputs. This ensures that you can use the debugger to step into the project's
sources when you start a debugging session in a project that has a dependency on
the free-form project. To declare the output files, right-click the free-form project
node and choose Properties. Then click the Output category in the Properties
window and specify the output file for each source folder.
Confirm that the target JDK is set in your Ant script and the source level is
specified in the Project Properties dialog box. When you step into JDK classes, the
IDE searches the platforms registered in the Java Platform Manager for a Java
platform with a matching source level. If no matching Java platform is found, the
IDE opens the source code for the IDE's default platform.
Create a target in your build script for debugging and map that target to the IDE's
Debug Project command. The IDE can assist you by generating a basic target and
mapping, but you might have to modify the target. For more information, see
Section 10.8.1.1, "How to Create a Debug Target for a Free-form Java Project."
For information on mapping an Ant target to a debugging command, see
Section 6.2.4.6, "Mapping an Ant Target to an IDE Command."
10.8.1.1 How to Create a Debug Target for a Free-form Java Project
To run a free-form project in the IDE's debugger, you have to have a special target in
your project's build script. That target needs to be mapped to the IDE's Debug Project
command.
Running and Debugging Java Application Projects 10-9
Debugging Applications
If you do not have a debug target written for your project, the IDE offers to generate a
basic target for you when you first try to debug the project. You can then inspect the
target and customize it for the project's specific requirements.
When the IDE generates a debug target, it looks for
information in the target you have mapped to the Run Project
command to determine such things such as the run classpath and the
project's main class. If you have a target mapped to the Run Project
command, there is a good chance that the generated debug target
works without further customization.
Note:
To create a debug target for a free-form project:
1. Set the free-form project as the main project by choosing Run > Set Main Project
in the main menu and selecting the project.
2.
Choose Debug > Debug Main Project from the main menu.
3.
Click Generate in the Debug Project dialog box.
When you click Generate, a target named debug-nb is created in a file named
ide-targets.xml. The generated ide-targets.xml file is a build script that
imports your main build.xml file, so your debug target can take advantage of
targets and properties set by or referenced by your main build script.
In addition, a mapping for this target is created in the project.xml file so that the
target is called whenever you choose the Debug Project command in the IDE. If
you write the target from scratch, you must also create this mapping yourself. For
more information, see Section 10.8.1.1.2, "Manually Mapping a Target to a Menu
Item."
4.
Verify that the generated debug-nb target properly takes into account all of the
elements of your project.
In particular, you might have to modify the <classpath> argument in the target if
it does not include all of the items in your run classpath.
After the target is created, you can begin debugging the project.
To debug the project:
1. Set a breakpoint in your main class by clicking in the left margin of the line where
you want to set the breakpoint.
The line with the breakpoint is highlighted in pink.
2.
Right-click the project's node again and choose Debug Project.
The target should run and start execution of the program. Progress of the running
target is shown in the Output window and the status of the debugger is shown in
the status bar at the bottom of the Output window.
10.8.1.1.1 A Typical Free-form Project Debug Target The generated Ant target does the
following:
■
■
Starts the debugger with the nbjpdastart task.
Stores the address at which the debugger listens for the application in the
jpda.address property (addressproperty="jpda.address"). You do not have to
define the jpda.address property in your Ant script or properties file. It is defined
by the IDE.
10-10 NetBeans Developing Applications with NetBeans IDE
Debugging Applications
■
■
Establishes the runtime classpath. If the IDE is not able to determine your runtime
classpath, placeholders are put in the script, which you must fill in yourself.
Runs the application in debug mode, passing the jpda.address property as the
address at which to connect to the debugger. Setting fork="true" ensures the
process is launched in a separate virtual machine.
You can add any additional JVM arguments or program
arguments in the java task as well.
Note:
For example, if the IDE is able to guess the runtime classpath, the debug-nb target that
the IDE generates in ide-targets.xml might look similar to Example 10–1:
Example 10–1
Defining a Free-form Debug Target
<?xml version="1.0" encoding="UTF-8"?>
<project basedir=".." name="YourProjectName">
<import file="../build.xml"/>
<!-- TODO: edit the following target according to your needs -->
<!-- (more info: http://www.netbeans.org/kb/articles/freeform-config.html#debugj2se) -->
<target name="debug-nb" depends="init,compile">
<nbjpdastart addressproperty="jpda.address" name="NameOfProject" transport="dt_socket">
<classpath path="ClasspathSpecifiedInYourRunTarget"/>
</nbjpdastart>
<java classname="MainClassSpecifiedInRunTarget"
classpath="ClasspathSpecifiedInYourRunTarget" fork="true">
<jvmarg value="-Xdebug"/>
<jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
</java>
</target>
</project>
If you do not have a run target mapped or the IDE otherwise cannot determine the
project's classpath or main class, the generated debug target includes "TODO"
placeholders for you to fill in these values as shown in Example 10–2.
Example 10–2
Generated debug target with “TODO” placeholders
<?xml version="1.0" encoding="UTF-8"?>
<project basedir=".." name="YourProjectName">
<!-- TODO: edit the following target according to your needs -->
<!-- (more info: https://netbeans.org/kb/articles/freeform-config.html) -->
<target name="debug-nb">
<path id="cp">
<!-- TODO configure the runtime classpath for your project here: -->
</path>
<nbjpdastart addressproperty="jpda.address" name="NameOfProject" transport="dt_socket">
<classpath refid="cp"/>
</nbjpdastart>
<!-- TODO configure the main class for your project here: -->
<java classname="some.main.Class" fork="true">
<classpath refid="cp"/>
<jvmarg value="-Xdebug"/>
<jvmarg value="-Xnoagent"/>
<jvmarg value="-Djava.compiler=none"/>
<jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
</java>
</target>
Running and Debugging Java Application Projects 10-11
Debugging Applications
</project>
To specify the runtime classpath, insert pathelement elements within the path element
and point them to the directories that contain the items in your classpath. For example,
you can use the location attribute of pathelement to specify the location of the
classpath items relative to your project directory as shown in Example 10–3. The
project directory is usually the one that contains the project's build.xml file.
Example 10–3
Specifying location of classpath items relative to a project directory
<path id="cp">
<pathelement location="libs">
<pathelement location="build">
</path>
10.8.1.1.2 Manually Mapping a Target to a Menu Item When you have the IDE generate a
target, the IDE automatically provides the mapping between the target and the IDE
command's menu item. However, if you have created the target manually, you must
also create the mapping manually.
To map the Debug Project command to a target in an external Ant script:
1. Open the project's project.xml file and add the following to ide-actions:
<action name="debug">
<script>path_to_Ant_script</script>
<target>target_name</target>
</action>
2.
Add the command to the project node's context menu, by adding the following
line to the <context-menu> target:
<ide-action name="debug"/>
The IDE maps the Debug Project action to the specified target in the project's Ant
script. For information on how to map a target to a debugging command, see
Section 6.2.4.6, "Mapping an Ant Target to an IDE Command."
10.8.1.1.3 Troubleshooting If you have successfully created a debug target and started
the debugger, but the debugger does not stop at breakpoints, the IDE is probably
lacking debugging information or knowledge of where your sources are. For more
information, see Section 10.8.1, "Debugging Free-form Projects."
10.8.1.2 How to Create a Debug Target for a Free-form Web Project
In a free-form project, you must set up your own Ant target to run a project in the
debugger. However, you can use the IDE to generate a debug target for you. When you
do so, the IDE maps the debug target to the Debug Project command. Alternatively, if
you have your own debug target, you must map it to the Debug Project command
yourself.
To generate a debug target:
1. Set the project as the main project and choose Debug > Debug Main Project
(Ctrl+F5) from the main menu or right-click the project in the Projects window and
choose Debug.
If no target is mapped to the Debug Project command, you are prompted to let the
IDE generate an IDE-specific debug target in nbproject/ide-targets.xml.
2.
Click Generate.
10-12 NetBeans Developing Applications with NetBeans IDE
Debugging Applications
The IDE does the following:
■
Generates a target named debug-nb. The target is generated in the new
nbproject/ide-targets.xml file, together with other targets that support it,
such as the -load-props, -check-props, -init, and debug-display-browser
targets. These targets do the following:
–
Checks whether Ant is running inside the IDE (if="netbeans.home").
–
Starts the debugger with the nbjpdaconnect task.
–
Connects the debugger to the application to be debugged at the specified
host (jpda.host) and port number (jpda.address).
–
Opens the IDE's web browser at the URL specified by the client.url
property.
These targets are not generated in the IDE. Therefore, you
need to change the generated code so that it looks as follows:
Note:
<target name="-load-props">
<property file="nbproject/project.properties"/>
</target>
<target name="-check-props">
<fail unless="session.name"/>
<fail unless="jpda.host"/>
<fail unless="jpda.address"/>
<fail unless="jpda.transport"/>
<fail unless="web.docbase.dir"/>
<fail unless="debug.sourcepath"/>
<fail unless="client.url"/>
</target>
<target depends="-load-props, -check-props" name="-init"/>
<target depends="-init" name="debug-nb" description="Debug
Project">
<nbjpdaconnect address="${jpda.address}" host="${jpda.host}"
name="${session.name}" transport="${jpda.transport}">
<sourcepath>
<path path="${debug.sourcepath}"/>
</sourcepath>
</nbjpdaconnect>
<antcall target="debug-display-browser"/>
</target>
<target name="debug-display-browser">
<nbbrowse url="${client.url}"/>
</target>
There's no need for you to customize the generated targets. All you
have to do is set the properties that the IDE requires to use the targets
it generated. For example, you need to tell the IDE where your
application's sources are. To do this, you will set properties in the
nbproject/debug.properties file that the IDE created for you when it
generated the debug-nb target above. Using the -load-props target
above, the IDE will load the properties when you run the debug-nb
target.
Running and Debugging Java Application Projects 10-13
Debugging Applications
■
■
3.
Example 10–4
Generates and defines debug properties. The properties are defined in the new
nbproject/debug.properties file. The properties define the following:
–
The sources that are to be debugged.
–
The server to which the application to be debugged is to be deployed.
–
The port number and address to be used.
–
The client URL.
Maps the debug-nb target to the Debug Project command.
In the Files window, go to the nbproject/debug.properties file and edit the
debug properties as shown in Example 10–3, if necessary.
Adding properties to a new debug.properties file
jpda.session.name=MyProject
jpda.host=localhost
# Sun Java System Application Server using shared memory (on Windows)
# jpda.address=localhost4848
# jpda.transport=dt_shmem
# Sun Java System Application Server using a socket
# jpda.address=9009
# jpda.transport=dt_socket
# Tomcat using shared memory (on Windows)
jpda.address=tomcat_shared_memory_id
jpda.transport=dt_shmem
# Tomcat using a socket
#jpda.address=11555
#jpda.transport=dt_socket
src.folders=src
web.docbase.dir=web
# you can change this property to a list of your source folders
debug.sourcepath=${src.folders}:${web.docbase.dir}
# Client URL for Tomcat
client.url=http://localhost:8084/MyProject
# Client URL for Sun Java System Application Server
# client.url=http://localhost:8080
Property
Value
Notes
jpda.session.name
The display name given in the
Sessions window when you debug
the project.
jpda.host
The host that the application to be
debugged uses to connect to the
debugger, such as localhost.
10-14 NetBeans Developing Applications with NetBeans IDE
Debugging Applications
Property
Value
Notes
jpda.address
The bundled Tomcat Web
Server defaults are 11555 for
socket connections and
tomcat_shared_memory_id for
shared memory connections.
To set a different address, right-click
the Tomcat node in the Services
window and choose Properties. In
the Properties sheet, change the
Debugging Port property (for socket
connections) or Name property (for
shared memory connections). Then
close the Properties sheet. Now stop
and restart the Tomcat Web Server, if
you had already started it.
jpda.transport
dt_socket (for socket
connections) or shmem (for
shared memory connections).
To set a different transport,
right-click the Tomcat node in the
Services window and choose
Properties. In the Properties sheet,
change the Debugging Type. Then
close the Properties sheet. Now stop
and restart the Tomcat Web Server, if
you had already started it.
web.docbase.dir
The location of your web root
(web.docbase.dir) and Java
source files (src.folders).
Multiple source roots can be included
in the sourcepath by means of the ":"
delimiter. Note that the Java source
folders must be specified as Source
Package Folders in the Java Sources
panel of the Project Properties dialog
box. (Right click the project, choose
Properties, then click Java Sources in
the Project Properties dialog box.)
src.folders
client.url
The URL that should be opened in
the IDE's default browser, such as
http://localhost:8084/MyProject.
If you use the IDE to generate the debug target, as described in the previous section,
the target is automatically mapped to the Debug Project command. However, if your
debug target was not generated by the IDE, you must map it to the Debug Project
command manually.
To map a debug target to the Debug Project command:
1. In the Projects window, right-click the project node and choose Properties.
2.
Click Build and Run in the left panel of the Project Properties dialog box.
3.
Click Add, select your debug target, and type a label, such as "Debug Project."
If you want to map the debug action to a target in a separate Ant script, open the
project's project.xml file and add the following to <ide-actions>:
<action name="debug">
<script>path_to_Ant_script</script>
<target>name_of_target</target>
</action>
To add the command to the project node's contextual menu, add the following to
<context-menu>:
<ide-action name="debug"/>
10.8.1.2.1 Using the Debug Target Before you can use your debug target, you need to
deploy your application. Therefore, start the server and run deploy the application.
Running and Debugging Java Application Projects 10-15
Debugging Applications
Note that the first time that you run the application per session, the Tomcat Web
Server asks you for a username and password. The only acceptable username and
password is that of a user with a "manager" role. This is defined in the
conf/tomcat-users.xml file in the Tomcat Web Server's base directory. To identify the
location of this directory, right-click the Tomcat Web Server instance node in the
Services window and select Properties. In the Properties dialog box, the Base Directory
property points to the Tomcat Web Server's base directory.
Once the application is deployed, stop the server and restart it in debug mode. The
way this is done depends on the server:
■
Bundled Tomcat Web Server
Expand the Servers node in the Services window, right-click the Bundled Tomcat
node, choose Start/Stop Server, and click Start Server (Debug).
■
External Tomcat Web Server
Run the catalina jpda start command.
Once the server has started in debug mode, choose Run > Debug Main Project. The
application is deployed and is attached to the debugger. The debugger stops at the first
breakpoint, after which you can Step into or Step over the code.
To use a debug target in a free-form web project:
1. Set breakpoints in your source files.
2.
Right-click the project node in the Projects window, choose Properties, click Java
Sources in the Project Properties dialog box, and make sure that all the source files
you want to debug are listed in the Source Package Folders list.
3.
In the Services window, expand the Servers node, right-click the server instance
and choose Start/Stop Server.
4.
Click Start Server (Debug).
5.
Make sure that you have a debug target and that it is mapped to the Debug
command, as described in the previous sections.
6.
Choose Debug > Debug Main Project (Ctrl+F5).
For more information debugging features that you can use for web applications in the
IDE, see Section 12.12, "Debugging a Web Application."
10.8.1.2.2 Troubleshooting the Debug Target Even though the IDE does its best to
generate a complete debug target for you, with properties that are tailored to your
specific environment, you should always analyze and fine tune the debug process.
Work through the questions below when you encounter problems while using an Ant
debug target from NetBeans IDE:
■
Has the web application been correctly deployed?
Check that the web application has been deployed:
■
1.
In the Services window, expand the Servers node, start the server (if not
started), expand the server's instance node, and expand the Web Applications
node.
2.
If you do not see your application's context (/MyProject, for the application in
this document), it has not been correctly deployed.
3.
Deploy the application.
Are you behind a firewall?
10-16 NetBeans Developing Applications with NetBeans IDE
Debugging Applications
Check that your proxy settings are correct. Depending on your proxy type do the
following:
■
–
HTTP Proxy. Choose Tools > Setup Wizard. In the wizard, select the Use
HTTP Proxy Server checkbox. Type the proxy host name in the Proxy Server
Name field and the port number in the Port field. Click Finish.
–
SOCKS Proxy. You must pass the SOCKS proxy host and proxy port
parameters to the JVM software when you start the IDE. On Microsoft
Windows machines, use the IDE-HOME/etc/netbeans.conf file to pass the
parameters. On UNIX and Linux machines, you can write a wrapper shell
script. Go to Help > Help Contents for details.
Is the server running in debug mode?
Check that the server has been started in debug mode:
■
1.
In the Services window, expand the Servers node and check that the server is
running. Note that even if it is running, it may not be running in debug mode.
2.
If it is not running, right-click it, choose Start/Stop Server, and click Start
Server (Debug). If it is running, but you are not sure that it is running in debug
mode, stop the server and restart it in debug mode.
Are the server's port and address set correctly?
Check that the jpda.address set in debug.properties matches the server's
settings:
1.
Right-click the server's node in the Services window and choose Properties.
2.
In the Properties sheet:
–
Check the Debugging Port property (for socket connections). By default, it
should be 9009 for the SJS Application Server or 11555 for the Tomcat Web
Server.
–
Check the Name property (for shared memory connections). By default, it
should be localhost4848 for the SJS Application Server or tomcat_shared_
memory_id for the Tomcat Web Server.
If you change the server's Debugging Port property or Name property, make
sure that it matches the related property in the debug.properties file.
3.
Close the Properties sheet and stop and restart the server, if you had already
started it.
Check that the jpda.transport set in debug.properties matches the server's
settings:
1.
Right-click the server's node in the Services window and choose Properties.
2.
In the Properties sheet, check the Debugging Type property:
–
dt_socket for socket connections
–
dt_shmem for shared memory (Windows)
If you change the server's Debugging Type property, make sure that it matches
the related property in the debug.properties file.
3.
■
Close the Properties sheet and stop and restart the server, if you had already
started it.
Unable to step through your code?
Running and Debugging Java Application Projects 10-17
Debugging Applications
If you are unable to step from line to line in your code, but only from breakpoint to
breakpoint, the IDE has not been able to find your sources. This is because you
have not specified your sources correctly.
–
Servlets: Choose Window > Debugging > Sources. The Sources window
displays all the Java source folders that are available for debugging. If you
want to debug a source folder that is not available in the Sources window,
specify it in the Project Properties dialog box:
*
Right-click the project node, choose Properties, click Java Sources.
*
Add the source folders to be debugged to the Source Package Folders table
or to the Test Package Folders table.
The target you use for compiling servlets must specify
debug="true" when calling the javac task. If a servlet is compiled
without debug info, the debugger will not stop on its breakpoints.
Note:
–
JSP pages: Make sure that you have defined a context path for the project:
*
Right-click the project node, choose Properties, click Web Sources.
*
Type the context path. For example, type /MyProject in the Context Path
field.
If you have set your breakpoints before specifying the context
path, you must remove and reset the breakpoints after specifying the
context path. In other words, the context path must be set first.
Note:
Also make sure that the sources are correctly specified in the debug.properties
file and in the debug-nb target. Note that if your nbproject folder is not housed
within the folder that houses your sources folder, you should set the following
properties for your src.folder and web.docbase.folders properties:
–
src.folders=${project.dir}/src
–
web.docbase.dir=${project.dir}/web
10.8.2 Debugging GUI Projects
You can use the visual debugger to help you locate and debug the code for visual
elements in your Java and JavaFX GUI applications.
10.8.2.1 GUI Snapshots
After you create a project you can start a debugging session, take a GUI snapshot of
the application, and then work with the snapshot to locate source code, add listeners
to events and view the event log of GUI components.
To take a GUI snapshot:
1. Click the Debug button in the toolbar to start a debugging session.
Alternatively, right-click the project node in the Projects window and choose
Debug.
When you start the session, the IDE will launch your application and open the
Debugging window.
10-18 NetBeans Developing Applications with NetBeans IDE
Debugging Applications
2.
Choose Debug > Take GUI Snapshot from the main menu.
When you choose Take GUI Snapshot, the IDE takes a snapshot of the GUI and
opens the snapshot in the main window.
10.8.2.2 Working with the Visual Debugger
The GUI snapshot is a visual debugging tool that can help you locate the source code
for GUI components. The source code for GUI components can sometimes be difficult
to locate and the snapshot provides a way for you to locate the code based on the GUI
instead of searching through the code. You can select components in the snapshot and
invoke tasks from the context menu to view the source code for the component, show
the listeners and set breakpoints on components.
10.8.2.2.1 Locating the Source Code for Components to use the GUI snapshot to navigate
to the lines in the source code where a component is declared and defined, you select a
component in the GUI snapshot and use the context menu to invoke various
commands.
you select a component in the GUI snapshot, you can use the
context menu to invoke various commands.
Note:
To locate the declaration and source code for the component:
1. In the GUI snapshot, select a component (for example, a button).
When you select a component in the snapshot, the IDE displays details about the
selected component in the Properties window. If the Properties window is not
visible you can choose Window > Properties from the main menu to open the
window.
The IDE also displays the location of the component in the form hierarchy in the
Navigator window.
2.
Right-click the component in the snapshot and choose Go to Component
Declaration from the context menu.
When you choose Go to Component Declaration, the IDE opens the source file in
the editor and moves the cursor to the line in the code where the component is
declared.
3.
Right-click the component in the snapshot again and choose Go to Component
Source.
When you choose Go to Component Source, the IDE opens the source file in the
editor and moves the cursor to the line in the source code for the component.
To locate the line in the source code where a component is added to its
container:
1. Open the Options window.
2.
Click the Java Debugger tab in the Java category in the Options window.
3.
Select Visual Debugging in the list of categories and select Track locations of
component hierarchy changes. Click OK.
4.
Stop your debugging session (if one is running).
Running and Debugging Java Application Projects 10-19
Debugging Applications
Note: After you enable the command in the Options window you
will need to restart your debugging session and take a new GUI
snapshot before you can use the Go to Hierarchy Addition command.
5.
Start a new debugging session and take a GUI snapshot.
6.
Right-click a component in the GUI snapshot and choose Go to Hierarchy
Addition.
The IDE will open the source code in the editor at the line where the component is
added.
10.8.2.2.2 Exploring Component Events you can use the GUI snapshot and the Events
window to explore component events.
To locate component listeners and the events that are triggered by the
components:
1. Right-click a component in the snapshot and choose Show Listeners from the
context menu.
When you choose Show Listeners, the IDE opens the Events window with the
expanded Custom Listeners node.
2.
Right-click an item below the Custom Listeners node and choose Go to
Component Source in the context menu.
The source code opens in the editor at the line where the listener is defined.
3.
Select another component in the snapshot.
Alternatively, you can select a component in the Navigator window.
When you select another component, the items in the Events window will change
automatically to display the listeners for the selected component.
4.
In the Events window, double-click the Event Log node to open the Select
Listener window.
Alternatively, you can right-click the Event Log node and choose Set Logging
Events from the context menu.
5.
Select a required listener from the dialog (for example,
java.awt.event.KeyListener). Click OK.
6.
In your application, complete an event (for example, type a character in a text
field).
The event is recorded in the events log. (For example, if you expand the Event Log
node you can see that each keystroke is now logged). New events appear each
time that you complete an event. If you expand an individual event, you can see
the properties of that event in the log.
If you expand the Called From node for an event you can see the stack trace for
the event.
10.8.2.3 How to Configure Java Debugger Options
You can configure the options for debugging Java applications in the Options window.
10-20 NetBeans Developing Applications with NetBeans IDE
Using the Debugger Windows
To configure Java debugging options:
1. Open the Options window by choosing Tools > Options from the main menu. (If
you are running on Mac OS X, choose NetBeans > Preferences.)
2.
Select the Java Debugger tab in the Java category of the Options window.
3.
Select a category in the Java Debugger tab to configure the global settings for the
behavior of the Java debugger.
4.
Click apply in the Options window to apply the changes.
10.9 Using the Debugger Windows
When you start a debugging session the IDE opens some debugging windows by
default. In addition to the main Debugging window in the left pane of the IDE, other
debugger windows open as tabs below the editor. You can open any debugger
window by choosing Window > Debugging > window-name (for example, Window >
Debugging > Breakpoints).
Each debugger window displays a variety of icons to relay information about the
object. For example, the Breakpoints window uses a small red square to indicate a
breakpoint set on a line. Some windows also include a node expansion control to the
left of the icon. Clicking this control expands and collapses the object.
The Debugging window opens in the left pane of the IDE and uses a tree structure to
display the threads and calls in the current debugging session. The current thread and
call are displayed in bold. You can expand the node for suspended threads to view the
call stack.
In the debugger tabs, information is organized into lists. Each list item represents a
single object. Each column represents a property of the object. Data displayed in blue
underlined text is linked to the source code.
Some elements of lists in the debugger tabs have editable properties, such as the value
property of a variable in the Variables window. If you select a property and the
property has a white background you can edit the property. A selected property with a
gray background cannot be edited.
10.9.1 Customizing a Debugger Window
You can rearrange elements of a debugger window or remove columns to display only
the information of interest.
To add or remove a column to a window:
1. Click
(to the right of the column titles) or right-click in the window and
choose List Options > Change Visible Columns.
2.
Click the appropriate checkbox to turn the display of information on or off.
3.
Click OK.
To rearrange the columns in a window:
■
Drag the column header to the right or left to place the column in the new
location.
To set the sort order of a window:
■
Right-click anywhere in the window and choose List Options > Sort > sort-order.
Running and Debugging Java Application Projects 10-21
Using the Debugger Windows
For all windows, you can sort the column in ascending or descending order. A
triangle is displayed in the column header. The direction in which the triangle is
pointing indicates whether the sort order is ascending or descending. Some
windows provide additional sort orders.
10.9.2 Choosing Current Context in the Debugger
The current context is the portion of your program on which the debugger is currently
focusing. When multiple sessions are running, only one session is current. Within the
current session, the thread from which the debugger regained control is the default
current thread. Inside the current thread, the most recent call is the default current call.
You can make any session, thread, or call current by right-clicking its node in the
appropriate debugger window and choosing Make Current.
10.9.2.1 Debugger Windows and Context
Most debugger windows depend on the current context. When you change the current
context, the contents of these windows are updated to reflect the new context.
For example, the Debugging window shows the threads in the current session, while
the Call Stack window shows the call stack for the current thread. The Variables
window shows the variables that are local to the current call, and the Loaded Classes
window shows the classes that have been loaded by the current session. For more
information on viewing classes and class instances, see Section 10.9.6, "Viewing
Program Information When Debugging."
The exceptions are the Breakpoints and Watches windows. These windows list all
breakpoints and watches set in the IDE. While the set of watches is shared by all
sessions, an individual watch expression is evaluated and displayed based on the
current context. For information on setting breakpoints, Section 10.9.4, "Managing
Breakpoints."
For information on debugging threads, see Section 10.9.6.8, "Debugging Threads in the
IDE."
For information on examining the call stack for the current thread, see Section 10.9.6.9,
"Using the Call Stack."
10.9.2.2 The Source Editor and Context
When a variable is active in the current context, the Source Editor displays the value of
the variable when you move the pointer over it. In cases where a program includes
different variables with the same name, the Source Editor displays the value based on
the current context, and not on the instance of the variable in the source code.
10.9.3 Attaching Source Code to a JAR File
When you add a JAR file or folder of compiled classes to a project's classpath, it is
often useful to add the source files for those classes so that you can view their contents
when working with them. Attaching source code to a JAR file or compiled classes
folder lets the IDE know where to find the source code for those classes. You can then
step into the source files when debugging and open the source files with the Go To
Source command.
For code completion to work properly in the IDE, you must
either attach a complete set of source files as a folder or add the
available source files as a Zip archive.
Note:
10-22 NetBeans Developing Applications with NetBeans IDE
Using the Debugger Windows
To attach source code to a JAR file or compiled classes folder:
1. Choose Tools > Libraries from the main menu.
2.
In the left pane of the Ant Library Manager, select the project library within which
the JAR file you want to add the source code to is located.
Only libraries already registered with the IDE are listed in the Ant Library
Manager's Class Libraries list.
3.
If the JAR file or classes folder for which you want to add the source code has not
already been added to a registered library, create a new empty library using the
New Library button.
4.
In the Classpath tab click Add JAR/Folder and specify the location of the JAR file
containing the compiled class files.
A class library can contain multiple JAR files as well as their Javadoc
documentation and source code.
5.
In the Sources tab, click Add JAR/Folder to add the folder or archive file
containing the source code.
6.
Click OK to exit the Ant Library Manager.
The IDE adds the selected JAR files and source code to the specified library and
automatically registers the source code in every project that has that JAR file on its
classpath.
When you create a Java class library for a single JAR file, you can simply add the JAR
file to the project's classpath to make the associated Javadoc and source code available.
If your Java library contains multiple JAR files, however, you must add the library
itself to the classpath. Adding the library to the classpath also makes it easier to share
the project with other developers. For information on setting the classpath, see
Section 6.2.3.1, "Managing the Classpath."
You can also associate the sources with a JAR file using the project's Project Properties
window. However, doing so creates the association only for that project.
To associate sources with a JAR file through the Project Properties window:
1. Open the Project Properties dialog box by right-clicking the project node and
choosing Properties.
2.
Select the Libraries node in the Categories pane.
3.
Select the JAR with which you want to associate the sources and click Edit.
4.
Specify the sources to be associated.
To attach source code for a Java platform:
1. Choose Tools > Java Platforms from the main menu.
2.
Select the platform in the left pane of the dialog box.
3.
In the Sources tab, add the folders or archive files containing the source code.
For free-form projects, set the target JDK in your Ant script and specify the source
level in the Project Properties dialog box (for more information, see Section 6.8,
"Setting the Target JDK"). When you step into JDK classes, the IDE searches the
platforms registered in the Java Platform Manager for a Java platform with a matching
source level. If no matching Java platform is found, the IDE opens the source code for
the IDE's default platform.
Running and Debugging Java Application Projects 10-23
Using the Debugger Windows
10.9.4 Managing Breakpoints
A breakpoint is a flag in the source code that tells the debugger to stop execution of the
program. When your program stops on a breakpoint, you can perform actions like
examining the value of variables and single-stepping through your program.
The IDE enables you to set several types of breakpoints using the New Breakpoint
dialog. You can also set line breakpoints directly in the Source Editor. Breakpoints can
be set for the following types of source elements:
■
■
■
■
■
Class. You can break when the class is loaded into the virtual machine, unloaded
from the virtual machine, or both.
Exception. You can break whenever a specific exception is caught, whenever a
specific exception is not handled in the source code, or whenever any exception is
encountered regardless of whether the program handles the error or not.
Field. You can stop execution of your program whenever a field in a specific class
is accessed (for example, the method was called with the variable as an argument),
modified or both.
Method. Program execution stops every time the method is entered, exited or
both.
Thread. You can break program execution whenever a thread starts, stops, or both.
The Source Editor indicates a breakpoint by highlighting the line at which the
breakpoint is set in red and placing an annotation in the left margin. The following
table describes the debugging annotations:
Table 10–1
Annotation
Debugging Annotations
Description
Breakpoint
Disabled breakpoint
Invalid breakpoint
Multiple breakpoints
Method or field breakpoint
Disabled method or field breakpoint
Invalid method or field breakpoint
Conditional breakpoint
Disabled conditional breakpoint
Invalid conditional breakpoint
Program counter
Program counter and one breakpoint
Program counter and multiple breakpoints
10-24 NetBeans Developing Applications with NetBeans IDE
Using the Debugger Windows
Table 10–1 (Cont.) Debugging Annotations
Annotation
Description
The call site or place in the source code from which the current
call on the call stack was made
Suspended threads
Thread suspended by hitting a breakpoint
All Java breakpoints are defined globally and, therefore, affect all IDE projects that
include the source on which a breakpoint is set. For example, if you set a class
breakpoint on com.me.MyClass in one project, the IDE stops execution every time it
encounters that class during a debugging session for other projects that include the
class.
You can view and organize all IDE breakpoints by choosing Windows > Debugging >
Breakpoints (Alt+Shift+5). If you open the Breakpoints window when a debugging
session is running, it closes automatically when you end the debugging session. If you
open the window when no debugging session is running, it stays open until you close
it.
By default, each entry contains a short text description of the breakpoint and a
checkbox indicating whether the breakpoint is enabled or disabled. You can enable or
disable a breakpoint directly in the Breakpoints window by selecting or deselecting the
checkbox.
10.9.4.1 How to Set a Java Breakpoint
All Java breakpoints are defined globally and therefore affect all IDE projects that
include the source on which a breakpoint is set. For example, if you set a class
breakpoint on com.me.MyClass in one project, the IDE stops execution every time it
encounters that class during a debugging session for other projects that include the
class.
To set a line, field or method breakpoint in the Source Editor:
■
Click in the left margin next to the line in the source code or put the insertion point
in the line and choose Debug > New Breakpoint from the main menu.
A field, method or line breakpoint is created depending on if the line contains a field
declaration, method declaration or other code. The corresponding breakpoint
annotation is visible in the left margin next to the line of source code.
The IDE tests the validity of set breakpoints when the debugger session is starting or
when a debugger session is already running. If a breakpoint is invalid the IDE uses a
broken annotation to indicate the invalid breakpoint and displays an error message in
the Debugger Console.
To set all other types of breakpoints:
1. In the Source Editor, select the code element on which you want to set a
breakpoint.
For example, if you want to set a class breakpoint on the class BeanCounter, select
the class name in the class declaration.
2.
Choose Debug > New Breakpoint (Ctrl+Shift+F8).
Running and Debugging Java Application Projects 10-25
Using the Debugger Windows
The New Breakpoint dialog box opens with a suggested breakpoint type and
target filled in.
3.
If necessary, adjust the suggested breakpoint type in the Breakpoint Type
drop-down list.
4.
Enter the package and class name for which you want to set the breakpoint.
5.
Set any additional options you require in the New Breakpoint dialog and click OK.
The IDE creates the new breakpoint for the selected source element.
To modify an existing breakpoint:
1. Choose Window > Debugging > Breakpoints (Alt+Shift+5) to open the
Breakpoints window.
2.
Right-click any breakpoint and choose Properties to open the Breakpoint
Properties dialog box.
3.
Adjust any settings or actions you require and click OK.
The IDE updates the breakpoint for the selected source element.
To enable and disable a breakpoint:
■
Right-click the breakpoint in the Breakpoints window and choose Enable or
Disable.
You can modify and enable line, field and method breakpoints by right-clicking the
breakpoint icon in the left margin of the Source Editor and choosing from the
Breakpoint submenu.
When a debugging session is running, use code completion in the New Breakpoint
dialog box.
10.9.4.2 How to Set a Conditional Breakpoint
You can set conditions on a breakpoint so that execution only breaks if the condition is
true. Set conditions on any breakpoint except thread breakpoints by selecting the
Conditions checkbox and entering the condition. For all breakpoints you can specify
how often the breakpoint is triggered by selecting the Break When Hit Count
checkbox and choosing a criteria from the drop-down list and specifying a numerical
value.
Class breakpoints and exception breakpoints enable you to set the following
conditions:
■
■
For class breakpoints, you can exclude classes triggering the breakpoint by
selecting the Exclude classes checkbox and specifying the classes to exclude.
For exception breakpoints, you can filter the classes triggering the breakpoint by
selecting the Filter on Classes Throwing the Exception checkbox and specifying
the names of classes to match or exclude.
To set a conditions on a breakpoint:
1. Create a new breakpoint or open an existing breakpoint's customizer by
right-clicking its name in the Breakpoints window and choosing Customize.
2.
Select the Condition checkbox and type the condition in the Condition field. The
condition must follow the Java syntax rules. The condition can include anything
that can be on the right side of the equal sign (=). The condition can also include
10-26 NetBeans Developing Applications with NetBeans IDE
Using the Debugger Windows
variables and methods that are within the current context. The following are
exceptions:
■
■
■
Imports are ignored. You must use fully qualified names, such as
obj instanceof java.lang.String.
You cannot access outerclass methods and variables directly. Use
this.variableName or this$1.
(Optional) Select the Break When Hit Count checkbox and choose a criteria
from the drop-down list and specify a numerical value.
Conditional line breakpoints have a
icon in the left margin of the Source Editor.
10.9.4.3 How to Organize Breakpoints Into a Group
The Breakpoints window lists all of the breakpoints defined for all of your IDE
projects. If you have numerous breakpoints set in the IDE, it is useful to organize these
breakpoints into groups. Once your breakpoints are placed into groups, you can
enable, disable, and delete them as a single unit.
To add a breakpoint to a custom group:
1. Choose Windows > Debugging > Breakpoints (Alt+Shift+5) to open the
Breakpoints window.
2.
Right-click the breakpoint and choose Move Into Group and select a custom
group from the list.
To create a custom group, right-click the breakpoint and
choose Move Into Group > New and type the name of the new group
in the dialog box.
Note:
To remove a breakpoint from a custom group:
■
In the Breakpoints window, right-click the breakpoint and choose Move Into
Group > Default.
Alternatively, you can modify how breakpoints are organized from the Breakpoints
window by clicking Breakpoint Groups (
) and selecting a grouping strategy from
the context window. If you choose Nested you can specify the specific groups and the
order of the groups that are displayed.
10.9.4.4 About Source Maps Support
Web client JavaScript debugger and node.js debugger use generated source maps to
allow debugging in the original source files.
To debug the code you wrote but not the code that is executed as compressed or
translated, the IDE scans your project files to find any present source map and assure
that any breakpoint set in the files which were translated for execution (for example,
compressed or transpiled), are submitted to the target files. During stepping through
the application, the code positions and variable names are translated according to the
existing source maps.
10.9.5 Managing Debugging Sessions
Debugging is the process of examining your application for errors. The process of
debugging is accomplished by setting breakpoints and watches in your code and
Running and Debugging Java Application Projects 10-27
Using the Debugger Windows
running it in the debugger. This enables you to execute your code one line at a time
and examine the state of your application to discover any problems.
When you start a debugging session the Debugging window opens in the left pane of
the IDE. Additional debugger windows also appear automatically at the bottom of
your screen.
You can also debug applications that are running on a remote machine by attaching
the debugger to the application process.
10.9.5.1 How to Manage a Local Debugging Session
Local debugging is the process of debugging a program that is running on the same
computer as the IDE. The IDE starts the debugger, then runs the application inside the
debugger. When you start a debugging session, the IDE automatically opens the
debugger windows and prints debugger output to the Output window.
10.9.5.1.1
Debugging the Main Project
Debugging commands in the Debug menu are generally run on the main project, and
when debugging a project it is recommended that you set the project as the main
project.
If no project is set as the main project the Debug Project command is run on the project
that is selected in the Projects window and the commands begin the debugging session
in the main class of the selected project. For information on how to set a main project,
see Section 6.4, "Setting the Main Project."
Table 10–2 displays the commands in the Debug menu and the corresponding toolbar
icons for starting and stopping the debugger.
Table 10–2
Basic Debugging Commands and Icons
Command
Icon
Debug Project
(Ctrl+F5)
Finish Debugger Session
Description
Starts the debugger and runs the program until it
reaches a breakpoint or exception or until the
program terminates normally.
Stops the debugger.
(Ctrl+F5)
Continue
(F5)
Runs the program until it reaches the next
breakpoint or until the program terminates
normally.
To debug an individual project:
■
Right-click the project in the Projects window and choose Debug.
Alternatively, select the project in the projects window and choose Debug >
Debug Project in the main menu.
The IDE runs the project in the debugger until execution stops or a breakpoint is
reached.
To debug an individual file:
■
Select any runnable file in the Projects window and choose Debug > Debug my_
file.
The IDE runs the file in the debugger until execution stops or a breakpoint is
reached.
10-28 NetBeans Developing Applications with NetBeans IDE
Using the Debugger Windows
10.9.5.2 How to Manage a Remote Debugging Session
Remote debugging is the process of debugging an application that is running on a
different computer. This technique is useful when you are developing an application
that runs on a web server or in a different environment than the computer on which
you are developing the application.
To start a remote debugging session:
1. On the computer where the application is located, start the application in
debugging mode.
2.
On the computer where the IDE is running, open the projects that contain the
source for the application.
3.
Choose Debug > Attach Debugger to open the Attach dialog box.
4.
Select the appropriate Connector from the drop-down list, enter any required
process information, and click OK.
For details on the transport and connector options, see the JPDA documentation,
Connection and Invocation Details, for your version of the JDK from the Java Platform
Debugger Architecture home page at
http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/conninv.html.
The instructions for starting an application in debugging mode and the method for
connecting to the VM depends on your VM. See your VM documentation for further
details.
You can view and select from the four most recent Attach
configurations by expanding the menu under the Debug button in the
toolbar.
Note:
10.9.5.3 How to Step Through Your Program
After execution of your program is halted, step through your lines of code using the
commands listed in Table 10–3 in the Debug menu or the corresponding icons in the
toolbar:
Table 10–3
Debugging Step Commands and Icons
Command
Step Over
(F8)
Step Over Expression
(Shift+F8)
Icon
Description
Executes one source line. If the source line
contains a call, executes the entire routine
without stepping through the individual
instructions.
Executes one method call in an expression. If an
expression has multiple method calls, you can
use Step Over Expression to step through an
expression and view the value of each method
call in the expression in the Variables window.
Each time you use the Step Over Expression
command, the debugger advances to the next
method call in the expression and the completed
method call is underlined. Step Over Expression
behaves like Step Over when there are no
additional method calls.
For more information, see Section 10.9.6.11,
"How to Step Through an Expression."
Running and Debugging Java Application Projects 10-29
Using the Debugger Windows
Table 10–3 (Cont.) Debugging Step Commands and Icons
Command
Icon
Executes one method call in a source line. If the
line has more than one method call you can
choose which method call to step into by using
the arrow keys or mouse in the source editor to
select the method call. The selected method call
to step into is indicated by a box around the
method call in the source editor. The most likely
method call in the line is selected by default.
Step Into
(F7)
Step Into Next Method
(Shift+F7)
Description
(no icon for
this
command)
Step Out
(Ctrl+F7)
Run to Cursor
(F4)
Executes one source line. If the source line
contains a call, the IDE stops just before
executing the first statement of the routine. You
can also start a debugging session with the Step
Into command. Program execution stops on the
first line after the main routine before any
changes have been made to the state of the
program.
Executes one source line. If the source line is part
of a routine, executes the remaining lines of the
routine and returns control to the caller of the
routine. The completed method call is
highlighted in the Source Editor.
Runs the program to the cursor location in the
Source Editor and pauses the program. The file
you have selected in the Source Editor must be
called from the main class of the main project.
To view source code files potentially available to the Debugger:
■
Choose Window > Debugging > Sources (Alt+Shift+8) to open the Sources
window.
The Sources window lists the source directories on your project classpath. The
current source file is checked by default, meaning that the Debugger uses it during
the debugging session. If you want the Debugger to be able to step into source files
other than the current one, you can select those files in this window.
10.9.5.4 How to Fix and Continue in a Debugging Session
If you find a problem while debugging, you can use the Apply Code Changes
command to fix your source and then continue debugging with the changed code
without restarting your program.
It is not possible to use the Apply Code Changes command to do the following:
■
Change a modifier of a field, a method, or a class
■
Add or remove methods or fields
■
Change the hierarchy of classes
■
Change classes that have not been loaded into the virtual machine
To fix your code:
1. From the main menu, choose Debug > Apply Code Changes to recompile and
begin repairing your source code.
■
If there are errors during compilation, nothing is changed in your program.
Edit your source code as needed, then execute the Apply Code Changes
command again.
10-30 NetBeans Developing Applications with NetBeans IDE
Using the Debugger Windows
■
If there are no errors, the resulting object code is swapped into the currently
executing program. However, all calls on the call stack continue running the
unfixed code. To use the modified code, you must pop from the call stack any
calls that contain modified code. When the calls are reentered, they use the
modified code.
If you modify the currently running method, the IDE displays
an alert box. If you click Pop Call, the most recent call is removed
from the current call stack. If you click Leave Call, the program
executes with the original version of the code. If there is only one call
in the stack, you cannot pop the call and continue. For more
information on popping the call stack, see Section 10.9.6.9, "Using the
Call Stack."
Note:
2.
Continue the program to verify that the fixed version of your code works correctly.
The Apply Code Changes command does not automatically rebuild JAR files,
executable files, or similar files. You must rebuild these files if you want to debug them
in a new session.
10.9.5.5 How to Finish a Debugging Session
If necessary, stop the current debugging session using the Shift-F5 shortcut. You can
also close a specific debugging session using the Sessions window.
To finish the current debugging session:
■
Choose Debug > Finish Debugger Session (Shift+F5).
To finish one of several debugging sessions:
1. Open the Sessions window by choosing Window > Debugging > Sessions
(Alt+Shift+6).
The information given for each session includes the session name and state. In
most cases, the state corresponds to the state of the process associated with the
session. One session is always considered the current session, unless no sessions
are running. By default, the current session is the session that you most recently
started.
2.
Right-click the debugging session you want to stop and choose Finish.
For information on local debugging sessions, see Section 10.9.5.1, "How to Manage a
Local Debugging Session."
For information on remote debugging sessions, see Section 10.9.5.2, "How to Manage a
Remote Debugging Session."
10.9.6 Viewing Program Information When Debugging
In the IDE, local variables are listed in the Variables window, however, it is also
possible to evaluate variables directly in the Source Editor. You can view the values
returned by each method call in an expression by stepping through an expression.
10.9.6.1 Using the Variables Window
For each variable within the current call, the Variables window displays information
including the variable name, type, and value. Choose Window >Debugging >
Variables to open this window.
Running and Debugging Java Application Projects 10-31
Using the Debugger Windows
The Variables window also displays all of the static fields from the present class and all
superclasses for each variable, as well as all of the inherited fields from all
superclasses. For information on how to a call the current call, see Section 10.9.2,
"Choosing Current Context in the Debugger."
You can change the value of a local variable directly in the Variables window and then
continue running your program with the new value in place.
In some cases, the debugger assigns a pound sign (#) and a number as the variable's
value. This number is an unique identifier of the given instance. You can use this
identifier to determine if a variable points to the same instance or to a different
instance. You cannot edit this value.
10.9.6.2 Using the Loaded Classes Window
The Loaded Classes window displays the classes loaded on the heap and the
percentage and number of object instances. You can sort the classes by class name or
the number or percentage of instances. You can also use the filter box at the bottom of
the window to filter the list by class name. If you open the Loaded Classes window
when a debugging session is running, it closes automatically when you end the
debugging session. If you open the window when no debugging session is running, it
stays open until you close it.
The contents of the Loaded Classes window is dependent on the current context.
When you change the current session, the Loaded Classes window is updated to show
the classes for that session. Choose Window > Debugging > Loaded Classes to open
this window.
To view information for a particular class, right-click a class in the Loaded Classes
window and select Show in Instances. The Instances window displays the number of
class instances, fields, and references to the class that occur in the current context.
10.9.6.3 Using the Events Window
The Events window displays the events associated with GUI form elements according
to the triggering order and also displays the listeners that are associated with the
event. Open the Events window by right-clicking a component in the Visual Debugger
and choosing Show Listeners in the context menu.
Expand the Custom Listeners node or the Internal SWT/Swing Listeners node to view
a list of listeners in the project. Right-click a listener and choose Go to Component
Source to open the source file at the line where the listener is defined.
10.9.6.4 Evaluating Variables in the Source Editor
You can also evaluate a variable directly in the Source Editor by moving the insertion
point over the variable. If the variable is active in the current context, the value of the
variable is displayed in a tool tip. In cases where a program includes different
variables with the same name, the Source Editor displays the value based on the
current context, and not on the instance of the variable in the source code. Structured
values can be expanded into a detailed view. Expandable tooltips feature an Expand
icon ( ) on the left. Alternatively, you can expand a tooltip by pressing the Space bar.
You can track the changes in the value of a variable during program execution by
setting a watch on the variable. When you create a watch, the value of the variable is
immediately evaluated and displayed in the Watches window.
10-32 NetBeans Developing Applications with NetBeans IDE
Using the Debugger Windows
10.9.6.5 How to Create a Watch
A watch enables you to track the changes in the value of a variable or expression
during program execution. The Watches window lists all of the watches you have
defined for all of your IDE projects.
To open the Watches window:
■
Choose Window > Debugging > Watches (Alt+Shift+2).
To create a watch from the Source Editor:
1. Select the variable or expression in the Source Editor, right-click, and choose New
Watch (Ctrl+Shift+F7).
The New Watch dialog box opens with the variable or expression entered in the
text field.
2.
Click OK.
The Watches window opens with the new watch selected.
To create a watch from the Variables window:
1. Choose Window > Debugging > Variables.
2.
Click the Create New Watch icon (
) in the toolbar.
You can click in the Value cell to edit the value directly in the Watches window.
If you specify an expression, follow the syntax rules of the debugger that you are
using.
When you create a watch, the value of the variable or expression is immediately
evaluated and displayed in the Watches window. The value of the watch is based on
the current context. When you change the current context, the Watches window is
updated to show the value of the watch for that context.
When a debugging session is running, you can use code completion in the New Watch
dialog box.
For information on how to view variable values during a debugging session, see
Section 10.9.6, "Viewing Program Information When Debugging."
10.9.6.6 How to Create a Fixed Watch
A fixed watch describes the object that is currently assigned to a variable while a
normal watch describes the content of the variable. Fixed watches are specific to the
Java 2 debugger.
For example, consider the following code:
java.awt.Dimension dim=new java.awt.Dimension(10,20);
java.awt.Dimension newDim=dim;
dim=new java.awt.Dimension(20,30);
newDim.height=15
With the debugger stopped on the second line, you can create a normal watch on the
variable dim. If you create a fixed watch on the variable dim, the watch describes the
object that is currently assigned to the variable, which is java.awt.Dimension(10,20).
If you press F8 to step over the code three times, the value of the normal watch
becomes java.awt.Dimension(20,30). This change occurred on the third line of
source code. The value of the fixed watch is java.awt.Dimension(15,20). The fixed
Running and Debugging Java Application Projects 10-33
Using the Debugger Windows
watch was created on the object with a height of 10, but the fourth line changed the
height of this object to 15.
To create a fixed watch:
■
In the Variables or Watches window, right-click a variable and choose Create Fixed
Watch.
The fixed watch is added to the Watches window.
10.9.6.7 How to Pin a Watch
You can set a watch or multiple watches in your code to review a variable value in the
Source Editor. The pinned watch updates its value like a watch in the Watches
window and keeps the last known value even after the debugging session finishes.
To pin a watch:
1. Hover a mouse over a variable or a selected expression in the Source Editor area
until the IDE displays the tooltip with the value of the variable or your selection.
2.
Press the Enter key or click the Pin icon (
) in the tooltip.
The IDE adds a watch pinned into the Source Editor and displays a pinned watch
window with two icons on the right side - the Comment ( ) and Close ( ) icons.
You can drag the pinned watch window with the mouse.
To display the pinned watches in the Variables and Watches windows, right-click in
either window and choose Show Pinned Watches from the context menu.
10.9.6.8 Debugging Threads in the IDE
All the threads created in the current session are displayed in the Debugging window.
Choose Window > Debugging > Debugging (Alt+Shift+9) to open the Debugging
window. You can also see the list of threads in the current session in the Threads
window. Choose Window > Debugging > Threads (Alt+Shift+7) to open the Threads
window.
The information given for each thread is the thread name, state and if the thread is
suspended. One thread is the current thread. By default, the current thread is the
thread in the current session from which the debugger gained control. When you
select a different current session, the Threads window is updated to show the threads
for that session.
10.9.6.8.1
Changing the Current Thread
Only one thread is the current thread at any given time. By default, the current thread
is the thread within the current session from which the debugger gained control. When
you switch between threads to debug, the Variables window is automatically updated
to reflect the data applicable to that thread.
To change the current thread:
■
Double-click any thread in the Debugging window to make it the current thread.
10.9.6.8.2
Suspending and Resuming Threads
You can suspend execution of a thread if you think it is causing problems and then
later resume the thread once the problem is solved. The Debugging window enables
you to easily see the threads in the debugging session and identify the running and
suspended threads. The icon to the left of the thread name indicates whether the
thread is suspended or waiting to be resumed.
10-34 NetBeans Developing Applications with NetBeans IDE
Using the Debugger Windows
You can suspend, interrupt and resume application threads by right-clicking a thread
in the Debugging window and choosing an action from the context menu.
Alternatively, you can click the Resume (
) and Suspend (
) buttons in the right
side of the Debugging window. Hide the Suspend and Resume buttons by clicking the
Show suspend/resume table button (
) in the Debugging window toolbar.
You can also resume and suspend threads in the Threads window.
10.9.6.8.3
Editor window icons
A thread icon in the left margin of the source editor indicates that there is a suspended
thread at that line. The following table describes the icons representing the thread
states that appear in the source editor during a debugging session.
Table 10–4
Icons
Thread State Icons
Description
Other suspended threads
Other threads suspended by hitting a breakpoint
To switch a suspended thread to the current thread:
■
In the source editor, right-click the suspended thread icon and choose Set Current
Thread To > new_current_thread.
10.9.6.8.4 Multi-threaded Applications When debugging a multi-threaded application, a
step in a particular thread can be interrupted by a breakpoint encountered in some
other thread. When this occurs, the IDE gives you the option to switch threads. The
IDE does not automatically switch the context to the new thread.
When a breakpoint in another thread is encountered, you are notified by a panel that
appears in the Debugging window. The current thread remains the current thread until
you explicitly switch it or the thread stops. Click the arrow in the panel in the
Debugging window and choose a thread to switch to that thread at any time. This
action enables you to continue debugging the current thread and when it is convenient
you can switch to the thread that hit a breakpoint.
You can use the Current Thread Chooser (Ctrl+8) to select the thread you want to be
the current thread.
10.9.6.8.5 Viewing Source Code for a Thread If you suspect the source code of a thread is
causing problems, you can examine it in the Source Editor.
To view a thread's source:
■
Right-click the thread in the Threads window and choose Go To Source.
If the source of the thread is available, the Source Editor jumps to the current call
on the thread's call stack.
10.9.6.9 Using the Call Stack
In a debugging session, you can see the call stack for the current thread in the
Debugging window (opened automatically whenever you start a debugging session).
If you expand the node for the current thread you can see a list of the sequence of calls
made during the execution of the thread.
Running and Debugging Java Application Projects 10-35
Using the Debugger Windows
The information given for each call (marked by a
icon) includes the name of the
call, followed by the file name and line number of the call's currently executing
statement. If the sources are available, you can right-click the call and choose Go To
Source to go to the source code of the call.
Alternatively, you can open the Call Stack window by choosing Window >
Debugging > Call Stack (Alt +Shift+3).
10.9.6.9.1 Changing the Current Call The current call (indicated in bold) is the most
recent call made by the current thread. When you select a different current thread, the
window is updated to show the calls for that thread. The Variables window is also
updated to display the values of variables for the current call.
To browse the call stack, do any of the following:
■
To move one level away from the main routine, choose Debug > Stack > Make
Callee Current (Ctrl+Alt+up arrow).
■
■
To move one level toward the main routine, choose Debug > Stack > Make Caller
Current (Ctrl+Alt-+down arrow).
To make a call current, double-click the call in the Call Stack window.
You can capture a textual representation of the call stack by right-clicking a a call and
choosing Copy Stack from the context menu. When you copy the call stack, the text is
copied to the clipboard. You can then paste the call stack into a text file.
10.9.6.9.2 Popping a Call From the Call Stack You can change the execution of your
program so that the next statement to be executed is one of the calls made earlier on
the stack. In general, popping, or removing, a call from the call stack does not undo
any effects that the call caused. For example, if a call opened a database connection
and then that call is removed, the database connection remains open.
You can only pop a call if the program being debugged is
paused.
Note:
To pop the most recent call from the call stack:
■
From the main menu, choose Debug > Stack > Pop Topmost Call.
The call is removed from the call stack. The program counter is moved to the line
before the instruction that made the removed call. If the source code is available,
the focus of the Source Editor is set to that line. When you continue program
execution, the call is repeated.
To pop multiple calls from the call stack:
■
In the Debugging window, right-click the call that you want to remain at the top of
the call stack and choose Pop to Here.
All of the calls above the selected call are removed from the call stack. The
program counter is moved to the line before the instruction that made the
removed call. If the source code is available, the program counter moves to that
line. When you continue program execution, the call is repeated.
10.9.6.10 How to Evaluate Code
When you are in a debugging session, you can evaluate any code snippet to view the
values of local variables for the current method, class variables, and method calls.
10-36 NetBeans Developing Applications with NetBeans IDE
Using the Debugger Windows
You can view the values returned by each method call in the expression by stepping
through an expression.
To evaluate an expression:
1. Start a debugging session.
2.
Choose Debug > Evaluate Expression (Ctrl+F9) from the main menu.
3.
Type a code snippet in the Evaluate Code window and click
in the bottom
right corner of the window). The result is shown in the Variables view. The result
with historical values is shown in the Evaluation Results view.
Click the Create New Watch button (
) in the Variables view to set a watch for
the expression. The watch is added to the Watches view.
If you evaluate a method that changes a global variable, the global variable's value is
changed in the debugging session as well.
If you try to evaluate a variable that is outside the scope of the current method, a
message displays "variable" is not a known variable in current context. Use
the Call Stack window to change the current method context.
If you try to access a global variable before the file that contains the variable is
instantiated, a message displays Cannot access instance variable "variable"
from static context.
10.9.6.11 How to Step Through an Expression
When you are in a debugging session, use the Step Over Expression command to step
through an expression and view the values returned by each method call in the
expression.
Use the Step Over Expression command to achieve a more fine-grained stepping than
other debugging steps. Step Over Expression enables you to proceed through each
method call in an expression and view the input parameters and resulting output
values of each method call. Invoke the Step Over Expression command just as you
would any other step commands. If there are no further method calls, Step Over
Expression behaves like the Step Over command.
Each method call in an expression has some input (parameters) and output values.
Each time you use the Step Over Expression command in an expression, the debugger
resumes VM execution and then stops before executing the next method call. You can
inspect the output values for the previous method and the input parameters for the
next method in the Variables window. Invoking Step Over Expression again resumes
the VM execution until the next method call in the expression.
To step through an expression:
1. Place a breakpoint in the line containing the expression you want to debug and
start the debugging session.
When you start the debugger, the VM stops before executing any of the method
calls in the expression.
2.
Choose Debug > Step Over Expression (Shift+F8) from the main menu.
The debugger steps to the first method call in the expression but does not execute
the method. The Variables window displays the input parameters of the method.
3.
Invoke Step Over Expression again to execute the first method and step to the
next method call in the expression.
Running and Debugging Java Application Projects 10-37
Using the Debugger Windows
The Variables window displays the output values of the executed method and any
input parameters for the next method in the expression.
In the Source Editor, the executed method call is underlined and the next method
call in the expression is highlighted. Mouse over the executed method to display a
tooltip and view the output values.
4.
Invoke Step Over Expression again to step to the next method call in the
expression.
The Variables window displays the output values under the Return Values node.
10-38 NetBeans Developing Applications with NetBeans IDE
11
Implementing Java GUIs
1
This chapter describes how to implement Java GUIs using the IDE’s Java GUI tools.
[12]
■
About Implementing Java GUIs
■
Working with the GUI Builder
■
Working with Layout Managers
■
Adding a Bean to the Window
■
Working with Database Applications and Beans Binding
■
Deploying GUI Applications
■
Configuring the GUI Builder
11.1 About Implementing Java GUIs
In Java applications, the components that comprise a GUI (Graphical User Interface)
are stored in containers called forms. The Java language provides a set of user interface
components from which GUI forms can be built.
The IDE's GUI Builder assists you in designing and building Java forms by providing
a series of tools that simplify the process.
11.1.1 The IDE's Java GUI Tools
The IDE provides several tools to simplify the process of building GUIs:
■
■
■
■
■
GUI Builder. The primary workspace within which GUI design takes place in the
IDE. The GUI Builder enables you to lay out forms by placing components where
you want them and by providing visual feedback in the form of guidelines. See
Section 11.2, "Working with the GUI Builder."
Navigator window. Displays a tree hierarchy of all components contained in the
currently opened form. Displayed items include visual components and
containers, such as buttons, labels, menus, and panels, as well as non-visual
components such as timers and data sources.
Palette window. A list containing all the components that can be added to forms.
You can customize the window to display its contents as icons only, or as icons
with component names.
Properties window. Displays the editable settings for the currently selected
component.
Connection wizard. Assists in setting events between components in a form
without the need of writing code manually.
Implementing Java GUIs 11-1
Working with the GUI Builder
■
Manager. Enables you to add, remove, and organize window components such as
Swing components, AWT components, Layouts, and beans.
In addition, the IDE provides support for the Beans Binding specification which
provides a way to synchronize the values of different bean properties. This support
also simplifies the creation of desktop database applications.
To access binding features, right-click a component, select Bind in the context menu,
and select a property from the drop-down list. For more information see "Working
with Database Applications and Beans Binding."
For more information about creating Java GUIs, see the Java GUI Application Learning
Trail at:
https://netbeans.org/kb/trails/matisse.html
For more information about handling events in your application, see the Creating a
GUI with JFC/Swing tutorial at:
http://docs.oracle.com/javase/tutorial/uiswing/
11.2 Working with the GUI Builder
The GUI Builder is a tool for designing GUIs visually. As you create and modify your
GUI, the IDE automatically generates the Java code to implement the interface. GUI
forms are indicated by form nodes ( ) in the Projects, Files, and Favorites windows.
When you open a GUI form, the IDE displays it in an Editor tab with toggle buttons
that enable switching between Source and Design views. The Design view enables you
to work with GUI forms visually while the Source view permits the form's source code
to be edited directly. Each time you select a form's Design toggle button, the Palette,
Navigator, and Properties windows appear automatically.
Components are typically added to a form using the window and arranged in the GUI
Builder workspace. As you work, the GUI Builder automatically displays guidelines
suggesting preferred alignment and anchoring for the components you add. Use the
Navigator window in conjunction with the Properties window to examine a form's
component and layout manager properties, manage component event handlers, and
define how code is generated.
Note: Interfaces created with the GroupLayout layout manager must
have the Swing Layout Extensions library available if they are run
outside the IDE. The Swing Layout Extension Library is included in
the Java Platform JDK 6 or higher, so no additional steps are needed if
you develop the application with JDK 6 or 7 and deploy in
environments that have JRE version 6 or higher. For more information,
see Section 11.6, "Deploying GUI Applications."
To design GUI applications:
These are the basic steps to create and deploy GUI applications:
1.
Create forms. Forms can be created within existing projects. To simplify handling,
a form includes containers, subcontainers, and components. Layout managers
control the arrangement of components within a container. You also have the
option to create a Multiple Document Interface (MDI) application.
2.
Edit forms. A component within a form has behavior, appearance, and
accessibility properties that can be modified directly or through the property
11-2 NetBeans Developing Applications with NetBeans IDE
Working with the GUI Builder
editor. See Section 11.2.10, "How to Manage Component Events" and
Section 11.3.1, "How to Set the Layout Manager."
3.
Preview forms. With the Preview Design capability you can test your form
without compiling or running it. See Section 11.2.14, "How to Preview a Form."
4.
Deploy the GUI application. Applications are typically distributed as JAR files.
Before deployment you must ensure that the JAR contains all necessary libraries.
See Section 11.6, "Deploying GUI Applications."
11.2.1 How to Create a New Form
In the IDE you can create JFC/Swing or AWT (Abstract Window Toolkit) forms,
pre-built sample application skeletons, or any class that is based on the JavaBeans
component architecture using the provided templates.
The GUI Builder cannot be used to edit GUI forms that were
created outside of the IDE.
Note:
To create a new GUI form in an existing project:
1. Choose File > New File from the main menu.
2.
In the New wizard's Project combo box, select the project for which you want to
create the form.
3.
Expand the Swing GUI Forms or AWT GUI forms node in the Categories pane and
select the desired form template. Click Next.
4.
Enter the GUI form's class name and location. Click Finish.
The IDE creates a blank form of the selected type and opens the form in the Source
Editor’s Design view.
In order to avoid repaint problems at both design and run
time, only AWT components should be used in AWT forms and only
JFC/Swing components should be used in JFC/Swing forms.
Note:
GUI Form Types in the New File Wizard:
The following table lists the types of form templates available in the IDE. Each differs
in the design time and run time look of the form, as well as in the code generated for
the form's class.
Table 11–1
GUI Form Types
Form Type
Description
JApplet
Program run by a Java-enabled web browser or other applet viewer.
JDialog
Modal or modeless window for collecting user input.
JFrame
Top-level application window.
JInternalFrame An internal frame that can be placed on a JDesktopPane component to create
an MDI application.
JPanel
Lightweight container for holding parts of an interface. In turn, the container
can be used in any other container, such as a JFrame, JPanel, JApplet, or
JDialog component.
Implementing Java GUIs 11-3
Working with the GUI Builder
Table 11–1 (Cont.) GUI Form Types
Form Type
Description
Bean Form
The template used to create a new form based on any JavaBeans component.
The new form can be visual or nonvisual. In the New wizard go to the
Superclass page and on the Form Superclass page specify the bean class. The
bean class that you specify when creating the new form must be in the
classpath and must be already compiled.
A bean is any class that complies with the JavaBeans component architecture.
A bean must have a public constructor without parameters. Use any
JFC/Swing component as an example of a JavaBeans class. For example, use
javax.swing.JButton to create a form to produce a customized button.
To use this template to create a plain container for holding beans, specify
java.lang.Object as the superclass.
AWT Forms
Visual forms that are based on the AWT. The AWT forms include Applet,
Dialog, Frame, and Panel.
Sample Forms
Customized sample forms that include a JFrame-based application with three
menus, a JFrame application that can be used as the main window for an MDI
application, and a dialog box with OK and Cancel buttons.
11.2.2 How to Work with Containers
Java GUIs are forms comprised of top-level containers within which are grouped
sub-containers as well as the various components used to provide the desired
information and control functionality.
11.2.2.1 Controlling View Focus
It is often useful to focus work on single subcontainers rather than the entire form the
GUI Builder generally displays. When working with large forms containing complex
nested hierarchies of containers, changing the scope of the GUI Builder's focus enables
you to concentrate on specific parts of your interface.
To change the GUI Builder's focus to a specific container:
In the GUI Builder or Navigator window, right-click the container you want to edit.
■
■
Choose Design This Container from the contextual menu.
The IDE adjusts the workspace display such that the current container fills the
work area and hides the form's other components. The form's entire hierarchy
remains available in the Navigator window.
To return the GUI Builder's display focus to the entire form:
■
Right-click the container in the GUI Builder.
■
Choose Design Top Container from the contextual menu.
The IDE adjusts the work area display such that the entire form is visible. If the
Design Top Container menu item is dimmed, you are already designing the entire
form.
11.2.2.2 Reordering Components Within a Container
The component order in a container follows the sequence in which components are
added. See Section 11.2.3, "How to Add a Component to a Form." If the layout
manager for a container does not use constraints (FlowLayout, BoxLayout, and
GridLayout), the order of components also determines how they are arranged visually.
11-4 NetBeans Developing Applications with NetBeans IDE
Working with the GUI Builder
You can reorder the components in the Navigator window or drag the components in
the form itself.
With layout managers that use constraints (BorderLayout, GridBagLayout,
CardLayout, AbsoluteLayout, and Null Layout), the order of components in the
container does not determine the order in which the components appear. For these
containers, the component order can only be changed in the Navigator window.
Although GridBagLayout uses constraints to determine how components are
arranged, component order determines the layout when the Grid X and Grid Y
constraints are not used. See Section 11.3, "Working with Layout Managers."
11.2.3 How to Add a Component to a Form
Once you have created a new form, you can add components to display information
and control functionality. In the IDE, you can add components several ways,
including:
■
Drag and Drop
■
Pick and Plop
■
The Navigator window.The IDE's Navigator window provides a hierarchical tree
view of the form's various components. Each form is represented by a root node
( within which all components in the form's class are contained. All other GUI
components are organized into one of the following two subnodes:
–
Form Container node ( ). Represents the top level of the form's hierarchy
and contains the visible components currently displayed in the GUI Builder.
–
Other Components node (
). Contains the form's non-visual components.
To add a component from the Palette:
1. To select a component in the window click its icon. Without releasing the mouse
button, drag the component to the desired location in the form. For more
information, see Section 11.2.4, "How to Select Components in a Form."
2.
If you want to add the component to the Other Components node, drag the
component to the white area outside the form in the GUI Editor's workspace.
The IDE adds the component to the selected container in the form.
To add multiple components from the Palette:
1. Click a component icon.
2.
Shift+Click in the form to place the first component.
3.
Click all locations.
If you want to add the component to the Other Components node, click in the
white area outside the form in the GUI Editor's workspace.
The IDE adds the components to the selected container in the form.
To add a component using the Navigator window:
1. In the Navigator window, right-click the container to which you want to add a
component.
2.
Choose the desired component from the Add From submenu.
The IDE adds the component to the selected container in the form.
Implementing Java GUIs 11-5
Working with the GUI Builder
To add a bean from the Projects, Files, or Favorites windows:
1. In the Files window, locate the bean's class node. The class must be a bean and it
must be compiled.
For a class to be a bean, it must be possible to create an
instance of the class using an empty public constructor.
Note:
2.
Right-click the class node and choose Copy from the contextual menu.
3.
Choose Paste from the contextual menu of either the GUI Builder or the Other
Components node in the Navigator window.
The IDE adds the bean to the current form. See Section 11.4, "Adding a Bean to the
Window."
When working with nested containers, it is sometimes difficult
to select the container to which you want to add the component. You
must first select the desired container before selecting the component
you want to add. You then select the component from the window,
hold down the Alt key, and click the desired container again to add
the component.
Note:
11.2.4 How to Select Components in a Form
The IDE's GUI Builder and Navigator window always display the same selected
component or components. Selecting a component in one window automatically
selects it in the other.
To select a single component:
Click the component's node in the Navigator window or click the component in the
GUI Builder.
To select multiple components, do one of the following:
■
Hold down the Control key while clicking multiple components in the Form
Editor or while clicking multiple nodes in the Navigator window.
■
■
In the GUI Builder, hold down the Shift key while holding down the left mouse
button and drag the mouse over each component in the group. A rectangle is
painted as the mouse is dragged over the group of components. When the mouse
button is released, all the components included in the rectangle are selected.
In the Navigator window, to select a consecutive group of components, Shift+click
the first one, and while holding down the Shift key, click the last component in the
group.
To select next and previous components:
Press Tab in the GUI Builder to select the next component or press Shift+Tab to select
the previous component.
11.2.5 Controlling Selection Depth
When working with nested components (components within a container like a panel
for example), clicking in the GUI Builder always selects the deepest component at the
11-6 NetBeans Developing Applications with NetBeans IDE
Working with the GUI Builder
point of the click. You can, however, select nested components on different levels using
modifier keys, as described below.
Right-click to display the contextual menu for the selected container or subcomponent.
The right-click action does not change the selection depth.
To select the parent container of a selected component:
1. Press and hold the Alt key.
2.
In the GUI Builder, click the selected component.
If the currently selected component does not have a parent container (i.e. it is the
container component for the entire form), Alt+Click selects the deepest component
at the point of the click.
To select a subcomponent of a selected container:
1. Press and hold both the Alt and Shift keys.
2.
Click the subcomponent.
If the currently selected component does not contain any subcomponents, the
container component for the entire form is selected.
It is often easier to select components using the Navigator
window than the GUI Builder.
Note:
11.2.6 How to Align Components
Once you have added components to a form you can adjust the alignment.
To align components:
1. Select the components you want to align in the GUI Builder's workspace.
2.
Click the appropriate align button in the GUI Builder toolbar. Alternately, you can
right-click either component and choose Align > Left in Column (or Align >
Right in Column) from the pop-up menu.
The IDE shifts the component positions such that the specified edges are aligned
and the component anchoring relationships are updated.
To align component baselines:
1. Select the component you want to align in the GUI Builder's workspace.
2.
Drag the component to the right or left of the selected component.
3.
A horizontal guideline appears indicating that the selected component's baseline is
aligned with the baseline of the second component and a vertical guideline
suggest the spacing between the two components. Click to position the
component.
The IDE snaps the second component into a position aligned with the baseline of
the first and displays status lines indicating the component spacing and anchoring
relationships.
To indent components:
1. Select the component you want to indent in the GUI Builder workspace.
2.
Select the component below the component below which you want to indent it.
Implementing Java GUIs 11-7
Working with the GUI Builder
3.
When guidelines appear indicating that the first component's left edge is aligned
with that of the JLabel, move it further to the right until secondary indentation
guidelines appear.
4.
Click to position the component.
The IDE indents the second component below the first component.
For more information of working with components see Section 11.2.4, "How to Select
Components in a Form," Section 11.2.7, "How to Size Components," and Section 11.2.8,
"How to Edit Component Properties."
11.2.7 How to Size Components
It is often beneficial to set several related components, such as buttons in modal
dialogs, to be the same size so they can be easily recognized as offering similar
functionality. You can also adjust the resizing behavior of components to ensure that
component relationships are maintained at runtime.
To set components to the same size:
1. Select all of the components you want to resize in the GUI Builder's workspace.
2.
Right-click any one of components, and choose Set the Same Size > Set Width (or
Same Size > Set Height) from the contextual menu.
The IDE sets the selected components to the same size and adds small graphic to
indicate the component relationships.
To set component resizing behavior:
1. Select the components whose auto resizing behavior you want to set.
2.
Right-click any one of the components and choose Auto Resizing > Horizontal (or
Auto Resizing > Vertical) from the pop-up menu.
The IDE sets the components auto-resizing behavior to resize horizontally at
runtime. The alignment guidelines and anchoring indicators are updated to
indicate the new component relationships.
For more information of working with components see Section 11.2.4, "How to Select
Components in a Form," Section 11.2.7, "How to Size Components," and Section 11.2.8,
"How to Edit Component Properties."
11.2.8 How to Edit Component Properties
Once you have added a component to a form, you can edit values in the Properties
window to modify its behavior and appearance.
To edit a component's properties:
1. Select the component in the GUI Builder or Navigator window to display its
properties in the Properties window.
If you select multiple components, their common properties
are displayed and any modifications apply to all of the selected
components.
Note:
2.
Click a button at the top of the Properties window to select an appropriate
property.
11-8 NetBeans Developing Applications with NetBeans IDE
Working with the GUI Builder
3.
In the Properties window select the property and enter the desired value.
4.
(Optional) If the property you want to edit has an ellipsis (...) button, click it to
open a special property editor where you can modify both the property and the
initialization code generated for it.
5.
(Optional) If you are using the property editor, use the Select Mode combo box to
choose between available custom editors for the property, make the necessary
changes, and click OK.
The IDE applies the new parameter values to the selected components.
To return a property to its default value:
Right-click the property name and choose Restore Default Value from the contextual
menu. The IDE returns the selected to its default value.
You can edit text label properties for common components
directly in the GUI Builder.
Note:
For more information of working with components see Section 11.2.10, "How to
Manage Component Events,"Section 11.3.4, "How to Set Layout Properties," and
Section 11.2.11, "How to Modify GUI Source Code."
11.2.9 How to Set Events with the Connection Wizard
Use the Connection wizard to set events between two components within a form
without having to write code manually.
To set an event using the Connection wizard:
1. Click the Connection Mode button ( ) in the GUI Builder toolbar.
2.
In the GUI Builder or Navigator window, select the component that fires the event.
Section 11.2, "Working with the GUI Builder."
Note:
3.
The selected component is highlighted in red when selected.
Select the component whose state you want to affect with the event.
Note:
The selected component is highlighted in red when selected.
4.
On the Connection wizard's Select Source Event page, expand the event type
directory node and select the event that the trigger component fires from the
Events list. Accept the default handler method name or type in a new name and
click Next.
5.
On the Specify Target Operation page, specify the operation to be performed on
the target component by selecting the appropriate radio button and choosing from
the list of operations. Click Next.
If you choose a method call with no parameters, the wizard’s
Finish button becomes available.
Note:
Implementing Java GUIs 11-9
Working with the GUI Builder
6.
(Optional) If you wish to enter event handler code directly, click the User Code
radio button and click Finish. The insertion point is placed in the new event
handler in the Source Editor, where you can write the event handler code yourself.
For more information see Section 11.2.10, "How to Manage Component Events."
7.
On the Enter Parameters page, specify the values for each tab's target property or
method by selecting the source from which each parameter's value is acquired.
The source code generated for each of the parameters is displayed in the
Generated Parameters Preview field.
8.
Click Finish.
The IDE automatically generates the code to connect the form's components.
11.2.10 How to Manage Component Events
The Java programming language uses events to enable GUI form behavior. Source
objects can trigger events which one or more objects with event listeners react to by
means of event handlers.
11.2.10.1 Defining Event Handlers
You can define event handlers using a component's property sheet or contextual menu.
You can also define an event handler using the Connection wizard.
To define an event handler using the property sheet:
1. Select the component in the Navigator window.
2.
Click the Events button at the top of the Properties window.
3.
Click the value of the desired event in the list. Initially, the value for all events is
<none>. When you click the value field, <none> is automatically replaced with
the default event name.
4.
Click the event's ellipsis (...) button to open the Handlers dialog box.
5.
Click the Add button to add a new name to the list of handlers. Click OK.
The code for the listener and the empty handler method body is generated.
You still must add the desired code for the new event handler
in the Source Editor.
Note:
To define an event handler using the contextual menu:
1. Right-click a form component in the Files window, Project window, or Navigator
window.
2.
Choose Events from the contextual menu and its submenus. Bold menu items in
the Events submenus indicate event handlers that have already been defined.
The code for the listener and the empty body of the handler method is generated.
The default name is assigned to the event handler.
3.
Add your code for the new event handler in the Source Editor.
11-10 NetBeans Developing Applications with NetBeans IDE
Working with the GUI Builder
If multiple events are of the same type, you can use the same
handler for all of them. For example, you could set both focusGained
and focusLost to use the button1FocusChange handler since they are
both of the type java.awt.event.FocusEvent. You can also use the
same handler for the same event on multiple components.
Note:
You can set the code generation style for how the component
event code is generated. Choose Tools > Options. Select the
Miscellaneous pane and then select the GUI Builder tab. Set the
Listener Generation Style property, one of Anonymous Innerclasses,
One Innerclass, or Main Class.
Note:
To add multiple handlers for one event:
1. In the Navigator window, select the component for which you want to add
multiple handlers.
2.
Click the Events button at the top of the Properties window.
3.
Select the event in the property sheet and click the ellipsis (...) button to display
the Handlers dialog box. Click the Add button and fill out the form. Repeat these
steps to add additional event handlers.
To remove event handlers:
1. In the Navigator window, select the component from which you want to remove
the event handlers.
2.
Click the Events button at the top of the Properties window.
3.
Select the event in the property sheet and click the ellipsis (...) button to display
the Handlers dialog box. Select the unwanted handler and click the Remove
button.
Alternately, go to the Properties window and delete the name of the handler you
want to remove.
4.
In the Handlers dialog box, select the unwanted handler and click Remove.
When you remove an event handler, the corresponding code block is deleted. If more
than one handler uses the same name and same block of code, deleting a single
reference to the code does not delete the code itself. You must delete all references to
delete the corresponding code block; a confirmation dialog box is displayed first.
For more information about how to handle events in your program, including
information about the Java event model, see the Creating a GUI with JFC/Swing tutorial
at:
http://docs.oracle.com/javase/tutorial/uiswing/
11.2.11 How to Modify GUI Source Code
The IDE automatically generates blue guarded blocks of code as you create your GUI
form in the GUI Builder. Guarded text generated includes:
■
■
Blocks of components' variable declarations.
The initComponents() method, in which form initialization is performed. This
method is called from the form's constructor and though it is not editable
Implementing Java GUIs 11-11
Working with the GUI Builder
manually, to affect the way it is generated, edit the Code properties in the
component's property sheet.
■
The header (and trailing brace) of all event handlers.
You can modify the way initialization code is generated and even write custom code to
be placed within the initialization code.
11.2.11.1 Modifying Code Generation for Form Components
You can modify the way initialization code is generated for a component, form, or
component property by editing its Code properties in the Properties window. In
addition, you can write custom code and specify where it should be placed within the
initialization code.
To modify a form component's guarded block:
1. In the Navigator window, select the component whose initialization code you
want to edit.
2.
Click the Code button at the top of the Properties window to view the Code
properties.
3.
Select the property you wish to edit and enter the desired value.
The IDE updates the selected component's guarded code block with the new
value.
Alternatively, you can customize code generated for a component through the Code
Customizer dialog box. To open this dialog box, right-click a component in the Design
view of the GUI Builder and choose Customize Code.
11.2.11.2 Setting Variable Modifiers for a Java Component
You can set the Java language modifiers for a Java element using the Variables
Modifier Property Editor dialog box.
To modify a component variable:
1. In the Navigator window, select the component whose variable modifier you want
to edit.
2.
Click the Code button at the top of the Properties window to view the Code
properties.
3.
Select Variable Modifiers and click the ellipsis (...) button.
The Variable Modifiers dialog box opens. You can edit the access modifiers or
other modifiers as needed.
11.2.11.3 Modifying Code Generation for a Property
The IDE enables form component properties to be initialized in more ways than
simply setting static values.
The IDE enables you to initialize property values from:
■
A static value you define
■
A component written to the JavaBeans architecture
■
A property of another component on the form
■
A call to a method of the form or one of its components. You can choose from a list
of methods that return the appropriate data type.
11-12 NetBeans Developing Applications with NetBeans IDE
Working with the GUI Builder
■
Code you define, to be included in the generated code
To modify the initialization code for a component’s property:
Follow these steps to modify the initialization code generated for a component's
property:
1.
Select the component in the Navigator window.
2.
Click the Properties button at the top of the Properties window.
3.
Select the property for which you would like to modify the initialization code.
4.
Click the ellipsis (...) button to bring up the Property Editor dialog box.
5.
Select Form Connection from the Select Mode combo box.
6.
In the Property Editor, select the type of initialization code you would like to add
(Value, Bean, Property, Method Call, or User Code).
■
■
If you select Value or User Code, you