Using the Oracle Service Bus Development Maven Plug-In

Introduction to the Oracle Service Bus Maven Plug-In

Maven is a build automation tool that lets you create and manage runtime projects.

The Oracle Service Bus development Maven plug-in provides Maven goals specific to the requirements of Service Bus projects and applications. You can use it to perform tasks such as packaging Service Bus projects or resources and deploying the package to a running server.

Maven Lifecycle Phases and Goals

Lifecycle phases give order to goal execution in a Maven POM file. A goal is a specific task, which can be mapped to one or more phases. The Oracle Service Bus development Maven plug-in provides goals that are specific to Service Bus projects and that can be used in conjunction with standard Maven goals to build and manage Service Bus projects and applications throughout the lifecycle phases.

Service Bus provides two custom goals, package and deploy. For information about the syntax and parameters for these goals, see Service Bus Development Maven Plug-In Goals. Table 58-1 lists the phases in the default Maven lifecycles for Service Bus, along with the goals mapped to each phase. If you map multiple goals to the same lifecycle phase, they are typically executed in the order you list them.

Table 58-1 Maven Lifecycle Phases for Service Bus

Phase	Description
package	Packages the Service Bus project resources in its distributable format, sbar (Service Bus archive file). The `com.oracle.servicebus.plugin:oracle-servicebus-plugin:12.1.3.0.0:package` goal is mapped to this phase.
pre-integration-test	Processes and deploys the package if necessary into an environment where integration tests can be run. The `com.oracle.servicebus.plugin:oracle-servicebus-plugin:12.1.3.0.0:deploy` goal is mapped to this phase.
install	Installs the package into the local repository, for use as a dependency in other projects locally. Service Bus uses the `org.apache.maven.plugins:maven-install-plugin:install` goal for this phase.

POM Files and Archetypes

Maven projects are defined by a POM file, which describes the project's artifact, the plug-ins to use, inheritance, and dependencies on other artifacts (such as system resources that are required to build Service Bus projects). An archetype is a template for creating a specific type of project. Service Bus provides two different archetypes, one for Service Bus projects and one for Service Bus system resources.

The Service Bus project archetype is named com.oracle.servicebus.archetype:oracle-servicebus-project:12.2.1-0-0. It is defined by the following archetype coordinates:

<groupId>com.oracle.servicebus.archetype</groupId>
<artifactId>oracle-servicebus-project</artifactId>
<version>12.2.1-0-0</version>
<name>Oracle Service Bus - Project Archetype</name>

The Service Bus system resources archetype is named com.oracle.servicebus.archetype:oracle-servicebus-system:12.2.1-0-0. It is defined by the following archetype coordinates:

<groupId>com.oracle.servicebus.archetype</groupId>
<artifactId>oracle-servicebus-system</artifactId>
<version>12.2.1-0-0</version>
<name>Oracle Service Bus - System Resources Archetype</name>

Installing and Configuring Maven

A distribution of Maven 3.2.5 is included with Oracle Fusion Middleware.

The Maven distribution is in the following location:

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

For information about installing and configuring 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."

The Oracle Service Bus development Maven plug-in is installed in the following location:

Service_Bus_Home/plugins/maven

How to Configure the Oracle Service Bus Development Maven Plug-In

The oracle-servicebus-plugin plug-in is provided as a pre-built JAR file and accompanying POM file. You use the Maven synchronization plug-in to populate a local or shared Maven repository from an Oracle home, which includes the Service Bus plug-in. For more information and complete instructions for installing and running the synchronization plugin, see "Populating the Maven Repository Manager" in Developing Applications Using Continuous Integration. The steps below include links to more specific sections of that guide.

To configure the Oracle Service Bus development Maven plug-in:

Navigate to ORACLE_HOME/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/12.2.1.
Run the following command to install the Maven sync plug-in:
```
mvn install:install-file -DpomFile=oracle-maven-sync-12.2.1.pom -Dfile=oracle-maven-sync-12.2.1.jar
```
For more options, see "Installing Oracle Maven Synchronization Plug-In."
Run the following command to seed the Oracle Service Bus 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."

