Transport SDK User Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Sample Socket Transport Provider

This chapter explains how to build and run the sample socket transport provider. This sample is installed along with Oracle Service Bus. The sample serves as an example implementation of a custom transport provider and the sample source code is available to you.

This chapter includes these topics:

 

Sample Socket Transport Provider Design

The primary purpose of the sample socket transport provider is to serve as an example transport provider implementation. This publicly available sample demonstrates the implementation and configuration details of the Transport SDK.

This section includes these topics:

Concepts Illustrated by the Sample

The sample transport is designed to send and receive streamed data to and from a configured TCP socket in Oracle Service Bus. The sample transport is intended to illustrate the following Transport SDK concepts:

Basic Architecture of the Sample

Figure 6-1 shows the basic architecture of the sample socket transport provider. Any client can connect to the server socket. Data is received at the server socket and passes through the pipeline. The response comes back through the outbound transport. The response is finally sent back to the inbound transport and back to the client.

Figure 6-1 Sample Socket Transport Architecture

Sample Socket Transport Architecture

Configuration Properties

Figure 6-2 illustrates the configuration properties for the transport endpoint. These properties are configured in the schema file: SocketTransport.xsd. See Sample Location and Directory Structure for information on the location of this file. This file allows you to extend the basic set of properties defined in the common schema provided with the SDK. Refer to the SocketTransport.xsd file for information on each of the properties.

Tip: See also 4. Define Transport-Specific Artifacts for more information on these configuration properties.
Figure 6-2 SocketEndpointConfiguration Properties

SocketEndpointConfiguration Properties

Also in the SocketTransport.xsd file are the request/response header and metadata properties, as illustrated in Figure 6-3. Refer to the SocketTransport.xsd file for more information on these properties.

Figure 6-3 Request/Response Header and Metadata Configurations

Request/Response Header and Metadata Configurations

 

Sample Location and Directory Structure

The sample socket transport provider is installed with Oracle Service Bus and is located in the following directory: 

ALSB_HOME/samples/servicebus/sample-transport

Figure 6-4 shows the directory structure for the sample socket transport provider. This section briefly describes the folders in the sample project. You can use this directory structure as a model for developing your custom transport provider.

Figure 6-4 Sample Transport Project Structure

Sample Transport Project Structure

Table 6-1 lists and briefly describes the sample-transport directories.

Table 6-1 Sample Transport Provider Directories
build
Created when you build the sample socket transport. Contains the built and packaged transport for use in Oracle Service Bus.
config
Configuration files directory.
SocketConfig.xml – Socket transport provider configuration that is used by the Transport SDK.
eclipse
Contains the plugin.xml file needed to add the sample transport to the Workshop for WebLogic environment.
help
 
l10n
Contains Internationalization files:
SocketTransportMessages.xml – Configuration file for text messages which are displayed on the Oracle Service Bus Console.
SocketTransportTextMessages.xml
META-INF
Contains application deployment descriptor files:
application.xml – J2EE application descriptor file
weblogic-application.xml – WebLogic application descriptor file
schemas
Contains the relevant schemas defined for this transport:
SocketTransport.xsd – Describes Socket Endpoint Request/Response Metadata/headers
src
Source tree of the sample transport
test
(not shown) Test files directory:
src – Source tree for test server and client
webapp
Contains the deployment descriptors required for the sample transport help Web application.

The following Ant build files are also located in the sample-transport directory:

 

Building and Deploying the Sample

This section explains how to build and deploy the sample transport provider.

Setting Up the Environment

  1. Create a new domain or use one of the preconfigured domains that are installed with Oracle Service Bus.
  2. Set the domain environment by running the following script:

DOMAIN_HOME/bin/setDomainEnv.cmd (setDomainEnv.sh on a UNIX system)

Building the Transport

To build the socket transport, do the following:

  1. In a command window, go to the sample home directory:

    2. ALSB_HOME/samples/servicebus/sample-transport

  2. Execute the following command: ant build-jar

This command compiles the source files and does the following:

Deploying the Sample Transport Provider

To deploy the sample transport provider on a server, do the following:

  1. Set the following variables in sample-transport/build.properties:

    2. wls.hostname

    wls.port

    wls.username

    wls.password

    wls.server.name

  2. Deploy the transport provider on the server by running the following command:

    3. ant deploy

 

Start and Test the Socket Server

The sample project includes a simple socket server and a client to test the server. You can use this socket server to test the socket transport provider.

This section includes the following topics:

Start the Socket Server

Run the following command to start the external service, which is a server socket that listens on a specified port and receives/sends the messages. 

java -classpath .\test\build\test-client.jar -Dfile-encoding=utf-8 -Drequest-encoding=utf-8 com.bea.alsb.transports.sample.test.TestServer <port> <message-file-location>

