Skip navigation.

Using WebLogic Integration - Business Connect

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents Index View as PDF   Get Adobe Reader

Document and Event APIs

The following topics describe the WebLogic Integration - Business Connect application program interfaces (APIs) for document integration and events.

Concepts

 


Java RMI Event Listening

The Java RMI event listening API enables a client to listen to document and system events generated by the WebLogic Integration - Business Connect Server application.

Calls made by WebLogic Integration - Business Connect Server into an event client run on a single Server thread. Any long-running processes should not be run within the isRemote or eventArriving methods. If long-running processing is required, the processing should be spun off onto a separate thread.

For the same reason, using multiple RMI event listeners could slow the performance of WebLogic Integration - Business Connect because of the single thread.

Events are passed in real time. They are not persisted for retrieval later.

System and document events are reported according to the event logging level set on the General tab under Tools—>Preferences in Administrator.

Performance is enhanced if the Java RMI API client and server application run on the same computer, but this is not a requirement. An API client running on the same computer is referred to as a local client. An API client running on a different computer is referred to as a remote client. If you set up a remote client, it should run on the same side of a firewall as the Server application. Running a remote client on the opposite side of a firewall presents RMI protocol difficulties.

RMI is the TCP/IP protocol employed. For more information about RMI, visit http://java.sun.com/products/jdk/rmi/index.html.

The following topics provide describe how to use the Java RMI event listening API.

Application Configuration

You must add event client RMI stubs to the WebLogic Integration - Business Connect Server class path.

You also must copy the cyclone.jar and xerces.jar files to your client's machine and make them available by modifying the classpath environment variable. The cyclone.jar file is required to be able to interface with the Server application. The xerces.jar file is required to send XML files to and receive them from the Server application. If you intend to use JMS to interface with the Server application you still must include these two files into your classpath. However, you must also include jms.jar and jndi.jar in your classpath. All of these files are located in the WebLogic Integration - Business Connect lib directory.

In Windows modify the class path in two places. First, modify the server.bat file in the WebLogic Integration - Business Connect bin directory. Add the path to the event client RMI stubs to the USERCLASSES environment variable. Secondly, modify the COMMAND LINE variable in the server.ini file, which also is in the bin directory. Add the path to the RMI stubs to the end of the already configured class path. If you run Windows service, also modify ECEngine.ini.

In UNIX modify the class path in the environment file in the bin directory.

Semantics

An event client must implement the following interface:

com.cyclonecommerce.cybervan.api.InterchangeEventListener

The methods that WebLogic Integration - Business Connect calls are defined in this interface. You must implement two methods: isRemote and eventArriving.

The event client must locate WebLogic Integration - Business Connect in the RMI Registry on the machine where WebLogic Integration - Business Connect Server is running. For this purpose use LocateRegistry.getRegistry and Registry.lookup.

The event client must be registered with WebLogic Integration - Business Connect. For this purpose use RemoteInterchangeServer.setEventListener.

Once registered the event client's eventArriving method is called for each event that WebLogic Integration - Business Connect produces. The possible events are defined in the com.cyclonecommerce.cybervan.api. EventConstants interface. The com.cyclonecommerce.cybervan.api.InterchangeEvent object passed to the eventArriving method is initialized with a com.cyclonecommerce.cybervan.api.InterchangeEventDescription object. The com.cyclonecommerce.cybervan.api.InterchangeEventDescription object contains a source, level, description and details for the event. If the event relates to a document (SEND, RECEIVED, PACKAGED and so on), the com.cyclonecommerce.cybervan.api.InterchangeEventDescription object also contains a com.cyclonecommerce.cybervan.api.IntegrationDocument object.

Scenario

Figure 16-1 shows a high-level view of the Java RMI event listening API.

Figure 16-1 Local or Remote Client Listens to Server Events

Local or Remote Client Listens to Server Events


 

Key to Figure 16-1

  1. API listener client registers at startup with WebLogic Integration - Business Connect Server application.
  2. Client listens as Server sends events.

Sample Code

The sample code for the Java RMI event listening API is in api/samplecode/EventClient.

If EventClient and WebLogic Integration - Business Connect are going to be run on separate machines, then you must modify the INTERCHANGE_HOST_ADDRESS and IS_REMOTE variables before compiling the code.

If WebLogic Integration - Business Connect has been configured to use a non default registry port, then you must modify LocateRegistry.getRegistry call before compiling the code.

For information about building and running the sample code, see the readme file in api/samplecode/EventClient.

 


JMS Integration for Events

The JMS integration for events API enables a client to listen to document and system events generated by the WebLogic Integration - Business Connect Server application.

JMS topics provide support for multiple listeners. Multiple listeners have no direct effect on the performance of WebLogic Integration - Business Connect.

JMS topics provide reliable messaging. As long as the JMS server is enabled, messages are stored until retrieval by a topic listener.

System and document events are reported according to the event logging level set on the General tab under Tools—>Preferences in Administrator.

The following topics describe how to use the JMS integration for events API:

Application Configuration

