Oracle Fusion Middleware provides a Maven plug-in and two archetypes are provided for Oracle SOA Suite and Oracle Business Process Management.

Table 6-1 describes the Maven coordinates.

Table 6-2 describes the goals supported by the Oracle SOA Suite plug-in.

The SOA Application archetype allows you to create a new SOA application with a single SOA Project in it. This can be imported in JDeveloper for editing.

The SOA Project archetype allows you to add a new SOA Project to an existing SOA Application.

You can create a new SOA application (containing a single SOA project) using the SOA Maven archetype.

To do so, run a command similar to the following:

mvn archetype:generate
     -DarchetypeGroupId=com.oracle.soa.archetype
     -DarchetypeArtifactId=oracle-soa-application
     -DarchetypeVersion=14.1.2-0-0
     -DgroupId=org.mycompany
     -DartifactId=my-soa-app
     -Dversion=1.0-SNAPSHOT
     -DprojectName=my-project

This command runs Maven's archetype plug-in's generate goal which allows you to create a new SOA Application from an archetype. Table 6-3 describes the parameters.

Table 6-3 Parameters for the Oracle SOA Suite Application

Parameter	Purpose
archetypeGroupId	The group ID of the archetype that you want to use to create the new SOA application. This must be com.oracle.soa.archetype, as shown in the previous example.
archetypeArtifactId	The artifact ID of the archetype that you want to use to create the new SOA application. This must be oracle-soa-application, as shown in the previous example.
archetypeVersion	The version of the archetype that you want to use to create the new SOA application. This must be 14.1.2-0-0, as shown in the previous example.
groupId	The group ID for your new SOA application. This would normally start with your organization's domain name in reverse format.
artifactId	The artifact ID for your new SOA application. This would normally be an identifier for this SOA application.
version	The version for your new SOA application. This would normally be 1.0-SNAPSHOT for a new project.
projectName	The name for the SOA project inside your new SOA application. This should be different to the name of the SOA application (artifactId).

You can also run the command without any arguments, as shown in the following example. In this case, Maven displays a list of available archetypes and prompts you to enter the required information.

mvn archetype:generate

After creating your application, it contains the following files, assuming you named your application my-soa-app and your project my-project, as shown in the previous example:

Description of the illustration maven_dt_013.eps

The generated project contains files and a handful of empty directories. The files are described in Table 6-4.

Table 6-4 Files Created for the Oracle SOA Suite Application and Project

File	Purpose
pom.xml	The Maven Project Object Model (POM) file that describes your new application. It includes the Maven coordinates that you specified for your application, and a reference to the SOA project inside the application.
PROJECT/pom.xml	The Maven POM file that describes your new project. It includes the Maven coordinates that you specified for your project, and the appropriate plug-in definitions to use the SOA Maven Plug-In to build your project into a SAR file.
PROJECT/composite.xml	Composite metadata.
.adf/META-INF/adf-config.xml	The definitions for MDS repositories that may be needed to build your composites.
Others	The remainder are the standard files that are created in any new composite. These are the same files as you would find in a new SOA Application and SOA Project created in JDeveloper.

You can create a new SOA project (in an existing SOA application) using the SOA Maven archetype.

To do so, run a command similar to the following, while in the SOA application directory:

mvn archetype:generate
    -DarchetypeGroupId=com.oracle.soa.archetype
    -DarchetypeArtifactId=oracle-soa-project
    -DarchetypeVersion=14.1.2-0-0
    -DgroupId=org.mycompany
    -DartifactId=my-second-project
    -Dversion=1.0-SNAPSHOT

This command runs Maven's archetype plug-in's generate goal which allows you to create a new SOA Project from an archetype. Table 6-5 describes the parameters:

Table 6-5 Parameters for the Oracle SOA Suite Project

