bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Using Application Integration

Importing and Exporting Application Views

This section presents the following topics:

- Import/Export Utility

- Import/Export Methods and Command Line

Import/Export Utility

WebLogic Integration provides a simple import/export utility for Application Views that can be executed from the command line, and incorporated into your code with the import/export API for Application Views. The output of the utility is a JAR file containing all artifacts owned by the Application View. You must manually import or export any artifacts that are used but not owned by the Application View.

Note: If the business process management (BPM) capabilities of WebLogic Integration are installed, you can use the workflow package import/export utility (accessible from the WebLogic Integration Studio) to migrate application integration data. For more information, see Migrating Application Integration Data.

The import/export utility allows you to export application integration metadata objects from the repository and to import those objects back into the repository. The utility allows you to import/export the following objects:

- Application views

- Connection factories (with descriptors as stored in the repository, not those deployed from WebLogic Server)

- Schemas

- Namespaces

All exported objects for a given invocation of the utility are stored in a JAR archive. When a previously exported JAR is imported, all objects in the JAR are imported, too. You can also append objects to an existing exported JAR, and deploy Application Views and connection factories on import.

Import/Export Methods and Command Line

The utility is available as an API and as a command-line tool. In both cases, the server must be running. The following sections describe the command-line parameters and the methods on the import/export utility.

Invoking the Import/Export Utility from the Command Line

The following is the command-line syntax for the import/export utility:

>     Usage: ImportExport <server_URL> <username> <password> <file>
>     [-codepage=Cp<codepage_number>] [-dump=< <namespace> | <'Root'> >]
>     [-append] [-overwrite] [-deploy]
>     < [-export [object_name]*] | [-import [edit-on-import_filename]] >

The following table shows the command-line parameters for the import/export utility.

Parameter | Description
--- | ---
server_URL | URL of WebLogic Server. This is required only if you are connecting from a remote client.
username | Your username for the specified WebLogic Server. This is required only if you are connecting from a remote client.
password | Your password for the specified WebLogic Server. This is required only if you are connecting from a remote client.
file | Name of the file to be created on export or to be imported into the repository.
-codepage | Sets the codepage used when writing to the console. This insures that characters are displayed correctly. The default value is Cp437, which is used in the United States. Other valid values include: Cp850 Multilingual (Latin I) Cp852 Slavic (Latin II) Cp855 Cyrillic (Russian) Cp857 Turkish Cp860 Portuguese Cp861 Icelandic Cp863 Canadian-French Cp865 Nordic Cp866 Russian Cp869 Modern Greek MS932 Japanese
-dump | Prints a list of all objects within both the specified namespace and other namespaces nested within it. To print a list of objects for the entire folder structure, specify Root.
-append | Appends exported items to the file specified by file.
-overwrite | Overwrites items already in the repository when import is being performed.
-deploy | Deploys the Application View or connection factory on import.
-export | Specifies an export operation and the name of the objects to be exported. Wildcards are allowed in object names. To export the entire folder structure, include Root in the list of object names.
-import | Specifies that objects contained in file should be imported into the repository. If an edit-on-import file is specified, objects are edited according to the instructions in the file. Edits are performed before the object is added to the repository and before deployment (if requested).

Editing on Import

When an edit-on-import file is specified, you can execute editing commands on the text for objects to be imported. The resulting editing is done before the object is stored in the repository or deployed. Otherwise, the method is used as described in Importing Objects.

The document specified must conform to the following DTD:

>     <!ELEMENT ApplicationView (replace*)>
>     <!ATTLIST ApplicationView name NMTOKEN #REQUIRED
>                                                         newName NMTOKEN #IMPLIED>

>     <!ELEMENT ConnectionFactory (replace*)>
>     <!ATTLIST ConnectionFactory name NMTOKEN #REQUIRED
>                                                             newName NMTOKEN #IMPLIED>

>     <!ELEMENT Schema (replace*)>
>     <!ATTLIST Schema name NMTOKEN #REQUIRED
>                                       newName NMTOKEN #IMPLIED>

>     <!ELEMENT replace EMPTY>
>     <!ATTLIST replace xpath CDATA #REQUIRED
>                                         old CDATA #REQUIRED
>                                         new CDATA #REQUIRED

The edit-on-import document contains sections, indicated by the <ELEMENT> tag, for each object to be edited. You can edit ApplicationView, ConnectionFactory, and Schema objects. Each section identifies an object by name and specifies the elements to be replaced. Optionally, each section can specify a newName attribute that can be used to assign a new name to an object.

Each replace element specifies the following:

- An xpath expression used to identify the nodes to be edited, among all the nodes in the object's XML descriptor

- An old value to search for in the selected nodes. The old value can be a Perl5 regular expression. If you specify an empty string ("") as the old value, all text in the selected nodes is matched.

- A new value with which to replace the old value. The new value must be a simple string.

