Skip to content

Commit

Permalink
docu
Browse files Browse the repository at this point in the history
  • Loading branch information
@rsoika
rsoika committed Aug 18, 2016
1 parent 3c89c6b commit 4e56c87
Showing 1 changed file with 91 additions and 99 deletions.
190 changes: 91 additions & 99 deletions src/site/markdown/maven.md
View file
Original file line number Diff line number Diff line change
@@ -1,69 +1,56 @@
# Maven
The Imixs-Workflow project contains a great deal of technologies which helps building powerful workflow applications. To integrate the Imixs-Workflow Engine into a business application, the project provides Maven artifacts.
The Imixs-Workflow project contains a great deal of technologies which helps building powerful workflow applications. To integrate the Imixs-Workflow Engine into a business application, the project provides Maven artifacts. Maven is a build and configuration tool which helps to organize a project and finding necessary libraries and artifacts through the Internet. Working with maven makes it almost simple to build applications based on different libraries or frameworks. General information about using Maven in a project can be found on the [Maven project site](http://maven.apache.org).

All results from the Imixs-Workflow project are provided as maven artifacts. Maven is a build and configuration tool which helps you to organize your project and finding necessary libraries and artifacts through the Internet. Working with maven makes it almost simple to build applications based on different libraries or frameworks.
## Downloads
All binaries from the Imixs-Workflow project are provided in the [maven-central-repository](http://search.maven.org/#browse). To download a binary directly from there you cab browse the [maven-central-repository](http://search.maven.org/#browse) and search for the keyword 'imixs'.

Imixs-Workflow supports maven and allows you to access all libraries easily to build your own project with workflow components. General information about using maven in a project you will
find in the [Maven project site](http://maven.apache.org).

##Downloads
All binaries from the Imixs-Workflow project are provided in the [maven-central-repository](http://search.maven.org/#browse). You can download each binary directly from there if you
browse the [maven-central-repository](http://search.maven.org/#browse) and search for the keyword 'imixs'.


##Maven Dependency
To add the dependency of Imixs-Workflow to your own maven proejct just add a new dependency to your pom.xml like shown in the following example:
## Maven Dependencies
To add the dependency of Imixs-Workflow to a maven proejct, the dependencies can be configured in the pom.xml like shown in the following example:

...
<properties>
.....
<org.imixs.workflow.version>3.9.0</org.imixs.workflow.version>
</properties>
...
<dependency>
<groupId>org.imixs.workflow</groupId>
<artifactId>imixs-workflow-core</artifactId>
<version>RELEASE</version>
<type>jar</type>
<groupId>org.imixs.workflow</groupId>
<artifactId>imixs-workflow-core</artifactId>
<version>${org.imixs.workflow.version}</version>
</dependency>
<dependency>
<groupId>org.imixs.workflow</groupId>
<artifactId>imixs-workflow-engine</artifactId>
<version>${org.imixs.workflow.version}</version>
</dependency>

Please take care about the version number. You will find the latest version number by browsing the [maven-central-repository](http://search.maven.org/#browse). You will find also more detailed informations about adding dependencies in the separate sections of the different Imixs-Workflow subprojects.
The latest version number can be look up by browsing the [maven-central-repository](http://search.maven.org/#browse). Also detailed information about each artifact are provided in separate sections of the different Imixs-Workflow subprojects.

##Snapshot Releases
Snapshot releases are newer releases of a component which are still under development. A Snapshot release should only be used in cases where the latest final release did not provide a
special feature or implementation you need to work with. You will find the Imixs snapshot releases at the [Sonatype Snapshot repository](http://oss.sonatype.org/content/repositories/snapshots).
### Snapshot Releases
Snapshot releases are newer releases of the Imixs-Workflow engine which are still under development. A Snapshot release should only be used in cases where the latest final release did not provide a specific feature or bug-fix needed to work with. The Imixs-Workflow snapshot releases are published inti the [Sonatype Snapshot repository](http://oss.sonatype.org/content/repositories/snapshots).

<strong>Note:</strong> The snapshot repository should only be used if snapshot releases are necessary for a specific build.
<strong>Note:</strong> The snapshot repository should only be used if snapshot releases are necessary for a specific build!

To access the Snapshot repository you need to add an additional configuration into your Maven settings.xml configuration file. On windows this config file is typically found or to be created in 'Documents and Settings/USERNAME/.m2'. On Linux the folder /.m2 will be found on the users home directory. To access the Sonatype Snapshot repository you only need to add the repository location. Here is an example of a settings.xml file.
To access the Snapshot repository the following additional repository location can be added into the Maven settings.xml configuration file or the project pom.xml.

<settings xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>default</id>
<activation>
</activation>
<repositories>
<!-- Sonatype Snapshot repository -->
<repository>
<id>sonatype-snaptshots</id>
<name>Sonatype Snapshot repository</name>
<url>http://oss.sonatype.org/content/repositories/snapshots</url>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>default</activeProfile>
</activeProfiles>
</settings>


...
<repositories>
<!-- Sonatype Snapshot repository -->
<repository>
<id>sonatype-snaptshots</id>
<name>Sonatype Snapshot repository</name>
<url>http://oss.sonatype.org/content/repositories/snapshots</url>
</repository>
</repositories>
....


##Deployment using Maven
Using [Maven](/api/maven_howto.html) makes it easy to setup an Enterprise Workflow Application.
Most of the steps described in the {{{./deployment.html}deplyoment guide}} can be simplified.
The following section will describe how you can use maven in your EAR and how you should setup the EAR and EJB pom.xml files.
## Java EE Module Configuration Using Maven
Using Maven makes it easy to setup an Java enterprise application. Most of the steps described in the [deployment guide](./deployment.html) can be simplified. The following section describes how you can use maven in your EAR and how you should setup the EAR and EJB pom.xml files.

###Configuring the EJB Module using maven
### Packaging the Imixs-Workflow engine into a EJB Module
Using the maven-ejb-plugin you can add a declaration for additional manifest entries. This makes it easy to add the Imixs JEE Components into your EJB module. The following example shows how to add the additional configuration to your pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
Expand All @@ -78,14 +65,17 @@ Using the maven-ejb-plugin you can add a declaration for additional manifest ent
<artifactId>imixs-workflow-jsf-sample-ejb</artifactId>
<packaging>ejb</packaging>
<version>0.0.2-SNAPSHOT</version>
<properties>
<org.imixs.workflow.version>3.9.0</org.imixs.workflow.version>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.6</source>
<target>1.6</target>
<source>1.7</source>
<target>1.7</target>
</configuration>
</plugin>
<plugin>
Expand All @@ -94,9 +84,9 @@ Using the maven-ejb-plugin you can add a declaration for additional manifest ent
<configuration>
<ejbVersion>3.0</ejbVersion>
<archive>
<!-- add the EJB module imixs-workflow-jee-impl -->
<!-- add the EJB module imixs-workflow-engine -->
<manifestEntries>
<Class-Path>imixs-workflow-engine-3.0.0.jar imixs-workflow-core-3.0.0.jar</Class-Path>
<Class-Path>imixs-workflow-engine-${org.imixs.workflow.version}.jar imixs-workflow-core-${org.imixs.workflow.version}.jar</Class-Path>
</manifestEntries>
</archive>
</configuration>
Expand All @@ -107,24 +97,12 @@ Using the maven-ejb-plugin you can add a declaration for additional manifest ent
</dependencies>
</project>

Be careful that the jar versions defined by the Class-Path entry are matching the versions provided by the EAR module!
__Note:__ The jar versions defined by the Class-Path entry need to match the jar versions provided by the module!

###Packaging the Imixs JEE Component into an EAR using maven
To package the Imixs JEE components into your EAR you can extend the pom.xml of your ear module. The following example shows how you define the structure of your EAR using maven:
### Packaging the Imixs-Workflow engine into an EAR
To package the Imixs-Workflow engine into an EAR the pom.xml can be configured as shown in the following example:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<description>jsf sample application</description>
<parent>
<artifactId>imixs-workflow-jsf-sample</artifactId>
<groupId>org.imixs.workflow</groupId>
<version>0.0.2-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<groupId>org.imixs.workflow</groupId>
<artifactId>imixs-workflow-jsf-sample-ear</artifactId>
<packaging>ear</packaging>
<version>0.0.2-SNAPSHOT</version>
...
<build>
<plugins>
<plugin>
Expand All @@ -133,29 +111,22 @@ To package the Imixs JEE components into your EAR you can extend the pom.xml of
<configuration>
<version>5</version>
<modules>
<webModule>
<groupId>org.imixs.workflow</groupId>
<artifactId>imixs-workflow-jsf-sample-web </artifactId>
<contextRoot>/workflow</contextRoot>
</webModule>
<!-- -->
<ejbModule>
<groupId>org.imixs.workflow</groupId>
<artifactId>imixs-workflow-jsf-sample-ejb</artifactId>
</ejbModule>
<!-- Web Module -->
....
<!-- EJB Module -->
...
<!-- EJB JPA -->
<!-- Imixs-Workflow -->
<JarModule>
<groupId>org.imixs.workflow</groupId>
<artifactId>imixs-workflow-engine </artifactId>
</JarModule>
<!-- Imixs Shared Libs -->
<JarModule>
<groupId>org.imixs.workflow</groupId>
<artifactId> imixs-workflow-core </artifactId>
</JarModule>
....
</modules>
</configuration>
Expand All @@ -175,22 +146,43 @@ To package the Imixs JEE components into your EAR you can extend the pom.xml of
<type>jar</type>
</dependency>
<!-- Application dependencies -->
<dependency>
<groupId>org.imixs.workflow</groupId>
<artifactId>imixs-workflow-jsf-sample-web</artifactId>
<type>war</type>
<version>0.0.2-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.imixs.workflow</groupId>
<artifactId>imixs-workflow-jsf-sample-ejb</artifactId>
<type>ejb</type>
<version>0.0.2-SNAPSHOT</version>
</dependency>
....
</dependencies>
</project>



__Note:__ The deployment descriptiors for the EJB Module (ejb-jar.xml) are not part of the Imixs-Workflow jar files and need to be provided by the deployed application. This enables the application to provide custom environment specific configurations. See the following example of a ejb-jar.xml file providing the JNDI Mail ressource to the Imixs-Workflow engine:


<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://java.sun.com/xml/ns/javaee" xmlns:ejb="http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"
version="3.0">
<enterprise-beans>
<session>
<ejb-name>WorkflowService</ejb-name>
<ejb-class>org.imixs.workflow.jee.ejb.WorkflowService</ejb-class>
<session-type>Stateless</session-type>
<!-- Mail Configuration -->
<env-entry>
<description>Mail Plugin Session name</description>
<env-entry-name>IMIXS_MAIL_SESSION</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>java:/mail/org.imixs.workflow.mail</env-entry-value>
</env-entry>
<ejb-ref>
<ejb-ref-name>ejb/PropertyService</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<remote>org.imixs.workflow.jee.util.PropertyService</remote>
</ejb-ref>
<!-- Mail resource -->
<resource-ref>
<res-ref-name>java:/mail/org.imixs.workflow.mail</res-ref-name>
<res-type>javax.mail.Session</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
</session>
</enterprise-beans>
</ejb-jar>

0 comments on commit 4e56c87

Please sign in to comment.