The default Administrator user can use the JMS Integration window Events tab to configure the Server application to publish all events to your system's JMS server and locate the JMS server by calling the JNDI provider in your JMS enterprise messaging system. This feature enables persistent event logging to the JMS server.

To use this tab your organization must have JMS experience and a working JMS enterprise messaging system.

In addition to completing this tab, you must add the names of the JAR or class files or both in the server.ini or server.bat file in Windows or your environment file in UNIX so the Server application can locate the JMS and JNDI provider. The server.ini and server.bat files are located in the installation directory bin subdirectory. In some cases, you need to add the name of only one JAR file (for example, swiftmq.jar), but you might have to include a series of jars or paths.

To display the JMS Integration window Events tab, select Tools—>API—>JMS and click the Events tab.

Figure 16-2 JMS Integration Window Events Tab

JMS Integration Window Events Tab


 

Field Descriptions

The following describes the fields on the JMS Integration window Events tab.

JNDI

Complete the following fields for the Java naming and directory interface (JNDI).

URL

Type the network URL that will be used to obtain access to the JNDI service provider for your JMS service. Example: smqp://localhost:4001/timeout=10000

Factory

Type the name for the JNDI service provider class. Example: com.swiftmq.jndi.InitialContextFactoryImpl

User name

Type a user name that will be used to access the JNDI provider. This value could be blank and is typically provided for in the JNDI URL. However, this will depend on the JNDI provider and how it is configured.

Password

Type a password for the JNDI user name. This value could be blank and is typically provided for in the JNDI URL. However, this will depend on the JNDI provider and how it is configured.

Confirm password

Type the password again.

JMS

Complete the following fields for the Java messaging service (JMS).

Topic

Type the name of the topic. Example: eventTopic

Topic connection factory

Type the connection factory as defined within the JMS provider. This value can be either in the form factory_name@router_name or the JNDI public symbol for the TopicConnectionFactory. Examples: plainsocket@router1 or TopicConnectionFactory22. This will depend on your JMS provider and how it is configured.

User name

Type a user name on the router that has access to the specified topic. This can be the same as the JNDI user name. However, this will depend on your JMS provider and how it is configured.

Password

Type the password for the JMS user name.

Confirm password

Type the password again.

Semantics

To use JMS event integration it would be useful for you to understand the Java event listening code, as both APIs have similar functionality.

A com.cyclonecommerce.cybervan.api.InterchangeEvent object is posted to the configured JMS topic for every event generated by WebLogic Integration - Business Connect. The InterchangeEvent is published to the JMS topic as a JMS ObjectMessage.

The com.cyclonecommerce.cybervan.api.InterchangeEventDescription object contains a source, level, description and details for the event. If the event relates to a document (SEND, RECEIVED, PACKAGED and so on), the com.cyclonecommerce.cybervan.api.InterchangeEventDescription object also contains a com.cyclonecommerce.cybervan.api.IntegrationDocument object.

Scenario

Figure 16-3 shows a high-level view of the JMS integration for events API.

Figure 16-3 JMS Integration for Events

JMS Integration for Events


 

Key to Figure 16-3

  1. Client registers a durable subscriber against topic.
  2. Server pushes ObjectMessage into JMS topic for each event.
  3. JMS server calls client code with ObjectMessage.

Sample Code

The sample code for JMS integration for events API is in api/samplecode/JMSEvents.

JMSEvents shows how to pull events out of the JMS topic after WebLogic Integration - Business Connect has written the event into the topic.

For information about building and running the sample code, see the readme file in api/samplecode/JMSEvents.

 


Local Java RMI Client for Document Exchange

The local Java RMI client for document exchange API enables a client to send documents to, and receive documents from, WebLogic Integration - Business Connect.

Calls made by WebLogic Integration - Business Connect Server into a document exchange client run on a Server thread. Any long-running processes should not be run within the isRemote or documentArriving methods. If long-running processing is required, the processing should be spun off onto a separate thread.

Sending and receiving documents is best achieved when the document exchange client is running on the same machine as WebLogic Integration - Business Connect Server. It is possible to run the document exchange client on a separate machine, but this is a much more complex configuration.

The following topics describe how to use the local Java RMI client for document exchange API:

Application Configuration

You must add document exchange client RMI stubs to the WebLogic Integration - Business Connect Server class path.

You also must copy the cyclone.jar and xerces.jar files to your client's machine and make them available by modifying the classpath environment variable. The cyclone.jar file is required to be able to interface with the Server application. The xerces.jar file is required to send XML files to and receive them from the Server application. All of these files are located in the WebLogic Integration - Business Connect lib directory.

In Windows modify the class path in two places. First, modify the server.bat file in the WebLogic Integration - Business Connect bin directory. Add the path to the document exchange client RMI stubs to the USERCLASSES environment variable. Secondly, modify the COMMAND LINE variable in the server.ini file, which also is in the bin directory. Add the path to the RMI stubs to the end of the already configured class path. If you run Windows service, also modify ECEngine.ini.

In UNIX modify the class path in the environment file in the bin directory.

Semantics

To use the document exchange API for a local Java RMI client, it would be useful for you to understand the Java RMI event listening code.

Receive Document

