Appendix A. Apache Chemistry OpenCMIS components

This appendix discusses where to get the latest Apache Chemistry OpenCMIS components, what they’re good for, and how to build them from source. It also covers how to update the InMemory server that we use throughout this book.

A.1. Apache Chemistry OpenCMIS

The Apache Chemistry project provides CMIS libraries and tools for several programming languages. At the time of this writing, there was support for Java (including support for Android), .NET, Python, PHP, and Objective-C. This appendix focuses on the Java tools and libraries that make up the Apache Chemistry OpenCMIS subproject.

A.1.1. OpenCMIS components overview

Figure A.1 provides a high-level overview of the OpenCMIS components. These are the building blocks.

Figure A.1. OpenCMIS components

• Client library— The OpenCMIS client library provides the Java code that lets you talk to a CMIS repository. Most of this book is about this library and its counterparts for other programming languages. The OpenCMIS client library depends on a set of third-party libraries that are required in order to build and run applications. We’ll explain in a moment how to obtain them.
• The client library consists of the client API, the client implementation, the client bindings, the commons API, and the commons implementation. There are two flavors of this library: the default client library, which works for Java SE applications and on several application servers; and the Android version, which is tailored to run on Android devices (see chapter 10 for details). Both versions support the AtomPub binding and the Browser binding. The Web Services binding is only supported by the default client library. The default library consists of five JARs, one for each component. The Android library is condensed into one JAR.
• CMIS Workbench— We use this tool a lot in this book. It’s an essential developer tool for CMIS client and server developers. It’s built on top of the client library.
• OpenCMIS TCK— The OpenCMIS Test Compatibility Kit (TCK) provides a set of tests that checks whether a CMIS repository is compliant with the CMIS specification and compatible with the OpenCMIS client library. You can find more details about the TCK in chapter 14.
• Server Webapps package— The Webapps package contains two CMIS test repositories and a web application to browse CMIS repositories. One of these repositories is the InMemory Repository that we use in this book. The other repository is called FileShare and turns a directory on your computer into a CMIS repository. Because it’s built on top of the filesystem, it only provides a subset of the CMIS features. There is no versioning or query support, for example.
• The browsing web application is the predecessor of the CMIS Workbench (not shown in figure A.1). It’s an obsolete component because the CMIS Workbench does much more and does it better. The browsing application might be useful in environments where the CMIS Workbench doesn’t run or only a web browser is available. These three web applications are packaged as WAR files and can be directly deployed into an application server.
• Server Framework—Chapter 14 covers in detail how to build a CMIS server with this framework. The framework consists of the server bindings (split into a package that contains the code and a package that contains all auxiliary files), server support, commons API, and commons implementation.
• The OpenCMIS build also creates a complete WAR file that’s deployable. If for whatever reason you don’t want to use Maven to generate the scaffolding for your server, you can use the contents of the WAR file as a starting point for your server development.
• OpenCMIS bridge— The bridge is a server component that routes incoming CMIS requests to another CMIS repository. On the way, it can switch the binding and filter, enrich, and federate data from the back-end repository. This book doesn’t cover the OpenCMIS bridge.
• OpenCMIS JCR bridge—This component puts a CMIS interface on top of a JCR repository. We don’t touch on this topic in this book. If you have questions, please refer to the Apache Chemistry mailing list. (See appendix E.)

Apart from these components, there are also packages that contain the source code and the Javadocs. These packages aren’t divided by component but contain the code and documentation for all components.

Let’s look next at how to get and build the OpenCMIS components.

A.1.2. Getting and using OpenCMIS components

OpenCMIS provides three ways of delivering its components for your use:

• Source code— Each OpenCMIS release provides the full source code, which can be easily built with Maven.
• Zip, JAR, and WAR packages— Each OpenCMIS component comes prepackaged and ready to use. The components can be directly deployed into an application server or unpacked and copied into a development project.
• Maven modules— The OpenCMIS components can also be referenced via Maven or other build environments that are compatible Maven repositories. This is the preferred way if you’re using Maven for your project.

Let’s go through the different options.

A.1.3. Building OpenCMIS

There’s usually no reason to build OpenCMIS other than getting the latest development version. But doing so is very easy. Here’s how you do it.

First you need the source code. Either go to the Apache Chemistry download page and get the source code package or get the source code via SVN. (See appendix E for the URLs.)

All OpenCMIS components are built together with Maven. Go the root directory of the source code, and run the following Maven command: mvn clean install. Maven may complain during the build that it doesn’t have enough memory. Give it more memory by setting the environment variable MAVEN_OPTS to -Xmx1024m -XX:MaxPermSize=256m.

