Creating a Infinity Process Platform Runtime Environment with Apache Maven

Apache Maven is a framework to help build, test, assemble, and deploy software artifacts. Infinity Process Platform provides all building blocks necessary to assemble a Infinity Process Platform Runtime Environment in a Maven repository, which can be reached at this address. If you are unfamiliar with Apache Maven, we recommend to read the Maven Quick Start guide.

Apache Maven uses a construct known as a Project Object Model (POM) to describe the software project being built, its dependencies on other external modules and components, and the build order. A POM provides entire configuration for a single project. General configuration includes the project's name, its owner and its dependencies on other projects. It is stored in a pom.xml file, which has to be in the "root" folder of your project. Maven dynamically downloads necessary components from one or more repositories.

A Maven project is basically just a directory structure with a pom.xml file. You can create these files manually or use a Maven archetype as a template for your project.

Maven Installation

To install and use Apache Maven on your machine there are two possibilities:

Note
Due to a bug in Maven version 3.0.4, you might face problems using this version while downloading dependencies from behind a proxy. In this case either switch to Maven version 3.0.3 or download the following jar:
http://repo.maven.apache.org/maven2/org/apache/maven/wagon/wagon-http-lightweight/2.2/wagon-http-lightweight-2.2.jar
and add it to the lib/ext folder in your Maven installation.

Maven Standalone Installation

You can download a Maven distribution at http://maven.apache.org/download.html. After downloading simply unzip it into a folder of your choice. Version 3.0 has been verified to work well with the Infinity Process Platform artifacts and is recommended, but other versions might be used as well without being officially supported.

Maven Eclipse Plugins

M2Eclipse is an integration of Maven functionality into the Eclipse platform that comes with an embedded Maven runtime. One benefit of using these plugins is the Maven Dependencies classpath, which automatically makes the dependencies in your POM file available on the classpath of your Eclipse project.

M2Eclipse Core Feature and M2Eclipse WTP Feature are shipped with Mars.

You will notice in the Console View that the M2Eclipse plugin updates the repository index information upon each startup. When you're working primarily with Infinity Process Platform's Maven repository, chances are that there won't be many changes too often and you can turn this behavior off to speed up the Eclipse workspace startup time. Select Window > Preferences > Maven > Download repository index updates on startup.

Setting the correct Maven installation path

Check if your Maven installation location is set to use the correct Maven version. If you experience any problems in using the Infinity Process Platform archetype catalog or in building Maven projects using M2Eclipse, this might be due to the fact that your M2Eclipse is configured to use the embedded Maven version that ships with it. Unless you configured it accordingly, this Maven version uses another settings.xml which does not contain the credentials and repositories required to access the archetype catalog and the artifacts in the repository. To solve this problem, change the Maven version used by M2Eclipse to a correctly configured Maven version. To set the location of your Maven installation do the following:

  1. Select Preferences > Maven > Installations
  2. In the Installations pane, click Add
  3. Browse to the location of your Maven installation

    Select Maven Version

You can now configure the Infinity Process Platform Maven repository and create the Runtime Environment.

Configuring the Maven Repository

The global Maven configuration is stored in the file settings.xml in the /usr/buildTools/apache-maven-3.2.5/conf/ folder or in the .m2 folder in the user's $home (on Windows: %homepath%) directory. It is recommended to use the .m2 folder. If you've never used Maven before, it is likely that this file is missing in which case you may use the following pre-configured template: settings.xml to get started by saving it into your .m2 folder, e.g. on Windows C:/Users/$username/.m2/settings.xml.

The Infinity Process Platform Maven Repository is available at https://infinity.sungard.com/repository/.

Access to the Infinity Process Platform Maven repositories is protected and you have to authenticate yourself with the credentials of the Infinity Process Platform Storefront. It is highly recommended that you encrypt your password in a hash before storing it in your local settings.

In order to do so login at https://infinity.sungard.com/repository/.


Figure: Login

Now go to your profile page by clicking on your login name in the upper-right corner.


Figure: Go to your Profile Page.

