Trading Partner Lightweight Client Sample

 

The Trading Partner Lightweight Client sample demonstrates two communication methods (browser and file-sharing) used when one or more trading partner hosts no BEA software. The sample is based on business practice functions and business processes for a requestor and replyer communicating via either a browser or a file-sharing client.

This section includes the following topics:

• Overview of the Lightweight Client Sample

• Running the Lightweight Client Sample

• Creating and Using Lightweight Clients

 

---

Overview of the Lightweight Client Sample

WebLogic Collaborate conversations usually take place between two trading partners who have both installed WebLogic Collaborate. Browser and file-sharing clients provide a way to communicate with trading partners who have not installed BEA software. The Lightweight Client sample demonstrates communication between a requestor trading partner using a browser client, and a replier trading partner using a file-sharing client.

Purpose of the Sample

The Lightweight Client sample demonstrates how business communication can take place between a requestor and one or more repliers that do not have WebLogic Collaborate installations. This communication is accomplished using two types of lightweight clients that are configured in a remote or host WebLogic Collaborate installation:

• Browser client—Uses JSP served up by predefined WebLogic Collaborate business processes to initiate a conversation, and send and receive messages. The Web host facilitates communication via JSP delivered on demand to the browser client. Uses the WebLogic Collaborate JSP tag libraries to send and check the messages using the WebLogic Collaborate mailbox interface.

• File-sharing client—Communication is accomplished using a file-sharing client. The requestor puts a message in a preconfigured mailbox located on the Web host. The replier uses a file-sharing client provided by WebLogic Collaborate to transfer messages between its mailboxes and file-sharing directories. The party using a file-sharing client in the conversation must have a pre-existing FTP installation.

In this sample, a business operation called by the replier's private workflow gets a request from a preconfigured directory, creates a reply based on the request, and puts the reply into a preconfigured output directory. This sample does not use an actual FTP server installation; it uses the business operation to simulate the FTP server.

Lightweight Client Sample Scenario and Diagrams

The Lightweight Client sample scenario involves two trading partners (one requestor and one replier) who communicate via a remote WebLogic Collaborate installation that has been preconfigured to handle lightweight clients.

The requestor sends a request for multiplication of two integer numbers. Requestor has no local WebLogic Collaborate installation. Instead, it uses a browser to access the JSPs that are served from a remote installation of WebLogic Collaborate. The JSPs create mailboxes and send XML requests using the WLC-provided JSP tag libraries. The same JSPs are also used to check the messages in the requestor's mailbox, as well as to delete messages from the requestor and replier mailboxes.

Note: In an actual business deployment, the requestor would not have access to the replier's mailboxes.

The replier uses a third-party FTP server application to communicate with some trading partners; it has no WebLogic Collaborate installation. The replier may use a proprietary mechanism for handling messages. It communicates with the requestor via a file-sharing client.

The Lightweight Client sample demonstrates the following events:

• Requestor's private workflow is triggered by an XML event from a JSP tag in the browser client.

• Replier's public workflow is triggered by a reply placed in the replier's out mailbox by the file-sharing client.

• Requestor's message and replier's message are put in the appropriate mailboxes.

In the Lightweight Client sample, there are four preconfigured mailboxes, one inbox and one outbox for each trading partner, as follows:

• Requestor using a browser client: BrowserTP1_Inbox and BrowserTP1_Outbox

• Replier using a file-sharing client: FtpTP1_Inbox, and FtpTP1_Outbox

  Figure 3-1 Lightweight Client Deployment Diagram

  
   

 

---

Running the Lightweight Client Sample

The Lightweight Client sample requires no additional configuration; it can be run as delivered. See Installing the Samples.

To run the Lightweight Client sample implementation:

1. If you have already run the Hello Partner sample you have already bulkloaded all of the data required to run the Lightweight Client sample. The Lightweight Client sample shares WebLogic Collaborate information with the Hello Partner sample.

   If you have not run the Hello Partner sample, see Hello Partner Sample. See also Installing the Samples.

