42 Sample Socket Transport Provider

This chapter describes how to build and run the sample socket transport provider. This sample and its source code are installed with Oracle Service Bus. The sample serves as an example implementation of a custom transport provider.

This chapter includes the following sections:

Section 42.1, "Sample Socket Transport Provider Design"
Section 42.2, "Sample Location and Directory Structure"
Section 42.3, "Building and Deploying the Sample"
Section 42.4, "Start and Test the Socket Server"
Section 42.5, "Configuring the Socket Transport Sample"
Section 42.6, "Testing the Socket Transport Provider"

42.1 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:

Section 42.1.1, "Concepts Illustrated by the Sample"
Section 42.1.2, "Basic Architecture of the Sample"
Section 42.1.3, "Configuration Properties"

42.1.1 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:

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 Oracle Service Bus pipeline.

42.1.2 Basic Architecture of the Sample

Figure 42-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 42-1 Sample Socket Transport Architecture

Description of "Figure 42-1 Sample Socket Transport Architecture "

42.1.3 Configuration Properties

Figure 42-2 illustrates the configuration properties for the transport endpoint. These properties are configured in the schema file: SocketTransport.xsd. See Section 42.2, "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 Section 39.3.4, "4. Define Transport-Specific Artifacts," for more information on these configuration properties.

Figure 42-2 SocketEndpointConfiguration Properties

Description of "Figure 42-2 SocketEndpointConfiguration Properties"

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

Figure 42-3 Request/Response Header and Metadata Configurations

Description of "Figure 42-3 Request/Response Header and Metadata Configurations "

42.2 Sample Location and Directory Structure

The sample socket transport provider is installed with Oracle Service Bus and is located in the following directory: OSB_ORACLE_HOME/samples/servicebus/sample-transport.

This section briefly describes some of the key folders in the sample project. You can use this directory structure as a model for developing your custom transport provider.

Table 42-1 lists and briefly describes key sample-transport directories.

Table 42-1 Key Sample Transport Provider Directories

Directory	Description
build	Created when you build the sample socket transport. Contains the built and packaged transport for use in Oracle Service Bus.
eclipse	Contains the plugin.xml file needed to add the sample transport to the Eclipse environment.
l10n	Contains Internationalization files: `SocketTransportMessages.xml` – Configuration file for text messages which are displayed on the Oracle Service Bus Administration Console. `SocketTransportTextMessages.xml`
META-INF	Contains application deployment descriptor files: `application.xml` – J2EE application descriptor file `weblogic-application.xml` – WebLogic application descriptor file
resources	`SocketConfig.xml` – Socket transport provider configuration that is used by the Transport SDK. Sample help files for the transport.
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:

build.properties – Properties file for Ant.
build.xml – An Ant build file with different targets for compile, build, stage, and deploy.

42.3 Building and Deploying the Sample

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

42.3.1 Setting Up the Environment

Follow these steps to set the environment for building the sample.

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

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

42.3.2 Building the Transport

To build the socket transport, do the following:

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

OSB_ORACLE_HOME/samples/servicebus/sample-transport
Execute the following command: ant build. This command compiles the source files in OSB_ORACLE_HOME/samples/servicebus/sample-transport/build.
After a successful build, execute the following command: ant stage. This command does the following:
- Copies sock_transport.ear sock_transport.jar to OSB_ORACLE_HOME/lib/transports.
- Creates OSB_ORACLE_HOME/eclipse/plugins com.bea.alsb.transports.socket_version to register the socket sample as a plug-in to Eclipse.

42.3.3 Deploying the Sample Transport Provider

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

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
```

42.4 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:

Section 42.4.1, "Start the Socket Server"
Section 42.4.2, "Test the Socket Transport"

42.4.1 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:

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)

42.4.2 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:

host-name – The host name of the Oracle 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 Oracle 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)

42.5 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:

Section 42.5.1, "Create a New Project"
Section 42.5.2, "Create a Business Service"
Section 42.5.3, "Create a Proxy Service"
Section 42.5.4, "Edit the Pipeline"

42.5.1 Create a New Project

To create a new project:

Start the Oracle Service Bus Administration Console.
Open the Project Explorer.
In the Change Center, click Edit.
In the Projects panel, enter SocketTest in the Enter New Project Name field.
Click Add Project. The new project appears in the project table.

42.5.2 Create a Business Service

Create a business service to talk to the server.

Click the SocketTest project name in the project table. The SocketTest panel appears.
From the Create Service menu, select Business Service. The General Configuration panel appears.
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 39-1.
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.

42.5.3 Create a Proxy Service

In this section, you create a proxy service.

From the Create Resource menu, select 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.

42.5.4 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.

To edit the pipeline:

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

Figure 42-4 Selecting the Message Flow Icon

Description of "Figure 42-4 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 42-5.

Figure 42-5 Editing the Message Flow

Description of "Figure 42-5 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 42-6.

Figure 42-6 Adding an Action

Description of "Figure 42-6 Adding an Action"
In the next panel, select <Service>.
In the Select Service window, select SocketBS from the list, and click Submit.
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.

42.6 Testing the Socket Transport Provider

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

Start the test server, as explained previously in Section 42.4.1, "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 42-7.

Figure 42-7 Starting the Test Console

Description of "Figure 42-7 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 42-8, a simple XML expression <x/> is entered in the text area.

Figure 42-8 Test Console

Description of "Figure 42-8 Test Console"
Click Execute. If the test is successful, information similar that shown in Figure 42-9 appears in the Test Console. In addition, the XML text input into the Test Console is echoed in the server console.

Figure 42-9 Successful Test

Description of "Figure 42-9 Successful Test"
Close the Test Console.