Using NetBeans

TM

IDE 3.6Feedback

Your Guide to Getting Work Done in NetBeans IDEWelcome to the Using NetBeans IDE 3.6 guide. This guide is designed to give you a more detailed introduction to the IDE than available in the Getting Started tutorial. Various aspects of the IDE are explored in detail. This guide is geared mostly for newcomers to NetBeans IDE, whether they are new to Java, new to using IDEs, or experienced IDE users that are switching over from a different IDE. This guide covers the following:q

TM

q

Setting Up Your Project r Basic IDE Concepts s The Filesystems Window s Projects in the IDE r Accessing Source Directories s Filesystems and the Java Classpath s Correctly Mounting Java Packages s Mounting Resource Libraries r Advanced Project Setup Creating and Editing Java Source Code r Creating Java Files s GUI Templates and Java Templates r Editing Java Files in the Source Editor s Using Abbreviations, Word Matching, and Code Completion s Configuring Code Completion s Adding Fields, Bean Properties, and Event Listeners s Working With Import Statements s Search and Selection Tools s Formatting Java Source Code r Navigating Between Documents r Configuring the Editor

Page 1 of 58

q

q

q

q

Compiling Java Programs r Compiling Files r Working with Compiler Types s Specifying the Compiler Type for Files and Projects s Creating Custom Compiler Types s Setting the Target Directory for .class Files r Cross-Compiling Between Java Platforms r Using JavaMake to Manage Class Dependencies Debugging Java Programs r Basic Debugging s Starting a Debugging Session s Debugger Windows s Stepping Through Your Code r Working With Breakpoints s Setting a Breakpoint s Setting Conditions for Breakpoint s Customizing the Output for a Breakpoint s Breakpoint Types r Setting Watches Packaging and Deploying Your Applications r Creating a JAR File s Creating a JAR Recipe s Compiling and Creating the JAR File s Mounting and Checking the JAR File r Modifying a JAR File s Adding Files to a JAR Recipe s Modifying the Manifest File s Setting the JAR Content Filter r Executing a JAR File Using Javadoc r Integrating Java API Documentation into the IDE s Making Javadoc Documentation Available in the IDE s Searching and Displaying Javadoc Documentation s Configuring the External Browser to Display Javadoc Files r Adding Javadoc Comments to Your Code r Generating Javadoc Documentation

Page 2 of 58

q

q

Specifying an Output Directory for Javadoc Files Team Development With CVS r Checking Out Sources s Mounting a CVS Filesystem s Specifying Advanced Command Options r Configuring a CVS Filesystem s Setting the Relative Mount Point s Shortening and Hiding File Status r Working With CVS Files s Using the Graphical Diff Tool s Creating and Applying Patches s Resolving Merge Conflicts Graphically r Making Safe Commits Configuring the IDE r Setting IDE Default Settings s Configuring IDE Startup Switches s Configuring General Java Settings s Working with Unknown File Types r Enabling and Disabling IDE Functionality s Disabling Modules s Installing New Modules from the Update Center r Boosting NetBeans Performance s Tuning JVM Switches for Performances

Page 3 of 58

Setting Up Your ProjectUsing NetBeans IDE 3.6 This section covers the basics of Previous - TOC - Next correctly setting up your IDE to start developing your projects. Feedback The process of managing project contents and properties is centered around the Filesystems window. The most common tasks in setting up a project are adding source files to the project, making resource libraries available to the project, correctly setting up the Java classpath, and configuring output directories for compiled classes and Javadoc documentation. This section covers:q

q

q

Basic IDE Concepts - The Filesystems window and working with projects. Accessing Source Directories - Adding source files and directories to a project, understanding filesystems, configuring the Java classpath, correctly mounting Java packages, and making class libraries (JAR files) available to the project. Advanced Project Setup - An example of a more advanced IDE project with two separate output directories for compiled classes and one for Javadoc documentation.

Basic IDE ConceptsBefore you start setting up your project, let's take a minute to get acquainted with some of the basic concepts involved with using the IDE.

The Filesystems Window

Page 4 of 58

The starting point for development in the IDE is the Filesystems window. The Filesystems window is where you organize your project contents, access and run commands on individual files, and view the structure of your source files. The Filesystems window contains all of the directories, packages, and archive files that you have added to your project. When you first run the IDE, the Filesystems window contains the NetBeans sample directory with some sample code. Each source file has its own Filesystems window node. These nodes have:q

q

Contextual Menu Commands - You can run commands on files by right-clicking them and choosing from the contextual menu. The commands that are available vary depending on the type of node you are working with. Properties - Choose Window > Properties (Ctrl-1) to open a contextPage 5 of 58

q

sensitive Properties window. The Properties window always shows the properties of the component in the NetBeans user interface that has the focus. If you want to open a persistent Properties window that only shows the properties of one Filesystems window node, right-click the node and choose Properties. If a property contains an ellipsis button (...), you can click the button to access a special property editors that you can use to define properties visually. Subnodes - You can expand most nodes in the Filesystems window to view subnodes representing the internl structure of the node's file. These subnodes often have their own properties and contextual menu commands.

The Filesystems window does not show a node for every file in a mounted directory. For example, for the compiled ColorPicker form object, the source directory contains the ColorPicker.java source file, the ColorPicker. form file used to build its GUI in the IDE, and the ColorPicker.class compiled class. The IDE hides .form and .class files by default, so only one node is shown for ColorPicker. You can also choose to hide files by type and extension.

Projects in the IDEA project is the basic unit of work in the IDE. It includes all the files with which you are working and the IDE settings that you apply to those files. The NetBeans IDE has a very straightforward projects system. You always have one project open at a time. Everything that is in the Filesystems window is part of the currently open project. You add directories and files to the project by mounting them as filesystems in the Filesystems window. Note: You do not have to create a new project for each application you are working on. You can add the source files for multiple applications to the Filesystems window and work on them at once. Each project, however, has only one classpath and set of IDE settings. Most IDE settings are applied at one of two levels: for the whole project or for individual files. Project-wide settings are managed in the Options window. You can open the Options window by choosing Tools > Options in the Main window. You configure settings on a file using the Properties window.

Page 6 of 58

When you open the IDE, the default project opens with some sample source mounted in the Filesystems window. If you do not need the examples, you can remove the sample filesystem by right-clicking the filesystem node and choosing Unmount Filesystem. You can also create an empty project by choosing Project > Project Manager and clicking the New button.

Accessing Source DirectoriesAs mentioned before, you access source directories and files in the IDE by mounting them in the Filesystems window. To mount a local directory as a filesystem, go to the Filesystems window, right-click the root Filesystems node ( ) and choose Mount > Local Directory.

Each project also contains some hidden filesystems that are added by the IDE. These filesystems contain the JDK sources which you can view in debugging sessions, common Java libraries, and Javadoc documentation libraries. You can view all of the filesystems in your project by right-clicking the root Filesystems node and choosing Customize. Note: If the sources you are working with are under version control, you can mount them as a VCS filesystem. VCS filesystems let you see files' versioning status and run VCS commands right in the Filesystems window. For more information, see Team Development With CVS.

Filesystems and the Java ClasspathMounting filesystems not only defines the contents of a project, it also defines the Java classpath for the project. Unlike in command-line development, the IDE ignores the CLASSPATH variable on your system and builds a unique internal classpath for each of your projects. This classpath is

Page 7 of 58

made up of all the mounted filesystems, including hidden filesystems and filesystems that are mounted by default by the IDE. Note: You can view all of a project's filesystems, including hidden filesystems, by rightclicking the root Filesystems node and choosing Customize. In general, whenever you want to add something to the classpath, you should mount it in the Filesystems window. This includes Java libraries (JAR files) that your code depends on (see Mounting Resource Libraries). You can also customize the classpath for various operations, like running, compiling, and debugging, using the filesystem's property sheet. Go to the filesystem's property sheet and set the Capabilities properties accordingly. For example, you should exclude filesystems that only contain Javadoc documentation from the classpath for running, compiling, and executing. In addition to building the classpath, mounting files in the Filesystems window also makes them available for other IDE tools such as code completion.

Correctly Mounting Java PackagesDirectories that contain Java source code must be mounted at the package root, which is the directory that contains the default package. The sources in the directories must be in packages corresponding to their position relative to the mount point. If a filesystem of Java sources is mounted at the wrong point, your source code will contain error markers in the Source Editor and will not compile.

Page 8 of 58