2. Run the Lightweight Client sample as follows:

   • Windows: From the Start menu, choose:
     WebLogic Integration 2.0—>Collaborate—>Samples—>Run Samples—>Lightweight Client

   • UNIX: Load the following sample file:

     http://localhost:7001/lwcWebApp/LwcMain.jsp

     The following illustration shows an example of the Lightweight Client main page.

     
      

3. Start the file-sharing client.

   Windows: Choose WebLogic Integration 2.0—>Collaborate—>Samples—>Lightweight Client—>Start File Sharing Client

   UNIX: Execute the following script:

   cd $WLC_HOME/config/samples/lightweightClient
   sh startFSClient.sh

Note: If you start the file-sharing client before the first JSP has been loaded, you will get a repeated Mailbox not found exception. These exceptions can be ignored, since mailboxes are created when the main JSP has been loaded for the first time. Once the mailboxes have been created these exceptions no longer appear.

1. Click Go to the request input page. The Request for Multiplication page is displayed as follows.
    

2. Test SendmsgTag and the wrapper Mailbox API by manually sending a message to BrowserTP1_Outbox as follows:

   1. Select two integers.

   2. Click—>Send Multiplication Request.

      Your display is updated, as shown in the following figure.

      
       

3. Test CheckallmsgTag by clicking Check all replies. A list of replies is displayed as shown in the following illustration.
    

   If no replies have been received, the following message is displayed.

   
    

4. Test DeleteallmsgTag as follows:

   1. Click—>Delete all messages in all mailboxes. A list of all the messages in all the WebLogic Collaborate mailboxes is displayed.
       
       

   2. Click—>Delete all messages in all mailboxes again. Displays the total number of messages deleted.

5. Test DeletemsgTag as follows:

   • On the Check All Replies screen shown in Step 6, select a message

   • Click Delete. The Delete One Reply screen confirms that the message was successfully deleted.
      

6. You can view message details as follows:

   • On the Check All Replies screen shown in Step 6, click on the message in the Message ID column that you want to view.

   • The View Reply Detail screen is displayed.
      

 

---

Creating and Using Lightweight Clients

This section provides information about creating and configuring lightweight clients:

• Lightweight Client Source Files

• Using the JSP Tag Library

• Configuring a Lightweight Client

• Configuring a Browser Client

Lightweight Client Source Files

The source directories included with WebLogic Collaborate contain all of the files required for creating your own lightweight clients. The Lightweight Client sample shares WebLogic Collaborate information with the Hello Partner sample.

Files and directories specific to the Lightweight Client sample are listed in the following table.

Source Directory	Contents
WLC_HOME\dtd\
lwcFileSync.dtd	TheDTD file for LwcFileSync.xml.
setenv.cmd setenv.sh	Makes sure that lwclient.jar, applications, and classes are included in JAVACLASSPATH for both the spoke configuration and WebLogic Server.
build.cmd build.sh	Builds all of the samples. Once this script is executed, lwcWebApp.war is created and placed under WLC_HOME\lib. All of the class files are placed under WLC_HOME\config\samples\applications\DefaultWebApp_myserver\WEBINF\classes. Note: The WAR file is prepackaged and installed when you install WebLogic Collaborate.
WLC_HOME\config\samples\lightweightClient\	Contains the source files for the business operation and its helper to be called by a workflow instance.
startFSClient.cmd startFSClient.sh	A script that starts the file-sharing client that is responsible for transferring a request from the replier's in mailbox to its file sharing directory, and for transferring a reply from the replier's out directory to its out mailbox.
LwcFileSync.xml	File read by the file-sharing client. You must modify the following sections for your environment: url wlcfilesync name directoryin directoryout
ftpDir\	A directory created for the Lightweight Client sample runtime execution. It simulates the file-sharing client's in and out directories. Contains FtpTP1_indir and FtpTP1_outdir to simulate the in and out directories on the file-sharing client. Names are hard-coded for the sample. Note: This directory and its associated subdirectories are created at runtime.
lwcWebApp\	Contains the files for the Web application, such as *.jpg and *.jsp files.
WEB-INF\	Contains the JSP tag library description file, and web.xml used by the Lightweight Client web application.
taglib\	Contains the reference implementation of the WebLogic Collaborate JSP tag libraries. Used for message management by com.bea.lwclient.LwcMailbox.