The following are requirements to receive a document:

  1. The document exchange client must implement the following interface:
  2. com.cyclonecommerce.cybervan.api.RemoteDocumentListener

    WebLogic Integration - Business Connect calls methods in the document exchange client that are defined in this interface. Two methods must be implemented: isRemote and documentArriving.

  3. The document exchange client must locate WebLogic Integration - Business Connect in the RMI Registry on the machine where WebLogic Integration - Business Connect is running. LocateRegistry.getRegistry and Registry.lookup are used for this purpose.
  4. The document exchange client must be registered with WebLogic Integration - Business Connect. RemoteInterchangeServer.setDocumentListener is used for this purpose.
  5. Once registered, the document exchange client's documentArriving method is called for each document that WebLogic Integration - Business Connect receives and successfully unpackages. The documentArriving method is not called for inbound documents that are rejected. If an MCD is created for a RosettaNet or ebXML document, the documentArriving method also is called for acknowledgments as well as documents.
  6. A com.cyclonecommerce.cybervan.api.DocumentArrivalEvent object is passed into each call to the documentArriving method. The DocumentArrivalEvent object contains a com.cyclonecommerce.cybervan.api.IntegrationDocument object. The IntegrationDocument object contains the meta-data describing the document received.

  7. The actual document content is not included in the IntegrationDocumet object. If the intent of your Document Exchange Client is to copy the document content to another location - the path to the file containing the document content can be determined by calling the IntegrationDocument object getPath method. It is then up to the Document Exchange Client to copy, move or delete the document.

Send Document

The following are requirements to send a document:

  1. Create and populate a DefaultDocument object.
    1. Use DefaultDocument.setSenderId to set the company that is sending the document.
    2. Set the file name.
    3. Set the path to the file. WebLogic Integration - Business Connect must be able to access this path.
    4. Set the document type (XML, EDI or binary).
    5. If sending a binary document, use DefaultDocument.setReceiverId to set the ID of the receiving partner. If an MCD is being used, however, do not set the partner ID. Otherwise, the partner ID is optional. Including the Partner ID might speed document packaging.
    6. If ebXML and trading with the file system interface (no MCD), set the packaging type to ebXML and the packaging version to 1.0 or 2.0. Otherwise do not set the packaging type and version.
    7. If ebXML and trading with the file system interface (no MCD), the ebXmlService and ebXmlAction are required.
    8. If ebXML and trading with the file system interface (no MCD), the userdata properties can optionally be set. See User-Defined Meta-Data for ebXML.
    9. You can use correlation IDs if supported by your back-end system. WebLogic Integration - Business Connect supports correlation IDs that are passed to it with documents from an API client. See Support for Correlation IDs. Do not set a correlation ID if an MCD is used.
  2. Call one of the overloaded RemoteInterchangeServer.sendDocument methods to send the document. We recommend using sendDocument(DefaultDocument) or sendDocumet(DefaultDocument, backup). If you use sendDocument(DefaultDocument, backup, synchronousSend), WebLogic Integration - Business Connect will not perform any transport failure retries.
  3. The call to sendDocument returns return a unique ID. This ID can be used to match to events passed to the RemoteEventListener interface. The unique ID value correlates to the ID returned by IntegrationDocument.getUniqueId for outbound document events (NEW, PACAKGED, SENT events).

Methods for Sending Documents

The RemoteInterchangeServer interface has three sendDocument methods. There can be confusion on which to use. This topic provides clarification. All three methods send the document to the indicated recipient via WebLogic Integration - Business Connect Server.

  1. sendDocument(IntegrationDocument document)
  2. The document contents are backed up before WebLogic Integration - Business Connect packages and sends the document.

    This is the simplest of the three methods. This method packages and backs up the outbound document before returning control to the client application. The document is sent to the destination partner based on the partner's configured send schedule. If the default schedule is used, control is returned to the client application before the document is actually sent to the partner. If the partner's send schedule is immediate send, control does not return to the client application until the document is successfully sent or rejected.

  3. sendDocument(IntegrationDocument document, boolean backup)
  4. This version of the sendDocument method allows the client application to specify if the outbound file should be backed up. Otherwise it works identically to the sendDocument(IntegrationDocument document) version of the method. Note that if the outbound document is not backed up, the Interchange Resend Logic, and document Resubmitted Logic does not work with the sent document. In other words, the document can never be resent on resubmit or failure to receive a ACK.

  5. sendDocument(IntegrationDocument document, boolean backup, boolean synchronousSend)
  6. This version of the sendDocument method allows the client application to override the partner's send schedule. If synchronousSend is true, the document is backed up (if not disabled), packaged and sent before control is returned to the client application. The partner's send schedule is ignored. If there is a transport failure, an exception is thrown back to the client application. No other attempt is made to send the document on transport failure.

    Note that if the document was successfully sent, and backups where enabled, WebLogic Integration - Business Connect will resend the document if an ACK is expected and not received.

    If synchronousSend is false, this method works just like sendDocument(IntegrationDocument document, boolean backup).

Scenarios

The following graphics show high-level views of the document exchange API for local Java RMI clients.

Figure 16-4 Local Client Receives a Document from WebLogic Integration - Business Connect

