WebObjects/Web Applications/Development/Third Party Jars

Problem
You're using Xcode, and you'd like to use one or more third party JAR files in your project.

As of WO 5.2, one reasonable solution would be to just toss all the JAR files that you need into /Library/WebObjects/Extensions/ (see What's New in WebObjects 5.2 in the section on Launch Architecture: http://developer.apple.com/documentation/WebObjects/WhatsNew5.2/ ). The problem with this solution is that it creates a bit of a management headache. You don't necessarily know which projects are using which JAR files, and you might have trouble if different projects were to need different versions of the same third party JARs.

For example, we have a project that uses the Batik SVG Toolkit. We needed classes from many of the jar files that are included with batik-1.5.1. But what happens when another project comes along that needs a different (e.g. a newer) version of Batik? We'd have to either make sure the old project works with the newer batik, or restrict ourselves to the old batik code for the new project.

Solution
One solution to this problem is to create a WebObjects framework that contains all the jar files for a particular version of an external project (like Batik). That way, several WO apps can use the same WO framework (e.g. batik-1.5.1.framework), but if a newer batik comes out that we need to use for a new project, and if it turns out to be at all incompatible with the old version, then we can just create another batik WO framework, named for the new version; e.g. something like batik-2.0.framework, if/when a batik-2.0 is released.

Here's how to do it (I'll continue to use my batik-1.5.1 example):

(1) In Xcode, create a new WebObjects Framework project (e.g. batik-1.5.1).

(2) Create a new group under the framework project's Resources group. This step is optional, but is recommended simply for organizational clarity. Also toward that end, I suggest you call your new group Java (we'll see why in a moment).

(3) Add the desired JAR files to this group. For my batik example, I selected all the .jar files in my batik-1.5.1/lib directory. Check Copy items into destination group's folder (if needed), and select the aggregate target (i.e. the one with the same name as your project).

(4) We want to add a new build phase to the aggregate target. Open the Targets group (under Groups & Files) and double-click on the aggregate target. It's essential that this new build phase be added to the aggregate target rather than the Application Server target!

(5) We want to add the new build phase at or near the end of the list of Build Phases. So right-click (or control-click) on the last build phase, select New Build Phase, then New Copy Files Build Phase. You can also drag the new build phase to a new position after you create it.

(6) Change the Where: popup for your new build phase to Java Resources.

(7) Back in the main project window, select all the JAR files that you added to your new Resources -> Java group, and drag them into the Files: area for your new Copy Files build phase (in the aggregate Target panel).

(8) Build and install your WO framework:

xcodebuild install -configuration Deployment DSTROOT=/

That's all there is to it. Inside your installed framework, you'll find all your .jar files located in the Resources/Java directory (e.g. /Library/Frameworks/batik-1.5.1.framework/Versions/A/Resources/Java), regardless of what you named the group in your project.

Many thanks to Chuck Hill for the key ingredients of this solution.

Another Solution
A WebObjects application will automatically load any .jars located in the sub-folder "Contents/Extensions" inside the .woa wrapper. Compared to the Frameworks method, it has the advantages of keeping the .woa completely self-contained and avoiding potential version conflicts if different WebObjects applications need different versions of the .jar file. The downside is that the .jar is not shared between applications, so that if you want to update it you need to update it for each .woa individually, and you can have multiple copies of the .jar taking up disk space. (The latter is usually not a problem these days.)

To automate this as a part of the build process in XCode, add a Copy Files build phase to the top-level target. Set the Destination to "Wrapper" and the Path to "Contents/Extensions".