If you have multiple source trees with the package root of each tree grouped together under one directory, you have to mount each package root separately. For example, in the directory structure pictured on the right, src is the package root for the class com.myapp.MyApp.java and lib is the package root for the class com.mylib.MyLib.java. In this example, you cannot simply mount MyProject - you have to mount src and lib separately. You can add more than one directory at a time by holding down the Control key and selecting multiple directories in the Mount wizard.

Mounting Resource LibrariesIf your code depends on any resource libraries, you have to mount the libraries in order to add them to the project's Java classpath. Resource libraries can be contained in regular directories or, more commonly, in JAR files. You can mount a JAR file as a filesystem in the IDE by right-clicking the root filesystem node and choosing Mount > Archive File. Mounting a resource library also makes all of its contents available for code completion. If you do not need to browse through the files in your resource library, you can hide the filesystem by setting its Hidden property to True. Note: You can display a hidden filesystem by right-clicking the root Filesystems node and choosing Customize. In the customizer, select the hidden filesystem and set its Hidden property to False.

Advanced Project SetupNow let's look at a more complicated project structure and how to mount it correctly in the IDE. We will be discussing a few concepts we haven't gone over yet, but you can use the links in the text to jump ahead to any sections that you are not clear about. Here is the structure of our project: MyProject Page 9 of 58

myApp src // contains sources for myApp lib // contains binary libraries (JAR files) used by myApp myLib src // sources for a library used by myApp and other applications lib // contains binary libraries (JAR files) used by myLib build myApp // output dir for compiled classes for myApp myLib // output dir for compiled classes for myLib lib // contains binary libraries (JAR files) used by both myApp and myLib doc // contains generated Javadoc for the project First, mount the myApp/src and myLib/src directories as separate filesystems. These are our main development directories - except for the doc directory, they will be the only filesystems that are visible in our Filesystems window when we are done setting up our project. Next, mount the output directories for our classes, build/myApp and build/ myLib, as separate filesystems. There is no reason to keep the output directories visible in the Filesystems window, since you can execute files from their source nodes in the development directories. Hide the filesystems by setting their Hidden property to True. Now let's set up the compiler types that will place the compiled classes for myApp and myLib in the correct build directories. First, go to the Options Window and make a copy of External Compilation called myApp Compilation. To set this compiler type to store compiled classes in the build/myApp directory, set the compiler type's Target property to build/ myApp. Then create another copy of External Compilation called myLib Compilation and set its Target property to build/myLib. Now we are ready to assign our custom compiler types to the sources in our source tree. This is a bit tricky, since you cannot just select a filesystem or group of files in the Filesystems window and set the Compiler property for all of them. Instead, we will search for all Java objects in each filesystem and assign the compiler type from the Search Results window. First, choose Window > Properties (Ctrl-1) to open the Properties window. Then right-click the myApp/src filesystem and choose Find. Click the Type

Page 10 of 58

tab and select Java Source Objects, then click Search. The Search Results window returns all the Java source files in myApp/src. Select all of the sources, then in the Properties window set the Compiler property to myApp Compilation. Follow the same process to assign myLib Compilation to all the Java sources in myLib/scr. Next we can set up our Javadoc output directory. Mount the doc directory as a filesystem. In the filesystem's property sheet, set the Use in Execution, Use in Compiler, and Use in Debugger properties to False and set the Use as Documentation property to True. Then go to the Options window and set the IDE to use it as the default Javadoc output directory for the project. The directory will then house all of the Javadoc documentation you generate for the source you are developing. This documentation will also be available for Javadoc index searches in the IDE. Finally, mount your resource libraries in the Filesystems window. In our example, the libraries are stored in JAR files throughout our source tree, so you have to mount them with the Mount > Archive File command. If you do not need to browse through the code in these libraries, hide the filesystems so that they do not clutter up your Filesystems window.

Previous - TOC - Next

Page 11 of 58

Creating and Editing Java Source CodeUsing NetBeans IDE 3.6 Creating and editing Java source code is the most Previous - TOC - Next important function that the IDE serves. After all, that's probably what you spend most of your day doing. NetBeans Feedback IDE provides a wide range of tools that can compliment any developer's personal style, whether you prefer to code everything by hand or want the IDE to generate large chunks of code for you. This section covers the following topics:q

q

q

q

Creating Java files - Using the New wizard and the IDE's templates to create new files, GUI form templates versus Java source templates. Editing Java files in the Source Editor - Using code completion and abbreviations, generating bean properties and event listeners, working with import statements, search and selection tools, and formatting Java code. Navigating between documents - switching between open files, cloning the view of a file, and splitting the Source Editor. Configuring the Source Editor - customizing the Source Editor to fit your development style.

Creating Java FilesNetBeans IDE contains templates and wizards that you can use to create all kinds of source files, from Java source files to XML documents and resource bundles. The easiest way to create a file is to right-click the directory node in the Filesystem window where you want to create the file and choose from the New submenu in the node's contextual menu. The New submenu contains shortcuts to commonly-used templates and an All Templates command that you can use to choose from all NetBeans templates. To demonstrate some of the IDE's source creation and editing features, let's recreate the ColorPreview class that comes with the colorpicker example in the IDE's sample code. Right-click any directory in your mounted filesystems and choose New > Java Class. Name the file ColorPreview and click Finish. The file opens in the Source Editor.

GUI Templates and Java TemplatesIf you want to visually edit a Java GUI form using the Form Editor, you have to create the form's source file using the IDE's Java GUI Forms templates. This template group contains templates for AWT and SWING forms. For example, you cannot create a normal Java class file and then change it to extend JPanel and edit it in the Form Editor. The form must be created from the JPanel template.

Editing Java Files in the Source EditorThe Source Editor is your main tool for editing source code. It provides a wide range of features that make writing code simpler and quicker, like code completion, highlighting of compilation errors, syntax highlighting of code elements, and advanced formatting and search features.

Page 12 of 58

Although we talk about the Source Editor as one component, it is really a collection of editors. Each type of source file has its own editor that provides different functionality. In this section we'll be dealing with the Java editor, but many of the same concepts apply to other editors. To open a Java source file in the Source Editor, double-click the file's node in the Filesystems window. Note: Double-clicking a Java form node ( ) in the Filesystems opens two tabs in the Source Editor: a source tab containing the Java source code for the form, and a Form Editor tab showing the designtime view of the form. To edit the source code for a Java form without opening the Form Editor, rightclick its node and choose Edit.

Using Abbreviations, Word Matching, and Code CompletionThe Source Editor provides many features that spare you from having to enter long Java class names and expressions by hand. The most commonly used of these features are abbreviations, code completion, and word matching. Code completion in the Java Source Editor lets you type a few characters and then choose from a list of possible classes, methods, variables, and so on to automatically complete the expression. The Source Editor also includes a Javadoc preview window that displays the Javadoc documentation for the current selection in the code completion box, if any exists. The Javadoc is drawn from the compiled source files mounted in the IDE. Abbreviations are short groups of characters that expand into a full word or phrase when you press the space bar. For example, if you enter psfs and press the space bar, it expands into public static final String. For a full list of the IDE's default abbreviations, click here. You can also add your own custom abbreviations for each type of editor. In the Options window, select Editing > Editor Settings > Java Editor and open the property editor for the Abbreviations property. You can use the Abbreviations property editor to add, remove, and edit the abbreviations for Java files. Word matching is a feature that lets you type a few characters of a word that appears elsewhere in your code and then have the Source Editor generate the rest of the word. Type a few characters and press Ctrl-L to generate the next matching word or Ctrl-K to generate the previous matching word. As a quick exercise, let's make ColorPreview extend JPanel. Put the insertion point after ColorPicker in the class declaration, then type ex and press the space bar to expand the abbreviation into extends. Then type the first few letters of javax. The code completion box should pop up after a few seconds. If it does not, you can always manually open it by pressing Ctrl-Space.

Page 13 of 58

Use the code completion box to enter javax.swing.JPanel.

Configuring Code CompletionThe IDE maintains a code completion database which it uses to provide suggestions for code completion and other features. The code completion database contains classes from the J2SK version 1.4, other commonly used APIs like the Servlet and XML APIs, and the sources in all of the filesystems you have mounted in your project. Whenever you mount a filesystem, the IDE automatically adds all of the filesystem's public and protected classes to the project's code completion database. You can also right-click the filesystem and choose Tools > Update Code Completions to configure which of the filesystem's classes are available for code completion. In the Options window, you can disable and enable code completion and set the length of the pause before the code completion box appears in the Source Editor. Select Editing > Editor Settings > Java Editor and set the Auto Popup Completion Window property and the Delay of Completion Window Auto Popup property accordingly. You can also turn off the Javadoc preview box for code completion. Select Java Editor and uncheck the Auto Popup Javadoc Window property.

