Using Apache Maven with OpenEye
===============================

.. _5 Minute Guide: http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html

.. _Getting Started Guide: http://maven.apache.org/guides/getting-started/

Maven is a tool that manages Java projects. In addition to other features, it enforces
requirements, manages dependencies, and defines artifact creation. This guide explains how to
use Maven With OpenEye jars.  To get familiar with Maven, please read the `5 Minute Guide`_
and the `Getting Started Guide`_.  The rest of this article assumes that Java
and Maven are installed and working.  It will be helpful to follow the sample
HelloMaven project, available at https://github.com/oess/HelloMaven, while
reading this guide.

Requirements
------------

.. _1.6: http://www.oracle.com/technetwork/java/javase/downloads/java-archive-downloads-javase6-419409.html

.. _1.7: http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html

.. _1.8: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

.. _3.3: http://maven.apache.org/download.cgi

.. _Git: http://git-scm.com/downloads

* Java x64: 1.6_, 1.7_, 1.8_
* Maven: 3.3_

Creating a Maven Project
------------------------

To create a new Maven project, the first step is to generate the layout.

.. code-block:: bash

   mvn archetype:generate -DarchetypeArtifactId="maven-archetype-quickstart" \
                           -DgroupId="com.user" \
                           -DartifactId=HelloMaven \
                           -Dversion="1.0-alpha" \
                           -DinteractiveMode=false

.. _package prefix: http://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html

The command above creates a new project called *HelloMaven* using a predefined
layout *maven-archetype-quickstart*. Maven has several predefined project layouts.
For example, an archetypeArtifactId of "maven-archetype-webapp" will
generate a layout for creating servlets. The layout in this example creates a
basic jar. *groupId* defines the `package prefix`_. Here, it is "com.user", but this
should be tailored to your company. For example: com.eyesopen.

Executing the ``mvn archetype:generate..`` command above creates a directory
with structure a like this::

   ./HelloMaven/src/main/java/com/user/App.java
   ./HelloMaven/src/test/java/com/user/AppTest.java
   ./HelloMaven/pom.xml

Using OpenEye Artifacts
-----------------------

Now that the project has been created, the next step is to tell Maven how to find the
OpenEye jars. Two pieces of information are required: the repository
server and the dependency definition; this information needs to be
added to the *pom.xml*.

.. rubric:: OpenEye Maven Repository

Add the following XML inside a ``<repositories>`` block.

.. code-block:: xml

   <repository>
      <id>openeye</id>
      <name>openeye-releases</name>
      <url>http://openeye.artifactoryonline.com/openeye/releases2</url>
   </repository>

.. rubric:: OpenEye Maven Dependency

Add the following XML inside a ``<dependencies>`` block.

.. code-block:: xml

   <dependency>
      <groupId>com.openeye</groupId>
      <artifactId>oejava</artifactId>
      <version>2015.Oct.1</version>
      <classifier>${oe.platform}-x64</classifier>
   </dependency>


Note that ``${oe.platform}`` is a property and may be defined as one of these
values:

   * Windows
   * Linux
   * macOS

The examples below define it as ``Linux``.

Finding Available OpenEye Versions
----------------------------------

The dependency above uses the 2015.Oct.1 version of OpenEye Jars.
Other versions are available and are listed in our Maven hosting site:

   https://openeye.jfrog.io/ui/repos/tree/General/releases2


Using OpenEye in HelloMaven
---------------------------

After defining the repository and dependency, the next step is to edit *App.java* and use
an OpenEye API.  In this example, *App.java* is modified to display the OEChem version.

.. code-block:: java

   package com.user;
   import openeye.oechem.*;

   public class App {
       public static void main(String[] args) {
           System.out.println("OEChem Version: " + oechem.OEChemGetRelease());
       }
   }

If everything is set up correctly, compiling should be easy..

Using Maven to Compile and Run
------------------------------

The following command will produce a jar in the ``target`` directory in HelloMaven:

.. code-block:: bash

   cd HelloMaven
   mvn package -Doe.platform=Linux

To run the application:

.. code-block:: bash

   mvn -q exec:java -Doe.platform=Linux -Dexec.mainClass="com.user.App"
   OEChem Version: 2.0.3

Thoughts
--------

A Maven project has several benefits.  Two stand out from this example.  First,
the dependencies are explicit and versioned.  This creates a standard
development environment for all developers working on the project.  It also
means that repeatable and reliable development environments can be tracked
with source code management.

The second benefit is that testing new versions of OpenEye jars is now simple:
change the version tag in the dependency definition and recompile.

Conclusion
----------

Maven makes managing dependencies very easy once established.
Maven has a mature and rich set of plug-ins for any project task.
Maven is also the industry best practice for Java projects.  The HelloMaven
example and more complex examples can be found on https://github.com/oess.

Having trouble getting started?  Contact support@eyesopen.com.