Example Edit-on-Import Document

The following edit-on-import descriptor document describes how to edit an Application View named DBMS.DBMS1 and rename it to DBMS.DBMS1a. The XML document illustrates three replacements for the Application View and one replacement for the connection factory.

>     <?xml version="1.0"?>
>     <!DOCTYPE edit SYSTEM "ImportExportEditOnImport.dtd">
>     <edit>
>           <ApplicationView name="DBMS.DBMS1" newName="DBMS.DBMS1a">
>                 <replace xpath="/applicationView/@connectionFactory"
>                       old=""
>                       new="com.bea.wlai.connectionFactories.DBMS.
>                                 DBMS1a_connectionFactoryInstance"/>
>                 <replace xpath="/applicationView/@connectionFactoryName"
>                       old=""
>                       new="DBMS.DBMS1a_connectionFactory"/>
>                 <replace               xpath="/applicationView/service[@name='Service1']/
>                   interactionSpecProperty[@name='sql']"
>                       old="CAJUN."
>                       new="PBPUBLIC."/>
>           </ApplicationView>

>           <ConnectionFactory name="DBMS.DBMS1_connectionFactory"
>             newName="DBMS.DBMS1a_connectionFactory">
>                 <replace xpath="/connection-factory-dd/jndi-name"
>                       old=""
>                       new="com.bea.wlai.connectionFactories.DBMS.
>                                 DBMS1a_connectionFactoryInstance"/>
>           </ConnectionFactory>
>     </edit>

The first replacement edits the connectionFactory attribute of the Application View descriptor and changes the text in this attribute to the new value. Note the use of an empty string as the old value to match all text in the node.

The second replacement edits the connectionFactoryName attribute of the Application View descriptor and changes the text in this attribute to the new value.

The third replacement edits the service descriptor for the service named Service1 and changes the interactionSpecProperty element named sql by replacing CAJUN. with PBPUBLIC. wherever it occurs.

The fourth replacement edits the jndi-name attribute of the connection factory descriptor and changes the text in this attribute to the new value.

Using the Import/Export API

The following sections describe the methods included in the import/export API. The class name for the import/export API is com.bea.wlai.client.ImportExport.

Connecting to the Server Instance

>     connect(<multiple signatures>)

The connect() method establishes a connection method with the server instance. Depending on where you initiate connections, you may need to specify different arguments for connect().

If you are initiating connections. . . | Then you must specify these arguments. . .
--- | ---
Within the same server | No arguments
From a remote client without InitialContext | URL (as a string), username, and password
From a remote client with InitialContext | InitialContext

Printing Objects in a Namespace

>     dumpNamespace(String namespaceName)

The dumpNamespace() method takes a string that represents the qualified name of a namespace, and prints out all objects within that namespace, as well as any other namespaces embedded in it.

Exporting Objects

>     exportNamespaceObjects(Set objectNames, boolean append, List errors)

The exportNamespaceObjects() method takes a list of object names (qualified names as strings) and exports them to the specified output file (see Specify File for Import/Export). All objects listed for export are examined for dependencies. Any objects that are used but not owned by an Application View are also exported.

When an Application View is exported, the ConnectionFactory and all the Schema objects on which the Application View depends are also exported. When a Namespace is exported, all objects in the namespace (including other namespaces) are also exported.

To append the exported file to an existing archive, or to overwrite or create the file, set append to true.

Any nonfatal errors encountered during the export are stored as Exception objects in the specified errors List object.

Importing Objects

>     importNamespaceObjects(boolean overwrite, boolean deploy, List errors)

The importNamespaceObjects() method takes all entries in the specified input file (see Specify File for Import/Export) and imports them into the repository. Set overwrite to true to overwrite existing metadata in the repository. Set deploy to true to deploy connection factories and Application Views on import.

Any nonfatal errors encountered during the import are stored as Exception objects in the specified errors List object.

Importing and Editing Objects

>     importNamespaceObjects(IDocument editOnImportDoc boolean overwrite,
>     boolean deploy, List errors)

When an edit-on-import document is specified, the importNamespaceObjects() method allows you to execute editing commands on the text for objects to be imported. The resulting editing is done before the object is stored in the repository or deployed. Otherwise, the method is used as described in Importing Objects.

The document specified in the editOnImportDoc argument must conform to the DTD shown in Editing on Import.

Specify File for Import/Export

>     setFile(File filename)

The setFile() method designates the file to be used as the export destination or import source.

Choosing Where to Print Messages

>     setPrintWriter(PrintWriter out)

The setPrintWriter() method designates a PrintWriter object to be used when messages (such as status, diagnostic, and error messages) are generated.

Choosing Whether to Print Messages

>     setQuiet(boolean quiet)

The setQuiet() method specifies whether to print progress and information messages. To print messages, set quiet to false. To disable message printing, set quiet to true.