Using the JSP Tag Library

The JSP tag library uses a wrapper to address the WebLogic Collaborate Messaging API. The JSP tag library is used with predefined workflows to interact with a mailbox, as shown in Figure 3-2.

Figure 3-2 Mailbox Scenario Using the JSP Tag Library

 

The mailbox shown in Figure 3-2 supplements the repository. The tag library accesses the mailbox as needed. The repository may also store mailbox messages. Error handling is based on standard Java exception and error handling via the WebLogic Collaborate Mailbox API classes and JSP delivered to the browser client.

For a complete listing of the JSP tags, see JSP Tag Reference.

Configuring a Lightweight Client

Additional steps are required when configuring a WebLogic Collaborate installation to support customers using lightweight clients.

A lightweight client does not need any security mechanisms; it is a daemon process that is independently run in its own Java Virtual Machine by WebLogic Collaborate. It serves any number of lightweight clients that have been configured through the LwcFileSync.xml configuration file. For additional information, see Edit the File-Sharing File later in this document.

Edit the Configuration File

Add the lightweight trading partner configuration information, shown in Listing 3-1 and Listing 3-2, to the WebLogic Collaborate config.xml file.

Listing 3-1 Web Application Configuration

<!-- LightweightClient settings -->
    <Application
      Name="LwcWebApp"
      Path="<WLC_HOME>/lib"
    >
      <WebAppComponent
        Name="LwcWebApp"
        ServletReloadCheckSecs="1"
        Targets="myserver"
        URI="LwcWebApp.war"
      />
    </Application>

Listing 3-2 File-Sharing Client Configuration

<StartupClass
      ClassName="com.bea.lwclient.Startup"
      Name="LwcStartup"
      Targets="myserver"
/>

Edit the File-Sharing File

Configure the lightweight client by editing lwcFileSync.xml. The file-sharing client configuration is defined in lwcFileSync.xml, and conforms to lwcFileSync.dtd.

Note: LwcFileSync.dtd must be located in the directory from which the file-sharing client is started.

Listing 3-3 contains the DTD file. Listing 3-4 provides a sample XML file that sets up the lightweight trading partners. Replace the values shown in bold with values that are appropriate for your lightweight client installation.

Listing 3-3 Example of lwcFileSync.dtd

<!-- This DTD describes file sharing client configuration file -->
<!ELEMENT wlcfilesyncconfig (wlcfilesync*) >

<!--  maxThreads The upper limit for number of threads permissible -->
<!--  in thread pool at a given point in time  -->
<!ATTLIST wlcfilesyncconfig  maxThreads CDATA #REQUIRED>

<!--  minThreads The lower limit for number of threads permissible -->
<!-- in thread pool at a given point in time -->
<!ATTLIST wlcfilesyncconfig  minThreads CDATA #REQUIRED>

<!--  maxIdleTime The maximum time interval thread could be idle -->
<!-- else removed from the pool -->
<!ATTLIST wlcfilesyncconfig  maxIdleTime CDATA #REQUIRED>

<!--  pollInterval Time interval defining wait interval before polling -->
<!ATTLIST wlcfilesyncconfig  pollInterval CDATA #REQUIRED>

<!--  url Weblogic URL used for JNDI lookup  -->
<!ATTLIST wlcfilesyncconfig  url CDATA #REQUIRED>

<!--  debug flag used to turn debugging on/off  -->
<!ATTLIST wlcfilesyncconfig  debug (TRUE | FALSE) "FALSE">

<!--  The following element is used to configure details of  LWTP -->
<!ELEMENT wlcfilesync EMPTY>