where:

Test the Socket Transport

Run the following command to start the service, which is a client to a configured socket proxy-service. It sends a message and receives the response from Oracle Service Bus. 

java -classpath .\test\build\test-client.jar -Dfile-encoding=utf-8 -Dresponse-encoding=utf-8 com.bea.alsb.transports.sample.test.TestClient <host-name> <port> <thread-ct> <message-file-location>

where:

 

Configuring the Socket Transport Sample

The sample consists of a test server and a test client. The client sends a message to the server. You configure Oracle Service Bus to receive and process the message.

This section describes these tasks:

Create a New Project

  1. Start the Oracle Service Bus Console.
  2. Open the Project Explorer.
  3. In the Change Center, click Edit.
  4. In the Projects panel, enter SocketTest in the Enter New Project Name Field, as shown in Figure 6-5.
    5. Figure 6-5 Adding a New Project


    Adding a New Project

  5. Click Add Project. The new project appears in the project table.

Create a Business Service

Create a business service to talk to the server.

  1. Click the SocketTest project name in the project table. The SocketTest panel appears.
  2. From the Create Service dropdown menu, select Business Service, as shown in Figure 6-6. The General Configuration panel appears.
    3. Figure 6-6 Creating a Business Service


    Creating a Business Service

  3. In the General Configuration panel, enter SocketBS in the Service Name field.
  4. Be sure Any XML Service is selected in the Service Type list, and click Next.
  5. From the Protocol menu, select socket, as shown in Figure 6-7.
    6. Figure 6-7 Choosing a Protocol


    Choosing a Protocol

  6. In the Endpoint URI field, enter: tcp://localhost:7031, and click Add.
  7. Click Next.
  8. In the next panel, accept the defaults by clicking Next.
  9. After viewing the Summary panel, click Save.
  10. In the Change Center, click Activate.

Create a Proxy Service

In this section, you create a proxy service.

  1. From the Create Resource menu, select Proxy Service, as shown in Figure 6-8.
    2. Figure 6-8 Creating a Proxy Service


    Creating a Proxy Service

  2. In the General Configuration panel, enter SocketProxy in the Service Name field.
  3. Be sure that Any XML Service is selected in the Service Type list, and click Next.
  4. From the Protocol menu, select socket.
  5. In the Endpoint URI field, enter tcp://7032, and click Next.
  6. In the next panel, accept the defaults and click Next.
  7. After viewing the Summary panel, click Save.
  8. In the Change Center, click Activate.
  9. Click Submit.

Edit the Pipeline

Now that the business and proxy services are defined, you can edit the pipeline to route incoming messages to the business service.

  1. In the Change Center, click Create.
  2. In the Resources section, click the View Message Flow icon in the SocketProxy row, as shown in Figure 6-9.
    3. Figure 6-9 Selecting the Message Flow Icon


    Selecting the Message Flow Icon

  3. In the Edit Message Flow window, click the SocketProxy icon and select Add Route from the menu, as shown in Figure 6-10.
    4. Figure 6-10 Editing the Message Flow


    Editing the Message Flow

  4. Click the RouteNode1 icon and select Edit Route from the menu.
  5. In the Edit Stage Configuration window, click Add an Action.
  6. In the Route Node window, click Add an Action and select Communication > Routing from the menu, as shown in Figure 6-11.
    7. Figure 6-11 Adding an Action


    Adding an Action

  7. In the next panel, select <Service>.
  8. In the Select Service window, select SocketBS from the list, as shown in Figure 6-12, and click Submit.
    9. Figure 6-12 Selecting the Service to Route To


    Selecting the Service to Route To

  9. In the Edit Stage Configuration window, click Save.
  10. Optionally, click the RouteNode1 icon and change the name to SocketBS.
  11. Click Save.
  12. In the Change Center, click Activate, and then click Submit.

 

Testing the Socket Transport Provider

In this section you test the transport provider using Oracle Service Bus Console.

  1. Start the test server, as explained previously in Start the Socket Server.
  2. In the Project Explorer, click SocketTest.
  3. In the SocketProxy row of the Resources table, click the Launch Test Console icon, as shown in Figure 6-13.
    4. Figure 6-13 Starting the Test Console


    Starting the Test Console

  4. In the Test Console, enter any valid XML stanza in the text area, or use the Browse button to select a valid XML file on the local system. For example, in Figure 6-14, a simple XML expression <x/> is entered in the text area.
    5. Figure 6-14 Test Console


    Test Console

  5. Click Execute. If the test is successful, information similar that shown in Figure 6-15 appears in the Test Console. In addition, the XML text input into the Test Console is echoed in the server console.
    6. Figure 6-15 Successful Test


    Successful Test

  6. Close the Test Console.

  Back to Top       Previous  Next