Using the Application Integration Design Console

Importing and Exporting Application Views

This section presents the following topics:

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.

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

Application views
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.

Migrating Application Views Using the Import-Export Utility

Use the Import-Export utility to migrate application views from a WebLogic Integration 7.0 environment to a WebLogic Integration 8.1 environment. As part of the migration, the utility removes the ACLs from the application view and converts the use of connection factories to use of resource adapters. The migrated application views are loaded into the file-based repository.

Note: You must define a project in WebLogic Workshop before migrating application views. The project determines the location of the repository.

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 scripts used to run the utility are located as follows:

WLI_HOME/bin/aiimportexport (cmd or sh)

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:

aiimportexport <appname> <root_dir> <file>
[-codepage=Cp<codepage_number>] [-dump=< <namespace> | <'Root'> >]
[-append] [-overwrite] [-publish] 
< [-export [object_name]*] | [-import [edit-on-import_filename]
[-eventProps=<connection_factory_name>,<properties_file_name>]*] >

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

Parameter	Description
appname	The name of J2EE application to which artifacts will be imported, or from which artifacts will be exported.
root_dir	The root directory of the AI repository within the given application.
`file`	Name of the JAR 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 The value specified must match your console's codepage. On Windows systems, use the `chcp` command to display the console's codepage.
-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` instead of overwriting the file. This option should only be used when `-export` is specified.
-overwrite	Overwrites items already in the repository and contained in the archive being imported. This option should only be used when `-import` is specified.
-publish	Publishes any application views after they are imported. This option should only be used when `-import` is specified.
-export	Specifies an export operation and the name of the objects (namespaces and application views) to be exported into `file`. When specifying an object within a namespace use a dot (.) as the delimiter, for example, `mynamespc.myappview`. 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).
`-eventProps`	This option is used only when importing a WebLogic Integration 7.0 or earlier export JAR. This option defines a mapping between the connection factory (qualified) name and a properties file that provides the properties needed for event generation within the adapter instance generated for the named connection factory. Multiple `-eventProps` arguments may be used as needed. These properties were specified in WebLogic Integration 7.0 within the EventRouter WAR file's `web.xml`. When creating the properties file for the `-eventProps` arguments, you should take the property name/value pairs from the `init-param` elements in the `web.xml` of the adapter's EventRouter WAR file. You can ignore the following properties from the `web.xml` file, and exclude them from the `-eventProps` properties file: `eventGeneratorClassName` `RootLogContext` `AdditionalLogContext` `LogConfigFile` `LogLevel` `MessageBundleBase` `LanguageCode` `CountryCode` If no `-eventProps` argument is found that maps a properties file to the qualified name for a connection factory, then when the connection factory is imported, the adapter instance generated has inbound messaging disabled. To specify event properties for the adapter instance at a later time, use the Edit Adapter Instance page of the Application Integration Design Console.

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