BEA Logo BEA WebLogic Integration Release 2.1 Service Pack 1

  BEA Home  |  Events  |  Solutions  |  Partners  |  Products  |  Services  |  Download  |  Developer Center  |  WebSUPPORT

   http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary

 

   WebLogic Integration Doc Home   |   B2B Topics   |   Administering B2B   |   Previous Topic   |   Next Topic   |   Contents   |   View as PDF

Working with the Bulk Loader

 

The following sections describe how to work with the Bulk Loader:

In addition to using the Bulk Loader, you can use the B2B Console to transfer data to and from the repository, as described in Importing and Exporting B2B Integration Components. For information about the repository, see Working with the Repository.

 

Understanding the Terminology

The following table describes some of the terms used in this chapter.

Table 7-1 Terms Used in This Chapter

This term . . .

Refers to . . .

XML declaration

A processing instruction that identifies the document as being XML. At a minimum, the XML version must be specified. If the document uses a character set other than the default, encoding="valid_encoding" must also be specified.

Doctype declaration

The XML document type (references the root element and DTD).

XML element

An element in an XML file.

attribute

An attribute for an XML element.

value

The value of either an attribute or a data element.

 

For example, consider the following repository data file:

 
<?xml version="1.0"?>
<!DOCTYPE wlc SYSTEM "WLC.dtd">
<wlc system-password="wlcsystem">
    <conversation-definition
        name="CMQPAConversation"
        version="1.1"
        business-protocol-name="XOCP"
        protocol-version="1.1">
        <role
            name="CMBuyer"
            wlpi-template="CMBuyerQPAPublic">
            <process-implementation wlpi-org="ORG1" />
        </role>
        <role
            name="CMSupplier"
            wlpi-template="CMSupplierQPAPublic">
            <process-implementation wlpi-org="ORG1" />
        </role>
   </conversation-definition>
</wlc>

In the previous file, the following examples of the definitions are used:

 

Importing Data into the Repository

The following sections provide information about importing repository data:

How the Bulk Loader Imports Data

As the following figure shows, the Bulk Loader parses a Bulk Loader configuration file to get instructions about transferring data from a repository data file into the repository. Both files are XML files. If the Bulk Loader detects any errors during this procedure, it creates an error log.

Figure 7-1 Using the Bulk Loader to Import Repository Data


 

The Bulk Loader uses the following logic to import data from a repository data file into the repository:

  1. If the B2B root element specified in the repository data file does not exist in the repository, the Bulk Loader creates it.

    Note: The B2B root element in a repository data XML file is wlc. This abbreviation is a legacy from a previous release.

  2. If the B2B root element specified in the repository data file already exists in the repository, the Bulk Loader uses the following logic to process each data element in the repository data file:

The following table describes the logic the Bulk Loader uses to recreate an existing element.

Table 7-2 Logic for Processing an Attribute

Does the element or attribute exist in the repository data file?

Attribute type

Logic

Yes

Does not matter

The Bulk Loader sets the data element value or attribute to the value specified in the repository data file.

No

IMPLIED

The Bulk Loader sets the data element value or attribute to null unless it is one of the attributes that has a special default value, as described in the following table.

No

REQUIRED

The Bulk Loader considers the data to be invalid. For more information, see Checking Data.

 

The following table lists the default values for special IMPLIED attributes.

Table 7-3 Default Values for Special IMPLIED Attributes

XML Element

Attribute

Default Value

wlc

large-msg-support-on

OFF

wlc

show-hidden

OFF

trading-partner

status

ENABLED

 

Note: The abbreviation wlc is a legacy from a previous release of the product. The wlc element corresponds to the top-level node, B2B, in the B2B Console.

Procedure for Importing Data into the Repository

Notes: In addition to using the Bulk Loader, you can use the B2B Console to transfer data to and from the repository, as described in Importing and Exporting B2B Integration Components.

You cannot run the Bulk Loader when the B2B engine is running. If the B2B engine has shut down abnormally, thus preventing the Bulk Loader from running, you can force the import, as described in Forcing the Bulk Loader.

To import data from a repository data file into the repository:

  1. Create a Bulk Loader configuration file.

    In it, include load-processing-parameters, which is the XML element that instructs the Bulk Loader to import data from the repository data file into the repository. For information about creating a Bulk Loader configuration file, see Working with the Bulk Loader Configuration File.

  2. Create a repository data file.

    For information about creating a repository data file, see Working with the Repository Data File.

  3. To import data from the repository data file into the repository, enter the command appropriate for your platform:

    In the preceding commands:

Note: For information about the bulkloader command, see WebLogic Integration Commands in Starting, Stopping, and Customizing BEA WebLogic Integration.

 

Exporting Data from the Repository

The following sections provide information about exporting repository data:

How the Bulk Loader Exports Data

As the following figure shows, the Bulk Loader parses a Bulk Loader configuration file to get instructions for transferring data from the repository to a repository data file. Both files are XML files. If the Bulk Loader detects any errors during this procedure, it creates an error log.

Figure 7-2 Using the Bulk Loader to Export Repository Data


 

Full and Partial Repository Exports

When you export data from the repository, you can specify a full export or a partial export, as described in the following table.

Table 7-4 Full and Partial Repository Exports

Type of Export

Description

Full

All the data is exported.

Partial

A subset of the data is exported.

 

By default, the Bulk Loader performs a full repository export.

To perform a partial repository export, use the entities XML element in the Bulk Loader configuration file to specify which data elements you want to export. The Bulk Loader uses the entities values to traverse the repository to the specified data elements.

For example, to export a specific collaboration agreement, include the <entities> element and specify some identifying information for the collaboration agreement in the required structure, as shown in the following listing. This strategy can be used for all types of data elements.

For a complete description of the entities XML element, see the WLCConfig.dtd file in the lib\dtd subdirectory of your WebLogic Integration installation directory.

Listing 7-1 Example of a Bulk Loader Configuration File for Exporting a Specific Collaboration Agreement

 
<?xml version="1.0"?> 
<!DOCTYPE wlc-config SYSTEM "WLCConfig.dtd">
<wlc-config>
    <unload-processing-parameters> 
       <database-url>jdbc:weblogic:oracle:REPO</database-url>
        <database-driver>weblogic.jdbc.oci.Driver</database-driver>
       <database-user-id>scott</database-user-id>
       <database-password>tiger</database-password>
       <xml-file-name>ExportRepoData.xml</xml-file-name>
       <entities>
          <wlc>
           <collaboration-agreement 
              name="QPA-XOCP-TP1-TP2" 
              version=1.2>
           <collaboration-agreement>
          <wlc>
       </entities>
    </unload-processing-parameters>
</wlc-config>

Short and Long Repository Exports

When you export data from the repository, you can specify a short export or a long export, as described in the following table.

Table 7-5 Short and Long Repository Exports

For this type of export . . .

The Bulk Loader organizes the output data . . .

Short (standard)

To represent the user's view of the repository.

Long (extensive)

As a snapshot of the repository, which can be useful when you migrate repository data from one database to another.

 

By default, the Bulk Loader exports repository data in the short format.

To perform a long repository export, set the format attribute for the unload-processing-parameters XML element in the Bulk Loader configuration file to long.

Because the long format includes internal repository data, in addition to values for various objects, we recommend that you use the long format only for the following reasons:

For an example of a Bulk Loader configuration file that specifies a format value, see Listing 7-3. For a complete description of the format attribute, see the WLCConfig.dtd file in the lib\dtd subdirectory of your WebLogic Integration installation directory, and Short and Long Repository Exports.

Procedure for Exporting Repository Data

Note: In addition to using the Bulk Loader, you can use the B2B Console to transfer data to and from the repository, as described in Importing and Exporting B2B Integration Components.

You cannot run the Bulk Loader when the B2B engine is running. If the B2B engine has shut down abnormally, thus preventing the Bulk Loader from running, you can force the export, as described in Forcing the Bulk Loader.

To export data from the repository to a repository data file:

  1. Create a Bulk Loader configuration file.

    In it, include unload-processing-parameters, which is the XML element that instructs the Bulk Loader to export data from the repository to a repository data file. For more information about creating a Bulk Loader configuration file, see Working with the Bulk Loader Configuration File.

  2. To export data from the repository to a repository data file, enter the command appropriate for your platform:

    In the preceding commands:

Note: For information about the bulkloader command, see WebLogic Integration Commands in Starting, Stopping, and Customizing BEA WebLogic Integration.

 

Deleting Data from the Repository

The following sections provide information about deleting repository data:

How the Bulk Loader Deletes Data

As the following figure shows, the Bulk Loader parses a Bulk Loader configuration file, which is an XML file, to get instructions about deleting data from the repository. The dotted line in the figure indicates that the Bulk Loader affects the repository without sending any data to it. If the Bulk Loader detects any errors during this procedure, it creates an error log.

Figure 7-3 Using the Bulk Loader to Delete Repository Data


 

Procedure for Deleting Repository Data