Parameter	Purpose
archetypeGroupId	The group ID of the archetype that you want to use to create the new SOA application. This must be com.oracle.soa.archetype, as shown in the previous example.
archetypeArtifactId	The artifact ID of the archetype that you want to use to create the new SOA application. This must be oracle-soa-project, as shown in the previous example.
archetypeVersion	The version of the archetype that you want to use to create the new SOA application. This must be 14.1.2-0-0, as shown in the previous example.
groupId	The group ID for your new SOA project. This would normally start with your organization's domain name in reverse format.
artifactId	The artifact ID for your new SOA project. This would normally be an identifier for this SOA project.
version	The version for your new SOA project. This would normally be 1.0-SNAPSHOT for a new project.

You can also run the command without any arguments, as shown in the following example. In this case, Maven displays a list of available archetypes and prompts you to enter the required information.

mvn archetype:generate

After creating your new project, it contains the following files, assuming that you named your project my-second-project:

Description of the illustration maven_dt_014.eps

The generated project contains files and a handful of empty directories. The files are described in Table 6-4.

The mvn generate command also updates your SOA Application POM to add the new project. For example, if you created this project in the application in Creating a New SOA Application and Project from a Maven Archetype, you would see the following list in the SOA Application POM:

<modules>
  <module>my-project</module>
  <module>my-second-project</module>
</modules>

When you have a SOA Application with multiple SOA Projects like this (a Maven multi-module project), Maven builds your projects one by one, in the order they are listed in the SOA Application POM.

You can edit your SOA application in Oracle JDeveloper to configure SOA composites.

1. Open the File menu, then select Import….
2. In the Import dialog box, select the Maven Project option and click OK.
   The Import Maven Projects dialog appears.
3. In the Root Directory field, enter the path to the application you want to import into JDeveloper.
4. In the Settings File field, enter the path to your Maven settings.xml file. The default value is most likely correct unless you are using a non-standard location for your Maven settings file.
5. Click Refresh to load a list of projects available at that location.
6. Select the projects that you want to import. Also, select Also import source files into application and Update existing JDeveloper Projects to synch with imported POM files.
7. Click OK to complete the import.

After you have written your project code, you can use Maven to build the project.

1. To run the SCA validation on your project, run this command:

   mvn compile
   

2. To build the SAR file, run this command:

   mvn package

To build these projects, you need to provide the build with access to an MDS repository. This can be either a file-based or a database-based MDS repository.

The MDS repository connection details are specified in the SOA Application/.adf/META-INF/adf-config.xml file. This means that any SOA Project which requires access to MDS, must be located inside a SOA Application.

If you create a new project using the SOA Maven Application archetype or using JDeveloper, the adf-config.xml file will contain the following default MDS repository configuration:

<metadata-store-usages>
  <metadata-store-usage id="mstore-usage_1">
    <metadata-store class-name="oracle.mds.persistence.stores.file.FileMetadataStore">
      <property name="metadata-path" value="${oracleHome}/integration"/>
      <property name="partition-name" value="seed"/>
    </metadata-store>
  </metadata-store-usage>
</metadata-store-usages>

This example defines a file-based MDS repository in the location ${oracleHome}/integration. If you run this build in Maven, the oracleHome variable may not be defined. In that case, you need to specify it on the Maven command line, as shown in the following example:

mvn compile -DoracleHome=MW_HOME/soa -DappHome=dir_for_application_for_proj

Notice that the value of oracleHome points to the soa directory in the Oracle Home in which you installed the SOA Quickstart or JDeveloper. That directory contains the seed MDS repository.

Alternatively, you can just update the adf-config.xml file to provide the full path to the MDS repository that you want to use.

If you want to use a database-based MDS repository, you must alter the configuration to specify the JDBC values, similar to that shown in the following example:

<metadata-store-usage id="mstore-usage_1">
  <metadata-store class-name="oracle.mds.persistence.stores.db.DBMetadataStore">
     <property name="jdbc-userid" value="your_prefix_mds"/>
     <property name="jdbc-password" value="<password>"/>
     <property name="jdbc-url" 
             value="jdbc:oracle:thin://@database.server:1521/service_name"/>
     <property name="partition-name" value="soa-infra"/>
  </metadata-store>
</metadata-store-usage>

To deploy your SOA project to the SOA server with Maven, you deploy the SAR file and edit the project POM.

mvn pre-integration-test

You can run SCA test suites with Maven.

