Projects‎ > ‎

Maven Support

This document will provide detail into the steps necessary to convert the existing OpenPTK ant based project to a maven based project.  Jira issue OPENPTK-107 will be used to track the progress of a potential migration to maven.

As quoted from the Apache Maven site:

"Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information."

Deployment Plan

  1. Create pom files:
    1. OpenPTK
      1. Core
        1. Base
        2. Client
        3. Framework
        4. Server
        5. Servlet
        6. Taglib
      2. Misc
        1. OpenSPMLv2
      3. Plugins
        1. MimeUtil
        2. SendEmail
        3. Templates
      4. Service
        1. EmbedJDBC
        2. JDBC
        3. JNDI
        4. OIMClient
        5. OracleIdMgr
        6. OracleJDBC
        7. SPML
        8. SPML2
        9. UnboundIDLDAP
      5. Apps
        1. CLI
        2. IdentityCentral
        3. Portlets
        4. Register
        5. SOAPWS
        6. UserManagementLite
      6. Samples
        1. Auth
        2. Client
        3. Framework
        4. Taglib
    2. commit svn changes
  2. Move src files
    1. re-locate src/java to src/main/java
    2. update pom files
    3. update ant script
    4. commit svn changes
  3. Documentation
    1. Maven
      1. Getting started
      2. Basic commands and options
    2. NetBeans project changes
      1. Remove NetBeans projects related to OpenPTK
      2. Access maven pom-based projects
    3. Services, getting and configuring non-public, dependant jars
      1. Oracle DB
      2. Oracle Idm 10g
      3. Oracle Idm 11g
    4. Services, re-distributable jars
      1. SPML
      2. SPML2
    5. Deprecation plan
      1. Local jar files in lib
  4. Release version of OpenPTK (Phase One of maven migration)
  5. Discontinue support for ant script
    1. remove lib folder and its jar files
    2. delete build files
  6. Release version of OpenPTK (Phase Two of maven migration)

File Structure

The high level structure of a maven project is based on similar principals already used in the OpenPTK ant bases structure.  Below is a table that attempts to show a couple of similarities in convention in the way that maven recommends a project layout and how OpenPTK does it today.  The only real difference is the injection of a couple directories (main, test) which hold the projects "main" code and "test" code.

 OpenPTK
Today
Maven
Convention
Build Configuration
build.xml
pom.xml
Source Code
src/java/org/...
src/main/java/org/...
Test Code
{not used today}
src/test/java/org/...

The way we organize each of the OpenPTK projects today still applies in a maven project structure.

Maven Info

A maven pom.xml file includes several top level items that define each maven project.  The required items are organized into a project definition like:

  <groupId>org.openptk</groupId>
  <artifactId>framework</artifactId>
  <version>2.1-SNAPSHOT</version>
  <packaging>jar</packaging>

  <name>OpenPTK-Framework</name>
  <url>http://www.openptk.org</url>

This information is used to uniquely identify:
  • the groupId or project this belongs to
  • the artifactId within the project
  • the version of the artifact
  • the packaging of the artifact (i.e. jar, war, zip)
  • the name of the project
  • the URL to obtain more information on about the project
For the most part, each of the current ant package targets would result in some type of maven pom.xml/project.  In some cases, these projects would consist of src code with compiles, etc...  In other cases, they may be pom build modules with other dependencies.

Maven Dependencies

In the same way that ant defines dependencies in a build.xml file, maven includes the ability to include dependency information in the pom.xml file.  An example might look like:

  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>${project.groupId}</groupId>
      <artifactId>base</artifactId>
      <version>${project.version}</version>
    </dependency>
  </dependencies>

In this example, there are a couple of dependencies:
  • junit (version 3.8.1)  - Automatic for standard maven projects
  • ${project.groupId} base (version ${project.version}) - This specifies a dependency on the base artifactId within the same project and version.

Proposed OpenPTK Maven Projects

Below is a proposed table including a cross reference of the OpenPTK Project names today to that of the mavon pom.xml components.

For all cases, the following groupId and version are proposed:
  • groupId = org.openptk
  • version = 2.1-SNAPSHOT

OpenPTK
Project
 Maven
Name
Maven
ArtifactId
Maven
Dependencies
BaseOpenPTK-Base
base
-
ClientOpenPTK-Client
client
base
jsr311-api (ver 1.1.1)
jersey-client (ver 1.11)
jersey-core (ver 1.11)
FrameworkOpenPTK-Framework
framework
base
ServerOpenPTK-Server
server
framework

