There any number of reasons to develop extensions to NetBeans. Perhaps you are a developer, working on a project that has some unique needs (such as deployment to a particular application server or use of a code analysis tool), and you use NetBeans and would like to have support for that tool integrated into your development environment. Or you could have a development tool that you would like to integrate with NetBeans and sell as an extension. Or you could simply be embarking on a project to create a large desktop application, and you can save several person-years by using the NetBeans core without its development-tool-specific functionality to handle the menus, windowing, file access, configuration, and browsing aspects of your application.
This half of the book is about writing modules to plug into NetBeans to extend its functionality. So it is of particular interest to people developing or using tools for software development, people developing desktop applications in Java, or anyone who simply uses the NetBeans IDE and would like to change the way something works. We assume you have some familiarity with NetBeans as a development tool and its user interface components and with the Java language.
The design of NetBeans is also a great example of well-crafted object-oriented architecture. Odds are good that this book will affect the way you think about how to build software.
Extensions to NetBeans are developed by writing Java code to the NetBeans Open APIs . API stands for Application Programming Interface and is the common industry term for interfaces a program exposes to allow other programs or components to interact with it.
Extensive documentation of the NetBeans APIs is available in Javadoc and prose format on the NetBeans web site. This book complements the Open APIs reference documentation; it isn’t a replacement. Javadoc is a very good tool for explaining APIs using their package and class structures as its organizing principle, and the Javadoc set for NetBeans contains excellent overviews of each API that cover how to use them. But people do not necessarily think in terms of a class hierarchy structure—generally, they start with a problem to solve. With this book we intend to provide a task-oriented guide to using these APIs. We hope to leave you with a rich understanding of how NetBeans works and the philosophy guiding its design.
Most people know NetBeans as an integrated development environment (IDE) written in Java. Being written in Java, it should (and generally does) run on a Java 2 JVM, version 1.3 or higher. What makes NetBeans different from other development environments is its flexibility. While the first incarnation of it was a tool for Java programming, over three generations of its architecture, it was redesigned to be a generic tools platform to support development in any language, not just Java. The key is its modular design. A basic, generic application runtime that does not even know it is an IDE is implemented in the NetBeans core. Extensions to this framework in the form of modules are what actually make it an IDE. The code editor, the Java language support, and almost everything you see in NetBeans is implemented as a pluggable module.
This means that not only can NetBeans be used as a tool for Java development, people can use the NetBeans core with only modules they’ve written (and possibly some other NetBeans modules) installed to build a desktop application that might have nothing to do with software development. A number of companies and individuals have done this, and the result is (at the time of this writing) four commercial IDEs that are NetBeans plus some custom modules (Sun’s Forte for Java, Compuware’s OptimalJ, Compaq NetBeans, and Zucotto’s Whiteboard) and applications running the gamut from a CAD tool for designing coal mines (ECSI Minex—http://www.ecsi.com.au/), to a tool for managing a hair salon (SalonTango), to a music composition and notation tool (Project XEMO—http://www.xemo.org/). By the time you read this, there will no doubt be many more. For an up-to-date list, see the netbeans.org third party page (http://www.netbeans.org/about/third-party.html).
Since all of the IDE-like behavior of NetBeans is implemented in the form of plug-in modules, you can use the NetBeans core to handle a lot of the grunt work involved in writing a desktop application. Most applications need access to files, need to provide menus and toolbars and windows, and need to store settings. Having the implementation of these things handled for you solidly by the NetBeans core can save a lot of development time and effort. NetBeans is to the desktop much what an application server is to a server computer—where an application server provides an execution context for arbitrary Enterprise JavaBeans, NetBeans provides an execution context for arbitrary modules. Both frameworks are designed to handle commonly needed tasks so you can concentrate on the actual logic.
The architecture of NetBeans breaks
down into two major sections: The
core (also referred to as the
application runtime) and the
Open
APIs. The core plus the Open APIs make up the NetBeans Platform.
These are represented in the org.netbeans.core.*
and org.openide.* Java packages, respectively, in
the source code for NetBeans. Binary libraries of these packages are
part of your installation of NetBeans in the files
$NB_HOME/lib/core.jar and
$NB_HOME/lib/openide.jar. The core implements
many interfaces defined in the Open APIs and is
NetBeans’ runtime engine. The Open APIs are the
toolset available to module authors who want to write modules to
implement functionality that will run inside NetBeans. A module is a
.jar (Java ARchive or JAR)
file that contains the module’s Java classes and a
manifest file, which describes the module and
how to install and uninstall it, to NetBeans’
runtime.
As with any application, for an IDE such architecture has a number of advantages. First is the ability to support multiple languages. Another significant advantage is the ability to wrap the functionality of other development tools and present it within the IDE. The simplest example of this kind of wrapping is the way external compilers and Java virtual machines can be used for compilation and execution by defining services that launch an external process and parse and present the output of that process (for example, compiler error messages). A more complex example would be the integration of a preexisting UML tool to allow seamless interaction with it through NetBeans’ user interface.
A number of the elements of NetBeans, such as the Filesystems, Nodes, and Explorer APIs, can also be used as standalone libraries for client- and server-side Java applications outside NetBeans. In a sense, NetBeans is a set of libraries.[2]
A caveat to this type of design is that no module should call functionality that does not appear in the Open APIs—for example, getting an object with an interface declared in the Open APIs and then casting to a core implementation class to access some method that isn’t defined in the APIs. The contract of an API is to provide access to functionality that will continue to work even if the underlying implementation is replaced. This means that there is no guarantee that anything not declared in the Open APIs documentation will be present in future versions of the IDE, and any code using the core implementation classes directly is liable to be broken in some future version of NetBeans. If you need to do something that is inconvenient or not possible with the APIs, on the NetBeans mailing lists (http://www.netbeans.org/about/community/lists.html), ask if there is a different approach you should take; if there is not, file an enhancement request in the bug tracking tool (http://www.netbeans.org/issues/query.cgi) on the netbeans.org web site.
Licensing of software and source code determines what other people can and cannot do with that software. The source code to NetBeans is available under a license called the Sun Public License, which is very non-restrictive.
This license allows you to do as follows:
Use NetBeans to create commercial or non-commercial software
Build modules that integrate with NetBeans and sell them or give them away
Redistribute NetBeans either for free or for sale with your own branding and custom configuration, with additional modules you supply and with removal of any modules you don’t want in your distribution.
Use parts of NetBeans code (for example, the Filesystems library, or the core) in your own applications, commercial or non-commercial.
The Sun Public License (SPL) is a minor variant of the Mozilla Public License (MPL), the license Netscape created when it released the sources to its web browser. The only significant differences are that the word Netscape is replaced by Sun Microsystems and the license covers open-sourcing the documentation as well, which Netscape did not explicitly do. For the full details (including a diff with the MPL) see http://www.netbeans.org/about/os/license.html.
NetBeans is an open source project hosted at http://www.netbeans.org/. This means that the source code for the entire IDE is available for download. A principle of open source is open communication, and design discussions happen on the public mailing lists at netbeans.org. The site is divided into various subproject sites (for example, http://editor.netbeans.org/) for the various modules that are part of NetBeans. Decisions are reached by consensus on the mailing lists (see Appendix E for an explanation of how this works in practice); there is a governance board consisting of two members chosen by the community on the mailing lists and one appointed by Sun Microsystems (which donated the code that started the project, employs many of the developers of NetBeans, and financially supports the site’s infrastructure). In the event of an intractable dispute, the board exists to make decisions. In practice, issues of such magnitude are extremely rare.
Because it is an open source project, you can also get involved in the ongoing development of NetBeans. Code contributions, patches, and bug fixes are always welcome. To learn more about getting involved in the NetBeans project, see the contributions page (http://www.netbeans.org/devhome/community/contribute.html).
If you write a module for NetBeans that you do not intend to sell, but which would be generally useful to the community at large, you have the option of contributing that module to netbeans.org. Please do! Assuming a compatible license, the sources can be hosted in CVS, mailing lists set up for discussing the ongoing maintenance of that code and bug categories for the module you created. If you want to do this, send a proposal to the [email protected] mailing list about your module, and assuming the consensus is that your module would be a good addition to the NetBeans project, follow the contribution instructions on the web site. See Appendix E for details.
Note that contributing a module involves an ongoing commitment to maintain it— it is never a good idea to contribute a module as a way of abandoning it.
The main pages of the NetBeans web site can be found at http://www.netbeans.org/. They include overviews of NetBeans, news from the various subprojects on the site, documentation, bug tracking, and indexes of interesting documents from subprojects such as new feature proposals, how-to’s, and FAQs.
The site, which uses an open source infrastructure called SourceCast,
is hosted by a company called CollabNet, under contract to Sun
Microsystems. As mentioned, NetBeans is modular—a lot of
subprojects are part of NetBeans, and if they were all hosted on the
top-level web site, the number of documents would quickly become
unmanageable. Instead, a module or set of modules has its own web
pages on a virtual host—a virtual web
site with a different name, for example, http://editor.netbeans.org/ for the pages
relating to the code editor. Each module project may have its own
mailing lists for development discussion, user questions, and such.
Not all do—it is at the discretion of the maintainers of that
particular project whether their project needs its own mailing lists.
Most projects are small enough that discussion should simply happen
on the top-level user and development mailing lists. There is a
convention for posting messages of interest only to developers of a
single module or topic of interest to a minority of members of a
mailing list: Put the topic in square brackets, for example,
[performance] Caught exceptions on startup.
There are also several “meta-projects,” which are not really modules in their own right, but exist as jumping-off points for related modules that have their own virtual hosts. An example of this is das.netbeans.org; DAS stands for Distributed Application Support—the project is mainly a homepage for getting to modules such as CORBA and RMI support. These meta-projects serve to group related modules and keep the initial list of projects confronting visitors to the site from being intimidatingly large.
Additionally, there are a number of subprojects that are not specifically coding-related, such as the http://qa.netbeans.org/ quality assurance subsite, which has graphs of the bug counts of recent builds, as well as other useful resources. Another interesting site of this type is http://ui.netbeans.org/, maintained by Sun’s team of human interface engineers, who work to ensure that the user interface to NetBeans is usable and consistent, and do other work such as icon and interaction design.
While open source sites should and generally do have low barriers to entry, some functions of the site require you to register and get a login ID and password. These include filing bug reports, signing up for mailing lists, and, of course, CVS (Concurrent Versioning System, the tool for storing and accessing source code) and administrative access. One of the purposes for this mechanism is to give people who are the maintainers of a project access permissions to manage their own mailing lists and project subsite, and so that when you file a bug, you’ll get an automated email if it’s fixed or its status changes.
Bugs are tracked using Issuezilla, an enhanced version of the Mozilla project’s bug tracking tool Bugzilla. Issuezilla lacks some bells and whistles, and has a somewhat intimidating query interface, but is generally usable. Eventually, CollabNet plans to replace it with a new system, but the timetable for this is still undetermined at the time of this writing. Items in Issuezilla are categorized as defects, enhancement requests, or tasks.
A simple query interface is available at http://www.netbeans.org/devhome/issues.html. Anyone can anonymously query the bug database; to enter new items in Issuezilla, you will need to register and get a login ID.
Open source is not just about writing code. There are many ways to participate in an open source community—the simplest is to download a copy of the software and join a mailing list. Open source is about people building software more efficiently by benefiting from each other’s expertise. Filing enhancement requests and bug reports and asking and answering questions on mailing lists are as important as writing code. Along with reading this book, we encourage you to subscribe to the [email protected], [email protected], or [email protected] mailing lists and get a sense of what the NetBeans community is like. See the NetBeans Mailing Lists page (http://www.netbeans.org/devhome/community/mail-top.html) to sign up.
The mailing lists on netbeans.org are particularly useful supplements to the contents of this book. Many subprojects have their own development mailing lists for discussion of development on that particular project (for example, [email protected]).
Another useful resource to supplement this book is the [email protected] mailing list. The http://openide.netbeans.org/ project is where the ongoing evolution of the Open APIs takes place. If you have questions about how to do something, the use of a particular part of the Open APIs, the APIs documentation, or this book, that is the place to go. As with any mailing list of this type, please check the Frequently Asked Question (FAQ) pages at http://www.netbeans.org/devhome/docs/index.html. You may well find the answer to your question there.
You can also read and post to the netbeans.org mailing lists via a newsreader, by connecting to news://news.netbeans.org. Note that posts from unregistered email addresses are moderated—they need to be approved by someone. So, if you post via a newsreader or by using an email address in the From: field of your email other than the one you registered with, there may be a delay before your first post appears. An increasing amount of “spam” mail is being sent daily to the netbeans.org mailing lists—moderators make sure this unwanted email does not end up cluttering the mailboxes of everyone on the mailing lists, hence the need for this protection mechanism.
Another useful resource is the NetBeans weekly newsletter, which is run by volunteers and mailed every Monday to the [email protected] mailing list. It contains summaries of what happened with NetBeans during the previous week, any new contributions, and links to web archives of interesting conversations from the public mailing lists.
For a listing of the top-level mailing lists and a form to allow you to subscribe to them, go to http://www.netbeans.org/devhome/community/lists.html. To subscribe to individual project mailing lists, follow the links from the home pages of the projects you are interested in. As with any set of community mailing lists, it pays to lurk a little while before posting, to get a feel for the community and a sense of what subjects are appropriate to each mailing list.
At the time of this writing, the NetBeans open source project has been running for more than two years. Here are some interesting statistics about it:
The oldest code in the codebase is from 1997, from NetBeans 2.0.
The codebase is currently around 800,000 lines of code.
There have been 386,300 downloads of NetBeans.
There have been more than a million downloads of Sun Microsystems’ distribution of NetBeans, Forte for Java.
The average number of messages on all the top-level mailing lists combined is around 2,000 messages per-month.
The combined subscribership count of all top-level mailing lists is about 2,000—of course, by the time you read this, many of these numbers will be even higher.
Not only are there tools to make general Java coding easier within NetBeans, but also there is a module that provides a substantial amount of help with building extensions to the IDE or building applications on the platform. This is the Open APIs Support module. It includes the following:
Templates for various kinds of objects commonly subclassed in writing extensions, with helpful comments and examples.
The NetBeans Open APIs Javadoc and prose reference documentation, installed in the IDE’s Javadoc repository, so the documentation can be viewed and searched from within the IDE.
Execution services for commonly used interface components—so instead of having to install a component you’re creating into the IDE, you can simply execute the component to test it.
The Bean Browser, which is rather like the traditional explorer tree, but allows you to browse objects within the internal hierarchy of objects in the IDE, which are not normally exposed by the user interface.
Support for dynamically reloading modules for testing purposes—it would be awful to have to restart the IDE to test each revision to one’s code.
Structural editing of XML layers (a configuration file most modules use) and graphical access to components and attributes of modules under development in the Explorer tree.
You will need the Open APIs Support module to do many of the examples in this book. To get the module, follow these steps:
Make sure you have a working Internet connection to download the module.
Select Tools → Update Center off the main menu.
If you are behind a firewall, click the Proxy Configuration button and enter the proxy configuration information.
Tip
If you are behind a SOCKS firewall, you will need to pass the proxy information to the JVM the IDE is running in. You need to do this when you start the IDE, for example,
runide.sh-J-DsocksProxyPort=1080-J-DsocksProxyHost=socksproxy.foo.com. Note that even if you are behind a SOCKS firewall, you should still be able to use a simple HTTP proxy if one is available—so this is seldom necessary. If you will need to use a SOCKS proxy every time you run NetBeans, create or edit the file called ide.cfg in $NB_HOME/bin to contain the preceding line switches.Follow the instructions in the Update Center wizard and wait for it to check for new modules.
Soon you will see a wizard pane with a list of modules you can add. Select the Open APIs Support module and the Open APIs Support with Ant module from the list of available modules in the Extensions category, and click Add. Click Next and follow the instructions on the remaining panels of the wizard, and the module will be downloaded and installed.
For more information see the module’s web page (http://apisupport.netbeans.org/).
No piece of software is ever “finished,” and this is certainly true of NetBeans. We began writing the book at the beginning of the NetBeans 3.2 release cycle; as this paragraph is being written, 3.3.2 is released, 3.4 is almost ready, and 4.0 looms on the horizon. There are ways to do things in NetBeans today that simplify things compared with the previous release, and there are ways of doing things that were recommended for 3.2 that are now deprecated (but, unless noted in the upgrade guide bundled with the Open APIs documentation, still function). This will be true of future releases as well. Where possible in this book, we project what changes are expected with 3.4 and higher. This book primarily covers NetBeans 3.3.x, though major changes in NetBeans 3.4 are noted where appropriate.
This shouldn’t be cause for alarm—great effort is put into making NetBeans backward compatible. What it does mean is that since technical books, particularly about software, are quickly obsolete, it is worth checking the upgrade guides for module authors for versions subsequent to 3.3, and the published errata for this book. For details on the pending changes known at this time, and the general direction in which the NetBeans APIs are evolving, see Appendix D.
As noted in the preface and throughout the text, sources and compiled module .nbm files for the examples in this book can be found at http://www.oreilly.com/catalog/netbeans.
[2] As this book is being written and NetBeans 3.4 is in development, one of the thrusts is to decompose the core into smaller, independent libraries implementing specific APIs. This work will further enable applications to use and distribute only the functionality needed.