1. Create a jndi.properties file (as you would if you were executing SCA Test Suites from ANT, for example) in your SOA composite project directory. This file contains the following information:

   java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory
   java.naming.provider.url=t3://test.server:7003/soa-infra
   java.naming.security.principal=weblogic
   java.naming.security.credentials=<password>
   dedicated.connection=true
   dedicated.rmicontext=true
   

2. Uncomment the jndi.properties entry in the SOA composite project POM (pom.xml) and ensure that it points to the file you just created.
3. The SOA Maven Plug-In runs the SCA Tests in the integration-test phase. To compile and package your composite, deploy it to a server and run the SCA Tests, run this command:

   mvn verify

While it is possible to manually create these resources through the WebLogic console, this would not be appropriate for an automated build environment. To address this issue, you can create WLST scripts and run them as part of the build to ensure that any necessary resources are created and configured on the runtime environment. You can run the WLST scripts at the appropriate time in your build using the weblogic-maven-plugin:wlst goal.

The following is an example of a WLST script to create a data source. You could add it to your project as misc/create-datasource.py:

# Copyright 2012, 2024 Oracle Corporation.
# All Rights Reserved.
#
# Provided on an 'as is' basis, without warranties or conditions
# of any kind, either express or implied, including, without 
# limitation, any warranties or conditions of title,
# non-infringement, merchantability, or fitness for a particular
# purpose. You are solely responsible for determining the
# appropriateness of using and assume any risks. You may not
# redistribute.
#
# This WLST script can be used as part of a continuous
# integration build process before deploying a SCA composite, to
# create any necessary Jakarta EE data sources on the WebLogic
# Server.
#
# In addition to creating the data source, this script will also
# update the resource adapter and redeploy it.
#
import time

#
# Edit these parameters before running this script.
#

# admin server url
url = 't3://localhost:7001'

# username to connect to the admin server
username = 'weblogic'

# password to connect to the admin server
password = 'password'

# the name for the EIS, as defined in the JDev DB Adapter wizard
eisName = 'eis/db/myDS'

# the server to target where the DbAdapter is deployed
serverName = 'soa_server1'

# the name for the data source
dsName = 'myDS'
# the JNDI name for the data source
jndiName = 'jbdc/myDS'

# the database url for the data source
dbUrl = 'jdbc:oracle:thin:@localhost:1521:orcl'

# the database user
dbUser = 'mark'

# the database password
dbPassword = 'password'

# the database driver to use
dbDriver = 'oracle.jdbc.xa.client.OracleXADataSource'

# the host where node manager is running
nmHost = 'localhost'

# the port to connect to node manager (5556 is the default port)
nmPort = '5556'

# the user to connect to node manager
nmUser = 'weblogic'

# the password to connection to node manager
nmPassword = 'password'

# the name of the weblogic domain
domain = 'soa_domain'

#
# Do not edit below this line.
#

uniqueString = ''
appName = 'DbAdapter'
moduleOverrideName = appName+'.rar'
moduleDescriptorName = 'META-INF/weblogic-ra.xml'

#
# method definitions
#
def makeDeploymentPlanVariable(wlstPlan, name, value, xpath,
                               origin='planbased'):
"""
Create a variable in the Plan.

This method is used to create the variables that are needed in the Plan in order to add an entry for the outbound connection pool for the new data source.
"""
try:
  variableAssignment = wlstPlan.createVariableAssignment(name, moduleOverrideName,moduleDescriptorName)
  variableAssignment.setXpath(xpath)
  variableAssignment.setOrigin(origin)
  wlstPlan.createVariable(name, value)
except:
  print('--> was not able to create deployment plan variables successfully')

