NetBeans The Definitive Guide (Tim Boudreau, Jesse Glick, Simeon Greene etc.) (Z-Library)

Table of Contents NetBeans: The Definitive Guide By Tim Boudreau, Jesse Glick, Simeon Greene, Vaughn Spurlin, Jack J. Woehr Publisher : O'Reilly Pub Date : October 2002 ISBN : 0-596-00280-7 Pages : 672 In NetBeans: The Definitive Guide, you'll find out how to use this IDE to its fullest, making your Java programming more efficient and productive than ever before. You'll understand the basics of the IDE, and quickly be utilizing the various editor and explorer windows. You'll also master many of NetBeans advanced features, and be working with XML documents, CVS repositories, Javadoc trees, and web applications, all within the NetBeans framework. TE AM FL Y Team-Fly®

ii Table of Content Table of Content .................................................................................................................. i Preface .............................................................................................................................. viii Is NetBeans for You? ................................................................................................. viii Is This Book for You? ................................................................................................. viii NetBeans and Java ...................................................................................................... ix NetBeans as the "Visual JDK" .................................................................................... xi NetBeans as a Tools Platform ................................................................................... xii NetBeans as an Open Source Community .............................................................. xii Contents of the Accompanying Sources ................................................................. xiv Licensing of the Code Examples in This Book ....................................................... xiv Writing Conventions in This Book............................................................................. xiv Comments and Questions ......................................................................................... xiv Acknowledgments ........................................................................................................ xv Chapter 1. Getting and Installing the IDE ....................................................................... 1 1.1 Platforms and Requirements ................................................................................. 1 1.2 Getting and Installing a JDK .................................................................................. 2 1.3 Which IDE Distribution?.......................................................................................... 3 1.4 Installing Binary Distributions ................................................................................ 5 1.5 Building the IDE from Source (Simple Builds) .................................................... 5 1.6 Running the IDE ...................................................................................................... 8 1.7 Updating the IDE Automatically .......................................................................... 14 1.8 You're Now Running NetBeans........................................................................... 15 Chapter 2. Concepts and Paradigms ............................................................................ 16 2.1 NetBeans and the Java Abstract Model of Computing.................................... 16 2.2 Explorer................................................................................................................... 17 2.3 Creating Packages and Classes ......................................................................... 33 2.4 Services .................................................................................................................. 36 2.5 Workspaces............................................................................................................ 38 2.6 Project Management............................................................................................. 40 2.7 Object Browser ...................................................................................................... 42 2.8 Summary................................................................................................................. 45 Chapter 3. Working with the Source Editor .................................................................. 46 3.1 Why Learn a New Editor? .................................................................................... 46 3.2 Opening the Source Editor................................................................................... 46 3.3 Context Menus ....................................................................................................... 47 3.4 Closing the Source Editor .................................................................................... 47 3.5 Code Completion................................................................................................... 47 3.6 Editor Colorings ..................................................................................................... 51 3.7 Shortcuts................................................................................................................. 52 3.8 Word Matching....................................................................................................... 52 3.9 Indentation Engines and Code Formatting ........................................................ 52 3.10 Automatic Edits.................................................................................................... 53 3.11 Other Editor Functionality .................................................................................. 54 3.12 A Simple Example............................................................................................... 55 Chapter 4. Debugging...................................................................................................... 58 4.1 Debugger Types .................................................................................................... 58 4.2 Breakpoint Types................................................................................................... 59 4.3 Adding and Removing Breakpoints .................................................................... 60 4.4 Setting Watches..................................................................................................... 63 4.5 Starting the Debugger........................................................................................... 63 4.6 The Debugger Window ......................................................................................... 65 4.7 The Variables View ............................................................................................... 66

iii 4.8 Remote Debugging in NetBeans ........................................................................ 67 Chapter 5. Compilation and Execution Services ......................................................... 70 5.1 Using Custom Compilation and Execution Services........................................ 70 5.2 Associating Services with Java Files.................................................................. 77 5.3 Building with Ant .................................................................................................... 77 Chapter 6. Customizing the Environment..................................................................... 82 6.1 The Setup Wizard.................................................................................................. 82 6.2 The Tools Options Dialog ............................................................................... 85 6.3 Configuring Toolbars............................................................................................. 86 6.4 Configuring Menus ................................................................................................ 87 6.5 Configuring Editors................................................................................................ 88 6.6 Command Line Options........................................................................................ 95 6.7 Modules................................................................................................................... 96 Chapter 7. Using Source Control (CVS) ..................................................................... 100 7.1 What Is CVS?....................................................................................................... 100 7.2 The How, When, and Why of CVS in NetBeans............................................. 102 7.3 Mounting CVS Sources ...................................................................................... 104 7.4 Exploring Versioned Sources ............................................................................ 105 7.5 Common CVS Operations.................................................................................. 105 7.6 Unexpected Results ............................................................................................ 109 7.7 Uncommon CVS Operations ............................................................................. 110 7.8 Mounting a Generic Versioning System........................................................... 110 7.9 One Final Tip........................................................................................................ 112 Chapter 8. GUI Building................................................................................................. 114 8.1 Creating a GUI Frame or Panel ........................................................................ 114 8.2 Adding Components to a GUI Container ......................................................... 116 8.3 Configuring Components.................................................................................... 117 8.4 Building Menus .................................................................................................... 118 8.5 Changing a Container's Layout ......................................................................... 119 8.6 Working with Borders.......................................................................................... 119 8.7 Accessibility .......................................................................................................... 120 8.8 Copying a Source Object ................................................................................... 121 8.9 The Connection Wizard ...................................................................................... 121 8.10 The GridBagLayout Customizer...................................................................... 122 8.11 Adding Event Handlers..................................................................................... 125 8.12 Using the Code Generation Properties.......................................................... 127 8.13 Working Around Code Generation ................................................................. 129 8.14 Containers Within Containers.......................................................................... 130 8.15 Building Complex GUIs .................................................................................... 131 Chapter 9. JavaBeans ................................................................................................... 133 9.1 Why Should I Make Beans? .............................................................................. 133 9.2 Creating JavaBeans............................................................................................ 133 9.3 Component Palette ............................................................................................. 143 Chapter 10. Using Javadoc........................................................................................... 146 10.1 Javadoc Support in NetBeans......................................................................... 146 10.2 Mounting Javadocs ........................................................................................... 146 10.3 The Javadoc Search Tool ................................................................................ 147 10.4 Creating Javadoc .............................................................................................. 149 Chapter 11. Working with XML..................................................................................... 157 11.1 Installing XML Support ..................................................................................... 157 11.2 Overview............................................................................................................. 157 11.3 XML Editors........................................................................................................ 158 11.4 Beyond Editing XML ......................................................................................... 160 11.5 Generating Java Classes ................................................................................. 165