Local Client Receives a Document from WebLogic Integration - Business Connect


 

Key to Figure 16-4

  1. Local client registers at startup with WebLogic Integration - Business Connect Server.
  2. Local client receives an event of an inbound document in WebLogic Integration - Business Connect.
  3. Local client reads the document on local file system.
  4. Figure 16-5 Local Client Sends a Document to WebLogic Integration - Business Connect

    Local Client Sends a Document to WebLogic Integration - Business Connect


     

Key to Figure 16-5

  1. Local client registers at startup with WebLogic Integration - Business Connect Server.
  2. Local client calls Server to send document.
  3. Server reads the document on the local file system.

Sample Code

The sample code for the local Java RMI client for document exchange API is in api/samplecode/FullClient.

If FullClient and WebLogic Integration - Business Connect are going to be run on separate machines:

If WebLogic Integration - Business Connect has been configured to use a non default registry port, the LocateRegistry.getRegistry call must be modified before compiling the code.

For information about building and running the sample code, see the readme file in api/samplecode/FullClient.

 


HTTP Client for Document Exchange

The HTTP or HTTPS client for document exchange API enables a client to send documents to, and receive documents from, WebLogic Integration - Business Connect.

Although documents can move via HTTP from a client to WebLogic Integration - Business Connect, inbound processing is via HTTP after WebLogic Integration - Business Connect notifies the client via RMI of a document arrival event. With this API the document exchange client and WebLogic Integration - Business Connect Server can run on the same or a different computer.

Calls made by WebLogic Integration - Business Connect Server into a document exchange client run on a Server thread. Any long-running processes should not be run within the isRemote or documentArriving methods. If long-running processing is required, the processing should be spun off onto a separate thread.

WebLogic Integration - Business Connect loads an HTTP or HTTPS server instance to process document submission and retrieval operations. These ports should be protected behind a firewall.

You can set up user name and password authentication for the API HTTP or HTTPS server in the Administrator application. You also can enable SSL authentication. See API Authentication.

If you use an API HTTPS server, you must use the certloader tool to load the SSL certificate. See Configuring an API Client to Authenticate the API Server.

The following topics describe how to use the HTTP or HTTPS client for document exchange API:

Application Configuration

You must set an API port in Administrator by selecting the Ports tab in Tools—>Preferences. Set the API HTTP port or API HTTPS port or both. The sample code uses API HTTP port 5082 by default.

You must add document exchange client RMI stubs to the WebLogic Integration - Business Connect Server class path.

In Windows modify the class path in two places. First, modify the server.bat file in the WebLogic Integration - Business Connect bin directory. Add the path to the document exchange client RMI stubs to the USERCLASSES environment variable. Secondly, modify the COMMAND LINE variable in the server.ini file, which also is in the bin directory. Add the path to the RMI stubs to the end of the already configured class path. If you run Windows service, also modify ECEngine.ini.

In UNIX modify the class path in the environment file in the bin directory.

Semantics

To use an HTTP or HTTPS client for document exchange, it would be useful for you to understand the code for Java RMI event listening and local Java RMI client for document exchange.

Receive Document

The following are requirements to receive a document:

  1. The document exchange client must implement the following interface:
  2. com.cyclonecommerce.cybervan.api.RemoteDocumentListener

    WebLogic Integration - Business Connect calls methods in the document exchange client that are defined in the interface. Two methods must be implemented: isRemote and documentArriving.

  3. The meta-data in the following table are associated with the received document.
  4. Parameter

    Description

    SENDEREDIID

    The ID of the document sender.

    RECEIVEREDIID

    The ID of the document receiver.

    NAME

    The file name of the inbound document.

    DOCTYPE

    Indicates whether the document is EDI, XML or binary.


     
  5. The document exchange client must locate WebLogic Integration - Business Connect in the RMI Registry on the machine where WebLogic Integration - Business Connect is running. LocateRegistry.getRegistry and Registry.lookup are used for this purpose.
  6. The document exchange client must be registered with WebLogic Integration - Business Connect. RemoteInterchangeServer.setDocumentListener is used for this purpose.
  7. Once registered, the document exchange client's documentArriving method is called for each document that WebLogic Integration - Business Connect receives and successfully unpackages. The documentArriving method is not called for inbound documents that are rejected. If an MCD is created for a RosettaNet or ebXML document, the documentArriving method also is called for acknowledgments as well as documents.
  8. A com.cyclonecommerce.cybervan.api.DocumentArrivalEvent object is passed into each call to the documentArriving method. The DocumentArrivalEvent object contains a com.cyclonecommerce.cybervan.api.IntegrationDocument object. The IntegrationDocument object contains the meta-data describing the document received.

  9. The actual document content is not included in the IntegrationDocument object. If the intent of your document exchange client is to copy the document content to another location, the URL to the document content can be determined by calling the IntegrationDocument object getInterchangeURL method or the getInterchangeHttpsURL method. It is then up to the document exchange client to perform an HTTP GET to retrieve the document content.

Send Document

