8 Building Java Projects

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 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."

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.

• 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.

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.

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.

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.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.

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, "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.

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.

<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>

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.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.

   Note:

   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.

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."

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.

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:

   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.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. In the Find Usages dialog box, select options for the scope of the search:

   • Classes and interfaces

   • Methods

   • Fields

3. 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.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 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.

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.

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.

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.

   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.

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:

   • 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.

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.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.

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.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.

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.

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.

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.

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 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.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 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.

   • Select Single Inspection and choose a single hint to be used in the source code analysis.

4. 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.

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.

   • Select Single Inspection and choose a single hint to be used in the source code analysis.

4. 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.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.

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.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.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.

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.

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:

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).

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.

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.

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.