Adding Fields, Bean Properties, and Event ListenersEven if you prefer to write your code the old-fashioned way, the NetBeans Java editor has some cool code generation features that you may find handy, especially when dealing with bean properties and event listeners. Let's start by adding some of the fields for our colors in ColorPreview. Go to the first line after the class declaration and type in the following code: private int red; Now let's turn this ordinary field into a bean property by making some getter and setter methods for it. Right-click anywhere in the field declaration and choose Tools > Generate R/W Property for Field. The following code is generated in the file: public int getRed() { return red; } public void setRed(int red) { this.red = red; } The methods now show up under the Methods node. The Bean Patterns node now also contains a bean property node for red. Now let's add both the field and the get and set methods at the same time. In the Filesystems window, right-click the Bean Patterns node for ColorPreview and choose Add > Property. In the dialog, enter green for the name and int for the type, then check Generate Field, Generate Get Method, and Generate Set Method and click OK. The following code is added to the file: private int green;

Page 14 of 58

public int getGreen() { return this.green; } public void setGreen(int green) { this.green = green; } So far, so good. But to fully generate a working bean that can get and set the value of each of the color bean properties and notify the caller of its changes, we have to add event listeners to each of the set methods. There are two ways to do this. You could right-click the Bean Patterns node and choose Add > Multicast Event Source to add the java.beans.propertyChangeListener methods, then enter the rest of the source by hand. An easier way is to generate all of the necessary code when you create the bean properties. First, let's get rid of all of the methods and fields we have created so far. You can do so by deleting the nodes from the Filesystems window or just by deleting the code in the Source Editor. Next, right-click the Bean Patterns node and choose Add > Property. Enter red for the name, int for the type, and select the Bound checkbox. Now you can set the dialog to generate not just the field and methods for the property, but also the property change support code. Click OK to generate the following code in the Source Editor: private int red; private java.beans.PropertyChangeSupport propertyChangeSupport = PropertyChangeSupport(this); new java.beans.

public void addPropertyChangeListener(java.beans.PropertyChangeListener l) { propertyChangeSupport.addPropertyChangeListener(l); } public void removePropertyChangeListener(java.beans.PropertyChangeListener l) { propertyChangeSupport.removePropertyChangeListener(l); } public int getRed() { return this.red; } public void setRed(int red) { int oldRed = this.red; this.red = red; propertyChangeSupport.firePropertyChange("red", new Integer(oldRed), new Integer(red)); } Then all you have to do is repeat the process for the green and blue properties and change the ColorPreview constructor to the following: public ColorPreview() { propertyChangeSupport = new java.beans.PropertyChangeSupport(this); }

Page 15 of 58

And that's it! You've got a nice working bean ready to be used by the ColorPicker program.

Working With Import StatementsWhenever the IDE generates Java source code, it uses the fully qualified names for all the elements it creates. There are two tools that you can use to add import statements to your code and change between simple names and fully qualified names: the Fast Import command and the Import Management Tool. To use the Fast Import command, place the insertion point on any class name and press Alt-Shift-I. In the following dialog box, specify whether to import the class or the entire package. Unfortunately, the Fast Import command does not change all fully qualified names for the class to simple names. A more complete tool for handling import statements is the Import Management Tool (IMT). By default, the IMT changes all occurrences of fully qualified names into simple names and creates a single-name import statement for each. Right-click anywhere in the ColorPicker file in the Source Editor and choose Tools > Import Management Tool. The first page of the IMT shows any unresolved identifiers in your file. These can occur when you incorrectly enter the class name or when you are referencing code that you do not have mounted in your project yet. You can enter a new package name to import for the classes, or import the classes as they are written. At this point, you can click Finish immediately to run the IMT with its default settings. You can also click Next to further customize the tool's actions. For example, if you are importing several classes from a single package, you may want to import the entire package. You can do so on the Removed Unused Imports page of the wizard. Change the Action column for the package from Use SingleName Import to Use Package Import.

Page 16 of 58

Search and Selection ToolsWhen you are dealing with a large group of files, the ability to quickly find, navigate to, and select certain strings or files is critical to your productivity. The following list gives you a quick overview of the search and selection tools that are available in the Source Editor: Keyboard Shortcut Ctrl-F Description of Command Search for text in the currently selected file. The Source Editor jumps to the first occurrence of the string and highlights all matching strings. You can use F3 to jump to the next occurrence and Shift-F3 to jump to the previous. Replace text in the currently selected file. Find the next occurrence of the word you searched for. Find the previous occurrence of the word you searched for. Search for the next occurrence of the word that the insertion point is on. Turn off search result highlighting.

Ctrl-H F3 Shift-F3 Ctrl-F3 Alt-Shift-H

Page 17 of 58

Alt-Shift-O

Open the Fast Open dialog box, which lets you quickly open a file. Start typing a class name in the dialog box. As you type, all files that match the typed prefix are shown. The list of files is generated from the the project's mounted filesystems. Go to source. This shortcut opens the file where the item at the insertion point is defined. Go to declaration. Similar to the previous shortcut, this opens the file where the variable at the insertion point is declared. Go to line. Enter any line number for the current file and press Enter to jump to that line. Add a bookmark ( ) to the line of code that the insertion point is currently on. If the line already contains a bookmark, this command removes the bookmark. Go to the next bookmark. Go to the next location in the jump list for the currently selected file. The jump list is a history of all locations where you made modifications in the Editor. Go to the previous location in the jump list for the currently selected file. Go to the next jump list location in all files (not the currently selected file). Go to the previous jump list location in all files.

Alt-O Alt-G Ctrl-G Ctrl-F2

F2 Alt-L

Alt-K Alt-Shift-L Alt-Shift-K

Formatting Java Source CodeThe IDE automatically formats your code as you write it. You can automatically reformat specific lines of code or entire files. The following table lists some common formatting commands. Keyboard Shortcut Ctrl-Shift-F Ctrl-T Ctrl-D Ctrl-E Ctrl-Shift-T Ctrl-Shift-D Description of Command Reformat the entire file or whatever text is selected in the Source Editor. Shift the current line or selection one tab to the right. Shift the current line or selection one tab to the left. Remove the current line. Comment out the current line or all selected lines with line comments ("//"). Remove comments. This command only works for lines that begin with line comments ("//").

Navigating Between DocumentsThe Source Editor makes it easy to manage large number of open documents at one time. The Source Editor displays a row of tabs for open documents. The tabs appear in the order in which you opened the documents. You can grab any tab and drag it along the row of tabs to move its position. Use the left and right buttons in the top-right corner to scroll through the row of tabs.

Page 18 of 58

To switch between open files, do any of the following:q

q q