The following are the requirements to send a document:

  1. The document to send must be posted (POST) to the WebLogic Integration - Business Connect API HTTP or HTTPS port. The URL is required to include the following meta-data as form variables:
  2. Parameter

    Description

    SENDERID

    The ID portion of an EDI ID without the EDI qualifier. This parameter is optional.

    SENDEREDIID

    The ID of the document sender. This parameter is required.

    RECEIVERID

    The ID portion of an EDI ID without the EDI qualifier. This parameter is optional.

    RECEIVEREDIID

    The ID of the document receiver.

    If you are sending a binary document, this parameter is required. Use DefaultDocument.setReceiverId.

    Do not use this parameter if an MCD is used. Otherwise, this parameter is optional.

    Using the receiver ID might speed document packaging.

    NAME

    The file name of the outbound document.

    DOCTYPE

    Indicates whether the document is EDI, XML or binary.

    REF0, REF1, REF2

    Deprecated.

    BACKUP

    Set to true to back up the outbound document or false for no backup.

    SYNCSEND

    Set to true to have the document backed up (if applicable), packaged and sent before control is returned to the client application. The partner's send schedule is ignored. If there is a transport failure, an exception is thrown back to the client and no other attempt is made to send the document.

    CORRID

    The correlation ID. See Support for Correlation IDs.

    REFID

    The reference to message ID. See Support for Correlation IDs.

    PACKAGINGTYPE

    If ebXML and trading with the file system interface (no MCD), set the packaging type to ebXML and the packaging version to 1.0 or 2.0. Otherwise do not set the packaging type and version.

    PACKAGINGVER

    If ebXML and trading with the file system interface (no MCD), set the packaging type to ebXML and the packaging version to 1.0 or 2.0. Otherwise do not set the packaging type and version.

    EBXMLSERVICE

    If ebXML and trading with the file system interface (no MCD), the ebXmlService is required.

    EBXMLACTION

    If ebXML and trading with the file system interface (no MCD), the ebXmlAction is required.

    USERKEY0 USERKEYn

    If ebXML and trading with the file system interface (no MCD), the userdata properties can optionally be set.

    USERDATA 0 USERDATAn

    If ebXML and trading with the file system interface (no MCD), the userdata properties can optionally be set. See User-Defined Meta-Data for ebXML.


     
  3. Create and populate a DefaultDocument object. Then create a com.cyclonecommerce.cybervan.api.InterchangeURL object and call the getPath method. This is one way to create the appropriate URL for sending a document.
    1. Use DefaultDocument.setSenderId to set the ID of the company for the document to be sent.
    2. Set the file name.
    3. Set the path to the file. WebLogic Integration - Business Connect must be able to access this path.
    4. Set the document type (XML, EDI or binary).
    5. If the document is binary, use DefaultDocument.setReceiverId to set the ID of the receiver. If you are using an MCD, do not include the receiver ID. Otherwise, using the receiver ID is optional. Including the receiver ID might speed document packaging.
    6. If ebXML and trading with the file system interface (no MCD), set the packaging type to ebXML and the packaging version to 1.0 or 2.0. Otherwise do not set the packaging type and version.
    7. If ebXML and trading with the file system interface (no MCD), the ebXmlService and ebXmlAction are required.
    8. If ebXML and trading with the file system interface (no MCD), the userdata properties can optionally be set. See User-Defined Meta-Data for ebXML.
    9. You can use correlation IDs if supported by your back-end system. WebLogic Integration - Business Connect supports correlation IDs that are passed to it with documents from an API client. See Support for Correlation IDs.
    10. Optionally, use synchronous sending to have the document packaged and sent before control is returned to the client application. The partner's send schedule is ignored. If there is a transport failure, an exception is thrown back to the client and no other attempt is made to send the document.
  4. Use POST to send the document to the URL returned by InterchangeURL.getPath. If applicable, the document submission client must handle SSL negotiation and HTTP basic authentication.
  5. The POST call returns a unique ID in the POST response. This ID can be used to match to events passed to the RemoteEventListener interface. The unique ID value correlates to the ID returned by IntegrationDocument.getUniqueId for Outbound Document events (NEW, PACAKGED, SENT events).

Scenarios

The following graphics show high-level views of the document exchange API via HTTP or HTTPS client.

Figure 16-6 Remote Client Receives a Document from WebLogic Integration - Business Connect

Remote Client Receives a Document from WebLogic Integration - Business Connect


 

Key to Figure 16-6

  1. Remote client registers at startup with WebLogic Integration - Business Connect Server.
  2. Remote client receives an event of an inbound document in Server.
  3. Remote client sends document GET.
  4. Remote client receives document.
  5. Figure 16-7 Remote Client Sends a Document to WebLogic Integration - Business Connect

    Remote Client Sends a Document to WebLogic Integration - Business Connect


     

Key to Figure 16-7

  1. Remote client registers at startup with WebLogic Integration - Business Connect Server.
  2. Remote client users HTTP POST to submit a document to the WebLogic Integration - Business Connect HTTP server.

Sample Code

The sample code for the HTTP or HTTPS client for document exchange API is in api/samplecode/FullClient.

The following modifications are required for the FullClient sample:

If WebLogic Integration - Business Connect has been configured to use a non default registry port, the LocateRegistry.getRegistry call must be modified before compiling the code.

For information about building and running the sample code, see the readme file in api/samplecode/FullClient.

 


Global JMS Document Integration

The global JMS document integration API enables a JMS server to send documents to, and receive documents from, WebLogic Integration - Business Connect for all active companies.

JMS topics provide reliable messaging. As long as the JMS server is enabled, messages are stored until retrieval by a topic listener. There is one inbound queue and one outbound queue.

You need knowledge of JMS programming to retrieve documents from, or submit documents to, a JMS topic.

Files are packaged immediately after retrieval from the JMS server. This is different than JMS integration by company, in which files are written to disk and then processed according to polling mechanisms.

WebLogic Integration - Business Connect registers a QueueMessageListener. This can reduce latency as compared to polling. However, thread thrashing can occur if too many large documents are pushed into WebLogic Integration - Business Connect simultaneously.

Document size is limited by memory constraints. JMS requires BytesMessages to be in memory when read from, or written to, the JMS server. There is no support for streaming. The result can be OutOfMemoryExceptions in the WebLogic Integration - Business Connect JVM when transferring large documents.

Partner send schedules are respected in sending documents.

The following topics describe how to use the global JMS document integration API:

Global Versus Company JMS Integration

WebLogic Integration - Business Connect enables JMS document integration globally for all companies, partners and document types, or by specific company, partner and document type combinations, or both. Global and company-level integration operate independently of each other.

With global JMS integration there is one inbound queue and one outbound queue for all companies, partners and document types. On the company level, a queue is required per company, partner and document type combination.

Parameters are required for documents WebLogic Integration - Business Connect retrieves from the JMS queue when global JMS integration is configured. These properties specify the sender, receiver, document type and other information. These parameters are passed to WebLogic Integration - Business Connect in a JMSMessage. If JMS integration is configured by company, however, the parameters are not required. This is because there is one queue per company, partner and document type combination and the parameter information already is established.

Regardless whether JMS integration is global or by company, WebLogic Integration - Business Connect provides values for the sender, receiver and document type parameters when passing inbound documents from partners to a JMS queue.

For information about JMS integration by company, see JMS Document Integration by Company.

Application Configuration

The default Administrator user can use the JMS Integration window Documents tab to configure WebLogic Integration - Business Connect to retrieve outbound documents from or direct inbound documents to a JMS queue. This affects inbound and outbound documents for all active company profiles, all partners and all document types: EDI, XML and binary.

The global treatment of all documents distinguishes this tab from JMS document integration that can be configured for a single company using the Company Profile window Integration tab. For more information see JMS Document Integration by Company.

To use the JMS Integration window Documents tab your organization must have JMS experience and a working JMS messaging system.

In addition to completing this tab, you must add the names of the JAR or class files or both in the server.ini or server.bat file in Windows or your environment file in UNIX so the Server application can locate the JMS and JNDI provider. The server.ini and server.bat files are located in the installation directory bin subdirectory. In some cases, you need to add the name of only one JAR file (for example, swiftmq.jar), but you might have to include a series of jars or paths.

To display the JMS Integration window Documents tab, select Tools—>API—>JMS and click the Documents tab.

Figure 16-8 JMS Integration Window Documents Tab

JMS Integration Window Documents Tab


 

Field Descriptions

The following describes the fields on the JMS Integration window Documents tab.

The fields are described once for inbound and outbound documents.

The Inbound Documents area is for configuring WebLogic Integration - Business Connect to place documents that have been received from partners and unpackaged on a back-end JMS queue.

The Outbound Documents area is for configuring WebLogic Integration - Business Connect to retrieve documents from a back-end JMS queue and then package and send the documents to partners.

Except for the user name and password, you can obtain the information needed to complete the tab from the JMS or JNDI provider's documentation. The information will vary depending on the provider. If you have questions, contact your JMS or JNDI provider.

JNDI

Complete the following fields for the Java naming and directory interface (JNDI).

URL

Type the network URL that will be used to obtain access to the JNDI service provider for your JMS service. Example: smqp://localhost:4001/timeout=10000

Factory

Type the name for the JNDI service provider class. Example: com.swiftmq.jndi.InitialContextFactoryImpl

User name

Type a user name for the JNDI provider. This value could be blank and is typically provided for in the JNDI URL. However, this will depend on the JNDI provider and how it is configured.

Password

Type a password for the JNDI provider. This value could be blank and is typically provided for in the JNDI URL. However, this will depend on the JNDI provider and how it is configured.

Confirm password

Type the password again.

JMS

Complete the following fields for the Java messaging service (JMS).

Queue connection factory

Type the connection factory as defined within the JMS provider. This value can be either in the form factoryname@routername or the JNDI public symbol for the QueueConnectionFactory. Examples: plainsocket@router1 or QueueConnectionFactory22. This would be dependent on your JMS provider and how it is configured.

Queue

Type the name of the queue in the form queuename@routername. Example: XMLQueue@router1

User name

Type a user name for the JMS provider. This can be the same as your JNDI user name. However, this will depend on how your JMS provider and how it is configured.