Note: You cannot run the Bulk Loader when the B2B engine is running. If the B2B engine has shut down abnormally, thus preventing the Bulk Loader from running, you can force the deletion of the data, as described in Forcing the Bulk Loader.

To delete repository data:

  1. We strongly recommend that you back up the repository before deleting any data from it. To back up the repository, perform a full, long (extensive) export, as described in Exporting Data from the Repository.

  2. Create a Bulk Loader configuration file.

    In it, include delete-processing-parameters, which is the XML element that instructs the Bulk Loader to delete data from the repository. For information about creating a Bulk Loader configuration file, see Working with the Bulk Loader Configuration File.

  3. To delete data from the repository, enter the command appropriate for your platform:

    In both commands, cfg_file is the pathname of the Bulk Loader configuration file that you created in step 2.

    Use the same command for importing, exporting, and deleting data. The Bulk Loader configuration file indicates which action the Bulk Loader should take.

    While deleting data, the Bulk Loader checks for errors, as described in Checking Data.

Note: For information about the bulkloader command, see WebLogic Integration Commands, in Starting, Stopping, and Customizing BEA WebLogic Integration.

 

Working with the Bulk Loader Configuration File

Bulk Loader configuration files contain the database login information and processing instructions required to carry out the desired task. Each Bulk Loader configuration is an XML file that conforms to the WLCConfig.dtd.

Although the sections that follow provide much of the information you need to create your own Bulk Loader configuration file, you may need to refer to the WLCConfig.dtd located in the lib\dtd subdirectory for certain details.

A Bulk Loader configuration file has a fairly simple structure. The root element <wlc-config> contains one of the following elements, depending on the action:

The following table summarizes the processing parameters that can be specified to carry out each type of action.

Table 7-6 Bulk Loader Configuration Processing Parameters

Elements and Attributes

Description

Attribute:

transaction-level

Is an attribute of:

<load-processing-parameters>
<delete-processing-parameters>

Specifies whether the data is imported in a single transaction, or in multiple transactions.

Valid values are all or default.

When set to default, or not specified, a transaction is initiated upon import or delete of each of the following entities: trading partners, conversation definitions, collaboration agreements, business protocol definitions, and logic plug-ins. If invalid data is detected during a transaction for any entity, the import is rolled back for the current transaction only; importing continues for the next transaction.

For additional information about error detection, see Checking Data Integrity.

Attribute:

database-initialization

Is an attribute of:

<load-processing-parameters>

Specifies whether or not to initialize the database. Valid values are yes and no.

yes—clears the existing B2B integration data from the repository during the import.

no—retains existing B2B integration data during the import. If the imported data describes elements and attributes that already exist in the repository, then the imported data overwrites the existing data for those specific values. (no is the default)

Attribute:

format

Is an attribute of:

<unload-processing-parameters>

Specifies whether the Bulk Loader exports data in the long (extensive) format or in the short (standard) format. Valid values are short and long. For more information, see Short and Long Repository Exports.

Attribute:

<database-url>

Is a required child of:

<load-processing-parameters>
<unload-processing-parameters>
<delete-processing-parameters>

URL for the database, as specified in the JDBC driver documentation. For a summary of the required URLs for supported drivers, see "Database Access Parameters" in Customizing WebLogic Integration in Starting, Stopping, and Customizing BEA WebLogic Integration

Element:

<database-driver>

Is a required child of:

<load-processing-parameters>
<unload-processing-parameters>
<delete-processing-parameters>

JDBC driver required to connect to the database. For supported drivers, see "Database Access Parameters" in Customizing WebLogic Integration in Starting, Stopping, and Customizing BEA WebLogic Integration

Element:

<database-user-id>

Is an optional child of:

<load-processing-parameters>
<unload-processing-parameters>
<delete-processing-parameters>

Database user ID, if required to connect to the database.

Element:

<database-password>

Is an optional child of:

<load-processing-parameters>
<unload-processing-parameters>
<delete-processing-parameters>

Database password, if required to connect to the database.

Element:

<database-properties>

Is an optional child of:

<load-processing-parameters>
<unload-processing-parameters>

Allows you to specify any properties the database driver may require, using the following syntax:

name1=value1[;name2=value2;name3=value3 . . . ]

In particular, if you are using a WebLogic jDriver, and the database is configured to use an alternate character set, then you must set the weblogic.codeset property. For example, if you are using the Shift_JIS character set in your locale, specify:

weblogic.codeset=Shift_JIS

Element:

<xml-file-name>

Is a required child of:

<load-processing-parameters>
<unload-processing-parameters>

Contains the name of the existing XML file to be imported, or the new XML file to be created to store the exported data.

