60 Using the Oracle Service Bus Development Maven Plug-In
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
.
60.1 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.
60.1.1 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 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 |
60.1.2 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>
60.2 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
60.2.1 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:
60.2.2 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.
60.3 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.
60.3.1 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:
60.3.2 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.
60.3.2.1 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:
60.3.3 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.
60.3.3.1 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:
60.3.4 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 |
---|---|
|
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. |
60.4 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.
60.4.1 package
The Maven plug-in provides the ability to control the building and deployment of a project as a resource through the POM. 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 tag 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 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. |
|
|
Specifies a list of files to include from the project/resource. Use this parameter to include specific files/directory from a directory. |
|
|
Specify the resource which points towards a configuration file. This configuration file can be used to specify which files need to be included and excluded. It is not a mandatory parameter. You can specify this value as an expression but at the same time this parameter should not be present in |
|
|
Specifies the export level as either RESOURCE or PROJECT. You can specify this value as an expression but it should not present in |
|
|
If this parameter is provided and set True, the SBAR file is neither generated nor depolyed. If set to False, or if this parameter is not provided, the SBAR file is both generated and deployed. This parameter should be added at all the places where OSB has given information regarding the package and deploy goal's parameters for |
60.4.2 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.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 at they parameter should not be present in pom.xml
otherwise 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 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. |
|
|
If this parameter is provided and set True, the SBAR file is generated, but not depolyed. If set to False, or if this parameter is not provided, the SBAR file is both generated and deployed. This parameter should be added at all the places where OSB has given information regarding the deploy goal's parameters for |
|
|
If this parameter is provided and set True, the SBAR file is neither generated nor depolyed. If set to False, or if this parameter is not provided, the SBAR file is both generated and deployed. This parameter should be added at all the places where OSB has given information regarding the package and deploy goal's parameters for |
|
|
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. |
|
boolean |
This flag 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. |
|
boolean |
This flag controls whether certain operational values of a resource are overwritten or preserved during import. If set to true, the existing operational values are preserved. |
|
boolean |
This flag 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. |
|
boolean |
This flag 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. |
|
boolean |
This flag 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. |
60.5 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
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.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
Below is an example of a POM file for Service Bus system resources. This 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.
"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>