Validate whether you have successfully installed the plug-in using the Maven help:describe goal.

mvn help:describe -DgroupId=com.oracle.servicebus.plugin
-DartifactId=oracle-servicebus-plugin -Dversion=12.2.1-0-0

The following information confirms the installation of the Service Bus plug-in:

Name: Oracle Service Bus - Plugin
Description: (no description available)
Group Id: com.oracle.servicebus.plugin
Artifact Id: oracle-servicebus-plugin
Version: 12.2.1-0-0
Goal Prefix: servicebus
This plugin has 2 goals:
servicebus:deploy
  Description: (no description available)
servicebus:package
  Description: (no description available)
For more information, run 'mvn help:describe [...] -Ddetail'

How to Use Maven Online Help

Maven online help provides you with a list of goals and their associated commands. Use the describe goal in the help plug-in to access online help. For example, enter the following command to obtain online help for the package goal:

mvn help:describe -Ddetail -Dcmd=com.oracle.servicebus.plugin:oracle-servicebus-plugin:package

See the Apache help plug-in describe goal documentation for additional information.

Using the Oracle Service Bus Development Maven Plug-In

You invoke Maven goals either through a Maven project POM file or from the command line. The preferred and recommended way is to use a Maven POM file, which can be created for both Service Bus projects and applications.

For more information about working with Maven in JDeveloper, see Building and Running with Apache Maven in Developing Applications with Oracle JDeveloper.

How to Generate a Service Bus Project POM File

When you create a Service Bus project in JDeveloper, a POM file is automatically created for that project. You can also manually generate a POM file for a Service Bus project using JDeveloper.

To generate a Service Bus project POM file in JDeveloper:

In the Application Navigator, right-click the project, point to New and select From Gallery.
Under the General category on the New Gallery dialog, select Maven.
Under Items, select Maven POM for Project and click OK.
Enter a name for the POM file and the directory where the POM will be located.
Enter a unique group ID, artifact ID and version for the project.

Together, these values form the fully qualified artifact name in the form of <groupId>:<artifactId>:<version>.
Enter a description for the project.
In the Packaging field, select sbar.
Clear or select Use this POM as the default for the project, depending on your requirements.
Click OK.

How to Generate a Service Bus Project POM File from an Archetype

You can generate a POM file for a project from the Service Bus project archetype in either JDeveloper or from a command line. Archetypes are templates for creating Maven projects.

Creating a Service Bus Project POM File from an Archetype in JDeveloepr

To generate a Service Bus project POM file from an archetype in JDeveloper:

In the Application Navigator, right-click the project, point to New and select From Gallery.
Under the General category on the New Gallery dialog, select Maven.
Under Items, select Generate from Archetype and click OK.

The Create Project From Archetype dialog appears.
Enter a unique group ID, artifact ID and version for the project.

Together, these values form the fully qualified artifact name in the form of <groupId>:<artifactId>:<version>.

For more information about the properties on this dialog, see the online help and Parameters for Generating a POM File . Note that these are not the archetype group and artifact IDs.
Enter the default package name and the directory where you want to store the project.
In the Maven Archetype field, click the browse icon to search for and select the oracle-servicebus-project archetype.

For information about searching for archetypes, see "How to Create Maven Projects Using Maven Archetypes" in Developing Applications with Oracle JDeveloper.
When you are done, click Finish on the Create Project From Archetype dialog.

Generating a Service Bus Project POM File from an Archetype Using a Command Line

To generate a Service Bus project POM file from an archetype using a command line:

From the directory for the Service Bus project for which you want to create the POM file, run the following command:
```
mvn archetype:generate 
 -DarchetypeGroupId=com.oracle.servicebus.archetype
 -DarchetypeArtifactId=oracle-servicebus-project
 -DarchetypeVersion=12.2.1-0-0 
 -DarchetypeRepository=Repository_Home
 -DgroupId=Group_ID
 -DartifactId=Artifact_ID
 -Dversion=1.0-SNAPSHOT
```
Where:
- Repository_Home is the path to the Maven repository to use. Instead of entering the path, you can simply enter local, which tells Maven not to look in any other repository it knows about and is more efficient.
- Group_ID is a unique, identifying name for the project to build.
- Artifact_ID is the name of the subdirectory in the current directory in which the project artifacts are generated.
For more information about the parameters for this command, see Parameters for Generating a POM File .
When the command line prompts you to confirm the properties configuration, type Y to confirm or N to cancel. Press Enter.

The POM file is generated in the directory from which you ran the command in the subdirectory specified by the artifact ID.

How to Generate a Service Bus System Resources POM File from an Archetype

You can generate a POM file for Service Bus system resources from the Service Bus system archetype in either JDeveloper or from a command line. Archetypes are templates for creating Maven projects.

Generating a Service Bus System Resources POM File from an Archetype in JDeveloper

To generate a Service Bus system resources POM file from an archetype in JDeveloper:

In the Application Navigator, right-click the project containing the system resources, point to New and select From Gallery.

Note:

For Service Bus system resources, the location in JDeveloper might be in Service Bus System Resources under Application Resources.
Under the General category on the New Gallery dialog, select Maven.
Under Items, select Generate from Archetype and click OK.

The Create Project From Archetype dialog appears.
Enter a unique group ID, artifact ID and version for the project.

Together, these values form the fully qualified artifact name in the form of <groupId>:<artifactId>:<version>.

For more information about the properties on this dialog, see the online help and Parameters for Generating a POM File . Note that these are not the archetype group and artifact IDs.
Enter the default package name and the directory where you want to store the project.
In the Maven Archetype field, click the browse icon to search for and select the oracle-servicebus-system archetype.

For information about searching for archetypes, see "How to Create Maven Projects Using Maven Archetypes" in Developing Applications with Oracle JDeveloper.
When you are done, click Finish on the Create Project From Archetype dialog.

Generating a Service Bus System Resources POM File from a Command Line

To generate a Service Bus system resources POM file from a command line:

From the directory where the Service Bus system resources are located, run the following command:
```
mvn archetype:generate 
 -DarchetypeGroupId=com.oracle.servicebus.archetype
 -DarchetypeArtifactId=oracle-servicebus-system
 -DarchetypeVersion=12.2.1-0-0 
 -DarchetypeRepository=Repository_Home
 -DgroupId=Group_ID
 -DartifactId=Artifact_ID
 -Dversion=1.0-SNAPSHOT
```
Where:
- Repository_Home is the path to the Maven repository to use. Instead of entering the path, you can simply enter local, which tells Maven not to look in any other repository it knows about and is more efficient.
- Group_ID is a unique, identifying name for the project to build.
- Artifact_ID is the name of the subdirectory in the current directory in which the project artifacts are generated.
For more information about these parameters, see Parameters for Generating a POM File .
When the command line prompts you to confirm the properties configuration, type Y to confirm or N to cancel. Press Enter.

The POM file is generated in the directory from which you ran the command in the subdirectory specified by the artifact ID.

Parameters for Generating a POM File

When you generate a POM file from a command line, use the following parameters to configure the project.

Parameter	Description
`archetypeGroupId`	The group ID of the archetype to use. For Service Bus, this is `com.oracle.servicebus.archetype`.
`archetypeArtifactId`	The artifact ID of the archetype to use. For a Service Bus project, this is `oracle-servicebus-project`. For Service Bus system resources, this is `oracle-servicebus-system`.
`archetypeVersion`	The version of the archetype to use. The current version is `12.2.1-0-0`.
`archetypeRepository`	The Maven repository to use.
`groupId`	The group ID of the project to build.
`artifactId`	The artifact ID of the project to build.
`version`	The version of the project to build.