iv Chapter 12. Developing Web Applications................................................................. 173 12.1 Why the IDE Supports Web Application Development ............................... 173 12.2 How the IDE Provides Web Application Support ......................................... 173 12.3 Creating a Web Application ............................................................................. 174 12.4 Working with JSP and HTML Files ................................................................. 176 12.5 Advanced Web Applications Features ........................................................... 178 12.6 Packaging and Deploying Web Applications ................................................ 180 Chapter 13. Extending NetBeans ................................................................................ 182 13.1 What's Different About NetBeans?................................................................. 182 13.2 The Core and the Open APIs .......................................................................... 183 13.3 NetBeans for Bean Counters .......................................................................... 188 13.4 Getting and Installing the Open APIs Support Module................................ 188 13.5 Life Is Change.................................................................................................... 189 13.6 Source Code for the Examples ....................................................................... 189 Chapter 14. Understanding the NetBeans APIs ........................................................ 190 14.1 Design Philosophy of NetBeans ..................................................................... 190 14.2 User-Level Customization................................................................................ 201 14.3 Modules—Overview.......................................................................................... 204 14.4 Interacting with the IDE .................................................................................... 208 Chapter 15. The Open APIs ......................................................................................... 211 15.1 APIs versus Core versus Modules ................................................................. 211 15.2 Service Provider Interfaces and Client APIs ................................................. 213 15.3 Overview of the APIs and Their Purposes .................................................... 213 15.4 Modules, JARs, and Class Loaders ............................................................... 241 15.5 Threading, Deadlocks, andHow to Avoid Them ........................................... 244 Chapter 16. Developing Modules—the New Module Wizard .................................. 247 16.1 The HelloWorld Module.................................................................................... 247 Chapter 17. Internals of the Running IDE................................................................... 251 17.1 The Activated Node(s)...................................................................................... 251 17.2 Cookies ............................................................................................................... 251 17.3 A Peek under the Hood .................................................................................... 252 17.4 Touring NetBeans with the Bean Browser .................................................... 253 17.5 Data Objects, Nodes, and Cookies ................................................................ 255 17.6 Filesystems and the Repository...................................................................... 256 17.7 Services .............................................................................................................. 256 17.8 Lookup ................................................................................................................ 257 17.9 Options................................................................................................................ 258 17.10 UI Components ............................................................................................... 259 17.11 Localization ...................................................................................................... 266 17.12 Wizards............................................................................................................. 266 17.13 Jumping-off Places ......................................................................................... 267 17.14 Special Folders in the System Filesystem .................................................. 268 Chapter 18. Creating the QuickPanel Module ........................................................... 271 18.1 Abstractions Covered in This Chapter ........................................................... 271 18.2 Creating the Project Files Drop-Down ........................................................... 272 18.3 FilterNode—Filtering Which Children of a Node Are Displayed ................ 276 18.4 Creating the Methods Drop-Down .................................................................. 278 18.5 Improving the Methods Drop-Down................................................................ 280 18.6 Creating the Module.......................................................................................... 284 18.7 A Little Homework ............................................................................................. 287 Chapter 19. A Mail-Based Filesystem......................................................................... 288 19.1 Building a Mail Reader in the NetBeans Paradigm...................................... 288 19.2 Implementing MailFileSystem Using AbstractFileSystem and JavaMail .. 288 19.3 Creating Folder Objects for Attachments ...................................................... 297