Unless the file is located in the current directory, the full path must be specified.

Element:

<encoding>

Is an optional child of:

<unload-processing-parameters>

Used to export the B2B configuration elements using the specified encoding (character set/code set). For a list of valid character set names and aliases, see http://www.iana.org/assignments/character-sets

Element:

<entities>

Is an optional child of:

<unload-processing-parameters>

Is a required child of:

<delete-processing-parameters>

Contains the entities to be deleted or unloaded. Refer to WLCConfig.dtd for definitions of the entity elements and subelements.

 

To use the Bulk Loader to import, export, or delete data from the repository:

  1. Create an XML file that specifies WLCConfig.dtd in the DocType declaration, and conforms to the structure required by the DTD.

  2. If you are importing or exporting data, set the xml-file-name XML element in the XML file to specify the pathname of the repository data file. If you specify only a filename, the Bulk Loader looks for the repository data file in the current working directory.

The following sections provide example Bulk Loader configuration files for importing and exporting data:

Bulk Loader Configuration File for Importing Data

The following listing is an example Bulk Loader configuration file for importing data into the repository.

Listing 7-2 Bulk Loader Configuration File—Import

 
<?xml version="1.0"?> 
<!DOCTYPE wlc-config SYSTEM "WLCConfig.dtd">
<wlc-config>
    <load-processing-parameters database-initialization="no"\
       transaction-level="all"> 
       <database-url>
          jdbc:oracle:thin:@rdbmshost:1521:WLIDB
       </database-url>
       <database-driver>
          oracle.jdbc.driver.OracleDriver
       </database-driver>
       <database-user-id>
          scott
       </database-user-id>
       <database-password>
          tiger
       </database-password>
       <xml-file-name>
          ImportRepoData.xml
       </xml-file-name>
    </load-processing-parameters> 
</wlc-config>

In addition to the processing parameters that are required in any Bulk Loader configuration file (DTD, database URL, database driver, database user ID, and database password), this example defines the following:

Although not shown in this example, the database-properties element is also available when exporting. This element can be used to specify any additional properties required by the JDBC driver.

Bulk Loader Configuration File for Exporting Data

The following listing is an example Bulk Loader configuration file for exporting data from the repository. In this case, the configuration file itself contains locale-specific characters (see xml-file-name), and therefore, the XML declaration must specify the appropriate encoding.

Listing 7-3 Bulk Loader Configuration File—Export

 
<?xml version="1.0" encoding="GB2312"?>
<!DOCTYPE wlc-config SYSTEM "WLCConfig.dtd">
<wlc-config>
  <unload-processing-parameters format="short">
      <database-url>
          jdbc:weblogic:mssqlserver4:WLIDB@myhost
      </database-url>
      <database-driver>
          weblogic.jdbc.mssqlserver4.Driver
      </database-driver>
      <database-user-id>
          myuserid
      </database-user-id>
      <database-password>
          mypassword
      </database-password>
      <xml-file-name>
          d:\bea1\RN2AITest\@nA&\exportedPeer1config.xml
      </xml-file-name>
      <encoding>
         GB2312
      </encoding>
     <database-properties>
          weblogic.codeset=GB2312
     </database-properties>
</unload-processing-parameters>
</wlc-config>

In addition to specifying values that are required in any Bulk Loader configuration file (DTD, database URL, database driver, database user ID, and database password), this example defines the following:

 

Working with the Repository Data File

The repository data file is an XML file that conforms to the WLC.dtd. To create a repository data file, create an XML file that specifies WLC.dtd in the DocType declaration, and conforms to the structure required by the DTD. Refer to the WLC.dtd, which is in the lib\dtd subdirectory of your WebLogic Integration installation directory, for the required structure.

The following listing shows a repository data file that creates an extended property set.

