There is a new breed of developer in today's Java community that is rapidly discovering Apache and more frequently the Jakarta part of the greater Apache community. These developers often come to us with little or no command-line experience, some cut their teeth on tools like Microsoft's Visual Basic or other such tools and later moved on to IDEs such as JBuilder, Netbeans and now Eclipse. While the first generation of Java developer became intimately familiar with command line tools, the JDK, the classpath and the ins and outs of things that are now the core of Java development, this "new breed" of developer often has little knowledge outside his own IDE, and sometimes doesn't even understand what it is doing. This guide does not hope to fix that but hopes to improve the situation and give the "IDE Developer" a stepping block, a starting point, if you will so that they too can participate in our Apache Jakarta community.

The Classpath is the fundamental concept behind Java's library usage. Think of the Classpath as the Java PATH in Windows or UNIX. Instead of telling the operating system where to find executables, it tells Java where to find class files. You can read more about the classpath here, and here

Most IDEs abstract you from the classpath by having you declare and set up libraries. A common mistake that most IDE developers make is to include two versions of the same library in the classpath often in the wrong order. This can cause a number of problems including errant behavior and strange jar sealing exceptions. It's best to start from scratch and never just "bootstrap" your project with a classpath from another project that is full of things it doesn't need.

Apache Jakarta is known for being full of helpful expert developers, however, the quickest way to wear out your welcome is to demand assistance without sorting out your classpath first. There is nothing more frustrating than a hard to kill bug that is actually fixed just someone has the old version in their classpath. So whether you're setting it in your IDE's library manager or at the command line, shell script, or through your Ant build tool: make sure you know what is in your classpath and that only what you need is there.

TODO: IDE specific instructions for JBuilder, Netbeans and Eclipse.

Most IDE developers see the IDE as the only modern and humane way to program and any other tools as primitive. This attitude will probably get you laughed out of Jakarta and for good reason. When you're working with multiple developers across multiple platforms, this is a very limited world view to have. Think of it, how well does your carefully crafted "project" file help run nightly automated builds so that all the code that has been checked in to version control can be verified? What about building on UNIX? Running unit tests as part of the build? Lastly, what about complex dependencies and source structures due to multiple code bases belonging to a project? (IDEs are notoriously rigid in the source directory structures they allow, some are breaking this presupposition, but some of the more popular ones still haven't). There is a tool which meets all of these requirements and is the Cat's Meow too. Its called Ant.

Ant started out as the build tool for the popular servlet engine now known as Tomcat. Ant's cousin in the C world is called Make. However unlike Make, Ant doesn't give you pathetic error messages about using tabs instead of spaces (sick! really sick!) and has a much more easily digestible syntax. Ant's syntax is based on XML, mostly because they didn't want to write a parser when there were plenty around. And writing an ant build.xml file is WAY easier than writing a makefile. Most modern Java IDEs support Ant either natively or through plugins. Some even have GUIs to abstract you from the build file, however, you will need to acquire some familiarity with Ant over time as these tools often break with the complex build procedures often required. Read more about Ant here, here and here.

Its a depressing fact, but most companies either do not use, or misuse revision control. Are you emailing files around? That is the wrong way to work on the team. Without proper sourcecode control we'd be up the creek without a paddle at the Apache Jakarta project. So we make extensive use of CVS here. One day this may change to a more modern and sophisticated revision control program like Subversion but that day hasn't quite come yet.

Revision control ensures that the old version of code is kept and that the deltas (or changes) are stored for newer versions. By using Tags you can even reproduce an entire software release from history. By using Branches you can develop two versions at once. For instance if we release 1.0 of our software, and start working on the 2.0 version only to discover a bug in 1.0; we can still create a 1.1 without getting any of the 2.0 code mixed in. This isn't only power, it's a necessity!

You NEED to read this if you don't understand how CVS works. Even if you never use the command-line tools, you need to understand the concepts behind CVS. At least scan it even if you're familiar with other revision control systems like Visual SourceSafe or PVCS, because CVS is its own beast.

All of the Apache Jakarta Project's software is stored in CVS under revision control. To contribute to a project you need to create "patches" in the "unified diff" format, by either using the cvs diff -u command or the GUI equivalent. The -u specifies the more brief and useful format. To do that you need to have a working copy of the software. Instructions and a list of modules can be found here. You'll even find instructions on how to use GUI tools with CVS, many of which are free. Eclipse and Netbeans already have very good support for CVS built in. In fact, Eclipse has a "Create Patch..." feature that defaults to the unified format.

A frequent question asked is "How do I get all these classes loaded into [name of IDE usually JBuilder] to run them in the debugger?" The answer is often: you don't. This certainly might make sense for apps or applets, but most applications these days are run in a servlet engine or other container such as Phoenix. For these: you set the sourcepath, you put the binaries in the classpath but you debug the code remotely. Meaning the code runs in tomcat or whatever and you run the debugger against it. Modern IDEs such as Eclipse when running against JDK 1.4.x or later can even change the code at runtime while debugging!

It does generally involve editing shell scripts or batch files which can be difficult for the IDE developer to commit to, but once you do, its basically over with. These instructions will assume you're running Tomcat 4.1.12 or similar (meaning its doubtful that 4.1.13 will be different but 5.0 very well might be) on Windows 2000 or similar.

• Setting up Tomcat for remote debugging Start Here
• Setting up Eclipse for remote debugging Continue here if using Eclipse
• Setting up Netbeans/Forte for remote debugging Continue here if using Netbeans or Forte