Password

Type a password for the JMS provider. This can be the same as your JNDI password. However, this will depend on how your JMS provider and how it is configured.

Confirm password

Type the password again.

Semantics

This API is an input and output source for documents. This is how it works: WebLogic Integration - Business Connect registers as a listener with the JMS server for the designated inbound queue. This means that any JMSMessage placed in the queue by another process is passed to WebLogic Integration - Business Connect, which verifies that it is a BytesMessage (a type of JMSMessage). If verified, WebLogic Integration - Business Connect packages and sends it to the partner. Likewise, every document WebLogic Integration - Business Connect receives from a partner is unpackaged, converted to a BytesMessage and placed on the designated inbound queue.

The API requires that the JMS messages be in the format BytesMessage. WebLogic Integration - Business Connect does not process any other type of JMSMessage (such as ObjectMessage). WebLogic Integration - Business Connect performs routing decisions based on JMS message string parameters that must be appended to each BytesMessage sent to it. If the required parameters are omitted, WebLogic Integration - Business Connect does not process the message. WebLogic Integration - Business Connect also places the same parameters on each message that it sends to the outbound queue. The parameters WebLogic Integration - Business Connect uses are in the following table.

Parameter

Description

SenderRoutingId

The ID of the document sender. This parameter is required.

TrueSenderId

The ID of the document sender. This is for document re-routing. This parameter is optional.

ReceiverRoutingId

The ID of the document receiver. This parameter is required.

TrueReceiverId

The ID of ultimate receiver of the document. This is for document re-routing. This parameter is optional.

DocumentType

Indicates whether the document is XML, binary, X12 or EDIFACT. This parameter is required.

DocumentSubType

The sub type of the message. This is used for EDI documents. This parameter is optional.

Path

The current path of the document. WebLogic Integration - Business Connect sets this value.

OriginalFileName

The original name of the file. This parameter is required.

CorrelationId

The assigned correlation ID of the document. This ID relates documents that are parts of conversations between partners in RosettaNet and ebXML exchanges. This parameter is optional.

RefToMessageId

The assigned reference message ID of the document. This ID relates the current document to another document. This parameter is optional.

SequenceId

Indicates duplicate document names by appending file names with _1, _2, _3 and so on. You only want to use this parameter when you have selected sequence duplicate file names on the Partner Profile window Preferences tab. WebLogic Integration - Business Connect sets this value.

DocumentId

The unique alphanumeric string WebLogic Integration - Business Connect assigns to the document. Appended to the value is the receiver's ID. WebLogic Integration - Business Connect sets this value.

ControlId

The control ID of an EDI document. Otherwise, the ID is XML or BINARY. WebLogic Integration - Business Connect sets this value.

Transport

The transport method used to receive the document. WebLogic Integration - Business Connect sets this value. The possible transports are:

Bundled HTTP
Bundled HTTPS
EMAIL
SMTP

ebXmlAction

Identifies an ebXML process within a service that processes the message. For example, NewOrder.

If you are using the file system ebXML protocol method, the user sets this for outbound documents. WebLogic Integration - Business Connect sets this value for inbound documents.

ebXmlService

Identifies an ebXML business process. For example, a purchase order.

If you are using the file system ebXML protocol method, the user sets this for outbound documents. WebLogic Integration - Business Connect sets this value for inbound documents.

PackagingType

If you are using the file system ebXML protocol method, set to ebXML for outbound documents. WebLogic Integration - Business Connect sets this value for inbound documents.

PackagingVersion

If you are using the file system ebXML protocol method, set to 1.0 or 2.0 for outbound documents, depending on whether your partner is compliant with 1.0 or 2.0. WebLogic Integration - Business Connect sets this value for inbound documents.


 

It would be helpful for you to understand the JMS event integration API to use this API.

Send Document

The following are the requirements for sending a document:

  1. Build a JMS BytesMessage. The contents of the BytesMessage should contain the raw document data and string parameters.
  2. Send the BytesMessage to the outbound queue.
  3. WebLogic Integration - Business Connect receives the BytesMessage from the queue. It then packages and send the document with the string parameters.

Receive Document

The following are the requirements for receiving a document:

  1. WebLogic Integration - Business Connect receives and unpackages a document
  2. WebLogic Integration - Business Connect creates a BytesMessage that contains the raw document content. The BytesMessage also includes the string properties.

Scenarios

The following graphics show high-level views of the JMS global document integration API.

Figure 16-9 Send Document with Global JMS Document Integration

Send Document with Global JMS Document Integration


 

Key to Figure 16-9

  1. Server registers a queue listener for outbound queue.
  2. Client publishes BytesMessage into outbound JMS queue.
  3. JMS server pushes BytesMessage into WebLogic Integration - Business Connect Server.
  4. Figure 16-10 Receive Document with Global JMS Document Integration

    Receive Document with Global JMS Document Integration


     

Key to Figure 16-10

  1. WebLogic Integration - Business Connect Server pushes BytesMessage into inbound JMS queue.
  2. Client can either register a JMS queue listener or periodically poll the inbound JMS queue.

Sample Code