v 19.4 Using FileSystem.Status Annotations to Mark Unread Messages ............ 298 19.5 BeanInfo—Displaying Filesystem Properties................................................ 300 19.6 Using the Wizard Framework to Set Up Mail Accounts .............................. 301 Chapter 20. Creating the User Interfacefor the Mail Client ...................................... 311 20.1 Creating a DataLoader for Messages ............................................................ 311 20.2 Creating a Threaded Mail View Using Filter Nodes..................................... 317 20.3 Creating a Mail Workspace.............................................................................. 330 Chapter 21. Score File Support.................................................................................... 335 21.1 Overview—Functionality to be Implemented ................................................ 335 21.2 Creating the Minicomposer Module................................................................ 335 21.3 Creating a UniFileLoader and MultiDataObject for *.score Files ............... 337 21.4 Creating an Editor Support for Scores ........................................................... 341 21.5 Creating a Fixed ExecCookie to Play Scores ............................................... 343 21.6 Creating a Simple Template ............................................................................ 346 Chapter 22. Creating a Structural View of the Score................................................ 349 22.1 Creating a ScoreCookie to Represent a Sequence of Notes..................... 349 22.2 Creating a ScoreSupport.................................................................................. 351 22.3 Lifecycle of the Score ....................................................................................... 356 22.4 An OpenSupport................................................................................................ 357 22.5 Indicating Parse Errors on the Node .............................................................. 364 Chapter 23. Compiling Scores ..................................................................................... 368 23.1 Creating the Compilers..................................................................................... 368 23.2 Creating and Using the Compiler Cookie ...................................................... 373 23.3 Displaying an Out-of-Date Badge on Score Icons ....................................... 377 Chapter 24. Executing Scores...................................................................................... 380 24.1 Creating the .au Player Executor.................................................................... 380 24.2 Creating Player Configuration Support .......................................................... 390 24.3 Creating a SystemOption for the Default Executor ...................................... 393 Chapter 25. Better Score Support in the Explorer..................................................... 399 25.1 The Clip Length Property ................................................................................. 399 25.2 Representing Notes as Subnodes Using Children.Keys............................. 402 25.3 Permitting Subnodes to Be Renamed or Deleted ........................................ 408 25.4 Permitting Subnodes to Be Added ................................................................. 411 25.5 Making Read/Write Properties on Subnodes................................................ 413 25.6 Reordering Subnodes....................................................................................... 416 25.7 Data Transfer—Cut, Copy, and Paste of Notes and Sequences .............. 420 Chapter 26. Tuning Modules for Performance & Memory Footprint....................... 431 26.1 Startup Performance vs. Runtime Performance........................................... 431 26.2 Operating Principles ......................................................................................... 432 26.3 Techniques......................................................................................................... 433 Chapter 27. Producing Modules (Packaging & Distribution) ................................... 441 27.1 Versioning........................................................................................................... 441 27.2 Upgrading User Settings .................................................................................. 447 27.3 Bundling Extension Libraries ........................................................................... 452 27.4 Internationalization and Accessibility ............................................................. 457 27.5 JavaHelp—Writing and Distributing................................................................ 460 27.6 Supporting User-Level Java APIs................................................................... 466 27.7 Creating the Module JAR File Within the IDE............................................... 470 27.8 Creating a Build Script Using Ant ................................................................... 471 27.9 Producing the .nbm File ................................................................................... 472 27.10 Publishing Using the Update Center............................................................ 474 27.11 Using ErrorManager to Log Problems ......................................................... 477 27.12 Testing .............................................................................................................. 479 Chapter 28. Building Your Distribution of NetBeans ................................................. 480

vi 28.1 Do You Need Your Own Distribution? ........................................................... 480 28.2 Licensing............................................................................................................. 481 28.3 Selecting a Baseline ......................................................................................... 481 28.4 Getting the Sources .......................................................................................... 482 28.5 Customizing the Build Process ....................................................................... 483 28.6 Adding Modules to a "Stock" Distribution ...................................................... 484 28.7 Creating Preconfigured Settings ..................................................................... 486 28.8 Branding ............................................................................................................. 487 Appendix A. A Tour of Existing Modules .................................................................... 499 A.1 Modules That Expose Functionality You Might Need ................................... 499 A.2 Incidental APIs, Utilities, and Extensions ........................................................ 503 A.3 Modules That Make Good Examples for Things You May Need to Implement.................................................................................................................... 504 Appendix B. Useful Utility Classes............................................................................... 510 B.1 XML Utilities ......................................................................................................... 510 B.2 Visual Components and Extensions to Standard Swing Components ....... 510 B.3 Lookup Implementations.................................................................................... 511 B.4 Threading ............................................................................................................. 511 B.5 Miscellaneous Utility Classes inorg.openide.util ............................................ 511 B.6 Serialization Helpers........................................................................................... 512 Appendix C. Resources................................................................................................. 513 C.1 CVSHome ............................................................................................................ 513 C.2 Java Environments ............................................................................................. 513 C.3 Java Tools............................................................................................................ 514 C.4 Secure Shell (SSH) Resources ........................................................................ 514 C.5 Cygwin for Windows ........................................................................................... 515 C.6 Newsgroups and Mailing Lists .......................................................................... 515 C.7 Web Sites............................................................................................................. 515 C.8 NetBeans Open Source Projects with Design Forms in the Distribution ... 516 C.9 Java-Oriented IDEs Other Than NetBeans .................................................... 516 Appendix D. Future Plans ............................................................................................. 518 D.1 Declarative Instantiation .................................................................................... 518 D.2 Uniform Lookup................................................................................................... 518 D.3 Datasystems II..................................................................................................... 519 D.4 The Looks API..................................................................................................... 519 D.5 Declarative Actions ............................................................................................. 520 D.6 Deprecation of IDE-Specific Functionality in the Open APIs ....................... 520 D.7 The Metadata Repository .................................................................................. 521 D.8 Project Support ................................................................................................... 522 Appendix E. Working with Open Source and NetBeans .......................................... 525 E.1 Practices............................................................................................................... 525 E.2 Resources ............................................................................................................ 533 E.3 Interacting Effectively on Mailing Lists............................................................. 536 Appendix F. Additional Modules and Where to Find Them ..................................... 538 F.1 Open Source Modules Available Via the Update Center .............................. 539 F.2 The Modules Marketplace on Flashline ........................................................... 540 F.3 IDEs That Are Distributions of the NetBeans IDE .......................................... 542 F.4 Open Source Application Projects Based on NetBeans ............................... 543 F.5 Commercial Applications Built on the NetBeans Platform ............................ 544 F.6 Commercial Modules Available for NetBeans ................................................ 545 F.7 Should You Create Your Own Update Server? .............................................. 547 Colophon.......................................................................................................................... 549