jsr311-api (ver 1.1.1)
asm-3.1.jar

ServiceOpenPTK-Service
service
framework
TaglibOpenPTK-Taglib
taglib
client
javaee-api




ext/Service/EmbedJDBC
OpenPTK-EmbedJDBC
service-embedjdbc
service-jdbc
ext/Service/JDBC
OpenPTK-JDBC
service-jdbc
framework
ext/Service/JNDI
OpenPTK-JNDI
service-jndi
service-jndi
ext/Service/LDAP
OpenPTK-LDAP
service-ldap
framework
ext/Service/OIMClient
OpenPTK-OIMClient
service-oimclient

ext/Service/OracleIdMgr
OpenPTK-OracleIdMgr
service-oracleidmgr

ext/Service/OracleJDBC
OpenPTK-OracleJDBC
service-oraclejdbc

ext/Service/SPML
OpenPTK-SPML
service-spml

ext/Service/SPML2
OpenPTK-SPML2
service-spml2

ext/Service/UnboundIDLDAPSDK
OpenPTK-UnboundIDLDAPSDK
service-unboundidldapsdk





Apps/CLI
OpenPTK-CLI
apps-cli

Apps/Demo
OpenPTK-Demo
apps-demo

Apps/Portlets
OpenPTK-Portlets
apps-porlets

Apps/Register
OpenPTK-Register
apps-register

Apps/IdentityCentral
OpenPTK-IdentityCentral
apps-identitycentral
 
Apps/SOAP-WS
OpenPTK-SOAP-WS
apps-soap-ws

Apps/UserManagementLite
OpenPTK-UML
apps-uml





Samples/Auth
OpenPTK-Samples-Auth
samples-auth

Samples/Client
OpenPTK-Samples-Client
samples-client

Samples/Framework
OpenPTK-Samples-Framework
samples-framework

Samples/Taglib
OpenPTK-Samples-Taglib
samples-taglib


Issues

Service specific builds

The "packaged" war files, for the server, should only contain the necessary Services.  There  are two reasons for this:
  1. Some of the Services depend on external JARs that are not automatically available from the Maven repository or should not be re-distributed by this project.  It will be difficult to build the Server if it "depends" on all the Services, like it does with "ant".
  2. The Server would have a smaller foot print, not needing the OpenPTK Service jars and their related dependent jars.
The following table identifies the "packages" and jars that are not automatically available in the maven repository.

 Maven Artifact Id Jars  Description Status
service-oimclientoimclient.jarOracle Identity Manager 11gThis is available through the installation process of Oracle Identity Manager 11g
service-oracleidmgrxlAPI.jar
xlAuthentication.jar
xlCache.jar
xlCrypto.jar
xlLogger.jar
xlUtils.jar		Oracle Identity Manager 10gThese are available through the installation process of Oracle Identity Manager 10g
service-oraclejdbcojdbc6.jarOracle JDBC driver.  This is available from the Oracle web site.  The end-user needs to download it.
service-spmlopenspml.jar
idm_80_openspml.jar		OASIS openspml v1 and Sun / Waveset impl.Available from the OASIS web site.  These jars can be re-distributed
service-spml2openptk-openspml2-toolkit.jar
openspml2-toolkit.jar
OASIS openspml v2 and Sun / Waveset impl.Available from the OASIS web site.  These jars can be re-distributed 

Configuration file specific builds

This "issue" is related to the above (Service specific builds) issue.

A deployment may need to specify a configuration file other than the default (openptk.xml).  A configuration file may only contain a specific Service.  There needs to be a process for copying a customized configuration file to the standard file name, during deployment.

Local JARs

Adding jars to the maven local repository.

service-oimclient

mvn install:install-file \
-DgroupId=com.oracle.iam \
-DartifactId=oracle-iam-oimclient \
-Dpackaging=jar \
-Dversion=11.1.1.3.0 \
-DgeneratePom=true \
-Dfile=oimclient.jar

service-oracleidmgr

mvn install:install-file \
-DgroupId=com.thortech \
-DartifactId=thortech-xlapi \
-Dpackaging=jar \
-Dversion=9.1.0 \
-DgeneratePom=true \
-Dfile=xlAPI.jar

