Oracle Service Bus provides an export tool that exports a Service Bus configuration directly from the file system to create a configuration .jar file. This appendix describes how to perform an offline export of a Service Bus configuration.
This appendix includes the following sections:
Section B.2, "Preparing to Export an Oracle Service Bus Configuration"
Section B.3, "Exporting an Oracle Service Bus Configuration"
Section B.4, "Export Settings File Format, Samples, and Schema"
For information about exporting resources using Eclipse, see Section 2.1.11, "Exporting Resources."
You can export a Service Bus configuration in offline mode using a command line, Ant task, or the WebLogic Scripting Tool (WLST). All methods use an export settings file to define how the export is executed and which files, folders, projects, or system resources to include in the generated configuration .jar file. If you use a versioning system to store Oracle Service Bus artifacts, you can use this process to create a deployable configuration .jar file from the source files stored in the versioning system.
The export tool runs in two phases, a load phase and an export phase. Each phase is configured in an export settings file. During the load phase, the export tool traverses the file system, identifies the files to read, converts the file content into the corresponding resource, and imports the file into the configuration framework. During the export phase, the export tool packages the loaded resources and projects into one or more configuration .jar files that you can then import into another Service Bus environment.
For the load phase, you can configure the following:
Directory structure: There is no dependency on the Eclipse workspace directory structure; you can specify project root directories, directories where system resources are located, and specific folders and files to include. This supports alternate directory structures for external versioning systems, such as Maven, where the project directories are not siblings in the directory structure.
File extensions: In Service Bus, each resource type uses a specific file extension, such as .proxy for proxy services, .xsl and .xslt for XSLT resources, and so on. Each extension can map to only one Service Bus resource type, but a resource type can map to multiple file extensions. In Eclipse, each resource has one default extension that cannot be changed, but you can also specify custom file extensions for a resource. In order for the export tool to recognize files with custom extensions, you need to define file extension mappings in the export settings file.
Inclusion and exclusion rules: When you specify a project or system resources folder, all Service Bus files are included in the export. You can use include and exclude statements for finer control over which files are included. For example, Eclipse and certain versioning systems create additional system folders and files within the project folders. These files might be recognized as Service Bus resources and included in the exported JAR file unless they are specifically excluded from the export.
The export phase is configured using an export settings file. You can export a Service Bus configuration at the project level or at the resource level, and you can define multiple configuration exports in one export settings file. For the export phase, you can configure the following:
Project-level export: At the project level, you specify the names of the projects to include as well as whether to include system resources. If no project names are provided, all projects added during the load phase are included in the generated export file.
Note:
Do not export at the project-level if detailed inclusions are defined for the load phase. This could result in all resources that were not included being deleted when you import the generated configuration .jar file on a target server.
Resource-level export: At the resource level, you specify the resources to export using inclusion and exclusion rules as described above. You can also specify whether to include dependencies. If no resources are specified in the export settings file, all resources are exported.
Multiple configuration JAR files: You can define multiple configuration .jar files in the export settings file, each of which can be configured differently. You can also specify whether to overwrite existing files of the same name.
For more information about configuring the export settings file, see Section B.4, "Export Settings File Format, Samples, and Schema."
You can map custom file extensions to Service Bus resource types so the export tool can recognize them as legitimate Service Bus files. Below are the default file extensions for Service Bus. If you use different file extensions, you need to map them in the export setting file. For an example of mapping file extensions to resource types, see Section B.4.4, "Mapping File Extensions."
Table B-1 Oracle Service Bus Resource File Extension Defaults
| Resource Type | Resource Type ID | File Extension |
|---|---|---|
|
Alert Destination |
AlertDestination |
.alert |
|
Business Service |
BusinessService |
.biz |
|
JAR Files |
Archive |
.jar |
|
JCA Adapter |
JCA |
.jca |
|
JNDI Providers |
ForeignJNDIProvider |
.jndi |
|
Message Flow |
FLOW |
.flow |
|
MFL Transformation |
MFL |
.mfl |
|
MQ Connection |
MQConnection |
.mqc |
|
Proxy Servers |
ProxyServer |
.ps |
|
Proxy Service |
ProxyService |
.proxy |
|
Service Account |
ServiceAccount |
.sa |
|
Service Key Providers |
ServiceProvider |
.skp |
|
SMTP Server |
SMTPServer |
.smtp |
|
Split-Join |
FLOW |
.flow |
|
UDDI Registry |
UDDIRegistry |
.uddi |
|
WS-Policy |
Policy |
.policy |
|
WSDL Document |
WSDL |
.wsdl |
|
XML File |
XML |
.xml |
|
XML Schema |
XMLSchema |
.xsd |
|
XQuery Transformation |
Xquery |
.xquery |
|
XSLT Transformation |
XSLT |
.xslt, .xsl |
Perform the following steps before you export a Service Bus configuration in offline mode:
Before you begin exporting resources, verify that you have the following in place:
Oracle Service Bus 11.1.1.7.0 or later is installed (Eclipse is not required).
The correct version of Java is installed. This should be Oracle JDK 1.6.0_35 or later, or Oracle JDK 1.7.0_07 or later.
You are assigned write permissions for the directory from which you will run the export tool. The tool is located in OSB_HOME/tools/configjar.
When you export the configuration, an exit value of 0 means the export succeeded.
Note:
If you have developed your own custom transport, you need to create an offline transport plug-in file and save it to OSB_HOME/config/plugins in your Service Bus installation. For more information, see Section 40.2.5, "Packaging Transports in Offline Mode."
Rather than using command line arguments when performing an offline export, the export tool refers to a settings file that you create. This file is in XML format and contains all of the required information for the export tool to be able to find and load files and then create the configuration JAR file. For information about the file format and schema definition, as well as examples of usage, see Section B.4, "Export Settings File Format, Samples, and Schema."
Before performing the export, you need to set the environment variables used by the tool by running the setenv.* file. You can customize this file before running it by modifying the JVM heap size, adding JAR files to the CLASSPATH, or adding system properties. If you have JAR resources that are included in the export and that require custom JAR files, make sure to add the paths and filenames of those custom JAR files to the CLASSPATH section of the setenv.* file; as shown below:
For Windows:
CLASSPATH=%CLASSPATH%;%CONFIGJAR_HOME%\custom\my_custom.jar
For UNIX or Linux:
CLASSPATH=$CLASSPATH$CLASSPATHSEP$CONFIGJAR_HOME/custom/my_custom.jar
Once you have customized the file, navigate to OSB_HOME/tools/configjar and run the following command:
For Windows:
setenv.bat
For UNIX or Linux:
source setenv.sh
The following sections describe scripting and command-line options for performing an offline export of an Oracle Service Bus configuration. A readme file located in OSB_HOME/tools/configjar contains additional information and instructions.
Exporting from the command line generates an Oracle Service Bus configuration JAR from the folders and files you specify in the export settings file. The command-line files, configjar.bat and configjar.sh, are located in OSB_HOME/tools/configjar.
Use the following syntax for Windows:
configjar.bat -settingsfile <FILE_NAME> [-debug] [-help]
Use the following syntax for UNIX or Linux:
./configjar.sh -settingsfile <FILE_NAME> [-debug] [-help]
The following parameters can be used at the command line:
-settingsfile FILE_NAME: Enter the path and filename of the export settings file. This parameter is required.
-debug: Include this optional parameter in the command to enable debug logging of the export process. If this flag is not included, debug logging is not performed.
-help: Include this optional parameter in the command to view usage information.
You can export an Oracle Service Bus configuration in offline mode using an Apache Ant build file. Service Bus includes a sample Ant build file named configjar-ant.xml in OSB_HOME/tools/configjar. You can use this file or create your own. Exporting using Ant generates an Oracle Service Bus configuration JAR from the folders and files you specify in the export settings file.
The sample Ant build file supports the following syntax:
ant -f <FILE_NAME> [-debug] [-failonerror] [-errorproperty]
Below is a sample Ant build file:
<project name="ConfigExport" default="usage" basedir=".">
<property environment="env" />
<property name="mw.home" location="${env.MW_HOME}" />
<property name="wl.home" location="${env.WL_HOME}" />
<property name="osb.home" location="${env.OSB_HOME}" />
<taskdef name="configjar"
classname="com.bea.alsb.tools.configjar.ant.ConfigJarTask" />
<target name="init">
<property name="task.debug" value="false" />
<property name="task.failonerror" value="true" />
<property name="task.errorproperty" value="" />
</target>
<target name="run" depends="init">
<fail unless="settingsFile"/>
<configjar debug="${task.debug}"
failonerror="${task.failonerror}"
errorProperty="${task.errorproperty}"
settingsFile="${settingsFile}" />
</target>
</project>
The following parameters are supported in the Ant build file:
settingsFile: The path and filename of the export settings file. This parameter is required
debug: Set this parameter to true to enable debug logging of the export process; otherwise set it to false. This parameter is optional and set to false by default.
failonerror: Set this parameter to true if you want the task to fail when the export tool fails. If you set it to false, the task does not fail even if the export tool fails, but the result is set in the property identified by the errorProperty parameter. The failonerror parameter is optional and set to true by default.
errorProperty: The name of the property that receives the result of a task that fails when the failonerror property is set to false. The errorProperty parameter is optional and is not specified by default.
You can export an Oracle Service Bus configuration in offline mode using the WebLogic Scripting Tool (WLST). To make sure WLST is configured correctly, use the WLST command-line file (wlst.bat or wlst.sh) provided with Service Bus. These files are located in OSB_HOME/tools/configjar.
Exporting using WLST generates an Oracle Service Bus configuration JAR from the folders and files you specify in the export settings file.
Use the following syntax for Windows:
wlst.bat <SCRIPTNAME>
Use the following syntax for UNIX or Linux:
./wlst.sh <SCRIPTNAME>
Below is a sample WLST script:
from com.bea.alsb.tools.configjar import ConfigJar
args = []
args.append('-settingsfile')
args.append('/osb/config/mySettings.xml')
ConfigJar.main(args)
For more information, see Oracle Fusion Middleware Oracle WebLogic Scripting Tool.
The following parameters can be used in the WLST script:
-settingsfile FILE_NAME: Enter the path and filename of the export settings file. If you use a relative path, the path resolves from the directory where the export tool resides (OSB_HOME/tools/configjar). This parameter is required.
-debug: Include this optional parameter in the command to enable debug logging of the export process. If this flag is not included, debug logging is not performed.
-help: Include this optional parameter in the command to view usage information.
By configuring the export settings, you can specify the files and folders to be included in the configuration JAR that is exported. You can do this at the project and resource level, and you can use a series of exclusion and inclusion rules for a finer level of control. The included files and folders make up the content set for the export.
The following topics describe the export settings file, provides samples, and include the schema definition:
The export settings file contains two main sections: source and configjar. The source element defines the files to be picked up during the load phase of the export tool. The configjar element defines which of the files that were picked up during the load phase will be included in the generated configuration JAR file during the export phase.
In the source element, you can specify the project root directories for the projects to export, the location of the system resources to export, and specific files to include or exclude. You can also map custom file extensions to Service Bus resource types so the export tool can recognize them as valid Service Bus components. For information about resource types and file extensions, see Section B.1.3, "File Extensions and Type IDs for Oracle Service Bus Resources."
Note:
If you specify relative directories for the project root or resource folders, the path is resolved relative to the directory in which the export settings file is located.
In the configjar element, you name the generated JAR file and specify rules at the project and resource level, including whether to include system resources at the project level and whether to include dependencies at the resource level. You can define multiple configjar elements; a JAR file is generated for each configjar element you define.
For guidance and restrictions on naming configuration JAR files, see Section 2.1.1, "Resource Naming Restrictions."
The same naming validation rules that are applied in Eclipse are also applied to the files to be included in the content set. Any files or folders that do not conform to these rules are excluded from the content set.
Folders and files must have valid names. For more information, see Section 2.1.1, "Resource Naming Restrictions."
For files, the extension must map to a Service Bus resource.
Two different resource type IDs cannot map to the same file extension. For more information about type IDs and file extensions, see Table B-1.
If the project validation itself fails, the project is still exported successfully.
When you use inclusion and exclusion rules, a file must match at least one of the inclusion rules and none of the exclusion rules to be included in the content set. For a file to be excluded, it must match at least one of the exclusion rules or none of the inclusion rules. If no inclusion or exclusion rules are defined, all files are automatically included.
The inclusion and exclusion rules are based on a simple pattern.
The pattern is applied on the file sub-path starting with the project name. It is not applied on the full file path.
An asterisk (*) is a wildcard representing any character. It can be used as part of a file or directory name.
When a double asterisk (**) is used alone, it matches zero or more directories and files.
This section provides sample export settings files that show ways to export Service Bus configurations using a variety of rule combinations for the load and export phases. The samples illustrate the following scenarios:
Example B-1 Exporting from a Non-Eclipse File Structure
The following sample illustrates how to package a project and its associated system resources from a structure like Maven. The location of the project is specified in the project element, and the location of the system resources is specified in the system element. This sample outputs two configuration JAR files. The first, sbconfig-po.jar, is a project-level configuration with no system resources. The second, sbconfig-po-system.jar, is a resource-level configuration with JNDI and SMTP resources.
<configjarSettings xmlns="http://www.bea.com/alsb/tools/configjar/config">
<source>
<project dir="/scratch/modulePO/src/main/resources/PO"/>
<system dir="/scratch/modulePO/src/main/system"/>
</source>
<configjar jar="/scratch/modulePO/sbconfig-po.jar">
<projectLevel includeSystem="false"/>
</configjar>
<configjar jar="/scratch/modulePO/sbconfig-po-system.jar">
<resourceLevel>
<resources>
<include name="**/*.jndi"/>
<include name="**/*.smtp"/>
</resources>
</resourceLevel>
</configjar>
</configjarSettings>
Example B-2 Exporting at the Project Level
The following sample illustrates how to package system resources from different locations and export them by project. You can delete any unneeded resources when you import the configuration.
<configjarSettings xmlns="http://www.bea.com/alsb/tools/configjar/config">
<source>
<system dir="/scratch/moduleX/src/main/system"/>
<system dir="/scratch/moduleY/src/main/system"/>
<system dir="/scratch/moduleZ/src/main/system"/>
</source>
<configjar jar="/scratch/sbconfig-systems.jar">
<projectLevel includeSystem="true"/>
</configjar>
</configjarSettings>
Example B-3 Excluding File Extensions in the Load Phase
This sample illustrates how to package all non-service resources into a configuration JAR file by defining exclusion rules in the source element. Compare this with Example B-4, "Excluding File Extensions in the Export Phase". Note that excluding files during the load phase is the recommended method for performance reasons.
<configjarSettings xmlns="http://www.bea.com/alsb/tools/configjar/config">
<source>
<project dir="/scratch/workspaces/myworkspace/projectX"/>
<project dir="/scratch/workspaces/myworkspace/projectY"/>
<fileset>
<exclude name="**/*.proxy"/>
<exclude name="**/*.biz"/>
<exclude name="**/*.flow"/>
</fileset>
</source>
<configjar jar="/scratch/workspaces/myworkspace/sbconfig-resources.jar">
<resourceLevel/>
</configjar>
</configjarSettings>
Example B-4 Excluding File Extensions in the Export Phase
The following sample illustrates how to package all non-service resources into a configuration JAR file by defining exclusion rules in the configjar element.
<configjarSettings xmlns="http://www.bea.com/alsb/tools/configjar/config">
<source>
<project dir="/scratch/workspaces/myworkspace/projectX"/>
<project dir="/scratch/workspaces/myworkspace/projectY"/>
</source>
<configjar jar="/scratch/workspaces/myworkspace/sbconfig-resources.jar">
<resourceLevel>
<fileset>
<exclude name="**/*.proxy"/>
<exclude name="**/*.biz"/>
<exclude name="**/*.flow"/>
</fileset>
</resourceLevel>
</configjar>
</configjarSettings>
Example B-5 Mapping File Extensions
The following example illustrates how to map additional file extensions to specific Service Bus resource types, in this case to XQuery and XML types.
<configjarSettings xmlns="http://www.bea.com/alsb/tools/configjar/config">
<source>
<project dir="/scratch/workspaces/myworkspace/projectX"/>
<project dir="/scratch/workspaces/myworkspace/projectY"/>
<extensionMapping>
<mapping type="Xquery" extensions="xquery,xq,xqy"/>
<mapping type="XML" extensions="toplink"/>
</extensionMapping>
</source>
<configjar jar="/scratch/workspaces/myworkspace/sbconfig.jar">
<resourceLevel/>
</configjar>
</configjarSettings>
Note:
When mapping file extensions, the type attribute must match a Service Bus resource type defined in Section B.1.3, "Oracle Service Bus Resource File Extension Defaults.".
Below is the schema definition for the export settings XML file. Some of the text below has been wrapped for readability.
<?xml version="1.0"?>
<xs:schema targetNamespace="http://www.bea.com/alsb/tools/configjar/config"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://www.bea.com/alsb/tools/configjar/config">
<xs:element name="configjarSettings" type="tns:configjarSettings"/>
<xs:complexType name="configjarSettings">
<xs:sequence>
<xs:element name="source" type="tns:source" />
<xs:element name="configjar" type="tns:configjar" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="source">
<xs:sequence>
<xs:choice minOccurs="1" maxOccurs="unbounded">
<xs:element name="project">
<xs:complexType>
<xs:attribute name="dir" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="system">
<xs:complexType>
<xs:attribute name="dir" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
</xs:choice>
<xs:element name="extensionMapping" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element name="mapping" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:attribute name="type" type="xs:string" use="required"/>
<xs:attribute name="extensions" type="xs:string"
use="required"/>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="fileset" type="tns:contentSet" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="configjar">
<xs:sequence>
<xs:choice minOccurs="1" maxOccurs="1">
<xs:element name="projectLevel" type="tns:projectLevel"/>
<xs:element name="resourceLevel" type="tns:resourceLevel"/>
</xs:choice>
</xs:sequence>
<xs:attribute name="jar" type="xs:string" use="required"/>
<xs:attribute name="overwrite" type="xs:boolean" use="optional"
default="true"/>
</xs:complexType>
<xs:complexType name="projectLevel">
<xs:sequence>
<xs:element name="project" type="xs:string" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="includeSystem" type="xs:boolean" use="optional"
default="false"/>
</xs:complexType>
<xs:complexType name="resourceLevel">
<xs:sequence>
<xs:element name="resources" type="tns:contentSet" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="includeDependencies" type="xs:boolean" use="optional"
default="true"/>
</xs:complexType>
<xs:complexType name="contentSet">
<xs:sequence>
<xs:element name="include" type="tns:contentSetPattern" minOccurs="0"
maxOccurs="unbounded"/>
<xs:element name="exclude" type="tns:contentSetPattern" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="contentSetPattern">
<xs:attribute name="name" type="xs:string" use="required"/>
</xs:complexType>
</xs:schema>