vii Copyright © 2003 O'Reilly & Associates, Inc. All rights reserved. Printed in the United States of America. Published by O'Reilly & Associates, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O'Reilly & Associates books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://safari.oreilly.com). For more information contact our corporate/institutional sales department: 800-998-9938 or corporate@oreilly.com. Nutshell Handbook, the Nutshell Handbook logo, and the O'Reilly logo are registered trademarks of O'Reilly & Associates, Inc. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O'Reilly & Associates, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps. The association between the image of European tree frogs and the topic of NetBeans™ is a trademark of O'Reilly & Associates, Inc. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries. O'Reilly & Associates, Inc. is independent of Sun Microsystems, Inc. While every precaution has been taken in the preparation of this book, the publisher and the author assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

viii Preface Is NetBeans for You? Is This Book for You? NetBeans and Java NetBeans as the "Visual JDK" NetBeans as a Tools Platform NetBeans as an Open Source Community Contents of the Accompanying Sources Licensing of the Code Examples in This Book Writing Conventions in This Book Comments and Questions Acknowledgments Is NetBeans for You? Is NetBeans for you? The algorithm for answering this question is: 1. Determine what NetBeans does. 2. Decide if that functionality is for you. NetBeans is first and foremost a well-crafted open source programmer's integrated development environment (IDE). It's powerful, it's useful, it's extensible, it's open, and it's free. Sometimes it is incorrectly thought that integrated development environments are intended to make Java™ programming easier. You know already, though, that advanced tools don't save work so much as they make the same amount of work yield more effective results. That's what NetBeans does; it allows you to trade one set of practices for another. The practices that NetBeans imposes are fully as intricate as your current development practices. More intricate, perhaps, because if you are a real programmer, you will want to supplement your work style with NetBeans rather than attempting to use NetBeans to completely replace your current work style. The practice of NetBeans development is not easier. It's just more effective than what you were doing before NetBeans. You get more done with NetBeans. Is This Book for You? Well, for a start, NetBeans: The Definitive Guide is a book written by a select team of NetBeans enthusiasts and experts, all of whom are talented and experienced programmers. Some have used NetBeans almost since the beginning. Each has had his theories about programming using NetBeans tested in real world software engineering. Also, members of the NetBeans development team watched over the evolution of this book, making suggestions, correcting misapprehensions, sometimes disagreeing with the authors'

ix conclusions in the course of a long-distance group authorship project conducted over the Internet, a project that took almost two years to complete. What's more, during the period in which the authors were preparing this book, NetBeans was changing. Features came and went. Visual layout changed, thus rendering carefully arranged screenshots out of date. Whole components appeared in and disappeared from the NetBeans core. If you've ever studied the computer science heuristic of "simulated annealing," you'll recognize the process that this book underwent: like a seven-folded samurai sword, our work has been melted and hammered out flat over and over again. NetBeans: The Definitive Guide presumes that you are a NetBeans beginner, not a beginner programmer. We are not going to teach you programming; we're going to teach you how to use NetBeans to enhance your programming productivity. NetBeans and Java Sun Microsystems' Java programming environment has transformed the software development model of many programming teams. Designed not only for portability and rapid prototyping, Java is as much a prefabricated software development methodology as a programming language. Life isn't always as simple as the Java approach tries to make it, but it is that simple often enough that Java is a good bet for many projects. If you have no extraordinary requirements, the basic Java model of development is handy to use. If you happen to have special requirements, the power and flexibility of Java combined with access to other code bodies via language resources such as the Java Native Interface (JNI) and runtime protocols such as Transport Control Protocol /Internet Protocol (TCP/IP) and Java's Remote Method Invocation (RMI) layer tend to assure that some Java-based solution is within practical reach. Java is huge, yet still hugely consistent. The core Java development tools sprang from the same collective brow as did the language itself. For documentation, there's Javadoc. For client-server communication, there's RMI. Even the IDE, or rather, any number of IDEs from any number of vendors, were anticipated. What Is JavaBeans™? Java was intended from its earliest days to cater to the integrated development model of drag-and- drop program composition. Apropos this requirement, among the core methodologies designed into Java development you will find the http://java.sun.com/beans/docs/spec.html, JavaBeans specification. JavaBeans is an instance of the general design pattern of mapping a single fundamental entity onto a multiple-class implementation. As handy as the metaphor of object orientation has proven, real programming goes well beyond "just objects" in complexity of structure. Performing design decomposition on modern programs reveals that they tend to consist of fundamental entities that cannot conveniently be mapped just to single classes in any practical programming language. JavaBeans is one possible multiple-class mapping of a design concept. If you think objects should communicate and cooperate reflexively, JavaBeans agrees with you. JavaBeans represents the object's ability to communicate with other entities, usually beyond runtime to design, compile, and configuration times.

x Sun engineers identified early on in the life of Java one particularly interesting category of entity requiring a multiple-class implementation, that of the reusable visual component. Such a component has both a runtime and a design-time persona. Components of this sort are used in an integrated development environment such as NetBeans. Each drag-and-drop component used in an IDE to design programs needs both a runtime class that embodies the component functionality and a design-time class that the IDE employs for the visual representation and manipulation of the class. The JavaBeans framework, although widely applicable beyond the creation of visual design components, has received its broadest exposure in that domain. Visual JavaBeans allows a component author to map the design persona of the component onto a separate Java class—the BeanInfo class—from the component's runtime class in a fashion portable between different IDEs. This design-time persona is critical to establishing a visual representation of the component to the user and to establishing a properties metaphor for configuring the component in the design tool. On the other hand, the design-time persona is excess baggage at runtime. The packaging of the design-time persona of a reusable visual entity into a secondary class allows superfluous information to be discarded at runtime. Java as an object-oriented programming environment possesses a more complete object model than does, say, C++. Java objects are capable of reflection. This means that objects and methods exist within Java to allow examination (often called reflection, sometimes called introspection) of an object's methods and data. The JavaBeans framework takes advantage of Java reflection by creating classes whose main purpose is to be a repository of information about another class. These Bean classes each typically bear the name of the first-order class they shadow with "BeanInfo" appended to the name. A BeanInfo class can itself be composed algorithmically in software, either by automated examination of the source code for the first-order class or by using reflection to examine the compiled form of the first-order class. Additional information about the first-order class may be contained within the BeanInfo class; for example, in the case of a visual widget, the BeanInfo class contains information about the default size, title, colors, and orientation of the first-order class and often an embedded icon to be used to represent the first-order class on the toolbar. Additionally, the Bean may possess methods that communicate application-specific information to tools aware of the significance of that information. Enterprise JavaBeans A more sophisticated application of the design pattern of mapping an entity to multiple classes is the http://java.sun.com/products/ejb/white.html, Enterprise JavaBean (EJB), where we find three classes—the home interface, remote interface, and implementation classes—collectively constituting one transactional entity rather than a visual entity. Interestingly, the name "NetBeans" was chosen because the early authors of the IDE were working on just such a transactional "bean" design pattern when their efforts were pre-empted by Javasoft's announcement of the Enterprise JavaBeans architecture. But the EJB architecture is subject matter for another book. The Core Concept of NetBeans The basic JavaBeans design pattern was conceived primarily to ensure that factoring and component reuse would become the norm in Java programming. The core concept of NetBeans visual development is the design pattern of composing program components packaged as JavaBeans out of subcomponents also packaged as JavaBeans.