def main():
  '''
  Copyright 2012, 2024 Oracle Corporation. All Rights Reserved.

  Provided on an 'as is' basis, without warranties or conditions
  of any kind, either express or implied, including, without
  limitation, any warranties or conditions of title, 
  non-infringement, merchantability, or fitness for a particular
  purpose. You are solely responsible for determining the
  appropriateness of using and assume any risks. You may not
  redistribute.

  This WLST script can be used as part of a continuous
  integration build process before deploying a SCA composite, to
  create any necessary Jakarta EE data sources on the WebLogic
  Server.

  In addition to creating the data source, this script will also
  update the resource adapter and redeploy it.
  '''

  print('!!! WARNING !!! This script will make changes to your WebLogic domain. Make sure you know what you are doing. There is no support for this script. If something bad happens, you are on your own! You have been warned.')

  #
  # generate a unique string to use in the names
  #
  uniqueString = str(int(time.time()))

  #
  # Create a JDBC Data Source.
  #
  try:
    print('--> about to connect to weblogic')
    connect(username, password, url)

    print('--> about to create a data source ' + dsName)
    edit()
    startEdit()
    create(dsName, 'JDBCSystemResource')
    cd('/JDBCSystemResources/%s/JDBCResource/%s' % (dsName, dsName)
    set('Name', dsName)
    cd('JDBCDataSourceParams/%s' % dsName)
    set('JNDINames', jarray.array([String(jndiName)], String))
    cd('../JDBCDriverParams/%s' % dsName)
    set('URL', dbUrl)
    set('DriverName', dbDriver)
    set('PasswordEncrypted', dbPassword)
    cd('../JDBCConnectionPoolParams/%s' % dsName)
    set('TestTableName', 'DUAL')
    cd('Properties/%s' % dsName)
    create('user', 'Property')
    cd('Properties/user')
    set('Value', dbUser)
    cd('/JDBCSystemResources/%s/JDBCResource/%s/ JDBCDataSourceParams/%s' % (dsName, dsName, dsName))
    set('GlobalTransactionsProtocol', 'TwoPhaseCommit')
    cd('/JDBCSystemResources/%s' % dsName)
    obj_name = ObjectName('com.bea:Name=%s,Type=Server' % serverName)
    set('Targets', jarray.array([obj_name], ObjectName))
    save()
    print('--> activating changes')
    activate()
    print('--> done')

    #
    # update the deployment plan
    #
    cd('/AppDeployments/DbAdapter')
    print('--> about to update the deployment plan for the DbAdapter')
    startEdit()
    planPath = get('PlanPath')
    appPath = get('SourcePath')
    print('--> Using plan ' + planPath)
    plan = loadApplication(appPath, planPath)
    print('--> adding variables to plan')
    makeDeploymentPlanVariable(plan, 'ConnectionInstance_eis/DB/' + dsName + '_JNDIName_' + uniqueString, eisName, '/weblogic-connector/outbound-resource-adapter/connection-definition-group/[connection-factoryinterface="javax.resource.cci.ConnectionFactory"]/connection-instance/[jndi-name="' + eisName + '"]/jndi-name')

    makeDeploymentPlanVariable(plan, 'ConfigProperty_xADataSourceName_Value_' + uniqueString, eisName, '/weblogic-connector/outbound-resource-adapter/connectiondefinition-group/[connection-factory-interface="javax.resource.cci.ConnectionFactory"]/
connection-instance/[jndi-name="' + eisName + '"]/connection-properties/properties/property/[name="xADataSourceName"]/value')
    print('--> saving plan')
    plan.save()
    save()
    print('--> activating changes')
    activate(block='true')

    cd('/AppDeployments/DbAdapter/Targets')
    print('--> redeploying the DbAdapter')
    redeploy(appName, planPath, targets=cmo.getTargets())
    print('--> done')
  except:
    print('--> something went wrong, bailing out')
    stopEdit('y')
    exit()

  #
  # disconnect from the admin server
  #
  print('--> disconnecting from admin server now')
  disconnect()

#
# this is the main entry point
#
if __name__ == '__main__' or __name__ == 'main':
  main()

To run this script during the pre-integration-test phase of your build, you would include a plugin section similar to the following in your SOA Project POM:

<plugin>
  <groupId>com.oracle.weblogic</groupId>
  <artifactId>weblogic-maven-plugin</artifactId>
  <version>14.1.2-0-0</version>
  <executions>
    <execution>
      <id>wlst-create-datasource</id>
      <phase>pre-integration-test</phase>
      <goals>
        <goal>wlst</goal>
      </goals>
      <configuration>
        <middlewareHome>/opt/soa1412</middlewareHome>
        <fileName>${project.basedir}/misc/create-datasource.py</fileName>
      </configuration>
    </execution>
  </executions>
</plugin>

If you add an ADF Human Task User Interface project to your SOA Application in JDeveloper, the application level POM is updated to add the new ADF project as a module and some <plugin> definitions are added to the <build> section to build the ADF project.

When you create an ADF Human Task project, some JDeveloper libraries are added to the build path for that project in JDeveloper. Additionally, JDeveloper checks to see if there are matching POMs for those libraries in your local Maven repository. If not, it creates those POMs for you. These new library POMs (if any are needed) are created with the Maven groupId = com.oracle.adf.library.

Note that the Maven repository used by JDeveloper can be specified in Tools/Preferences/Maven/Repository; it may not be the default repository in $HOME/.m2.

Note the following:

• If you want to build these ADF Human Task projects on another machine, for example, a build server, which is using a different Maven repository (local or remote), copy these new POMs to that Maven repository.

• The server on which you build the ADF Human Task projects must have access to a JDeveloper installation, because the ojdeploy Maven plug-in, which is used to package the ADF project into an EAR file, depends on the JDeveloper Oracle Home being present.

• If you want to deploy the EAR file as part of the application build, you need to add a new <plugin> section to invoke the weblogic-maven-plugin:deploy goal in the appropriate phase of your build, most likely pre-integration-test. Note that the EAR file is located in the appHome/deploy directory, not in the ADF project's directory. This is due to the fact that a single EAR file may contain multiple ADF Human Task project WAR files.

• If you target the deployment to the SOA server (as shown in the following example), the ADF URI is automatically registered in the appropriate MBean so that the SOA or BPM Workspace application can find it.

  <plugin>
    <groupId>com.oracle.weblogic</groupId>
    <artifactId>weblogic-maven-plugin</artifactId>
    <version>14.1.2-0-0</version>
    <executions>
      <execution>
        <id>deploy-human-task-ui</ui>
        <goals>
          <goal>deploy</goal>
        </goals>
        <phase>pre-integration-test</phase>
        <configuration>
          <adminurl>t3://localhost:7001</adminurl>
          <user>weblogic</user>
          <password>password</password>
          <source>${project.basedir}/deploy/adf1.ear</source>
          <verbose>true</verbose>
          <name>${project.build.finalName}</name>
          <targets>soa_server1</targets>
        </configuration>
      </execution>
    </executions>
  </plugin>

• To be able to deploy the EAR file, you also need to set up the appropriate MDS configuration in appHome/.adf/META-INF/adf-config.xml. This is most likely a database-based MDS store, as shown in What You May Need to Know About Building SOA Projects. For the build to work correctly, and the deployed application to function correctly, this database must be accessible from both the build server and the runtime server. This may not be practical in production environments, so you may need to define multiple deployment profiles for the ADF project.

You can undeploy your composite using the undeploy goal.

mvn com.oracle.soa.plugin:oracle-soa-plugin:undeploy
    -DserverURL=http://test.server:7001
    -Dcomposite.name=my-project
    -Dcomposite.revision=1.0
    -Dcomposite.partition=test
    -Duser=weblogic
    -Dpassword=<password>

The SOA Parent POM contains the following properties:

<properties>
  <!--
  These two properties are defined in com.oracle.maven:oracle-common, you can overwrite them here.
  Users who do not want to add plain text password in their properties or pom
  file, should use the userConfigFile and userKeyFile options for deployment.
  <oracleUsername>USERNAME</oracleUsername>
  <oraclePassword>PASSWORD</oraclePassword>
  -->

  <!-- Change the default values according to your environment -->
  <oracleServerUrl>http://localhost:8001</oracleServerUrl>
  <oracleServerName>soa_server1</oracleServerName>
  <oracleMiddlewareHome>/opt/soa1412</oracleMiddlewareHome>
</properties>

You can set these properties or define any other properties that you want to have available to SOA Projects. To refer to a property in your SOA Project POM, use the syntax $propertyName, for example $oracleServerName would be replaced with soa_server1 in the previous example.