Enter your current password in the Current Password entry field and click Unlock.


Figure: Unlock

Click Update. A hash is being generated in the Encrypted Password field.


Figure: Encrypted Password Creation

Copy the generated XML server element to the <servers> section in your local settings.xml file. Choose a server ID. In the following example we use "ipp-libs-dev". If you have used the pre-configured settings.xml template, this entry already exists and you should simply replace it.

<servers>
  <server>
    <id>ipp-libs-dev</id>
    <username>${username}</username>
    <password>${password-hash}</password>
  </server>
</servers>

Set up a profile for Infinity Process Platform in the <profiles> section of the settings.xml file. If you have used the pre-configured settings.xml template, this entry already exists.

<profile>
   <id>ipp</id>
   <activation>
     <activeByDefault>true</activeByDefault>
   </activation>
   <repositories>
     <repository>
       <id>ipp-libs-dev</id>
       <!-- ipp-libs-dev contains the repositories: ipp-releases, ipp-3rd-party, iaf-java-releases, 
            ipp-experimental, ipp-snapshots, ipp-3rd-party-nondistributable -->
       <url>https://infinity.sungard.com/repository/ipp-libs-dev</url>
       <releases>
         <enabled>true</enabled>
         <!-- updatePolicy>daily</updatePolicy -->
       </releases>
       <snapshots>
         <enabled>true</enabled>
         <updatePolicy>always</updatePolicy>
       </snapshots>
     </repository>
     <repository>
       <id>ipp-snapshots</id>
       <url>https://infinity.sungard.com/repository/ipp-snapshots</url>
       <snapshots>
         <enabled>true</enabled>
         <updatePolicy>always</updatePolicy>
       </snapshots>
     </repository>
     <repository>
       <id>public-jboss</id>
       <name>JBoss Repository</name>
       <url>https://repository.jboss.org/nexus/content/groups/public-jboss</url>
     </repository>
   </repositories>
 </profile>

Make sure that the ipp-libs-dev repository setting matches with the one in the servers section.

Provided Maven Archetype Templates

The archetype-catalog.xml file contains all Infinity archetypes templates. If you like to use it as local archetype catalog, you can download it from:

https://infinity.sungard.com/repository/ipp-libs/


Figure: Download the archetype-catalog.xml

and place it in folder .m2 of the user's $home (on Windows: %homepath%), where the settings.xml file is located as well.

To view the provided archetypes, edit the catalog file. All archetypes are identified by the groupId: com.infinity.bpm.archetypes. The artefactId determines the specific archetype. The following projects are provided:

For example the following archetype definition is used to prepare a Infinity Process Platform Portal deployment for Tomcat 7:

<archetype>
    <groupId>com.infinity.bpm.archetypes</groupId>
    <artifactId>ipp-archetype-tc7-ipp-portal-war</artifactId>
    <version>RELEASE</version>
    <repository>https://infinity.sungard.com/repository/ipp-libs</repository>
    <description>
        This project prepares a Infinity Process Platform Portal WAR deployment for Tomcat 7
    </description>
</archetype>

Creating a Maven Project

Depending on the Maven installation you have chosen above (standalone or Eclipse plugin), projects can be created in different ways. Please note that these are merely examples to get you started.

Using the Command Line to create a new Maven Project

You can use the following command line to create a new Maven project, e.g. with the provided Tomcat archetype mentioned above:

mvn archetype:generate -DarchetypeGroupId=com.infinity.bpm.archetypes
    -DarchetypeArtifactId=ipp-archetype-tc7-ipp-portal-war -DarchetypeVersion=<version>
    -DgroupId=com.infinity.test -DartifactId=ipp-portal -Dversion=1.0-SNAPSHOT