xi This might be called the "matryoshka doll pattern" of software design, after the Russian folk art of nested dolls, each of which is structurally complete in itself yet whose "semantic" resides in its recursively containing other structurally complete dolls. NetBeans makes use of JavaBeans and the generation of new JavaBeans so automatic that it's almost always easier to generate a simple component, "bean" it, and drag it into the next-higher- level component you wish to compose than to do things any other way. The architects of Java were largely successful in achieving this goal of providing a usable and compelling model for component packaging. And in the vanguard of this success we find NetBeans, the subject of our book. In case you were wondering, many programmers use NetBeans productively without often (or ever) straying into Bean construction. NetBeans as the "Visual JDK" NetBeans is an IDE. As such, it resembles other IDEs used in modern software engineering for authoring programs in languages such as C/C++, Forth, Ada, FORTRAN, COBOL, and RPG. NetBeans, however, is integrated with the code that is developed under NetBeans in a way that is impossible in many other languages (though Forth, Smalltalk, and LISP foreshadowed this sort of introspective language structure). It is as if NetBeans were itself the visual manifestation of the Java Development Kit (JDK) and of the Java Foundation Classes (Swing). Per the core concept of NetBeans, the essential model of visual programming is as follows: 1. Use JavaBeans from the NetBeans component palette to create a visual component. 2. Wrap that component as a JavaBean. 3. Add that component to the NetBeans component palette, either to an extant palette or to a user- or application-specific palette. 4. Use the new component in the creation of more complex enclosing visual components. The process is repeated as many times as necessary, both forming many components out of the same selection of JavaBeans and continually enhancing the palette by the more deeply nested JavaBean composition. Thus a simple visual program is composed of a small selection of top-level JavaBeans and any wrapper or nonvisual helper classes that are required. All the Usual Features NetBeans offers all the usual and expected features of an IDE: • A syntax-coloring editor aware not only of the Java language, but also XML, HTML, and many other languages • Component inspector • Object browser TE AM FL Y Team-Fly®

xii The NetBeans Object Browser has in the latest revisions of NetBeans moved out of the core to become an optional external module that you may install via the NetBeans Update Center if you so choose. • Debugger • Integrated source control support for o External Concurrent Versions System (CVS) o Built-in CVS o Most external source control systems of your choice • In addition to its own internal build system and compiler, NetBeans offers integration with external compilers and an external build system, http://jakarta.apache.org/ant/index.html, Jakarta Ant, one that is rapidly becoming the dominant build tool in the Java/XML world and beyond • "Wizard" dialogs to assist the user at choice points It also has many other features and tools about which you will read about later in this book. NetBeans as a Tools Platform NetBeans is an extraordinarily versatile tools platform. We could say that NetBeans is like a Swiss army knife onto which new blades can be attached at any time. NetBeans itself is written wholly in Java, which is why it runs on any platform that supports the JDK. Furthermore, the runtime configuration of NetBeans is described in XML. When the core of NetBeans loads, it configures and launches the rest of the system. The core reads the XML description and loads the appropriate modules, that is, components written in Java against the NetBeans API. It is this modules concept that allows extension of NetBeans. Many or most of the important features of NetBeans are modules that can be detached from the system and upgraded as needed. And because NetBeans is open source software, you are free to modify and recompile any modules whose behavior you wish to change. Thus, NetBeans has a close relationship with the programs it is developing that most other IDEs do not possess. NetBeans itself is developed in NetBeans, and any NetBeans user who wishes to join in may be part of that process. In fact, NetBeans is so attractive a platform for tool architects that over 80 organizations have specifically ported their tool applications to NetBeans modules to make it more convenient for developers to use their tools. Visit the http://www.netbeans.org/third-party.html, Who is building on top of NetBeans, page to browse the eclectic mix of target applications from business and industry that use NetBeans as their development front end or as glue to hold their application presentation together. Beyond the usefulness of adding features by adding modules to NetBeans, understanding how the individual tools that make up the NetBeans experience interoperate is a beneficial exercise for understanding the integration of component-based software. Whatever applications you wish to develop using NetBeans, if you work diligently and are lucky, over time the programs you write will come to be as well architected as NetBeans itself. NetBeans as an Open Source Community

