1  Basic Approach

As described in the System Requirements section of ObMimic’s Read Me document, the classpath for compiling and running tests that use ObMimic must include ObMimic’s obmimic.jar library, and must also include a Java EE API or Servlet API library that is not limited to compile-time use only.

The following sections explain one approach for achieving this for projects that use Maven™ (though you do, of course, remain free to achieve this using different Maven commands and project configurations, or by any other means as you see fit).

1.1  Adding the obmimic.jar library

For projects using Maven, the obmimic.jar library can be made available to Maven builds by installing it into your local Maven repository by means of the following command:

mvn install:install-file -Dfile=...path.../lib/obmimic.jar -DpomFile=...path.../etc/obmimic.pom.xml

where:

  • “...path....” is the path of the ObMimic installation (as given by the OBMIMIC_HOME environment variable, assuming this has been set as per ObMimic’s installation instructions).
  • The “-DpomFile” argument can be omitted if using version 2.5 or higher of the Maven “Install” plug-in (as this will then automatically use an equivalent pom.xml file that is built into the obmimic.jar archive itself).
  • A “-Djavadoc” argument can be added to point to a zipped copy of the ObMimic’s “docs/api” directory if you also want to make ObMimic’s javadoc available from the Maven repository (see below for further details).

The resulting Maven repository entry has a groupId of com.openbrace and an artifactId of obmimic, and can be used within a Maven-based project by adding the following dependency into the project’s POM (and adjusting the “version” setting as appropriate or desired):


    <dependency>
        <groupId>com.openbrace</groupId>
        <artifactId>obmimic</artifactId>
        <version>1.2.001</version>
        <scope>test</scope>
    </dependency>
      

1.2  Providing a suitable Servlet API library

If your project does not currently include a suitable Java EE API or Servlet API on the classpath used for compiling and running its tests, then this will also need to be added.

In particular, note that the Java EE API jars identified by a groupId of “javax” and artifactIds of “javaee-api” and “javaee-web-api” are deliberately restricted to compile-time use only. Attempting to use these at run-time when executing tests will typically fail, as they lack various classes and other resources that are required by their own internal code (for more complete details and explanation, see the FAQ entry “Why do I get an UnacceptableApiJarException?”).

If your project currently uses such a Java EE API compile-time only library, you will therefore need to either:

At worst, adding the following dependency into your project’s POM should ensure that all necessary Servlet API classes and resources are available to your test runs:


    <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        <version>3.1.0</version>
        <scope>test</scope>
    </dependency>
      

2  Alternatives and Options

In some cases, to access ObMimic’s Javadoc within your IDE you may need or wish to make this Javadoc available from your local Maven repository alongside the obmimic.jar archive (as opposed to using it directly from the ObMimic installation’s “docs/api” directory or accessing the online copy on the OpenBrace website). In particular, some IDEs may only enable Maven-based projects to use locally-stored Javadoc for libraries if the Javadoc can be obtained from a jar archive (and may even require this to be within the Maven repository), and not from a full set of Javadoc files at some arbitrary location.

Where necessary you can achieve this by:

  • Using any appropriate tool to zip the entire contents of the ObMimic installation’s “docs/api” directory into a zip file or jar archive;
  • Installing the ObMimic library into your local Maven repository as shown in section 1.1 above but with the addition of a “-Djavadoc;” argument pointing to the zipped file.

For example, if you zip the ObMimic javadoc into an “obmimic-javadoc.zip” archive within the ObMimic installation’s “docs” directory, you can then include it in the installation of the obmimic.jar library into your local Maven repository by using the following command:

mvn install:install-file -Dfile=...path.../lib/obmimic.jar -DpomFile=...path.../etc/obmimic.pom.xml -Djavadoc=...path.../docs/obmimic-javadoc.zip

where “...path....” is the path of the ObMimic installation (as described in section 1.1 above).

This will result in an “obmimic-1.2.001-javadoc.jar” archive within ObMimic’s entry in the local Maven repository, which can then be used in your projects as the Javadoc for the obmimic.jar library.

3  Explanation and Further Details

The Apache Maven Project’s Guide to installing 3rd party JARs page explains how to add third-party jars such as ObMimic’s obmimic.jar into a local Maven repository for use in your Maven-based projects.

To support this:

  • For users of version 2.5 or higher of the Maven “Install” plug-in, a suitable pom.xml for the obmimic.jar library is included at the appropriate location within the obmimic.jar itself (at a path within the jar archive of META-INF/maven/com.openbace/obmimic/pom.xml).
  • For users of earlier versions of the Maven “Install” plug-in, a separate copy of the same pom.xml file is also included in the ObMimic installation’s “etc” directory as the file “obmimic.pom.xml”.

For a more complete explanation of why some Java EE API jars are not suitable for use with ObMimic, see the FAQ entry “Why do I get an UnacceptableApiJarException?”). For details of which Java EE and Servlet API jars are suitable for use with ObMimic, refer to the System Requirements section of ObMimic’s Read Me document.