Use the drop down list at the top-right of Source Editor. The drop down list displays all of your open files in alphabetical order. Press Alt-Left and Alt-Right to move one editor tab to the left or right. Press Ctrl-` to open the IDE window manager, which contains icons for each open document in the Source Editor as well as all open windows like the Filesystems window.

You can also:q

q

q

q

Maximize the Source Editor. Double-click any document tab or press Shift-Escape to hide all other IDE windows. If you have split the Source Editor, only the partition you maximize is displayed. Clone a document. Right-click the document in the Source Editor and choose Clone Document. Split the Source Editor. Grabbing any document tab and drag it to the left or bottom margin of the Source Editor. A red box shows you where the new Source Editor partition will reside once you drop the document. Any Source Editor partition can also be split any number of times. Move documents between Source Editor partitions. Grab the document tab and drag it to the row of tabs in the destination partition.

Configuring the EditorTo configure Source Editor settings, open the Options window and expand Editing > Editor Settings. The Editor Settings node has subnodes for the editors used for each different file type. In this section, we will be looking at configuring the Java editor, but many of the settings are the same for all editors. Here is a quick overview of some of the more common customizations to the Source Editor:q

q

q

q q

q

q

q

View or change abbreviations. Open the property editor for the Abbreviations property and make any changes to the list. View or change all keyboard shortcuts for the IDE. Open the property editor for the Key Bindings property. View or change all recorded macros. Open the property editor for the Key Bindings property. Turn off code completion. Set the Auto Popup Completion Window property to False. Set the font size and color for code. Use the Font Size property to quickly change the font size for all Java code in the Source Editor. Open the property editor for Fonts and Colors to change the font and color of each type of Java code, like method names or strings. Change the indentation used in your code. You can switch between indentation engines by choosing a new engine from the Indentation Engine property. You can also configure each indentation engine by opening the property editor for the property. Set how many spaces are inserted for each tab in your code. Set the Tab Size property accordingly. Turn off Javadoc for code completion. Go to the Expert tab and set the Auto Popup Javadoc Window to False.

Previous - TOC - Next

Page 19 of 58

Compiling Java ProgramsBasic compilation is simple. You select the file or folder you want to compile and choose the appropriate Build or Compile command. The IDE then compiles the files using the compilation type you have specified for them. The NetBeans IDE also gives Using NetBeans IDE 3.6 Previous - TOC - Next Feedback

you tools to deal with more complex project compilation, such as JavaMake for dependency management and advanced compilation options for cross-compiling for different SDK versions. In this section you will learn about the following:q

TM

q

q

q

Compiling files - the behavior of the Compile and Build commands and viewing output from the compiler. Working with compiler types - which one to use, creating custom compiler types, setting the output target directory. Cross-compiling between Java platforms - specifying the compiler executable or libraries used in compilation. Using JavaMake to Manage Class Dependencies - managing complex dependencies between Java classes.

Compiling FilesTo compile a file or directory, select it in the Filesystems window and choose one of the following from the main window:q

q

q

q

Build > Compile (F9) to compile only those files that are new or have changed since the last compile. The up-to-date check is done by comparing timestamps between the source (.java) and products (.class) of the compile. This command does not compile the files in subfolders. Build > Compile All (Shift+F9) to compile only those files that are new or have changed since the last compile, including the files in subfolders. Build > Build (F11) to build all the selected files from source regardless of their up-to-date status. This command deletes the sourcename.class files in the folder and compiles the source files. This command does not remove .class files or compile source files in subfolders. Build > Build All (Shift+F11) to build all files from source within the selected folder and its subfolders .

Any compilation errors and output are displayed in the Output Window. In the Output Window you can:q q q

Click any error to jump to the location in the source file where the error occurred. Copy the output to the clipboard by right-clicking in the window and choosing Copy. Redirect the output to a file by right-clicking in the window and choosing Start Redirection of This View to File. The output is written to the output directory in your IDE's user directory. You can also choose a specific directory to redirect the output to under Output Window settings in the Options window.

Working with Compiler TypesNow that we've seen how compilation is initiated, let's look at how the NetBeans IDE defines the rules for how compilation is carried out. Compiler types are the IDE's main tool for specifying compilation options. To view and configure compiler types, go to the Options window and expand Building > Compiler Types.

Page 20 of 58

Internal Compilation compiles files within the same virtual machine as the IDE using the javac compiler of the IDE's default SDK. External Compilation spawns a new VM for compilation. While Internal Compilation is faster, External Compilation offers you greater configuration options. All other compiler types shipped with the IDE are basically copies of External Compilation that have been configured for different compiler executables. Additional IDE modules may insert their own compiler types, such as the RMI Stub Compiler from the RMI module.

Specifying the Compiler Type for Files and ProjectsYou can specify which compiler type is used for compilation at two levels:q

q

The project-wide default compiler type. Open the Options window, select Editing > Java Sources, and set the Default Compiler property. The compiler type for an individual file. Right-click the file in the Filesystems window, choose Properties, and set the Compiler property.

Creating Custom Compiler Types

Page 21 of 58

Each compiler type contains properties that affect how the compiler generates code, such as whether to generate debugging information and which libraries to use. You can configure compiler types in the Options window under Building > Compiler Types. Remember that when you change a compiler type's property, that property is changed for all files that use that compiler type. If you need to set different options for only some files in your project, you should make a copy of the compiler type with the desired configuration changes, then set the appropriate files to use this new compiler type. You can create a new compiler type with default settings by right-clicking the Compiler Types node in the Options window and choosing from the New menu. To copy an existing compiler type with all of its settings, right-click the compiler type and choose Copy. Then right-click the Compiler Types node and choose Paste > Copy. Note: You can also change compiler options from any Java source file node's property sheet. Just rightclick any Java source file node in the Filesystems window, choose Properties, and click the ellipsis (...) in the Compiler property. Remember, though, that the properties you change in the Compiler dialog box are applied to all files that use this compiler type.

Setting the Target Directory for .class FilesBy default, the IDE generates your compiled .class files to the same directory as the Java source files you are compiling. If you want to keep your .class files in a separate directory, first mount the target directory in the IDE. Because the compiler generates classes into subfolders of the class package, you only need to direct the output to the root of the filesystem. For example, in the figure on the right Digits.java is in the package com. mycompany. If you redirect the compiler output to the build directory, the compiler automatically generates the com and mycompany directories to house Digits.class. Once you have mounted the output directory, select the compiler type's node in the Options window. The Target property for the node contains a combo box with all mounted filesystems in your project. Select the output directory in the combo box. For more information on mounting complex project structures, see Advanced Project Setup.

Cross-Compiling Between Java PlatformsBy default, the IDE compiles sources against the JDK on which it is running. You may, however, want to compile an application to optimize it for a specific version of the Java platform. In this case, you will want to compile the sources against a specific Java platform's system libraries and possibly using a specific compiler version. For example, you might be developing an application that is designed to run on JDK 1.3 while running the IDE on JDK 1.4. In this case, want to configure the compiler type for your source files to use the JDK 1.3 compiler. To do so, select the compiler type type used by your source files (for example, External Compilation) in the Options window. Then click the ellipsis button in the External Compiler property. The External Compiler dialog box, shown below, opens.

Page 22 of 58

This dialog defines how the IDE makes calls to the compiler executable. The Process field points to the executor that is used. In this case, the Process field is using the {jdk.home}variable to point to your computer's default SDK. The Arguments field uses variables to insert the various compilation options that are defined for the compiler type, such as Debug or Optimize. To switch this compiler type to use a different Java platform's compiler executable, click the ellipsis button and browse to the executable, or type the absolute path to the executable in the field. Also, since you are not using the JDK 1.4 compiler, make sure to uncheck the Enable JDK 1.4 Source property. However, you might need to compile an application against an older JDK version without using the older JDK's compiler. For example, you might need to compile applets against JDK 1.1, but not want to use the JDK 1.1 compiler because of performance reasons. In this case, set the compiler type's Boot Class Path property to the desired Java platform libraries. Again, make sure the Enable JDK 1.4 Source property is unchecked.

Using JavaMake to Manage Class DependenciesWhen you compile Java classes, the compiler performs a basic dependency analysis on the classes you are compiling. The compiler looks for classes that the class being compiled is dependent on, checks if they are up-to-date as described above, and compiles any classes that are not up-to-date. For simple projects this is often enough. For code with complex dependency relationships, however, the normal Java dependency checking mechanism isn't enough. For examples of what kinds of dependency relationships are missed by javac, see http://www.experimentalstuff.com/Technologies/

Page 23 of 58

JavaMake/index.html. NetBeans IDE solves this problem by integrating JavaMake, a tool that provides more extensive dependency management between Java classes. You can enable JavaMake for all of your project's Java classes by selecting Editing > Java Sources in the Options window and checking the Use JavaMake property. The first time you compile a project with JavaMake, the IDE examines all of the classes in a project's mounted filesystems and records the dependency information in a project database. The IDE only records dependency information for filesystems which have compilation enabled. The IDE uses this information during compilation to perform a complete check for any dependent classes that need compilation. When JavaMake is enabled, the Compile and Build commands behave differently than when using normal compilation. The behavior of the commands is as follows:q

q

Compile/Build. Only compiles or builds the selected files without checking the status of dependent classes. Compile All/Build All. Compiles the selected file and checks all dependent classes. If any dependent classes are not up-to-date, the IDE compiles them. These commands effectively build or compile the entire project, regardless of which class they are run on

Previous - TOC - Next

Page 24 of 58

Debugging Java ProgramsNetBean's debugging features expand on the capabilities provided by the JPDA debugger. You can visually step through source code and monitor the state of watches, variables, strings, and other elements of your code's execution. In this section you will learn about:q

Using NetBeans IDE Previous - TOC - Next Example Code:q q

arrayFill.java sampleBean.java

Feedback

q

q

Basic debugging - Starting a debugging session, using the Debugger windows, and stepping through your code. Working with breakpoints - Adding and removing a breakpoint, different types of breakpoints, setting breakpoint conditions, and customizing the output of a breakpoint. Setting watches - Adding a watch or fixed watch to an object.

Basic DebuggingIn this section, we will use a simple example to demonstrate how to start a debugging session, step through your code manually, and monitor variables and method calls in the Debugging workspace. We will leave more advanced functions like setting breakpoints and watches for the following sections. Our example for this section is the arrayFill program. This program is very simple. It creates an array of sampleBeans, each one of which has two properties, firstName and lastName. It then assigns values to the properties of each bean and prints out the values. The first thing you want to do is run the program to see if it throws any exceptions. Open arrayFill.java and press F6 to execute it. The following output should appear in the Output window: java.lang.NullPointerException at arrayFill.loadNames(arrayFill.java:27) at arrayFill.main(arrayFill.java:34) Exception in thread "main"

Page 25 of 58

Starting a Debugging SessionWhen you start a debugging session in the IDE, the IDE compiles the files that you are debugging, runs them in debug mode, and displays debugger output in the Debugger windows. To start a debugging session, select the file that you want to debug and choose one of the following commands from the Debug menu:q

q

q

Start > Run in Debugger (Alt-F5). Runs the program until the first breakpoint is encountered. Step Into (F7). Starts running the program and stops at the first executable statement. Run to Cursor (F4). Starts a debugging session, runs the program to the cursor location in the Source Editor, and pauses the program.

Since you did not set any breakpoints in the example program, just select arrayFill in the Filesystems window and press F7. The IDE opens the file in the Source Editor, displays the Output window and Debugger windows, and stops just inside the main method.

Debugger WindowsLet's take a minute to look at the Debugger windows. The Debugger windows automatically open whenever you start a debugging session and close when you finish the session. By default, the IDE opens three Debugger windows: the Local Variables window, Threads window, and Call Stack window. You can open other Debugger windows by choosing from the Window > Debugger menu. When you open a Debugger window during a debugging session, it closes automatically when you finish the session. If you open a

Page 26 of 58

Debugger window when no debugging session is open, it stays open until you close it manually. You can arrange Debugger windows by dragging them to the desired location. The following table lists the Debugger windows. Name Local Variables Watches Shortcut Ctrl-Alt-1 Ctrl-Alt-2 Description Lists the local variables that are within the current call. Lists all variables and expressions that you elected to watch while debugging your program. Lists the sequence of calls made during execution of the current thread. Displays the hierarchy of all classes that have been loaded by the process being debugged. Lists the breakpoints in the current project. Lists the debugging sessions currently running in the IDE. Lists the thread groups in the current session. Provides session, threads, calls, and local variables in a single view.

Call Stack Classes Breakpoints Sessions Threads All in One

Ctrl-Alt-3 Ctrl-Alt-4 Ctrl-Alt-5 Ctrl-Alt-6 Ctrl-Alt-7 Ctrl-Alt-8

Stepping Through Your CodeYou can use the following commands in the Debug menu to control how your code is executed in the debugger:q

q

q

Step Over (F8). Executes one source line. If the source line contains a call, executes the entire routine without stepping through the individual instructions. Step Into (F7). Executes one source line. If the source line contains a call, stops just before executing the first statement of the routine. Step Out (Alt-Shift-F7). Executes one source line. If the source line

Page 27 of 58

q q

q

is part of a routine, executes the remaining lines of the routine and returns control to the caller of the routine. Pause. Pauses program execution. Continue (Ctrl-F5). Continues program execution. The program will stop at the next breakpoint. Run to Cursor (F4). Runs the current session to the cursor location in the Source Editor and pauses the program.

In our example, use the F7 key to step through the code one line at a time. The first time you press F7, you are presented with a dialog saying that the IDE couldn't find java. lang.ClassLoader. loadClassInternal in the mounted filesystems. If you want to be able to step through methods in the JDK as well, mount the JDK sources in the Filesystems window. Otherwise, use the Step Out option in this dialog to have the debugger execute the process without trying to open the file in the debugger. The NullPointerException occurred in the loadNames call, so when you step to that call, watch the value of the names array in the Local Variables view. Each of the beans have a value of null. You can continue stepping through the loadNames method - the names beans are null throughout. The problem here is that while the line sampleBean[] myNames=new sampleBean[fnames.length]; initiates the array that holds the beans, it does not initiate the beans themselves. The individual beans have to be initiated in the loadNames method by adding the following code in line 28: names[i]=new sampleBean();

Working With BreakpointsMost programs are far too big to examine one line at a time. More likely,

Page 28 of 58

you set a breakpoint at the location where you think a problem is occurring and then run the program to that location. You can also set more specialized breakpoints, such as conditional breakpoints that only stop execution if the specified condition is true or breakpoints for certain threads or methods. In this section, we will use the arrayFill program from the last example, so you will have to recreate the bug by commenting out the code you added above.

Setting a BreakpointIf you just want to set a simple line breakpoint, you can click the left margin of the desired line. A line breakpoint icon ( ) appears in the margin. You can remove the line breakpoint by clicking it again. For more complex breakpoints, use the New Breakpoint (Ctrl-Shift-F8) command in the Debug menu. The New Breakpoint dialog box lets you choose the type of breakpoint you want to create and set breakpoint options such as conditions for breaking or the information that the breakpoint prints to the Output window.

Setting Conditions for a BreakpointConditional breakpoints only stop execution if a specified boolean expression is true. If you want to set a conditional breakpoint, open the New Breakpoint dialog box and enter an expression in the Condition field. For example, open arrayFill.java, set the insertion point in the loadNames method call in the main method, and press Ctrl-Shift-F8. In the dialog box, enter myNames=null in the Condition field and click OK. The conditional breakpoint icon ( ) appears in the margin before the method call. Then press Alt-F5 to start debugging the program. The execution should break at the loadNames method call.

Page 29 of 58

Customizing the Output for a BreakpointIn the New Breakpoint dialog box, you can also specify what information is printed when a breakpoint is reached. Enter any message in the Print Text field at the bottom of the dialog box. You can use variables to refer to certain types of information you want displayed.

Breakpoint TypesThe following table lists the different breakpoint types that are available. Type Line Description You can break execution when the line is reached, or when elements in the line match certain conditions.

Page 30 of 58

Method

When you set a breakpoint on a method name, program execution stops every time the method is executed.

Exception You have several options for setting a breakpoint on an 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. Variable You can stop execution of your program whenever a variable in a specific class and field is accessed (for example, the method was called with the variable as an argument) or modified. You can break program execution whenever a thread starts, stops, or both. When you set a breakpoint on a class, you can stop the debugger when the class is loaded into the virtual machine, unloaded from the virtual machine, or both.

Thread Class

Setting WatchesA watch enables you to track the changes in the value of a variable or expression during program execution. To set a watch, select the variable or expression you want to set a watch on in the Source Editor, then right-click and choose New Watch (Ctrl-Shit-F7). You can also create fixed watches in the Watches view. While a normal watch describes the content of a variable, a fixed watch describes the object that is currently assigned to the variable. To create a fixed watch, right-click any item in the Local Variables or Watches view and choose Create Fixed Watch.

Previous - TOC - Next

Page 31 of 58

Packaging and Deploying Your ApplicationsThe standard tool used for packaging and deploying Java applications is the Java Archive (JAR) file format. JAR files are packaged with the ZIP file format. You can use JAR files for simple compression and archiving of your application class files, or you can specify more advanced options like signing and verifying your JAR files or making them runnable. The IDE provides several features that help you to easily create and work with JAR files. This section covers the following topics:q

Using NetBeans IDE 3.6 Previous - TOC - Next Example Code:q

NetBeans example code (ZIP)

q

q

Feedback Creating a JAR File - Using JAR recipes to specify JAR file contents and properties, creating a manifest, creating and mounting the JAR file. Modifying a JAR File - Adding and removing files to an existing JAR file, making changes to the manifest, and setting custom file filters. Executing a JAR File - Specifying the main method in the manifest and executing your application.

Creating a JAR FileTo create a JAR file in the IDE, you first create a JAR recipe that specifies the contents and properties of the JAR file. You then create the JAR file itself by running the Compile command on the JAR recipe file. In this example we will create a JAR file using the example sources that are automatically mounted in the IDE when you first start the IDE. If you have lost or deleted the example sources, you can download them using the link above.

Creating a JAR RecipeTo create a JAR recipe, choose File > New from the Main window. In the wizard, expand the JAR Archives node, choose JAR Recipe, and click Next. In the second page of the wizard, specify the name and location of the JAR file you are going to produce. The third page of the wizard is where things start getting interesting. This is where you specify the contents of the JAR file. Select any directory or file from the panel in the left of the wizard and use the Add button to schedule it for inclusion in the panel on the right. The panel on the left shows all of your mounted filesystems. At this point you can click Finish to create the JAR recipe, or click Next to specify more detailed options.

Page 32 of 58

The fourth page of the wizard lets you set special options for the JAR file contents. The most important part of this page is the Target Directory column, which shows the directory structure of the JAR file's contents. For Java sources, the directory structure must correctly match the Java package structure of the Java classes. If the filesystem from which you added the contents was correctly mounted at the Java package root, this should automatically be configured correctly. For example, the target directory for our examples.colorpicker.ColorPicker class is correctly set at examples/colorpicker. Finally, the fifth page of the wizard lets you generate the manifest file for the JAR file. The JAR manifest file contains meta information for handling the files contained in the JAR file, such as the location of the main method or signing information. For more information about the JAR manifest file, click here.

In the JAR Manifest page of the wizard, you can generate basic manifest information automatically, enter information by hand, or use an existing file as the manifest file. For now, let's just enter the basic manifest information by clicking the Generate button. Then click Finish to create the JAR Recipe.

Page 33 of 58

The JAR recipe node appears in the Filesystems window, as shown in the figure on the right. The JAR recipe node includes a subnode for the JAR file it creates and a Contents subnode listing all of the JAR recipe contents. You can use the property sheet to modify the contents and properties of the JAR recipe, such as the compression level and file filter used to produce the JAR file. To open the property sheet, right-click the JAR contents node and choose Properties.

Compiling and Creating the JAR FileOnce you have created a JAR recipe, you can compile its contents and create the JAR file by right-clicking the JAR recipe and choosing Compile. The contents of the JAR file are compiled using whatever compiler types and settings you assigned to them in the IDE. See Compiling Java Programs for more information on compilation settings.

Mounting and Checking the JAR FileIf you want to check your JAR file to make sure that the directory structure and manifest file are correct, you can mount the JAR file in the Filesystems window. To mount the file, right-click the JAR recipe node or the JAR file node under it and choose Mount JAR. You can then expand the JAR file to view its contents and execute any executable classes it contains. Mounting a JAR also adds it to the project's classpath.

Modifying a JAR FileOnce you have created a JAR recipe, you can modify all aspects of the JAR file that it produces. Your main tool for modifying a JAR recipe is its property sheet. You can open the property sheet by right-clicking the JAR recipe node and choosing Properties. Whenever you modify the JAR recipe, you can update its corresponding JAR file with your changes by recompiling the JAR recipe. Note: If you make any changes to the JAR recipe and recompile the JAR file, these changes are not reflected in the mounted JAR file. You have to unmount the JAR file and mount it again to view the changes.

Adding Files to a JAR RecipeYou can add files to a JAR recipe using the Contents property in the JAR recipe's property sheet. The Contents property editor lets you add files and directories to the JAR recipe like you do in the JAR Recipe wizard. The Chosen Content pane on the right also contains the Target Directory and Target Name info, so you can check that the JAR file's directory structure is correct.

Page 34 of 58

In our case, we want to add the entire colorpicker directory to the JAR recipe, since the ColorPicker application will not work without the other classes in the directory. To do so, select the directory and click Add. Then click OK and recompile the JAR recipe to update the JAR file.

Modifying the Manifest FileTo modify the manifest file, open the property sheet for the JAR recipe node and click the ellipsis button for the Manifest property. The Manifest property editor is basically the same as the Manifest page in the JAR Recipe wizard. You can enter the manifest information by hand, generate the basic information using the Generate button, or use an existing manifest file using the Load From File button.

Setting the JAR Content FilterUse a JAR recipe's File Filter property to specify which types of files should be included in your JAR file. When you create a JAR 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 JAR filter does this for you by excluding all .java, .jar, and .form files from your JAR file. In the File Filter property editor, you can also set the filter using a POSIX-style regular expression. The Regular Expression field checks your expression's syntax and displays any invalid expressions in red text. The custom filter is stored in the JAR recipe file, so you can use or edit the filter if you later modify the JAR. The table on the right provides some examples of regular expressions you can write. For a guide to regular expression syntax, click here. Regular Expression \.html$ \.java$ (\.html$)|(\.java$) (Key)|(\.gif$) Description Include all HTML files Include all Java files Include all HTML and Java files Include all GIF files and any files with Key in their name

Executing a JAR FileIn order to execute a JAR file, you must first specify the JAR file's main class in the manifest. If the sources in your JAR file depend on sources located in other JAR files, the manifest must also contain the classpath to those JAR files. It is not enough to have the JAR files mounted in the IDE, since the IDE classpath is ignored when running a JAR file. To make the example JAR file runnable, open the Manifest property editor for its JAR recipe and add the following line: Main-Class: examples/colorpicker/ColorPicker Then compile the JAR recipe to produce the new JAR file. You can then run the JAR file by right-clicking the JAR recipe node and choosing Execute. The ColorPicker application should open in a new window.

Page 35 of 58

Previous - TOC - Next

Page 36 of 58

Using JavadocJavadoc is the Java programming language's tool for generating API documentation. Java API documentation describes important elements of your code, such as methods, parameters, classes, fields, and so forth. You can insert special Javadoc comments into your code so that they will be automatically included in the generated documentation. Describing your code within the code itself rather than in a separate document helps to keep your documentation current, since you can regenerate your documentation as you modify it. In this section, you will learn about the following:q

Using NetBeans IDE 3.6 Previous - TOC - Next Example Code:q

NetBeans example code (ZIP)

Feedback

q

q

Integrating Java API documentation into the IDE - Searching for and displaying Javadoc, mounting and configuring Javadoc filesystems, configuring the IDE's Web browser to display Javadoc files, and integrating Javadoc with code completion. Adding Javadoc comments to your code - Rules and special tags for Javadoc comments, tools for automatically commenting your code, and correcting errors in comments. Generating Javadoc documentation - Using the standard Javadoc doclet, initializing generation, and specifying the output directory for the generated files.

Integrating Java API Documentation into the IDEThe IDE lets you integrate API documentation for the code you are working on into the IDE itself. You can then quickly bring up the documentation for any classes in your code or even when you're looking for a particular class or method in the code completion box. The referenced API documentation can be stored in an archive file, regular directory, or on the Internet.

Making Javadoc Documentation Available in the IDEIn order to make Javadoc documentation available in the IDE, you must mount the documentation as a Javadoc filesystem. A Javadoc filesystem is any directory, archive file, or location on the Internet that contains API documentation. You mount Javadoc filesystems in by choosing Tools > Javadoc Manager from the main window. Use the Add buttons to add the appropriate type of Javadoc filesystem. You must mount each filesystem at the directory that contains the Javadoc index, which is located in a document called index.html file or a directory called index-files. (Sometimes both an index file and an index directory are present). The directory that contains the Javadoc index is usually called api or apidocs. For example, if you want to make the NetBeans Execution API documentation available directly from the netbeans.org portal, click Add HTTP and enter http://www.netbeans.org/download/dev/javadoc/ ExecutionAPI/.

Page 37 of 58

For each filesystem, you can specify the following:q

q

q

Hidden. Specifies whether this filesystem is visible in the Filesystems window. You should set this property to False if you want to browse through the documentation tree in the Filesystems window. Search Engine. Specifies the default Javadoc search engine. The Japanese version of the search engine lets you to search internationalized Javadoc documentation. Root Offset. If your Javadoc documentation is inside a JAR or zip file, the Javadoc index is sometimes buried in the file's hierarchy. Since you can only mount the JAR or zip file as a whole, you have to set the Root Offset for these filesystems to the directory that contains the Javadoc index. (For HTTP and local filesystems, you just mount the filesystem directly at the directory that contains the Javadoc index.)

Searching and Displaying Javadoc DocumentationThe easiest way to search for Javadoc documentation for any element of Java code is to select any occurrence of the element in the Source Editor and press Shift-F1. Doing so opens the Javadoc Index Search in a Source Editor tab. The Javadoc Index Search tab displays all matching entries in your mounted Javadoc filesystems. Select any search result to view the Javadoc in the bottom panel of the dialog box, or double-click a search result to open it in the IDE's external browser.

Page 38 of 58

If you prefer to browse through your Javadoc filesystem hierarchy, choose the Javadoc filesystem from the View > Documentation Indices menu. The filesystem's index page is opened in your external web browser.

Configuring the External Browser to Display Javadoc FilesJavadoc files are displayed in the IDE's designated web browser. To set the IDE's designated web browser, choose Tools > Setup Wizard and choose a browser from the Web Browsers combo box. The Setup Wizard lists all of the web browsers installed on your system.

Page 39 of 58

If you select a web browser and it does not open correctly, it is possible that the IDE does not have the correct location for the browser executable. You can configure the web browser by opening the Options window, expanding IDE Configuration > Servers and External Tool Settings > Web Browsers and selecting the web browser. Open the property editor for the Browser Executable property, then click the ellipsis button for the Process field to locate your browser executable. Then click OK to exit the dialog box. If your Web browser uses a proxy to access the Internet from behind a firewall, you must also configure the browser to bypass the proxy for local files. If this option is not set, you could get a 404 File Not Found error when you try to display Javadoc files that reside on your local machine.

Adding Javadoc Comments to Your CodeJavadoc comments are special comments (marked by a /**, as opposed to a /* for regular comments) that describe your code. When you generate Javadoc documentation for a source file, all of the Javadoc comments in the file are automatically included in the documentation. You can put special tags describing elements of your code in Javadoc comments and format your comments with XHTML tags. The IDE provides an Auto Comment tool that analyzes your code for any elements that have incomplete or incorrect documentation and lets you enter the documentation right in the tool. To see how the Auto Comment tool works, let's use it on one of the example files that comes with the IDE. In the IDE's default project, go to the examples/colorpicker directory and double-click the ColorPreview Java file node to open the file in the Source Editor. The ColorPreview class is a simple bean that sets the background color for a visual component to various

Page 40 of 58

colors. The code is already completely documented, so to see how the Auto Comment tool works let's first put some errors in the documentation. In the comment above the addPropertyChangeListener method, remove one of the stars (*) to change it from a Javadoc comment to a regular comment. Now right-click anywhere inside the Source Editor and choose Tools > Auto Comment. The Auto Comment tool shows all of the methods in the file that should be commented in the top left of the tool. You can use the buttons above this field to choose which methods are processed by the tool.

As you can see, all of the methods in the file have the green "correct Javadoc" icon except for addPropertyChangeListener, which has a red "missing Javadoc" icon. Select addPropertyChangeListener to see what problem the tool found with the method's comment. Use the View Source button to jump to the line in the Source Editor where the method first appears and the Refresh button to rescan the file for incorrect comments. You can add Javadoc comment text and tags in the right side of the tab.

Generating Javadoc DocumentationOnce you have entered Javadoc comments into your code, you can generate the HTML Javadoc files for your source files. The Java language uses a program called a doclet to generate and format the API documentation files. Although there are numerous doclets that produce documentation in a wide variety of formats, the standard doclet used by the IDE generates HTML documentation pages. To generate documentation, right-click any file or folder and choose Tools > Generate Javadoc. By default, the doclet generates the documentation files to the javadoc directory in your user directory. The doclet generates the Javadoc index files (including frame and non-frame versions, package lists, help pages explaining how the documentation is organized, and so forth) into the javadoc directory. Individual files describing each class are generated into subdirectories that match the directory structure in your source tree. For example, if you run the

Page 41 of 58

Generate Javadoc command on the sampledir filesystem, the javadoc directory contains the Javadoc index for the filesystem and a directory called examples with all of the individual documentation files.

Specifying an Output Directory for Javadoc FilesYou can specify any mounted filesystem as the output directory for generated Javadoc files. For example, if you want to create a docs directory to house API documentation for sources in the sampledir filesystem, create the docs directory somewhere on your system and mount it in the IDE. Then go to the Options window, select Code Documentation > Doclets > Standard Doclet, and choose the docs directory in the Destination property.

Previous - TOC - Next

Page 42 of 58

Team Development With CVSUsing NetBeans IDE 3.6 Version control software (VCS) programs track the changes to a set of files Previous - TOC - Next and manage how users access and change those files. A VCS is an essential tool for any team of developers that works on a common code Feedback base. It lets you roll back any unwanted changes, avoid conflicts when two developers alter the same file, and establish different development branches on the same codeline. NetBeans IDE integrates VCS functionality right into the IDE itself, letting you view versioning status and run VCS commands on files in the Filesystems window. The IDE uses VCS profiles to pass commands and arguments to the VCS executable on your machine. Profiles for Concurrent Versioning System (CVS), Visual Safe Source (VSS) and Polytron Version Control System (PVCS) are included in the IDE, and you can download experimental profiles for other VCS programs from the netbeans.org website. The IDE also includes a built-in CVS executable that you can use without having CVS installed on your computer. In this section, we will cover the basics of using CVS in the IDE. Although command usage differs between VCS applications, many of the concepts discussed here are common to all VCS applications. This section covers:q

q

q q

Checking Out Sources - Mounting CVS filesystems, selecting which sources to check out, and running CVS commands. Configuring a CVS Filesystem - Configuring CVS filesystems and changing the display of file status information. Working With CVS Files - Generating diffs and patches, applying patches, and resolving merge conflicts. Making Safe Commits - Finding all modified files in your working directory, checking for mistakes, committing your changes.

Checking Out SourcesLike all source files, you have to mount version controlled sources in the Filesystems window to be able to work with them. You mount version controlled sources in a VCS filesystem. A VCS filesystem is just like a regular IDE filesystem, except that it is directly linked to the VCS repository so you can use it to call VCS commands right in the Filesystems window. You can mount a source directory that is already under version control, or mount an empty directory and check out source files from the CVS repository. To illustrate how to check out sources in the IDE, let's check out the Beans module from the NetBeans CVS repository. We will use the anoncvs guest account, so you do not have to worry about registering with netbeans.org to complete this example.

Mounting a CVS FilesystemTo get started, choose Versioning > Mount Version Control from the main window. In the wizard, select CVS in the Version Control System Profile combo box.

Page 43 of 58

Now you can start filling in the CVS repository information. First, you need to create a directory to house the sources. Click the Browse button in the Working Directory field and create a directory called beans somewhere on your system. Then fill in the following CVS server information:q q q q q

CVS Server Type - pserver CVS Server Name - cvs.netbeans.org CVS Server User Name - the anonymous login name, anoncvs CVS Repository - the location of the sources on the repository server, /cvs Use Built-In CVS Client - sets which CVS client the IDE uses

Before you finish mounting the CVS filesystem, you have to log in to the server. Click the Login button without entering a password. . (No password is necessary for the anoncvs account.) If the command succeeds, the text beneath the Password field changes to You are already logged in. If the command fails, check your connection to the Internet and your firewall settings.

Page 44 of 58

Note: To use CVS, you must be able to access the Internet on the CVS port (2401 by default). Click Finish to close the wizard and mount the filesystem. A new CVS filesystem node appears in the Filesystems window. Now that you have mounted the filesystem, you can get the sources from the repository. Right-click the filesystem node and select the CVS submenu. This submenu contains CVS commands that you can run on your files. Hold down the Ctrl key and choose Checkout from the CVS menu. The CVS Checkout dialog box lets you set advanced options for the CVS Checkout command. The "." in the Module(s) field indicates that you want to check out the entire CVS repository. Since we only want to check out the Beans module, enter beans in this field and click OK. Alternatively, you can click the Select button to view a list of all modules in the repository and then select from the list. Once you run the command, the VCS Output window opens listing the CVS command status and the CVS output. You can kill the command by clicking the Stop button. When the command finishes, you can expand the filesystem and begin working with the files.

Specifying Advanced Command OptionsThe IDE's CVS support lets you set all of the command options that are available on the command line. To see a command dialog in which you can specify advanced command options, hold down the Ctrl key when choosing a command from the CVS commands menu. You can also configure a VCS filesystem to always display the advanced options dialog of CVS commands. Right-click the filesystem's node in the Filesystems window and choose Properties, then set the filesystem's Advanced Command Options property to True.

Configuring a CVS FilesystemOnce you have checked out your files, you can usually start working with them immediately. You may, however, need to further configure the filesystem to correctly build the Java classpath or display VCS status information. The two main tools for configuring a CVS filesystem are the VCS filesystem customizer, in which you can change the server and user information that you entered when mounting the filesystem, and the filesystem's property sheet. Right-click the filesystem and choose Customize to view the filesystem's customizer, or choose Properties to view the filesystem's property sheet.

Page 45 of 58

Setting the Relative Mount PointLike all Java filesystems in the IDE, CVS filesystems must be mounted at the directory that contains the default package. In order for all your VCS commands to function correctly, however, the filesystem must be mounted at the working directory root. You can resolve this problem by mounting the filesystem at the working directory root, then setting the relative mount point at the default package root. For example, the default package for the sources in the Beans filesystem is in the src directory. To set the relative mount point, right-click the filesystem node and choose Customize. Click the Select button in the Relative Mount Point field, expand beans, and select src. Then click OK to apply your changes. If you want to mount more than one directory as a default package root, hold down the Ctrl key, select all of the relative mount points, and click OK. Each relative mount point is mounted as its own filesystem.

Shortening and Hiding File StatusExpand the Beans filesystem to take a look at how NetBeans IDE displays CVS status information. The name of each file is followed by the file's status, its revision number, and if you are working on a branch also the branch tag name. If you double-click a file to open it in the Source Editor, you will notice that the CVS status information is also printed on the file's Source Editor tab. This status information can actually be problematic, because it makes the Source Editor tabs take up a lot of room. One solution is to set Shorten File Statuses to True in the filesystem's property sheet . This option saves some space, but not very much. As you can see, the IDE also displays a badge for each file that expresses its CVS status. The badges and their meanings are shown in the table below. Badge Description For the most part, you probably just want to know whether a file is up-to-date or not. You can therefore hide all file status information and just use the badges. If you need to Locally modified see more versioning information, like the file's version number or sticky tag information, you can always run the CVS Status command on the file. Locally removed To hide all status information, open the filesystem's property sheet and click the ellipsis in the Annotation Pattern property. The Annotation Pattern property editor shows a node Merge conflict for each type of CVS status information, plus subnodes that govern how the information is displayed. Simply delete each node (except the Variable:filename node, of course) Needs checkout and click Apply Changes. If you find that you miss the status info, you can always display it again by opening this dialog box and clicking Restore Defaults. Up-to-date

Working With CVS FilesOne of the main advantages of CVS is that it lets you see how your files evolve as you and members of your development team make changes to them. NetBeans IDE expands on this functionality by making it easier to view changes to files and resolve conflicts between file revisions. It also makes it easier to prepare your checkins and check for mistakes before you commit.

Using the Graphical Diff ToolWhen diff version-controlled files on the command line, the diff command compares two file revisions and prints out the differences between the two revisions along with the line numbers where they occurred. Although many command-line users are adept at reading long diff print outs, new users (and even some command-line veterans) often find this format confusing.

Page 46 of 58

NetBeans IDE uses a graphical diff viewer to display both file revisions side-by-side with the differences highlighted. The repository version is shown in the left pane, and your working file is shown in the right pane. You can use the buttons in the top left-hand corner of the viewer to navigate through the revision differences.

To run a graphical diff on a file, right-click it in the Filesystems window and choose CVS > Diff Graphical. If you run the command without any advanced options specified, it compares your working directory version with the head revision in the repository. If you want to specify which revisions to diff by tag name or date, hold down the Ctrl key while choosing the command and enter the information in the advanced command dialog. Unlike the Diff Textual command, you cannot run the Diff Graphical command on a directory. You can, however, select several files in the Filesystems window and run the Diff Graphical command on them. The diff for each file appears in its own Source Editor tab. As we will see in the Making Safe Commits section, you can also use the Search Results window as a powerful tool to find and diff all Locally Modified files in a filesystem.

Creating and Applying PatchesA patch file lets you take a snapshot of the changes between two revisions and send them to another developer without checking in the changes or even requiring the other developers to have a CVS connection to the repository. Patch files are often used when a development team wants to evaluate a proposed change before checking it into the repository. To create a patch, right-click the directory or file you want to create the patch from and choose CVS > Diff Textual. Click OK without specifying any options if you want to diff your working directory against the current head revision in the repository, or enter any additional options like specific tags or dates.

Page 47 of 58

The patch is displayed in the VCS Output window. Right-click inside the VCS Output window and choose Save to File, then specify a location and name for the file. To apply a patch file, right-click the exact file or directory from which the patch was created and choose Tools > Apply Patch. Then browse to the location of the patch file and click OK. If you want to undo the changes made by the patch, you can delete the modified files and then run the Update command to get a clean version from the repository.

Resolving Merge Conflicts GraphicallyWhen you update a locally modified file, CVS merges changes from the repository with the changes you have made to your local file. If someone else on your development team has committed changes to the same lines that you have changed in your working directory, a merge conflict occurs. CVS marks merge conflicts by bracketing the offending lines with error markers (>>). In the following example, the changes to the field name have generated the merge error. The first line of the error shows what you have in the working directory, and the second line shows what is in the repository. > 1.2 Normally, you would open the file in a text editor, delete the error markers and the version you do not want to keep, and commit the file. (You do not necessarily have to choose one of the two versions - you could write something completely new.) As long as the error markers are present in the file, CVS will not let you check it into the repository. The IDE provides a Merge Conflicts Resolver that makes resolving merge conflicts easier. To open the tool, rightclick any file whose status is Merge Conflict and choose Resolve Conflicts. The Merge Conflicts Resolver looks very similar to the Graphical Diff tool - it displays the repository revision on the right, working revision on the left, and the final version in the bottom.

Page 48 of 58

Use the Accept buttons to choose which of the two versions you want to accept. You can use the Accept & Next buttons to resolve a conflict and jump to the next conflict. You cannot write into the bottom panel of the Merge Conflicts Resolver, so if you want to write something new rather than accepting either of the two versions, close the dialog and resolve the conflict manually in the Source Editor.

Making Safe CommitsCVS lets you roll back most changes to the repository, so for the most part you do not have to worry about your commits doing permanent damage to your project. Still, introducing code that breaks your project's build process or introduces critical bugs is embarrassing and time-consuming to fix. This can often happen not because your code contained bugs, but because you forgot to check something in or checked something in that you did not mean to. You can make sure your commits are safe by following these simple steps: 1. Update your sources. Always make sure that the sources in your working directory match what is presently in the repository. To update sources, right-click any CVS filesystem node or folder node and choose CVS > Update. 2. Search by VCS status. Right-click the CVS filesystem node and choose Refresh Recursively to make sure all file status information is current. Then right-click the CVS filesystem node and choose Find. Click the Status tab, select Up-To-Date, and select the Match Only Files That Do Not Meet the Selected Criteria check box. Click OK to list all files that are not up-to-date in the Search Results window. You can then run all your CVS commands from the Search Results window. 3. Remove any unwanted files from the search results. Make sure the Search Results window only contains those files you want to commit. You can remove any file from the Search Results window by right-

Page 49 of 58

clicking it and choosing Remove From Search. r For Merge Conflict files, right-click and choose Resolve Conflicts. r For Local or Unknown files, make sure the files don't belong in the repository. If they do belong in the repository, add them by right-clicking them and choosing CVS > Add. The files' status changes to Locally Added - they will be added when you perform your commit. r For any Locally Removed or Locally Added files, make sure you really want to remove or add the files from the repository. r For any Needs Merge, Needs Patch, or Needs Update files, update the files by right-clicking them and choosing CVS > Update. 4. Diff your files. Select all of the files in the Search Results window and run the Diff Graphical command on them. Examine your changes in the Diff Viewer to make sure nothing slipped in by mistake. 5. Build and run your project. The best way to make sure that your changes will not break the build is to build your project and quickly test it for any obvious bugs. 6. Commit your changes. Finally, you're ready to commit your changes to the repository. Select all of the files in the Search Results window, right-click the files, and choose CVS > Commit. Type a description of your changes in the Commit dialog box and click OK.

Previous - TOC - Next

Page 50 of 58

Configuring the IDEOne of the main strengths of NetBeans IDE is its versatile configurability. You can customize your working environment to fit your needs and personal development style. Having all of these options can, however, make it difficult to find the exact setting you are looking for. In this section you will learn about the following:q

Using NetBeans IDE 3.6 Previous - TOC Feedback

q

q

Setting IDE default settings - Using the Options window and startup switches, setting general settings for Java source files, and dealing with unknown file types. Enabling and disabling functionality - Turning modules on and off and downloading new modules from the Update Center. Boosting NetBeans performance - Getting better performance using startup parameters, disabling modules, and manually initializing garbage collection.

Setting IDE Default SettingsThe main tool for configuring default settings in the IDE is the Options window. You can open the Options window by choosing Tools > Options.

IDE settings are grouped under Options window nodes in the left panel of the window. Select any node to set