This chapter describes how to use the Oracle Service Bus development Maven plug-in to build and manage Service Bus projects. The Oracle Service Bus development Maven plug-in lets you package and deploy Service Bus projects 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. For information on installing and using Maven to build applications and projects, see http://maven.apache.org/users/index.html.
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.
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 60-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 60-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 |
|
pre-integration-test |
Processes and deploys the package if necessary into an environment where integration tests can be run. The |
|
install |
Installs the package into the local repository, for use as a dependency in other projects locally. Service Bus uses the |
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.1.3-0-0. It is defined by the following archetype coordinates:
<groupId>com.oracle.servicebus.archetype</groupId> <artifactId>oracle-servicebus-project</artifactId> <version>12.1.3-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.1.3-0-0. It is defined by the following archetype coordinates:
<groupId>com.oracle.servicebus.archetype</groupId> <artifactId>oracle-servicebus-system</artifactId> <version>12.1.3-0-0</version> <name>Oracle Service Bus - System Resources Archetype</name>
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 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
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:
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.
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.
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:
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.
To generate a Service Bus project POM file from an archetype in JDeveloper:
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.
To generate a Service Bus system resources POM file from an archetype in JDeveloper:
When you generate a POM file from a command line, use the following parameters to configure the project.
| Parameter | Description |
|---|---|
|
|
The group ID of the archetype to use. For Service Bus, this is |
|
|
The artifact ID of the archetype to use. For a Service Bus project, this is |
|
|
The version of the archetype to use. The current version is |
|
|
The Maven repository to use. |
|
|
The group ID of the project to build. |
|
|
The artifact ID of the project to build. |
|
|
The version of the project to build. |
The Oracle Service Bus development Maven plug-in provides two goals specific to Service Bus, which are described in the following sections:
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 known as an .sbar file. 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 packing 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 60-2 Parameters for servicebus:package Goal
| Name | Type | Description |
|---|---|---|
|
|
|
Specifies the location to the Oracle Fusion Middleware home directory. You can specify this value as an expression. |
|
|
|
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. |
|
|
|
Specifies a list of files to exclude from the project. Use this to exclude things like versioning system files. |
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 60-3 Parameters for servicebus:deploy Goal
| Name | Type | Description |
|---|---|---|
|
|
|
Specifies the address and port on which the Administration Server is listening. The default value is: |
|
|
|
Specifies the administrative user name. |
|
|
|
Specifies the administrative password. |
|
|
|
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. |
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. The one you use depends on the resources you are working with.
Example - Service Bus Application POM File
Below is an example of a Service Bus application POM file. This 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
Below is an example of a POM file for a Service Bus project. This file inherits from a parent POM named project-12.1.3 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.1.3.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
Below is an example of a POM file for Service Bus system resources. This file inherits from a parent POM named system-12.1.3 in the Maven repository. With the inheritance, the system resources POM file is more streamlined.
"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.1.3.0.0</version>
</parent>
<groupId>OrdersAndPayments</groupId>
<artifactId>System</artifactId>
<version>1.0</version>
<packaging>sbar</packaging>
</project>