Service Bus Development Maven Plug-In Goals

The Oracle Service Bus development Maven plug-in provides two goals specific to Service Bus, which are described in these sections.

package: Packages the Service Bus project resources in its distributable format, sbar (Service Bus archive file).
deploy: Deploys Service Bus projects and applications to a running server. This goal supports files in the SBAR format.

package

The Maven plug-in provides the ability to control the building and deployment of a project as a resource through the POM file (pom.xml). You can achieve this functionality in two ways: by directly passing the configuration xml or by passing the list of resources/files needed to include and exclude in pom.xml. The Maven plug-in parses the configuration xml file to check which files need to be included and excluded and then adds files as specified in the configuration xml file in the config JAR.

Full Name

com.oracle.servicebus.plugin:oracle-servicebus-plugin:package

Description

The package goal creates a configuration JAR file from the resources associated with a POM file, and packages the resources into a Service Bus-specific archive file (.sbar). By default, the Maven plug-in assumes the resources being packaged are project resources, but a Service Bus application can also include system resources, which are shared among projects. System resources are packaged differently than project resources, so when you package system resources, you need to set the system flag to true.

The Maven plug-in uses the offline export (configuration JAR) tool to package the Service Bus resources. It places the temporary files created by the export tool in project/.data/maven/configjar. The settings for the export tool are derived from the Maven project context. When packaging project resources, Service Bus performs the export at the project level; when packaging system resources, Service Bus performs the export at the resource level. It uses the default extension mappings. For more information, see Exporting a Service Bus Configuration Offline. The export tool writes information to a log file located at Project_Home/.maven/configjar/configjar.log.

The directories that contain Service Bus resources often contain additional files that you might want to exclude from the generated package. For example, you can exclude metadata files used by the versioning system. You can define an exclusion list to make sure these files are not included when the .sbar file is generated. By default, the following files and folders are excluded for the project archetype: servicebus.sboverview, pom.xml, .settings/, and .data/. For the system archetype, pom.xml and .data/ are excluded.

Validation errors that occur during packaging are not reported, and packaging does not fail if there are validation errors.

Parameters

Use the following parameters to customize the packaging process.

Table 58-2 Parameters for servicebus:package Goal

Name	Type	Description
`excludes`	`String[]`	Specifies a list of files to exclude from the project. Use this parameter to exclude files such as versioning system files.
`exportLevel`	`String[]`	Mandatory. Specifies the export level as either `RESOURCE` or `PROJECT`. You can specify this value as an expression but it should not present in `pom.xml`, or it will pick its value from the `pom.xml` instead of the value passed through the expression.
`includes`	`String[]`	Specifies a list of files to include from the project/resource. Use this parameter to include specific files/directory from a directory.
`oracleHome`	`java.lang.String`	Specifies the location of the Oracle Fusion Middleware home directory. You can specify this value as an expression.
`passphrase`	`java.lang.String`	Specifies a passphrase for encryption or decryption of sensitive information in the Service Bus project: When a Maven package goal is executed, the `.sbar` file is generated with sensitive information (such as the service account) encrypted when a passphrase is passed in the Maven command. When a Maven deploy goal is executed to deploy the generated `.sbar` file, the sensitive information is decrypted when the passphrase in specified. Note: If the `.sbar` file is imported into Service Bus directly using the console (instead of executing a Maven deploy command), then the passphrase should be provided in the user interface. This parameter can be added either as a configuration parameter in a project POM file as `<passphrase>[passphrase]</passphrase>` or it can be specified in a Maven command line as `-Dpassphrase=passphrase` This parameter is available in 12c (12.2.1.4) only if you have installed Service Bus patch 32020936 or later. Sign in to My Oracle Support and search for the patch number to locate and download the patch.
`resources`	`String[]`	Specifies the resource which points towards a configuration file. This configuration file can be used to specify which files need to be included and excluded. You can specify this value as an expression but at the same time this parameter should not be present in `pom.xml`, or it will pick its value from the `pom.xml` instead of the value passed through the expression. The value of this parameter can be an absolute path or a relative path.
`skipAll`	`java.lang.boolean`	If set to `true`, the `.sbar` file is neither generated nor deployed. If set to `false`, or if this parameter is not provided, the `.sbar` file is both generated and deployed. This parameter should be added in all places where Service Bus has given information regarding the package and deploy goal's parameters for `oracle-servicebus-plugin`. To skip project deployment on a running server, it can be added either as a configuration parameter in a project POM file as `<skipAll>true</skipAll>` or it can be issued in a Maven command line as `-Dosb.skip.All=true`
`system`	`java.lang.Boolean`	Specifies whether the resources being packaged are system resources, which are shared by multiple projects within a Service Bus application. The default value is `false`. You must set this value to `true` when packaging system resources.
`weblogicRootDirectory`	`java.lang.String`	Specifies the path to the JDeveloper `bin` folder where the JDeveloper launcher command resides, if the service account for the Service Bus project is created using JDeveloper. This parameter can be added either as a configuration parameter in a project POM file as `<weblogicRootDirectory>[weblogicRootDirectory]</weblogicRootDirectory>` or it can be specified in a Maven command line as `-DweblogicRootDirectory=weblogicRootDirectory` This parameter is available in 12c (12.2.1.4) only if you have installed Service Bus patch 32020936 or later. Sign in to My Oracle Support and search for the patch number to locate and download the patch.

