Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Service Bus
11g Release 1 (11.1.1.7)

Part Number E15866-09
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
PDF · Mobi · ePub

B Exporting an Oracle Service Bus Configuration Offline

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:

For information about exporting resources using Eclipse, see Section 2.1.11, "Exporting Resources."

B.1 About the Export Process

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.

B.1.1 Configuring the Load Phase

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.

B.1.2 Configuring the Export Phase

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."

B.1.3 File Extensions and Type IDs for Oracle Service Bus Resources

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


B.2 Preparing to Export an Oracle Service Bus Configuration

Perform the following steps before you export a Service Bus configuration in offline mode:

B.2.1 Before You Begin

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."

B.2.2 Creating the Export Settings File

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."

B.2.3 Configuring the Environment

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

B.3 Exporting an Oracle Service Bus Configuration

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.

B.3.1 Exporting a Configuration Using the Command Line

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.

Syntax

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]

Parameters

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.

B.3.2 Exporting a Configuration Using Ant

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.

Syntax

The sample Ant build file supports the following syntax:

ant -f <FILE_NAME> [-debug] [-failonerror] [-errorproperty]

Sample Build File

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>

Parameters

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.

B.3.3 Exporting a Configuration Using WLST

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.

Syntax

Use the following syntax for Windows:

wlst.bat <SCRIPTNAME>

Use the following syntax for UNIX or Linux:

./wlst.sh <SCRIPTNAME>

Sample WLST Script

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.

Parameters

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.

B.4 Export Settings File Format, Samples, and Schema

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:

B.4.1 Export Settings File Format

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."

B.4.2 Validation

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.

B.4.3 Inclusion and Exclusion Rules

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.

B.4.4 Export Settings File Samples

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.".

B.4.5 Export Settings File Schema Definition

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>