6.2 Create Shared User Libraries
When working with third-party commercial or open source libraries, or with standard APIs such as J2EE, it's common to require several JAR archives in combination. If these are used in only one project, then you can configure the build path as described in the previous section. However, you may need to include the libraries several times in a modular multi-project structure. It would be easier to define the combined library as a single entry.
This kind of configuration is called a user library in Eclipse. The JAR files contained within a user library are identified by an absolute file path external to the Eclipse workspace. It's helpful to have a consistent location for these libraries on your local or network file system. A library's files also might be located within a vendor product installation directory. We'll use the following file structure:
/eclipse-contrib/ libraries/ axis-1.2beta/ j2ee/ jarkata-basic/ jakarta-j2ee/
Download the Apache Axis distribution (see References) and unzip its JAR files into the axis-1.2beta folder (or a similar folder name based on a newer version). Standard vendor-independent interface libraries are available for J2EE specifications such as Servlets, EJB, JNDI, JavaMail, and others; place these JARs into the j2ee folder. Many other useful utilities are available from the Apache Jakarta project, including the log4j library. Place these JAR files in the jakarta-basic and jakarta-j2ee folders.
We could use a classpath variable to include J2EE library files from Tomcat or JBoss installations, just as we did with the Servlet library earlier in this chapter. However, because we may deploy to several different application servers, and because our project code is written to the standard J2EE APIs, we gain more flexibility by creating a vendor-independent J2EE user library. A user library allows us to add a single Java Build Path entry that includes all JAR files required for our J2EE development.
Open the Eclipse preferences page for user library configuration located in the category Java > Build Path > User Libraries. The configuration for the Apache Axis library is shown in Figure 6-7. Press the Add JARs... button, browse to the Axis library folder, and select the archive files.
Figure 6-7 Create a new user library for the Apache Axis Web Services toolkit.
Download source and Javadoc ZIP files for each user library, if they are available. Doing so enables maximum benefit from Content Assist and Javadoc display when using these libraries in Eclipse. For convenience, place these files in the same directory as the binary JAR files. While adding each JAR file to the user library, also edit the associated Javadoc location and source attachment parameters. These values are shown for the axis.jar file in Figure 6-7.
The user library preferences page includes buttons for importing and exporting library definitions to a separate file that can be shared with your team membersnote that this import/export is separate from the more general import/export of all workbench preferences. Export your new libraries to a file named EclipseDistilled.userlibraries and then notify other team members that they should import this file into their user library settings. This file does not contain the library's filesit only contains the file path locations to JARs, source attachments, and Javadoc HTML.
If others who import this file use a different file structure for organizing their external library files, they must edit the library definitions to remove and add the JAR files with correct path locations. Unfortunately class path variables are not available to parameterize the library file locations.
6.2.1 Linked Library Project
A useful hybrid strategy is to configure a user library that is also available as a linked folder in your Eclipse workspace. Follow these steps:
Create a simple project in your workspace. Unlike Java projects, a simple project has no Java build path configuration in its properties. Use the command File > New > Project > Simple Project.
Uncheck the option to use a default project location within the workspace folder and enter the path for your \eclipse-contrib\libraries folder (see Figure 6-8).
Your new libraries project should look similar to the one in Figure 6-9.
Figure 6-8 Create a new simple project with linked folder location.
Figure 6-9 Java projects with sharing common libraries.
The Apache Axis distribution includes both the source code and Javadoc HTML files in one ZIP file, which is named axis-src-1_2beta.zip in this illustration. This file is used within the user library configuration to add source attachment and Javadoc to classes in this JAR file. Also notice the inclusion of a PDF specification file related to the JAX RPC library. You can double-click this file from within Eclipse to launch an external PDF reader.
In previous configuration of the orders project, we created a lib subfolder, copied the log4j JAR file into it, and then added this archive to the project build path. However, this approach can lead to a lot of duplication when we need the same JAR in several projects. Now we can use the shared libraries project to add log4j, or other jakarta-basic archives, into any of our projects.
In Figure 6-9, the shared log4j JAR has been added to both the orders and ubl projects. In addition, the Apache Axis Library is also included in the ubl project configuration as a user library; it includes a combination of six interdependent JAR files.
Eclipse has very flexible capabilities for configuring user libraries and leaves opportunity for creative arrangements. The hybrid approach described here has several benefits:
Gather all of your open source libraries in a common folder named /eclipse-contrib/libraries.
Download binary, source, Javadoc, and other related specifications into the same folder. Leave source and Javadoc files compressed in ZIP files.
Create a simple project in each Eclipse workspace using a linked folder location for the project's contents. If you use multiple workspaces to separate your work as described in Chapter 3, then they can share the same reference libraries.
Create user libraries when you often use several JAR files in combination. Export the user library definitions to share them between workspaces.
Use the libraries project to add other individual JAR files to the build path of Java projects; use the Add JARs... button for portable location references.