xiii Many "real programmers" are not well-disposed toward IDEs. An IDE is no substitute for knowing the fine details of a programming language and its toolchain. Some IDEs surreptitiously introduce into a program de jure dependencies on a vendor's libraries or de facto human dependency on the IDE for program maintenance. Worse, many IDEs obstruct the flow of creativity and impose their theories of software engineering upon the work flow in a fashion likely to clash with the programmer's creative muse. NetBeans has none of these flaws to any great extent. It neither ties the user to proprietary libraries nor renders source unmaintainable to an ordinary editor. NetBeans is an IDE for the expert programmer, yet gentle and easy for the novice. It achieves this by being the product of a community of expert Java programmers who have labored to render their own Java practice more enjoyable and more productive. Such individuals have no doctrine to impose other than the doctrine of mutual assistance, free software, and coding that must bear the scrutiny of the public eye. NetBeans is open. Modules may be added and, perhaps more importantly, subtracted from the NetBeans installation. NetBeans source can also be modified under NetBeans and then recompiled to the tastes of the user. The usefulness of NetBeans is that there is as little of NetBeans between the programmer and his or her program as the programmer wills. Don't Be Cross that This Book Is Cross-Platform As we have mentioned, unlike other IDEs for Java, NetBeans is coded in pure Java. This means that NetBeans runs on any platform that offers the minima, particularly in terms of the Java environment. One easily anticipated result of this flexibility of NetBeans is that the various authors of this book are each working on different platforms and at different levels of this open source project. Therefore, illustrations in this book will be somewhat inconsistent because they are drawn from screenshots of NetBeans running in the Java environments for Linux, Solaris, Windows, and possibly other operating systems. We could have standardized on one platform to present the illustrations, but why play favorites? You, our readers, will be running NetBeans on a variety of platforms. The model of NetBeans behavior is consistent and pervasive even if the shape and color of its scroll bars change from platform to platform. It is in the nature of open source projects such as NetBeans to change rapidly. The authors of this book are working with NetBeans 3.3.1 and are trying in this book to be as general as possible in describing the functionality and operation of NetBeans because by the time you read this, some bright idea unknown to us at the time of writing may have worked its way into the latest release. Please remember this point, especially when viewing the illustrations, and do not be surprised if the layout of some or many windows has changed. It's almost certain that this will have occurred, but generally in the direction of augmented functionality. Rarely does a feature disappear, but this too has been known to happen from release to release, when one feature is replaced by a more advanced feature or set of features. In such cases, reading through the release notes may help point the way to finding the desired feature in its new location or its replacement.

xiv Contents of the Accompanying Sources The accompanying source download contains the following things: • The source code to all of the examples in the book. • Any libraries or other code required by the examples in this book. • NetBeans Module files for complete NetBeans modules demonstrated in the half of the book on writing your own extensions modules for NetBeans. These files can be easily loaded into NetBeans to install the modules: just select Tools Update Center and choose Install Manually Downloaded Modules when prompted. The accompanying sources can be downloaded from http://www.oreilly.com/catalog/netbeans. Licensing of the Code Examples in This Book All of the source code examples in this book are open source and licensed under the Sun Public License, and you may copy or reuse them or portions thereof under its terms. Writing Conventions in This Book The structure of NetBeans, both internally and to the user, is very hierarchical. Very often you will open a dialog from a menu, which will then display a tree structure that you will need to navigate. In the procedures in this book, these containers are named inline—for example, "select Tools Options IDE Configuration Look and Feel Menu Bar File" refers to both menu items and entities within the tree in the dialog that appears. Literally this translates to: Click the Options item on the Tools menu. Expand the folder IDE Configuration, its subfolder Look and Feel, and that folder's subfolder Menu Bar in the resulting dialog, and select the tree node labeled File. This convention is also followed in the NetBeans documentation. We use the term $NB_HOME to denote the base directory for an installed copy of NetBeans. A similar convention of using Unix-style environment variables is used to denote other information that varies between systems, such as nbuser$VERSION. For brevity, most code examples omit import statements and such—we want this book to be readable. All of the code examples in the book are included in full source form on the accompanying downloadable sources. Code listed in the book is generally formatted for readability and so may differ in indentation and line breaks from the downloadable sources. Comments and Questions Please address comments and questions concerning this book to the publisher: O'Reilly & Associates, Inc. 1005 Gravenstein Highway North

xv Sebastopol, CA 95472 (800) 998-9938 (in the United States or Canada) (707) 829-0515 (international or local) (707) 829-0104 (fax) We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at http://www.oreilly.com/catalog/netbeans To comment or ask technical questions about this book, send email to bookquestions@oreilly.com For more information about our books, conferences, Resource Centers, and the O'Reilly Network, see our web site at http://www.oreilly.com Acknowledgments This book could not have been created without the guidance, encouragement, and deadlines from our O'Reilly editors. Mike Loukides has been with us from the start, keeping us on track and moving forward. Brett McLaughlin joined later to give the project its final push and polish. Reviewers All of the authors are grateful to the NetBeans open source community for giving us the motivation to create this book, and especially to the community members who provided crucial feedback while the book evolved from early drafts to, we hope, a much finer finished product. They include Kevin Anderson, Wendy Blatt, Baerrach bonDierne, Joseph Bowbeer, Vincent Brabant, Mike Braden, Steve Brown, Dan Byers, James W. Y. F. Chan, Maarten Coene, Nicolai Czempin, Joan Friedman, Meg Garrison, Richard Gregor, Tim Halloran, Jirka Hana, Kristen Howe, Mike Hulse, Ben Hutchison, Jan Chalupa, Allan Jacobs, Kyley Jex, Thomas Kellerer, Petr Kuzel, Michael Lam, Louis Luangkesorn, Fiona MacGill, Cal McPherson, Karsten Meier, Francis Perreault, Ignacio Moran Pozzi, John Pramod, Patil Prashant, John Richardson, Georg Riker, Rochelle Roccah, Roxie Rochat, Adrian Romanelli, Phil Sager, Brian Sanders, Scott Schram, Jack Schuster, Bill Seddon, Julian Sinai, Andrew Stevens, Ray Tayek, Josef Templ, Jaroslav Tulach, Bryan Vold, Christopher Webster, and Michael Wever. There were others whose comments did not go through the email feedback channel or whose names could not be discerned from their email addresses. Please be assured that we greatly appreciated your contributions, even though your name may not be included in this list. Simeon Greene Firstly, I would like to thank my wife, Nikki, who continually supported me through many late nights working on the book. She was there every step of the way, and this accomplishment would not have been possible without her being at my side. I would also like to thank Tim Boudreau for coming up with the idea for this book and being a real driving force behind the idea becoming a reality.