mvn install:install-file \
-DgroupId=com.thortech \
-DartifactId=thortech-xlauthentication \
-Dpackaging=jar \
-Dversion=9.1.0 \
-DgeneratePom=true \
-Dfile=xlAuthentication.jar

mvn install:install-file \
-DgroupId=com.thortech \
-DartifactId=thortech-xlcache \
-Dpackaging=jar \
-Dversion=9.1.0 \
-DgeneratePom=true \
-Dfile=xlCache.jar

mvn install:install-file \
-DgroupId=com.thortech \
-DartifactId=thortech-xlcrypto \
-Dpackaging=jar \
-Dversion=9.1.0 \
-DgeneratePom=true \
-Dfile=xlCrypto.jar

mvn install:install-file \
-DgroupId=com.thortech \
-DartifactId=thortech-xllogger \
-Dpackaging=jar \
-Dversion=9.1.0 \
-DgeneratePom=true \
-Dfile=xlLogger.jar

mvn install:install-file \
-DgroupId=com.thortech \
-DartifactId=thortech-xlutils \
-Dpackaging=jar \
-Dversion=9.1.0 \
-DgeneratePom=true \
-Dfile=xlUtils.jar

service-oraclejdbc

mvn install:install-file \
-DgroupId=com.oracle.jdbc \
-DartifactId=oracle-jdbc \
-Dpackaging=jar \
-Dversion=6 \
-DgeneratePom=true \
-Dfile=ojdbc5.jar

service-spml

mvn install:install-file \
-DgroupId=org.openspml \
-DartifactId=openspml \
-Dpackaging=jar \
-Dversion=1.2.2 \
-DgeneratePom=true \
-Dfile=openspml.jar

mvn install:install-file \
-DgroupId=org.openspml \
-DartifactId=openspml-idm80 \
-Dpackaging=jar \
-Dversion=1.2.2 \
-DgeneratePom=true \
-Dfile=idm_80_openspml.jar

service-spml2

mvn install:install-file \
-DgroupId=org.openspml.v2 \
-DartifactId=openspmlv2-toolkit \
-Dpackaging=jar \
-Dversion=2 \
-DgeneratePom=true \
-Dfile=openspml2-toolkit.jar

mvn install:install-file \
-DgroupId=com.sun.idm \
-DartifactId=idmclient \
-Dpackaging=jar \
-Dversion=1 \
-DgeneratePom=true \
-Dfile=idmclient.jar

Set up

Extra setup steps options
The generated deployable war file (for the server) may need to be specific to a combination of the web container and identity repository

  Jetty (embed) Tomcat 6 Glassfish v3 Weblogic 10.3
 derby X X  
 mysql    
 oracle db    
 jndi    
 unboundid    
 OIM 11g    X
 OIM 10g    
 spml    
 spml2    

.m2

Create a settings.xml file in your ${HOME}/.m2 directory.  This file contains maven related settings that are unique to users system.  The following example has local tomcat settings:

<settings>
    <servers>
    <server>
        <id>tomcat</id>
        <username>admin</username>
        <password>admin</password>
    </server>
    </servers>
</settings>

Tomcat

https://wiki.base22.com/display/btg/How+to+create+a+Maven+web+app+and+deploy+to+Tomcat+-+fast

Commands


 Command Description
 mvn cleanRemove the build files from the local directories 
 mvn compileCompile the local source files
 mvn packagePackage the local object files into their package formats
 mvn installInstall the packages into the local maven repository (~/.m2)
 mvn testRun associated JUnit tests
 mvn tomcat:deployDeploy war file to tomcat : localhost:8080
 mvn tomcat:redeployRe-deploy war file
 mvn tomcat:undeployUn-deploy war file
 mvn help:active-profiles
 Show which profiles are active
 mvn <cmd> -P <profile1>,<profile2>,...
 Specify the profile to use
  • derby : (default) embedded java db
  • jndi : LDAP using JNDI
  • mysql : MySQL database table
  • oim10g : Oracle Identity Manager 10g (register only)
  • oim11g : Oracle Identity Manager 11g
  • oracledb : Oracle database table
  • spml : SPML v1
  • spml2 : SPML v2
  • unboundid : LDAP using UnboundId SDK
mvn jetty:run-war
mvn jetty:run-war -P <profile>
Run the embedded Servlet Container (jetty) with the specified Profile.  Note:  run this from the ./projects/OpenPTK/Server directory
mvn assembly:assembly
Used by the CLI App to "assemble" the zip file ... unzip and use it