Sample Socket Transport Provider

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

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.

Concepts Illustrated by the Sample

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

Implementing the set of Transport SDK APIs that are required to build a custom transport.
Performing transport endpoint validations, such as checking that no socket endpoint is listening on the configured address.
Implementing several UI configuration options, including socket properties and message patterns.
Implementing a one-way or synchronous request-response message pattern.
Using POJOs (Plain Old Java Objects) for metadata and headers of endpoint requests and responses.
Showing how streaming is used in the AquaLogic Service Bus pipeline.

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.

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.

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.

Sample Location and Directory Structure

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

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.

Table 6-1 Sample Transport Provider Directories
build	Directory which contains all the class files
config	Configuration files directory. `SocketConfig.xml` - Socket transport provider configuration that is used by the Transport SDK.
l10n	Contains Internationalization files: `SocketTransportMessages.xml` - Configuration file for text messages which are displayed on the Aqualogic Service Bus Console. `SocketTransportTextMessages.xml`
lib	Directory which contains the sample deployment unit `sock_transport.ear`
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

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

Building and Deploying the Sample

Setting Up the Environment

Building the Transport

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

BEA_HOME/weblogic92/samples/servicebus/sample-transport

where BEA_HOME is the directory in which you installed AquaLogic Service Bus.

Execute the following command: ant build-jar

This command compiles all the source files, creates sock_transport.ear, and puts it in the directory: BEA_HOME/weblogic92/servicebus/lib

Deploying the Sample Transport Provider

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

wls.hostname

wls.port

wls.username

wls.password

wls.server.name

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

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.

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.

port - The port number at which ServerSocket is listening, which is the port number in the business service.
message-file-location - (optional) The location of the message-file which will be sent as a response to the business service.
file-encoding - A system property that is the encoding of the file. (default = utf-8)
request-encoding - The encoding of the request that is sent by the socket business service. (default = utf-8)

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 AquaLogic Service Bus.

host-name - The host name of the AquaLogic Service Bus server.
port - The port number at which the proxy service is listening.
thread-ct - The number of clients that can send a message to AquaLogic Service Bus.
message-file-location - (optional ) The location of the message file that will be sent as a response to the business service.
file-encoding - An optional argument specifying the encoding of the file. (default = utf-8)
response-encoding - The encoding of the response received from the socket proxy service. (default = utf-8)

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 AquaLogic Service Bus to receive and process the message.

Create a New Project

Start the AquaLogic Service Bus Console.
Open the Project Explorer.
In the Change Center, click Edit.
In the Projects panel, enter SocketTest in the Enter New Project Name Field, as shown in Figure 6-5.

Figure 6-5 Adding a New Project

Adding a New Project

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

Create a Business Service

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

Figure 6-6 Creating a Business Service

Creating a Business Service

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

Figure 6-7 Choosing a Protocol

Choosing a Protocol

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

Create a Proxy Service

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

Figure 6-8 Creating a Proxy Service

Creating a Proxy Service

In the General Configuration panel, enter SocketProxy in the Service Name field.
Be sure that Any XML Service is selected in the Service Type list, and click Next.
From the Protocol menu, select socket.
In the Endpoint URI field, enter tcp://7032, and click Next.
In the next panel, accept the defaults and click Next.
After viewing the Summary panel, click Save.
In the Change Center, click Activate.
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.

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

Figure 6-9 Selecting the Message Flow Icon

Selecting the Message Flow Icon

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

Figure 6-10 Editing the Message Flow

Editing the Message Flow

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

Figure 6-11 Adding an Action

Adding an Action

In the next panel, select <Service>.
In the Select Service window, select SocketBS from the list, as shown in Figure 6-12, and click Submit.

Figure 6-12 Selecting the Service to Route To

Selecting the Service to Route To

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

Testing the Socket Transport Provider

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

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

Figure 6-13 Starting the Test Console

Starting the Test Console

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.

Figure 6-14 Test Console

Test Console

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.

Figure 6-15 Successful Test

Successful Test

Close the Test Console.

Transport SDK User Guide

Sample Socket Transport Provider