xvi While contributing to this book, I had the pleasure of meeting some wonderful people who have encouraged and inspired me in many ways. Of these, Vaughn Spurlin and Michael Loukides deserve special mention. They both have kept me writing. Finally, I would like to thank my family, especially my mother, and friends, especially Eric Staudt, for their never-ending support of me and all my endeavors. Thanks also to God for the talents that he gave me. Vaughn Spurlin Thanks first to my wife, Myrna, whose support and encouragement made the difference between wishing I had time to take on a significant project and actually sitting down and making it happen. Coauthor Tim Boudreau deserves special notice for getting the project off the ground with the original outline and has my sincere gratitude for inviting me to join. Finally, thanks to my colleagues at Sun Microsystems for their patience and assistance while I learned about NetBeans and to Sun's management from Scott McNealy on down for their vision in making the NetBeans phenomenon possible. Jack Woehr Thanks to the ladies and gentlemen of Pure Matrix, Inc., (http://www.purematrix.com/), who were unstinting in their generous loan of network bandwidth, an important consideration for an author constantly downloading new subrevisions of the Java Development Kit and of NetBeans itself. Thanks also to Jon Erickson, Editor in Chief of Dr. Dobb's Journal, (http://www.ddj.com/), who has offered guidance and support to my writing projects over the past 12 years. And thanks to my mom and dad, Mindell S., and Dr. Harry J. Woehr, for their encouragement and support. Born in the Roaring 'Twenties, they understand not a line of my technical writing, but they always buy a copy anyway. Jesse Glick Thanks go to Sun Microsystems for tolerating my peregrinations during the writing of this book, and to Michael Loukides and Brett McLaughlin among other staff at O'Reilly for their amazing patience, competence, and all-around cheer. I was tickled pink by the number of detailed and helpful comments we received during the public review cycle for this book. Several people sent lengthy and well-thought-out reviews of many consecutive chapters—quite a lot of work, and completely volunteer. We can only hope that whatever wisdom lives in this book in tandem with the NetBeans community will pay them back threefold for their time. Thank you to the tireless creators of Emacs, DocBook XSL, Xalan, the GIMP, CVS, Ant, and the many other free tools whose quiet reliability helped give this book a tangible form. Nothing would have been written had it not been for the support of friends to distract me during fits of writer's block. You know who you are, but I will thank Kristy anyway. I would finally like to thank my parents for paying my way through college and all that stuff. It wasn't wasted.

xvii Tim Boudreau First and foremost, I thank my coauthor, colleague, and dear friend Jesse Glick, the accidental linguist. He has definitely been guru and I apprentice through the arduous process of writing this book. How could one not enjoy working with a colleague who wrote a Java method, the name of which was a single character in Sanskrit, just to see if he could? And for educating me in the dangers of indoor acid rain. Also thanks to Danese Cooper, without whom this project would never been started, Mike Loukides and Brett from O'Reilly, my coauthors, and the many reviewers named above, whose feedback helped make this book what it is. Further, in no particular order: • Jon Locke—for introducing me to TRS-80 Basic in 1982, being my partner in crime as 13 year olds with a pre-Internet startup, with fond memories of selling 5 1/4-inch floppies in sandwich baggies, discovering 1K digital audio sampling through the cassette port, and arguing over printing the documentation in letter quality mode because it would take three days on the dot-matrix printer. • Kami Pazderniková—for giving me the extra excuse I needed to move to a country I love. • Jarda Tulach—for nearly killing me with drunken bicycling in the mountains—or was it when I stole your swimming cap? Regardless, it's rare and wonderful to have such friends. • Doug Finn and Todd Hebert and all the others in Western Mass—for actually supporting my crazy decision to give up life as a well-compensated contractor and go pursue the crazy idea of working for a startup in the Czech Republic for almost no money. Maybe now we'll have some time to record some music... • Evan Adams—for being a mentor and friend and providing a roadmap and sometimes unwelcome advice for an independent-minded and often unruly former contractor, on how to survive and thrive in Dilbert-land. • Ian Formánek—for being a friend, fellow musician, and manager extraordinaire. You have a surfeit of taste! That is, however, curable with medication... • Harold Wolfe and the others at Helios Custom Training—who gave me my first taste of the joys and horrors of doing jobs for huge corporations. The debt is mine; I learned more than I thought I was learning, and in return was far more of a pain in the ass than you deserved. • And all of the other people who have been part of my life over the course of getting the book done: Mike Boyer, George Dvôrák, Mike Gisondi, Monika Mayová, Bill Moffitt, Dan Roberts, Katka Rychtariková, and my tolerant roommates Jan Kratochvil and Karel Zatloukal. Special thanks to Don Bruce and Tracy Feldstein for letting me squat in their home and be "office gnome" for most of April 2002! And finally, thanks to the NetBeans community and Sun Microsystems for making NetBeans a project worth participating in and writing about. And last, but certainly not least, to my parents, for everything.

1 Chapter 1. Getting and Installing the IDE Section 1.1. Platforms and Requirements Section 1.2. Getting and Installing a JDK Section 1.3. Which IDE Distribution? Section 1.4. Installing Binary Distributions Section 1.5. Building the IDE from Source (Simple Builds) Section 1.6. Running the IDE Section 1.7. Updating the IDE Automatically Section 1.8. You're Now Running NetBeans 1.1 Platforms and Requirements NetBeans has a set of basic requirements that must be checked before attempting to run the IDE. This section details these requirements. 1.1.1 What Are the System Requirements to Run NetBeans? Large and complex Java programs are demanding of memory and processor resources, and NetBeans is no exception. Furthermore, whereas some programs can anticipate approximately how much memory or CPU time they will need, NetBeans, which allows the user to design an arbitrarily complex project, can make no such a priori assessment. The absolute minima for running NetBeans are much more modest than the practical minima. For instance you can run NetBeans on an AMD 5x86 at 166 MHz with 64 MB of RAM and a 640 X 480 screen resolution, but only if you have no real work to do in NetBeans or any other tasks to perform on the machine in question. We know because we have tried it. That said, we list in Table 1-1 the practical minima for running NetBeans on several popular platforms. These are of necessity somewhat subjective. One rule of thumb is that serious developers should take our word on the minima, but you can get by with less machine than we recommend if you only plan to explore NetBeans lightly (preparatory to finding yourself a more satisfactory platform on which to do serious development). Table 1-1. NetBeans minimum requirements on several popular platforms Platform Processor (MHz) Memory (MB) Disk (MB) Screen resolution Color palette Linux on Intel 233 128 75 800 X 600 65535 Mac OS X 400 256 75 Any modern color display Any modern color display Solaris on Intel 330 256 75 1024 X 768 16 million Solaris on Sparc UltraSparc II 300 512 75 1024 X 768 16 million Windows on Intel 330 192 75 800 X 600 16 million

2 The README.HTML shipped with a recent cut (3.3 beta 2) of NetBeans indicated minimal requirements somewhat more relaxed those listed in the table. However, these requirements are overly optimistic, and you'll find yourself having trouble doing meaningful work without more horsepower behind NetBeans. For instance, this chapter and its illustrations are being developed on a Sun Blade with a 500-MHz UltraSparc II and 640 MB of memory. A medium-sized project currently open in NetBeans is consuming about 184 MB of memory on this machine, with peaks noticeably higher while compiling. As with any advanced design tool, NetBeans will always cheerfully accept more hardware resources and perform better for having them. The bigger and the more complex your projects are, the more NetBeans will want. Also, you must consider what else you will be running at the same time as NetBeans. Are you developing an EJB project and debugging by running either JBoss or WebLogic as an application server instance on your local machine? Give that Wintel/Lintel machine a minimum of 512 MB physical RAM and your Solaris Sparc machine 640 MB to 1 GB. Hint: If you're going to spend a little to upgrade your system for NetBeans, you'll generally get more satisfaction out of increasing memory size first before you try other improvements such as processor speed, disk space, and so on. 1.2 Getting and Installing a JDK You need the JDK installed on your computer to run NetBeans. 1.2.1 The Java Development Kit Sun Microsystems' JDK consists of: • The runtime engine for the Java programming environment • The compiler and other basic tools essential to Java development • The fundamental Java class libraries that make Java usable 1.2.2 Relationship of JDK to JRE The Java Runtime Environment (JRE) consists of: • The runtime engine for the Java programming environment • The fundamental Java class libraries that make Java usable The JRE is a runtime for users. The JDK is the complete software development environment for Java. Sun and other Java implementors provide the JRE packaged independently of the JDK. Everything that is in the JRE is also in the JDK—the JDK is a pure superset of the JRE. You will need the full JDK to do NetBeans development. NetBeans uses the development tools in the JDK to do much of its work.

3 1.2.3 Obtaining the JDK Many operating systems nowadays, such as Linux and Solaris, come with a JDK pre-installed. Even so, you may want to obtain a later version of the JDK. At the web site java.sun.com (http://java.sun.com/) you can obtain free of charge the JDK for the following operating environments: • Linux • Solaris (both for Sparc and x86 architectures) • Microsoft Windows Other JDKs exist for various platforms created by various other vendors and open source software organizations. Among them are: • Blackdown (http://www.blackdown.org) • FreeBSD (http://www.freebsd.org/java/) • IBM (http://www.ibm.com/developerworks/java/) 1.2.3.1 What JVM flavors and version are known to be supported by the IDE? You will need JDK 1.3 or above to run NetBeans. Consult the NetBeans JVM Frequently Asked Questions (FAQ) (http://www.netbeans.org/ide/support/faqs/installation.html) for more information about obtaining the JDK and setting it up in your particular operating environment. You will also find pertinent information in the NetBeans HowTo (http://www.netbeans.org/project/www/articles/howtos.html). 1.3 Which IDE Distribution? You have several choices when picking a distribution of the NetBeans IDE to download and run on your personal computer or workstation. Your choices are • Download or order the current Sun ONE Studio 4 packaging of NetBeans from the Sun ONE Studio 4 web site (http://wwws.sun.com/software/sundev/jde/index.html). Sun ONE Studio 4 is the product formerly known as Sun Forte for Java. • Download the latest stable release of NetBeans from the NetBeans downloads page (http://www.netbeans.org/downloads.html). • Download an earlier stable release of NetBeans from the NetBeans downloads page (http://www.netbeans.org/downloads.html). • Download a reasonably stable beta release of NetBeans from the NetBeans downloads page (http://www.netbeans.org/downloads.html). • Download the latest build of NetBeans from the NetBeans downloads page (http://www.netbeans.org/downloads.html). • Download the Q-build of NetBeans from the NetBeans Q-Builds Program (http://qa.netbeans.org/processes/q-builds-program.html). Your choice will balance the trade-off between stability, commonality of experience with a wide range of developers of all skill levels, and advanced technology, as summarized in Table 1-2.