deploy

The Maven plug-in provides the ability to control the import settings so as to not overwrite all the security configuration. To achieve this functionality, you need to add Boolean parameters in the Maven plug-in POM file (pom.xml). These parameters are passed to the configuration framework through the Maven plug-in. To maintain backward compatibility, they are not mandatory and their values are false by default. These parameters can specify a value as an expression but they should not be present in pom.xml or the expression value will not be picked.

Full Name

com.oracle.servicebus.plugin:oracle-servicebus-plugin:deploy

Description

The deploy goal deploys Service Bus projects to a running server. This goal supports the Service Bus deployment format, SBAR. It does not require a local server installation. By default, deploying projects does not apply any updates to environment values. If you want to update the environment values, you can create a configuration file with the new environment values and specify that configuration file when you run deploy.

For each deployment, a new session is created and named in the following format:

Service_Bus_Maven-artifactId-currentTime

The current time extends to milliseconds.

When you package a Service Bus project using Maven, Service Bus generates a configuration JAR file, which can then be deployed to a running server using the deploy goal. Service Bus uses the default import plan, which includes dependencies and does not preserve environment variables, security settings, or credentials.

If any resources fail to import, the information is logged and the goal execution fails. If all resources import successfully and you specified a configuration file, Service Bus applies the new environment variables. Once the deployment completes successfully (that is, there are no conflicts in any of the resources), Service Bus activates the session. In case of any failures or conflicts, Service Bus does not activate the changes or apply the new environment variables, but it does retain the session so you can research the failures.

Parameters

Use the following parameters to customize the deployment process. You can specify any of the parameters using an expression.

Table 58-3 Parameters for servicebus:deploy Goal