This creates a Maven project based on the maven-archetype-quickstart type ( http://maven.apache.org/archetype/maven-archetype-bundles/maven-archetype-quickstart/). For details on the Maven Archetype Plugin, please refer to http://maven.apache.org/archetype/maven-archetype-plugin/.

If some of the following parameters are not entered in the command itself, the command line prompts to enter these parameters:

Using the M2Eclipse Plugin to create a new Maven Project

You can achieve the same result as via the command line described in the previous section by using the New Project Wizard in Eclipse:

  1. Select File > New > Other and select Maven Project:

  2. Choose project name and location and click Next.

Configuring the catalog

Choose one of the following three options to add the archetype catalog:

Selecting the archetype

The archetypes provided by Infinity Process Platform are displayed.

Available Archetpyes
Figure: Available Archetpyes

To select the archetype and specify its parameters, proceed as follows:

  1. Choose one of these archetypes and click Next.

  2. Specify the Archetype parameters:
    1. Enter the Group Id, e.g. com.infinity.bpm.archetypes
    2. Enter the Artifact Id, e.g. ipp-portal
    3. Click Finish

Deselecting the JSF Configurator option to avoid Missing HttpServlet class error

After creating a new project based on archetypes, a missing HttpServlet class error is displayed in the Problems view due to an issue with the m2e-wtp Eclipse plugin. The plugin enables the JavaServer Faces project facet, because it identifies JSF dependencies, and thus also applies additional files to the project. To avoid this issue, do the following:

  1. Open the Window > Preferences dialog
  2. Select Maven > Java EE Integration
  3. Deselect the JSF Configurator option in the Select active Java EE configurators section

    Maven Preferences

Importing an existing Maven Project in Eclipse

To import an existing Maven project into your Eclipse workspace, select File > Import > Maven > Existing Maven Projects.

Import Maven projects
Figure: Importing existing Maven projects

Now M2Eclipse detects all pom files pertaining to the project and generates the project structure in Eclipse.

Select Maven project
Figure: Select Maven project to import

After a successful import, you can see the imported project folder in your Project Explorer.

Imported project folder
Figure: Imported project folder

Using Apache FOP dependency causes errors after an upgrade from IPP versions earlier than 8.0

In case you use a custom development and upgrade from an IPP version earlier than 8.0, you face issues caused by dependencies on Apache FOP (Formatting Objects Processor). Adding the following exclusion to your project's pom.xml file resolves the problem:

<exclusion>
   <artifactId>batik-js</artifactId>
   <groupId>org.apache.xmlgraphics</groupId>
</exclusion>

Retrieving Dependencies and creating WAR/EAR Files

Now enter the following command to retrieve all dependencies and create the determined WAR or EAR file with these dependencies:

mvn package

In folder target you find the created WAR or EAR file, e.g.:


Figure: Created Portal WAR

Building Client Workspaces for Console and Sysconsole Tools

Archetypes are provided to create environments for console and sysconsole clients:

Creating a Spring based Console Environment

The archetype ipp-archetype-console-spring-client helps to create a Spring based console environment. You can use it in the following way:

mvn archetype:generate -DarchetypeGroupId=com.infinity.bpm.archetypes 
   -DarchetypeArtifactId=ipp-archetype-console-spring-client 
   -DarchetypeVersion=<version> 
   -DgroupId=your.package.name -DartifactId=console -Dversion=1.0-SNAPSHOT
   -Dgoals=generate-resources

The generate-resources goal copies all dependencies into the lib folder and the carnot.properties into the etc folder of your workspace environment. Now you can execute the console command like:

bin/console.bat -user <username> -password <password> <console-cmd>

Creating a Sysconsole Client Environment

The archetype ipp-archetype-sysconsole-client creates a sysconsole client environment. You can use it in the following way:

mvn archetype:generate -DarchetypeGroupId=com.infinity.bpm.archetypes 
   -DarchetypeArtifactId=ipp-archetype-sysconsole-client  
   -DarchetypeVersion=<version>
   -DgroupId=your.package.name -DartifactId=console -Dversion=1.0-SNAPSHOT
   -Dgoals=generate-resources

The generate-resources goal copies all dependencies into the lib folder and the carnot.properties into the etc folder of your workspace environment. Now you can execute the sysconsole command like:

bin/sysconsole.bat -password sysop createschema