The sample code for the global JMS document integration API is in api/samplecode/JMSClient.

For information about building and running the sample code, see the readme file in api/samplecode/JMSClient.

 


JMS Document Integration by Company

The JMS document integration by company API enables a JMS server to send documents to, and receive documents from, WebLogic Integration - Business Connect for a single active company.

JMS topics provide reliable messaging. As long as the JMS server is enabled, messages are stored until retrieval by a topic listener. There is one queue by company and document type and direction.

You need knowledge of JMS programming to retrieve events from a JMS topic.

WebLogic Integration - Business Connect writes the file to be sent to disk after retrieving it from the JMS server. The system then packages the document according to the usual document polling mechanisms. This is different than global JMS document integration, in which a documents is packaged immediately after WebLogic Integration - Business Connect retrieves it from the JMS server.

Document size is limited by memory constraints. JMS requires BytesMessages to be in memory when read from, or written to, the JMS server. There is no support for streaming. The result can be OutOfMemoryExceptions in the WebLogic Integration - Business Connect JVM when transferring large documents.

See Global Versus Company JMS Integration.

The following topics describe how to use the JMS document integration by company API:

Application Configuration

Use the JMS Options window for configuring document integration with a JMS queue. To access the window, select by document type as the integration method on the Company Profile window Integration tab, select an integration option for EDI, XML or binary documents and click Options. See Company Profile Integration Tab.

To use this tab your organization must have JMS experience and a working JMS messaging system.

In addition to completing this tab, you must add the names of the JAR or class files or both in the server.ini or server.bat file in Windows or your environment file in UNIX so the Server application can locate the JMS and JNDI provider. The server.ini and server.bat files are located in the installation directory bin subdirectory. In some cases, you need to add the name of only one JAR file (for example, swiftmq.jar), but you might have to include a series of jars or paths.

This window is for configuring JMS document integration for a single company. To configure JMS document integration for all companies, see Global JMS Document Integration.

Figure 16-11 JMS Options Window

JMS Options Window


 

Field Descriptions

The following describes the fields on the JMS Options window.

The fields are described once for inbound and outbound documents.

The Inbound Documents area is for configuring WebLogic Integration - Business Connect to place documents that have been received from partners and unpackaged on a back-end JMS queue.

The Outbound Documents area is for configuring WebLogic Integration - Business Connect to retrieve documents from a back-end JMS queue and then package and send the documents to partners.

Except for the user name and password, you can obtain the information needed to complete the tab from the JMS or JNDI provider's documentation. The information will vary depending on the provider. If you have questions, contact your JMS or JNDI provider.

JNDI

Complete the following fields for the Java naming and directory interface (JNDI).

URL

Type the network URL that will be used to obtain access to the JNDI service provider for your JMS service. Example: smqp://localhost:4001/timeout=10000

Factory

Type the name for the JNDI service provider class. Example: com.swiftmq.jndi.InitialContextFactoryImpl

User name

Type a user name for the JNDI provider. This value could be blank and is typically provided for in the JNDI URL. However, this will depend on the JNDI provider and how it is configured.

Password

Type a password for the JNDI provider. This value could be blank and is typically provided for in the JNDI URL. However, this will depend on the JNDI provider and how it is configured.

Confirm password

Type the password again.

JMS

Complete the following fields for the Java messaging service (JMS).

Queue connection factory

Type the connection factory as defined within the JMS provider. This value can be either in the form factoryname@routername or the JNDI public symbol for the QueueConnectionFactory. Examples: plainsocket@router1 or QueueConnectionFactory22. This would be dependent on your JMS provider and how it is configured.

Queue

Type the name of the queue in the form queuename@routername. Example: XMLQueue@router1

User name

Type a user name for the JMS provider. This can be the same as your JNDI user name. However, this will depend on how your JMS provider and how it is configured.

Password

Type a password for the JMS provider. This can be the same as your JNDI password. However, this will depend on how your JMS provider and how it is configured.

Confirm password

Type the password again.

Semantics

See Semantics for Global JMS Document Integration.

Scenarios

The following graphics show high-level views of the JMS document integration by company API.

Figure 16-12 Send Document with JMS Document Integration by Company

Send Document with JMS Document Integration by Company


 

Key to Figure 16-12

  1. Client publishes BytesMessage into outbound JMS queue.
  2. WebLogic Integration - Business Connect Server polls for JMS BytesMessage in the outbound queue.
  3. Server writes BytesMessage contents to the outbound directory for the appropriate company.
  4. Server packages and sends document based on polling intervals.
  5. Figure 16-13 Receive Document with JMS Document Integration by Company

    Receive Document with JMS Document Integration by Company


     

Key to Figure 16-13

  1. WebLogic Integration - Business Connect Server pushes BytesMessage into inbound JMS queue.
  2. Client can register a JMS queue listener or periodically poll the inbound JMS queue.

Sample Code

The sample code for the JMS document integration by company API is in api/samplecode/JMSIntegration.

The sample code models listening for events and document submission and retrieval.

For information about building and running the sample code, see the readme file in api/samplecode/JMSIntegration.

 

Skip navigation bar  Back to Top Previous Next