Name	Type	Description
`oracleServerUrl`	`java.lang.String`	Specifies the address and port on which the Administration Server is listening. The default value is: `t3://localhost:7001`
`oracleUsername`	`java.lang.String`	Specifies the administrative user name.
`oraclePassword`	`java.lang.String`	Specifies the administrative password.
`skip`	`java.lang.boolean`	If this parameter is provided and set to `true`, the `.sbar` file is generated, but not deployed. If set to `false`, or if this parameter is not provided, the `.sbar` file is both generated and deployed. This parameter should be added in all places where Service Bus has given information regarding the deploy goal's parameters for `oracle-servicebus-plugin`. To skip project deployment on a running server, it can be added either as a configuration parameter in a project POM file as `<skip>true</skip>` or it can be issued in a Maven command line as `-Dosb.skip.deploy=true`
`skipAll`	`java.lang.boolean`	If this parameter is provided and set to `true`, the `.sbar` file is neither generated nor deployed. If set to `false`, or if this parameter is not provided, the `.sbar` file is both generated and deployed. This parameter should be added in all places where Service Bus has given information regarding the package and deploy goal's parameters for `oracle-servicebus-plugin`. To skip project deployment on a running server, it can be added either as a configuration parameter in a project POM file as `<skipAll>true</skipAll>` or it can be issued in a Maven command line as `-Dosb.skip.All=true`
`customization`	`java.io.File`	Specifies the location and name of a Service Bus configuration file that will update environment values for the environment in which the Service Bus archive is being deployed.
`preserveExistingEnvValues`	Boolean	Controls whether certain environment values inside of a resource are overwritten or preserved during an import. If set to `true`, the existing environment values are preserved.
`preserveExistingOperationalValues`	Boolean	Controls whether certain operational values of a resource are overwritten or preserved during import. If set to `true`, the existing operational values are preserved.
`preserveExistingSecurityAndPolicyConfig`	Boolean	Controls whether certain security and policy configuration of a resource are overwritten or preserved during import. If set to `true`, the existing security and policy configurations are preserved.
`preserveExistingCredentials`	Boolean	Controls whether username/passwords and PKI credentials of a resource are overwritten or preserved during import. If set to `true`, the existing credentials are preserved.
`preserveExistingAccessControlPolicies`	Boolean	Controls whether access control policies of a resource are overwritten or preserved during import. If set to `true`, the existing access control policies are preserved.

Oracle Service Bus Development Maven Plug-In POM File Samples

Service Bus has three different types of POM files: one for Service Bus applications, one for Service Bus projects, and one for Service Bus system resources.

Example: Service Bus Application POM File

A Service Bus application POM file is an aggregation file that lists all the projects to compile in an application, allowing you to run Maven against a single POM file instead of each individual project POM file. Maven executes the modules in the order in which they are listed in the application POM file.

<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
 http://maven.apache.org/maven-v4_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>OrdersAndPayments</groupId>
    <artifactId>OrdersAndPayments</artifactId>
    <version>1.0-SNAPSHOT</version>
 
    <packaging>pom</packaging>
 
    <modules>
        <module>System</module>
        <module>Orders</module>
        <module>Payments</module>
    </modules>
 
</project>

Example: Service Bus Project POM File

A Service Bus project POM file inherits from a parent POM named project-12.2.1 in the Maven repository. With the inheritance, the project POM file is more streamlined.

Note that System is a reserved project name in Service Bus specifically for system resources. This should not be used as the artifact ID when using the project archetype.

<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
 http://maven.apache.org/maven-v4_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>
 
    <parent>
        <groupId>com.oracle.servicebus</groupId>
        <artifactId>project</artifactId>
        <version>12.2.1.0.0</version>
    </parent>
 
    <groupId>OrdersAndPayments</groupId>
    <artifactId>Orders</artifactId>
    <version>1.0-SNAPSHOT</version>
 
    <packaging>sbar</packaging>
 
    <dependencies>
        <dependency>
            <groupId>OrdersAndPayments</groupId>
            <artifactId>System</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>
    </dependencies>
 
</project>

Example: Service Bus System Resources POM File

A Service Bus system resources POM file inherits from a parent POM named system-12.2.1 in the Maven repository. With the inheritance, the system resources POM file is more streamlined.

Note that System is a reserved project name in Service Bus specifically for system resources. The artifact ID must be System when using the system archetype.

<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
 http://maven.apache.org/maven-v4_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>
 
    <parent>
        <groupId>com.oracle.servicebus</groupId>
        <artifactId>system</artifactId>
        <version>12.2.1.0.0</version>
    </parent>
 
    <groupId>OrdersAndPayments</groupId>
    <artifactId>System</artifactId>
    <version>1.0</version>
 
    <packaging>sbar</packaging>
 
</project>