<!--  LWTP name -->
<!ATTLIST wlcfilesync name CDATA #REQUIRED>

<!--  path of the incoming directory on local file system -->
<!ATTLIST wlcfilesync directoryin CDATA #REQUIRED>

<!--  path of the outgoing directory on local file system -->
<!ATTLIST wlcfilesync directoryout CDATA #REQUIRED>

Listing 3-4 Example of lwcFileSync.xml

<?xml version="1.0"?>
<!DOCTYPE wlcfilesyncconfig SYSTEM "LwcFileSync.dtd">
<wlcfilesyncconfig maxThreads="9"
            minThreads="3"
            maxIdleTime="5000"
            pollInterval="2000"
            url="t3://localhost:7001"
            debug="FALSE">
<wlcfilesync name="FtpTP1" 
            directoryin="<WLC_HOME>/ftpDir/FtpTP1_indir"
            directoryout="<WLC_HOME>/ftpDir/FtpTP1_outdir"/>
</wlcfilesyncconfig>

Configuring a Browser Client

WLC supports two methods of configuring a browser client, depending on the security paradigm desired:

• Configuring an HTTP Browser Client

• Configuring an HTTPS (SSL) Browser Client

Configuring an HTTP Browser Client

To configure an HTTP lightweight client, you must edit the web.xml file. To turn on security for a browser client, complete the following procedure:

1. The JSP developer responsible for the HTML user interface for trading partner lightweight client Web application(s) uses the sendmsg tag and provides the following mandatory argument : security = ON or OFF.

   The workflow template developers can also turn security on and off using the examples.lightweightClient.LwcBizOp.putMessage() method that also accepts a string as its last argument for SECURITY. To turn security on or off, the developer passes one of the following arguments: ON or OFF.

2. The person responsible for the hosted Web application deployment modifies WLC_HOME\lwcWebApp\WEB-INF\web.xml to add security constraints for all the users with permission to use the application.

   For example, to provide a new user with security privileges to use the Web application lwcWebApp.war, add the following code:

     <security-constraint>
       <web-resource-collection>
         <web-resource-name>lwcWebApp</web-resource-name>
         <url-pattern>/*</url-pattern>
       </web-resource-collection>
      <auth-constraint>
        <role-name>newpartner</role-name>
      </auth-constraint>
     </security-constraint>

     <login-config>
      <auth-method>BASIC</auth-method>
     </login-config>

     <security-role>
       <role-name>newpartner</role-name>
     </security-role>

3. The newpartner user must be a valid WebLogic Server user. The user can be created using either the WebLogic Server Administration Console or the WebLogic Collaborate Administration Console. For details, see the BEA WebLogic Server Administration Guide, or Administering BEA WebLogic Collaborate, respectively.

4. The newpartner user must be mapped to a valid trading partner lightweight client. This mapping is done using the WebLogic Collaborate Administration Console. Through the Console, you create the trading partner lightweight client and map the user's identification to the appropriate trading partner record. For details, see Administering BEA WebLogic Collaborate.

5. You must create a collaboration agreement between newpartner and the WebLogic Collaborate hub. Use the WebLogic Process Integrator Studio to create the collaboration agreement. For details, see Using the BEA WebLogic Process Integrator Studio.

Configuring an HTTPS (SSL) Browser Client

To configure a lightweight HTTPS (SSL) client, perform the following steps:

1. Configure certificates at both the browser and the WebLogic Collaborate nodes.

2. Create a WebLogic Server user called newpartner, who will run the browser on behalf of a trading partner lightweight client. You can create this user through either the WebLogic Server Administration Console or the WebLogic Collaborate Administration Console.

3. Use the WebLogic Collaborate Administration Console to create the trading partner lightweight client.

4. Map newpartner to the trading partner record.

5. Create a collaboration agreement between the lightweight client and the WebLogic Collaborate hub, using the WebLogic Collaborate Administration Console. For details, see Administering BEA WebLogic Collaborate.