After the build is complete, walk through the directories. Under each component directory there should be a target directory that contains a zip, JAR, or WAR package. These are the packages you can download from the Apache Chemistry website. We’ll look at them next.

A.1.4. Download packages

The packages you download from the Apache Chemistry website contain everything you need for the corresponding component. This includes all the required JAR files and auxiliary files. If you need to know which dependencies are required, find the DEPENDENCIES file. In zip packages, it should be in the top directory. In JAR and WAR files, it’s in the META-INF directory.

For example, if you want to use the OpenCMIS client library, make sure you copy all dependencies to your project. Although your project may compile without them, it may not work or, worse, may do something unexpected at runtime. Depending on the Java version you’re using, the JVM provides similar libraries or the same library in a different version, and OpenCMIS might not be compatible with them.

Remember, the simplest (and recommended) way to deal with the dependencies is to use Maven.

A.1.5. Maven modules

Using Maven is the preferred way to use OpenCMIS. The main advantage is that it takes care of the dependencies and transitive dependencies. In chapter 6, we explain how to get the OpenCMIS client library with Maven. Chapter 14 covers the Server Framework and shows how to generate the scaffolding with Maven.

The OpenCMIS components for this book are slightly different from their default OpenCMIS counterparts. The next section explains how to update them.

A.1.6. OpenCMIS components for this book

In this book, we use the CMIS Workbench and the InMemory server. Although it shouldn’t be necessary, you can update them with the latest OpenCMIS version.

The CMIS Workbench is the same one you get from the Apache Chemistry website, except for the embedded Groovy code examples from the book. If you want to update, get the CMIS Workbench from Apache Chemistry. The zip file that comes with the book contains all the Groovy examples as simple files. You can open them directly in the Groovy console.

The InMemory server is a bit different. The original InMemory Repository from the Apache Chemistry website comes as a WAR file that you have to deploy into a servlet engine of your choice. When you run it, it contains only a few simple documents and types.

The InMemory Repository that we use in this book embeds the Tomcat servlet engine and is preloaded with documents and types that are used in this book. To update this InMemory Repository with the latest OpenCMIS release, you have to replace the OpenCMIS JARs and dependencies as follows:

1.  Remove all JAR files starting with chemistry-opencmis from your InMemory Repository directory.

2.  Download the InMemory server (OpenCMIS Server Webapps) and the client library (OpenCMIS Client With Dependencies) from the Apache Chemistry website. (See appendix E for the URL.)

3.  Unzip the Webapps zip file. Find the InMemory server WAR file, and unzip that, too.

4.  Copy all files in the WEB-INF/libs folder into your InMemory Repository directory.

5.  Unzip the client library package into the InMemory Repository directory, and overwrite all files.

6.  Restart the server.

The InMemory Repository should now be using the OpenCMIS version you’ve provided. (If you want to rebuild the server from scratch, use the source code available in the inmemory-cmis-server-pack.zip file.)

A.1.7. Using the OpenCMIS client library on an application server

Applications servers like WebLogic, WebSphere, and GlassFish provide environments that are slightly different from each other. The OpenCMIS client library had difficulties working in a few of those environments up to the OpenCMIS version 0.9.0-beta-1. It was necessary to tweak the application server’s class loading to get it to run, and there were special packages for WebLogic and WebSphere.

OpenCMIS 0.9.0 reduced the number of dependencies and therefore reduced the chance of potential conflicts. The AtomPub binding and the Browser binding should work without any special configuration. An OpenCMIS session that uses the Web Services binding requires a hint, though. OpenCMIS has to know which JAX-WS implementation the application server uses. Please refer to your application server documentation for this information.

If your application server uses the Oracle/Sun JAX-WS Reference Implementation (RI), add the following parameter to your session parameters when you set up the OpenCMIS session:

parameter.put(SessionParameter.WEBSERVICES_JAXWS_IMPL, "sunri");

If the application server relies on the JAX-WS implementation that’s shipped with an Oracle JRE or a JRE derived from it, use this session parameter:

parameter.put(SessionParameter.WEBSERVICES_JAXWS_IMPL, "sunjre");

If the application server provides the Apache CXF implementation of JAX-WS, use the following parameter:

parameter.put(SessionParameter.WEBSERVICES_JAXWS_IMPL, "cxf");

And, finally, on WebSphere 7.0.0.5 and later, use this session parameter:

parameter.put(SessionParameter.WEBSERVICES_JAXWS_IMPL, "websphere");

If you run into a problem with that, ask about it on the Apache Chemistry mailing list. You’ll find the address in appendix E.