Managing Utility JARs in an IBM Rational Application Developer-ClearCase Environment

As an integrated development environment (IDE) platform, Eclipse (and therefore IBM® Rational® Application Developer) has greatly improved your ability to produce tools to improve your everyday software development productivity. However, Eclipse itself is built with a single-user mentality (see the Jazz project for a development environment built with a team focus). Your personal workspace contains all of the resources you need to design, develop, build, and test your application. If you need to work as a team, Rational Application Developer (RAD) moves all of this responsibility to the Eclipse team layer.

The standard starting point for team development in Rational Application Developer is to get your workspace populated with the resources needed for development, and then simply execute the Team > Share Project action. This lets the team layer take over. Say, for example, that you have ClearCase installed and you have the ClearCase SCM Adapter enabled. Its functionality will take over and guide you in getting the necessary resources from your workspace inserted into a ClearCase repository. If you look closely at the resources in your workspace, you will most likely find lots of Java™ archive (JAR) files. These Utility JAR files are very prevalent today. However, Rational Application Developer gives you multiple ways to utilize Utility JAR files.

Utility JARs

Most Java applications today take advantage of a large set of Utility JARs; many of them open source solutions to common problems. Probably one of the most common is the use of log4j ( as a logging solution. There are hundreds if not more of these types of open source solutions available, where someone has already provided an implemented solution to a common application need. These solution implementations are usually provided as JAR files.

In addition, most organizations today provide encapsulating frameworks and custom implementations of these open source solutions in an attempt to simplify or standardize an organization’s approach to their use. The net effect of this is that most Java™ 2 Platform, Enterprise Edition (J2EE) applications need to utilize many of these Utility JARs, sometimes on the order of 20, 30, or more of them.

There are multiple ways to include Utility JARs in your projects, and then include them in your Java build path. This article will take a look at three methods, and then discuss their pros and cons.

Method 1

The first way to take advantage of Utility JARs is to simply include them in your Web projects. You can include Utility JARs in a Web project in the Web-INF\lib directory. To include all of the JARs in that directory in your build path, use the included build path library, "Web App Libraries," to add these JARs to your Web project build path. Figure 1 illustrates the log4j JAR file in the Web project’s Web-INF\lib directory(on the left), and how it displays in the Web App Libraries when you look at the project via the Package Explorer.

Figure 1. Including a JAR file in your Web project
the .jar file in the navigatorthe .jar file in Package Explorer

You can quickly examine how practical this may be. On the surface this is quite simple to do. However, if you expand this to many Utility JARs and many applications, there are situations where this might cause issues down the road. There may be multiple Web projects included in a single EAR (Enterprise Archive). Using this method, each Web project will contain its own set of Utility JARs. This will make your EAR file unnecessarily bloated. You also run the risk of having different versions of Utility JARs in different Web projects without realizing it. This may cause slight differences in behavior that are hard to track down.

Method 2

There is a second method of utilizing Utility JARs that improves upon this, and allows you to include Utility JAR files in an EAR project. You may import JAR files into an EAR project as J2EE Utility JARs. These JARs are then available to any project that is included in the EAR, as shown in Figure 2.

Figure 2. Including JARs in EARs
Image of Project Explorer workspace

To add a Utility JAR to an EAR project, right-click the deployment descriptor and select Import > J2EE Utility Jar. The Import wizard gives you many options to choose from. The third option allows you to copy an external JAR file into your EAR project as a Utility JAR, as shown in Figure 3.

Figure 3. Import options
image of Utility Jar Import dialog
image of Utility Jar Import dialog

To then add an EAR Utility JAR file to your Web project’s build path, you will edit the Web project’s ...\META-INF\MANIFEST.MF file with the Jar Dependency editor. Here you are provided a list of JARs or modules contained by the EAR that you may include as dependencies, as shown in Figure 4.

Figure 4. Select Classpath scope and dependencies
image of the JAR Dependency Editor
image of the JAR Dependency Editor

You will then see those JAR files under the "Web App Libraries" entry in the build path, as shown in Figure 5.

Figure 5. Imported JAR files
Image of Project Explorer workspace
Image of Project Explorer workspace

This solution solves the problem of having multiple copies of the same Utility JAR in a single application. Both Web and EJB projects can take advantage of the MANIFEST.MF Jar Dependency editor to include EAR Utility JARs in the project build path. Furthermore, the Rational Application Developer build process includes the Utility JARs in the resulting EAR for deployment. However, there is another issue worth exploring.

If you continue to include these Utility JARs in each application, you are storing these JAR files over and over again in your version control repositories. For a large organization, you may have hundreds of copies of the same Utility JAR file throughout the version control system. This is wasted storage space. There is also the concept of architectural control that this method does not solve either. If your organization attempts to provide standard Utility JAR bundles that represent the accepted versions or implementations that all applications should use, then you should not allow projects to simply copy those JARs into their projects, or you will lose the ability to control and govern the use of the standardized Utility JARs. This is solved by the third method.

Method 3

A third way that you can use Utility JARs in an EAR project is to import them as linked resources. You can again accomplish this using the Import wizard. For this current method, pick the fourth option, which is Create Linked Utility Jars in an existing EAR from an external location, as shown in Figure 6.

Figure 6. Selecting a different import type in the wizard
image of the Utility Jar Import wizard
image of the Utility Jar Import wizard

When you click Next, you are then asked for an external location where you would find the JARs. You are also given the ability to define a Linked Path Variable, as shown in Figure 7. This variable is then used as the path to the external JARs instead of the actual physical path.

Figure 7. Specifying external location
image of dialog to specify directory and variable
image of dialog to specify directory and variable

The resulting Project Explorer looks the same, but a small icon on the log4j .jar file indicates that the resource is linked to a physical file outside the workspace.

Figure 8. Icon in project explorer
Image of Project Explorer workspace

Using this method, each developer can provide their own physical path definition to this variable. This prevents each developer from having to set up the exact same physical path on their desktop to reach the external location. The linked resources are actually kept in the EAR’s .project file. If you open the .project file, you will see that the Link Path Variable is used instead of the actual physical path, as shown in Figure 9.


Figure 9. The Link Path variable in the .project file code
.project file source code
.project file source code

The definition of that Link Path Variable is maintained in your workspace preferences. All of your developers will need to insure that they have this variable defined, and that it points to a location that contains the necessary Utility JARs, as shown in Figure 10:

Figure 10. Specifying the location for Linked Resources
image of project source
image of project source

From a workspace perspective, the end result looks the same, and everything behaves as if the Utility JAR is actually physically in the EAR project. Therefore, it provides all of the benefits mentioned previously, like only one copy of a Utility JAR in your application. However, it also fixes the problem of multiple copies of the same JAR file kept in various places throughout your version control repository. Since the Utility JARs are not physically kept in the EAR project, they are therefore not added to source control when you share a project.

The question then becomes "where do you keep the Utility JARs so that everyone can reference them?" The easiest choice is to put them out on a shared network drive somewhere. An even better solution is to take advantage of ClearCase UCM to also providing some architectural governance of the use of Utility JARs.

Utility JAR governance

ClearCase UCM provides a simple but effective way to manage and govern the use of Utility JARs. If an organization has a central team that is responsible for providing guidance on the use of open source solutions, and also provides organizational frameworks that each application is required to use, then there is an ideal way to combine the linked resource method described previously with the use of a ClearCase UCM read-only component. Here is how you can do it.

Version Control

The central team should create and maintain a UCM component that is used to deploy versions of the accepted Utility JAR files that should be used by application teams. Each bundle of JAR files should be baselined to distinguish different releases of the Utility JARs. As each team creates their UCM projects for their work, they should include this component as a read-only component in their UCM projects. The path to this component through their view then becomes the physical definition of the Linked Path Variable used to reference the linked Utility JARs, as shown in Figure 11.

Figure 11. UCM component for version control
UCM component diagram
UCM component diagram

This is what the view might look like on the file system mapped to, for example, the Z drive:

Sample view of source code file system

Therefore, the UTILITY_JAR Link Path variable would be defined as Z:\MyVOB\UtilityJarComponent\UtilityJars\. If another developer had her view mapped to the X: drive, that person would have her own definition of the variable. This method allows the central Utility JAR team to manage that component. Each project may include that component, but in a read-only mode only. This enforces the Utility JAR producer-consumer model, and forces projects to be the consumer.

Once again, you can examine all the benefits that this solution gives you. You get the benefit of only one copy of a Utility JAR file in an application. You also get the benefit of not storing the Utility JARs physically in the EAR project, which saves repository space. You also get some level of Utility JAR governance, because a central team manages the contents of the Utility JAR component. Each project then consumes that component by utilizing the Linked Path variable.

However, there is one more scenario that you need to consider. How about the case where you have a large number of Utility JARs, and you need to create a snapshot view from a repository half way around the world? If the Utility JARs are simply a component in your UCM project, they will all be fetched from the repository to your snapshot view root each time you create a new view. This can take a very long time, depending upon your network link to your repository.

Create a separate view for JAR access

If you are using UCM projects to create distinct configurations for different releases, you will find yourself regularly creating new views. In addition, if you need for some reason to quickly create a new view for a fast production fix, the vast majority of time will be consumed in the creation of the view, not the fix itself.

Therefore, it makes even more sense to create a separate view altogether, simply for access to the Utility JAR component. You can create a single UCM project that includes the Utility JAR component in read-only mode. Each developer would then create a view associated with that UCM project, as shown in Figure 12.

Figure 12. Separate view
UCM component diagram
UCM component diagram

That view would be used to fetch and manipulate a single copy of the Utility JARs. Since the component is read-only, you are free to rebase that view to any baseline, forward or reverse. This gives you complete control over which Utility JAR baseline you have, and the additional advantage of needing only one copy of the Utility JARs for any number of projects on which you may be working.

You would then set your Linked Path Variable to point to the Utility JARs component in the Utility JARs view, as shown in Figure 13. All of the views that contain your project source can be created much faster, because they will not contain the Utility JARs.

Figure 13. Setting your Linked Path Variable
image of Utility JAR Import dialog
image of Utility JAR Import dialog


Eclipse (and therefore Rational Application Developer) has helped to usher in an increasingly valuable toolset to help you build complex J2EE applications. However, due to its "single-user" mentality, without some manual intervention, you will quickly have problems managing your Utility JARs. However, with a little forethought about the problem, you can take advantage of the features that are provided by Rational Application Developer and ClearCase to create a simple way for project teams to access approved sets of Utility JARs. You can also govern their use by managing them in a ClearCase UCM component.

Downloadable resources

Related topics

  • In the Rational Application Developer area on developerWorks, get the resources you need to advance your skills with this tool.
  • Find more resources for build and release engineers and managers in the Build Forge area of the developerWorks Rational zone, including articles and whitepapers, links to training, discussion forums, product documentation and support.
  • Find more resources for ClearCase users and administrators in the ClearCase area of the developerWorks Rational zone, including articles and whitepapers, plug-ins, scripts and triggers; and links to training, discussion forums, product documentation and support.
  • ClearQuest users and administrators can find more resources in the ClearQuest section of the developerWorks Rational zone, including ClearQuest hooks, Eclipse plug-ins, product documentation, articles and whitepapers.
  • Check out the Web-based training catalog for Eclipse, Rational Application Developer, and ClearCase courses.
  • Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
ArticleTitle=Managing Utility JARs in an IBM Rational Application Developer-ClearCase Environment