Listing 7-4 Example of a Repository Data File for a New Extended Property Set

 
<?xml version="1.0"?>
<!DOCTYPE wlc SYSTEM "WLC.dtd">
<wlc 
    name="WLC" 
    large-msg-support-on="ON"
    large-msg-min-size="10000"
    large-msg-location="c:\temp"
    proxy-host="andrew"
    proxy-port="7502" 
    description="The WLC Hub" >
 
    <extended-property-set name="EPS 1">
        <xml-element name="C1">
            <xml-attribute name="C1_A1" value="C1_A1 Value"/>
            <xml-element name="C1G1">
                <xml-element name="C1G1_T1" text="C1G1_T1 Value"></xml-element>
                <xml-element name="C1G1_T2" text="C1G1_T2 Value"></xml-element>
                <xml-element name="C1G1_T3" text="C1G1_T3 Value"></xml-element>
            </xml-element>
            <xml-element name="C1G2" text="C1G2 Value"></xml-element>
            <xml-element name="C1G3" text="C1G3 Value"></xml-element>
        </xml-element>
        <xml-element name="C2">
            <xml-attribute name="C2_A1" value="C2_A1 Value"/>
            <xml-attribute name="C2_A2" value="C2_A2 Value"/>
            <xml-attribute name="C2_A3" value="C2_A3 Value"/>
            <xml-element name="C2G1" text="C2G1 Value"></xml-element>
            <xml-element name="C2G2">
                <xml-element name="C2G2_T1" text="C2G2_T1 Value"></xml-element>
                <xml-element name="C2G2_T2" text="C2G2_T2 Value"></xml-element>
                <xml-element name="C2G2GG1">
                    <xml-attribute name="C2G2GG1_A1" value="C2G2GG1_A1 Value"/>
                    <xml-element name="C2G2GG1_T1" text="C2G2GG1_T1
                        Value"></xml-element>
                </xml-element>
            </xml-element>
            <xml-element name="C2G3" text="C2G3 Value"></xml-element>
        </xml-element>
    </extended-property-set>
 
</wlc>

 

Checking Data

The following sections describe how the Bulk Loader checks data:

Creating an Error Log

To keep track of errors, the Bulk Loader creates a file named wlc.log in the current working directory. If a wlc.log file already exists, the Bulk Loader renames the existing file by appending a timestamp to the name in the following format: wlc.log.yyyy.mm.dd.hh.mi.ss. Then the Bulk Loader creates a new wlc.log file. The following table describes the fields in the timestamp.

Table 7-7 Timestamp Appended to Name of Existing Log File

This string . . .

Indicates the . . .

yyyy

Year

mm

Month in numeric format (between 01 - 12)

dd

Day in numeric format

hh

Hour (between 00 - 23)

mi

Minute

ss

Second

 

Validating XML Files

Before it processes any data, the Bulk Loader validates the XML files. The following table lists the files that the Bulk Loader validates for each type of Bulk Loader task.

Table 7-8 Files Validated by the Bulk Loader

For this task . . .

The Bulk Loader validates . . .

Importing data

Bulk Loader configuration file

Repository data file

Exporting data

Bulk Loader configuration file

Deleting data

Bulk Loader configuration file

 

To validate one of these types of XML files, the Bulk Loader checks it against the corresponding .dtd file. If the Bulk Loader detects an error in the XML file, it stops without processing the data.

Checking Data Integrity

After validating the XML files, the Bulk Loader checks the data integrity while it is processing the data. To check data integrity, the Bulk Loader verifies that the information in the XML files does not conflict with the information in the repository.

For example, if the Bulk Loader is adding a new data element to the repository and if the new data element references another data element, the Bulk Loader makes sure that the referenced data element exists in the repository or in the repository data file.

Checking Data Integrity While Importing or Deleting

To have data integrity checked while data is being imported or deleted, set the transaction-level attribute in the Bulk Loader configuration file, as shown in Listing 7-3. If you do not set transaction-level, the Bulk Loader uses the default value. The Bulk Loader performs one of the following sets of actions, depending on the value of transaction-level:

Checking Data Integrity During an Export

If the Bulk Loader detects invalid data in the Bulk Loader configuration file, it does not perform the export.

 

Forcing the Bulk Loader

By default, the Bulk Loader does not import, export, or delete data while the B2B engine is running. If, for some reason, the B2B engine does not shut down normally, the Bulk Loader fails with the following error:

ERROR: WLC is still running or was shut down abnormally.

You can override this error and force the command to execute by adding the -force option to the Bulk Loader command file. You can update the existing Bulk Loader command file, or you can copy and update the file, as described in the following procedure:

  1. Make a copy, with a new name, of the Bulk Loader command file appropriate for your platform, as shown in the following examples:

  2. Open the new file (in this example, the bulkloaderforce command file) in your preferred text editor.

  3. Locate the following line in the new file:
java %DB_JVMARGS% -classpath %WLICP% com.bea.b2b.bulkloader.BulkLoader -v %CTLFILE%

  1. Add the -force option to this line, as follows:

    java ... com.bea.b2b.bulkloader.BulkLoader -v -force %CTLFILE%

  2. Save and close the file.

  3. Execute the newly created command file to force the import or export of the desired data.

 

back to top previous page next page

 

Copyright © 2002 BEA Systems, Inc. All rights reserved.
Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.