48 Using the Oracle SOA Suite Development Maven Plug-In

This chapter describes how to use the Oracle SOA Suite development Maven plug-in to build and manage SOA composite application projects. The Oracle SOA Suite development Maven plug-in enables you to compile, package, deploy, test, and undeploy a SOA composite application in a Maven environment.

This chapter includes the following sections:

For more information about using Maven with Oracle Fusion Middleware, see Developing Applications Using Continuous Integration and Using the WebLogic Maven Plug-In in Developing Applications for Oracle WebLogic Server.

For detailed information on using Maven to build applications and projects, see http://maven.apache.org/users/index.html.

48.1 Introduction to the Oracle SOA Suite Maven Plug-in

Maven is a build automation tool that enables you to create and manage runtime projects. Using the Oracle SOA Suite Maven plug-in, you can build and manage a SOA composite application. Maven relies on an artifact repository for all of its dependencies. All the installed Oracle libraries are propagated into the Maven repository. This enables Maven to recognize them as artifacts and address them in the Project Object Model (POM) file.

48.1.1 POM Files and Archetypes

Maven projects are configured using a POM file. The POM file describes dependencies such as the SOA Infrastructure tools that are required to build the composites.

An archetype is a template for creating a project. Archetypes are provided to create a new SOA application containing a single SOA project, or to add an additional SOA project to an existing SOA application. These archetypes provide for the ability to compile, package, deploy, test, and undeploy a SOA composite application.

The following shows a sample Maven POM file for Oracle SOA Suite:

<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
 http://maven.apache.org/xsd/maven-4.0.0.xsd"
 xmlns="http://maven.apache.org/POM/4.0.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.test</groupId>
    <artifactId>MyComposite</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>sar</packaging>
    
    <!--
           This POM was generated from the SOA Maven Archetype.
           Comments in this POM guide you how to use it with your project.
           This POM relates to this SOA Composite, i.e. the one in this same
           directory. There is another POM in the SOA Application directory (up
           one) which handles the whold SOA Application, which may contain
           additional projects.
 
           The parent points to the common SOA parent POM.  That is a special POM
           that is shipped by Oracle as a point of customization (only).  You can
           add default values for properties like serverUrl, etc. to the SOA
           common parent POM, so that you do not have to specify them over and
           over in every project POM. 
    -->
    <parent>
        <groupId>com.oracle.soa</groupId>
        <artifactId>soa-project-common</artifactId>
        <version>12.1.3-0-0</version>
    </parent>
    
    <properties>
        <!-- these parameters are used by the compile goal -->
        <scac.input.dir>${project.basedir}/SOA/</scac.input.dir>
        <scac.output.dir>${project.basedir}/target</scac.output.dir>
        <scac.input>${scac.input.dir}/composite.xml</scac.input>
        <scac.output>${scac.output.dir}/out.xml</scac.output>
        <scac.error>${scac.output.dir}/error.txt</scac.error>
        <scac.displayLevel>1</scac.displayLevel>
        <!-- if you are using a config plan, uncomment the following line and
             update to point to your config plan -->
        <!--<configplan>${scac.input.dir}/configplan.xml</configplan>-->
 
        <!-- these parameters are used by the deploy and undeploy goals -->
        <composite.name>${project.artifactId}</composite.name>
        <composite.revision>${project.version}</composite.revision>
        <composite.partition>default</composite.partition>
        <serverUrl>serverUrl</serverUrl>
        <user>user</user>
        <password>password</password>
        <overwrite>true</overwrite>
        <forceDefault>true</forceDefault>
        <regenerateRulebase>false</regenerateRulebase>
        <keepInstancesOnRedeploy>false</keepInstancesOnRedeploy>
 
        <!-- these parameters are used by the test goal -->
        <!-- if you are using the sca-test (test) goal, you need to uncomment the
             following line and point it to your jndi.properties file. -->
        <jndi.properties.input>${basedir}/jndi.properties</jndi.properties.input>
        <scatest.result>${scac.output.dir}/testResult</scatest.result>
        <!--  input is the name of the composite to run test suties against -->
        	<input>MyComposite</input>
    </properties>
 
    <!--
           These refer to the properties defined above.  You should probably not
           need to make any changes beflow this point - these just point to the
           properties above.
    -->
    <build>
        <plugins>
            <plugin>
                <groupId>com.oracle.soa.plugin</groupId>
                <artifactId>oracle-soa-plugin</artifactId>
                <version>12.1.3-0-0</version>
                <configuration>
                    <compositeName>MyComposite</compositeName>
                    <composite>${scac.input}</composite>
                    <sarLocation>${scac.output.dir}/sca_${project.artifactId}_
                                 rev${composite.revision}.jar</sarLocation>
                    <serverUrl>${serverUrl}</serverUrl>
                    <!-- note: compositeRevision is needed to package, revision is
                         needed to undeploy -->
                    <compositeRevision>${composite.revision}</compositeRevision>
                    <revision>${composite.revision}</revision>
                    <scacInputDir>${scac.input.dir}</scacInputDir>
                    <!-- note: if this composite contains a component that depends
                         on MDS to build, e.g. a Human Task or Business Rule, then
                         you will need to uncomment the next line, and edit it to
                         point to your application directory (which contains
                         .adf/adf-config.xml file with MDS configuration in it -->
                    <!--<appHome>${project.basedir}/..</appHome>-->
                    <!--  If you have a composite which contains a component that 
                          depends on MDS (eg. Human Task, Business Rule) AND you 
                          want to use a file-based MDS repository, then you
                          need to do either:
                          1. update the .adf/META-INF/adf-config.xml to point to
                             the correct location of the file based repository,
                             i.e. remove the reference to ${oracle.home} in that
                             file, or
                          2. define oracleHome here and leave the adf-config.xml
                             file as is.  Note that the correct value is the path
                             to your SOA Quickstart or JDeveloper install
                             directory, with "/soa" appended to it.
                    -->
                    <!--<oracleHome>JDEV_HOME/soa</oracleHome>-->
                    <user>${user}</user>
                    <password>${password}</password>
		                    <input>${input}</input>
                </configuration>
                <!-- extensions=true is needed to use the custom sar packaging
                     type -->
                <extensions>true</extensions>
            </plugin>
        </plugins>
    </build>
</project>

Note:

If you are using a component in your composite that depends on MDS, such as Human Tasks or Business rules, you must uncomment the <appHome>${project.basedir}/..</appHome> line and edit it to point to your application directory.

If you are using a component that depends on MDS and you want to use a file-based MDS, such as the one referenced in the default adf-config.xml file, you must also uncomment the <oracleHome>JDEV_HOME/soa</oracleHome> line and edit it to point to your SOA Quickstart or JDeveloper install directory, with /soa appended to it.

The following shows the archetype coordinates in the POM file for creating an Oracle SOA Suite Application:

<groupId>com.oracle.soa.archetype</groupId>
<artifactId>oracle-soa-application</artifactId>
<version>12.1.3-0-0</version>

48.1.2 Maven Plug-in Goals

Goals are associated with different phases of the composite life cycle.

When you invoke a goal associated with a life cycle phase, Maven executes all goals mapped to all phases up to and including the goal you name. For example, if you execute the test goal, the compile, package, and deploy goals are executed before the test goal. The description of each goal in this section lists the actions performed when each goal is invoked.

To support the life cycle of building and deploying a SOA composite application, the following executable plug-in goals are provided.

  • compile (scac)

  • package (sar)

  • deploy

  • test (sca-test)

  • undeploy

Before executing a goal, ensure that you have provided all of the necessary parameters for that goal in the POM file. See POM Files and Archetypes for a sample POM file.

Note:

If you have changed the name of the project, composite, or project directory, ensure that you update the POM file with the new names before executing any of these goals.

The following example shows the groupId, artifactId, and version coordinates for Oracle SOA Suite plug-ins in the POM file.

<groupId>com.oracle.soa.plugin</groupId>
<artifactId>oracle-soa-plugin</artifactId>
<version>12.1.3-0-0</version>
48.1.2.1 compile

The compile goal compiles a SOA composite application. Oracle SOA Suite provides a native Maven implementation for this goal. The following command compiles the SOA composite application:

mvn compile
48.1.2.2 package

The package goal packages the artifacts of a SOA composite application into a SOA archive (SAR) file. The following command compiles and packages the SOA composite application:

mvn package
48.1.2.3 deploy

The deploy goal deploys the SOA composite application. Oracle SOA Suite provides a native Maven implementation for this goal. The following command compiles the SOA composite application, packages the composite into a SAR file, and deploys the SAR file to the server.

mvn pre-integration-test
48.1.2.4 test

The test goal performs a test of a SOA composite application. Oracle SOA Suite provides a native Maven implementation for this goal.

You must first create tests in Oracle JDeveloper before running the test goal. For more information about creating tests using JDeveloper, see Automating Testing of SOA Composite Applications.

You must also include a jndi.properites file before running the test goal. Edit the following line in the POM file to point to a jndi.properties file: <jndi.properties.input>${basedir}/jndi.properties</jndi.properties.input>

The following shows a sample jndi.properties file:

         java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory
         java.naming.provider.url=t3://servername:7103/soa-infra
         java.naming.security.principal=weblogic
         java.naming.security.credentials=welcome1
         dedicated.connection=true
         dedicated.rmicontext=true

The following command compiles the composite, packages the composite into a SAR file, deploys the SAR file to the server, and tests the composite.

mvn verify
48.1.2.5 undeploy

The undeploy goal undeploys the SOA composite application. Oracle SOA Suite provides a native Maven implementation for this goal. The following command undeploys the composite.

Note:

The undeploy goal is not mapped to a life cycle phase. You must explicitly invoke it by name.

mvn com.oracle.soa.plugin:oracle-soa-plugin:undeploy

48.1.3 Using Maven Online Help

Maven online help provides you with a list of goals and their associated commands. For example, enter the following command to obtain online help for the Maven test goal:

mvn help:describe -Ddetail=true -Dplugin=com.oracle.soa.plugin:oracle-soa-plugin:12.1.3-0-0 -Dgoal=test

This command displays the following help details:

oracle-soa:test
Description: Description: To execute SCA Test Suites.
Implementation: com.oracle.soa.plugin.SoaTest
Language: java
Bound to phase: verify
Goal Prefix: oracle-soa

Available parameters:

   format (Default: native)
      User property: format
      The format of the output - 'native' or 'junit'.

   input
      Required: true
      User property: input
      The name of the composite to execute tests against.

   jndiPropertiesInput
         Required: true
         User property: jndi.properties.input
         Path to JNDI properties file required for SCA Test execution.
         This file should contain contents similar to the following:
         java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory
         java.naming.provider.url=t3://servername:7103/soa-infra
         java.naming.security.principal=weblogic
         java.naming.security.credentials=welcome1
         dedicated.connection=true
         dedicated.rmicontext=true

      partition (Default: default)
         User property: partition
         Which SOA partition the composite is deployed in.

      result (Default: ${java.io.tmpdir}/out)
         User property: result
         Where to place the results.

      timeout (Default: 300)
         User property: timeout
         How long to wait for tests to complete before timing out.

48.2 Installing the Oracle SOA Suite Maven Plug-in

A distribution of Maven 3.0.5 is included with Oracle Fusion Middleware in the following location:

Middleware_Home/Oracle_Home/oracle_common/modules/org.apache.maven_3.0.5

For information about installing Maven for Oracle Fusion Middleware, see "Installing and Configuring Maven for Build Automation and Dependency Management" in Developing Applications Using Continuous Integration. Be sure to follow the setup instructions in Section 5.1, "Setting Up the Maven Distribution" and Section 5.2, "Customizing Maven Settings."

48.2.1 How to Configure the Oracle SOA Suite Maven Plug-In

Before you can use the Oracle SOA Suite Maven plug-in you must populate the Maven repository with Oracle artifacts. For more information about populating the repository, see "Populating the Maven Repository Manager" in Developing Applications Using Continuous Integration for more information. The steps below link to specific sections of this guide.

To configure the Oracle SOA Suite development Maven plug-in:

  1. Navigate to ORACLE_HOME/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/12.1.3.
  2. Run the following command to install the Maven sync plug-in:
    mvn install:install-file -DpomFile=oracle-maven-sync-12.1.3.pom -Dfile=oracle-maven-sync-12.1.3.jar
    

    For more options, see "Installing Oracle Maven Synchronization Plug-In."

  3. Run the following command to seed the Oracle SOA Suite development Maven plug-in into the Maven repository:
    mvn com.oracle.maven:oracle-maven-sync:push -DoracleHome=ORACLE_HOME
    

    Where ORACLE_HOME is the full path to your Oracle Fusion Middleware installation. For more options, see "Running the Oracle Maven Synchronization Plug-In."

  4. Validate whether you have successfully installed the plug-in using the Maven help:describe goal.
    mvn help:describe -DgroupId=com.oracle.soa.plugin
    -DartifactId=oracle-soa-plugin -Dversion=12.1.3-0-0
    

    The following is an excerpt of the information that confirms installation of the Oracle SOA Suite plug-in:

    Name: Oracle SOA Maven Plugin
    Description: This plugin allows users to compile, package, deploy, test and  undeploy SOA composites.
    Group Id: com.oracle.soa.plugin
    Artifact Id: oracle-soa-plugin
    Version: 12.1.3-0-0
    Goal Prefix: oracle-soa
    This plugin has 6 goals:
    oracle-soa:compile
    

48.3 Using the Oracle SOA Suite Maven Archetype

Use the Oracle SOA Suite archetype to generate a POM file for a SOA application. Run the following command from the parent directory into which you want to add a SOA application. The SOA application is created in a subdirectory named from the value of the artifactId property.

Note:

SOA Applications created using the Oracle SOA Suite Maven archetype are the same as those created in Oracle JDeveloper using the Create SOA Application wizard.

mvn archetype:generate 
 -DarchetypeGroupId=com.oracle.soa.archetype
 -DarchetypeArtifactId=oracle-soa-application
 -DarchetypeVersion=12.1.3-0-0 
 -DarchetypeRepository=local
 -DgroupId=org.my.test
 -DartifactId=test-soa-application
 -DprojectName=test-soa-project
 -Dversion=1.0-SNAPSHOT

Where:

Property Description

archetypeGroupId

Enter the group ID of the archetype to use (com.oracle.soa.archetype).

archetypeArtifactId

Enter the artifact ID of the archetype to use (oracle-soa-application).

archetypeVersion

Enter the archetype version (12.1.3-0-0).

archetypeRepository

Enter the Maven repository to use. (Optional)

groupId

Enter the group ID of the project to build (for this example, org.my.test).

artifactId

Enter the artifact ID of the project to build. This becomes the name of the subdirectory (for this example, test-soa-project) in the current directory. The SOA application and the first SOA project are created in this subdirectory.

projectName

Enter the name for the SOA Project to be created inside the SOA application This is also the name of the composite.

package

Enter the name for the SOA Project to be created inside the SOA application. (Optional)

version

Enter the version of the project to build (for this example, 1.0-SNAPSHOT)