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.
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.
Figure A.1 provides a high-level overview of the OpenCMIS components. These are the building blocks.
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.
OpenCMIS provides three ways of delivering its components for your use:
Let’s go through the different options.
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.
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.
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.
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.)
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.