SharingData: Developing a Java client and service to share data among tasks

Goal

This tutorial walks you through how to develop a client application and service to share data among all tasks in a session. The data is shared by all invocations of tasks within the same session.

You learn how to use different data objects for input, output, and common data.

At a glance

  1. Build the sample client and service

  2. Package the sample service

  3. Add the application

  4. Run the sample client and service

  5. Walk through the code

Build the sample client and service

On Windows

Compile with the .bat file

You can build client application and service samples at the same time.

Change to the %SOAM_HOME%\4.0\samples\Java\SharingData directory and run the .bat file:
build.bat

Compile with the Ant build file

You can build client application and service samples at the same time.

Change to the %SOAM_HOME%\4.0\samples\Java\SharingData directory and run the command:
ant

Compile in Eclipse

To compile in Eclipse, see "Symphony plug-in for Eclipse" in the Application Development Guide.

On Linux

You can build client application and service samples at the same time.

  1. Change to the conf directory under the directory in which you installed Symphony DE.
  2. Set the environment:
    • For csh, enter

      source cshrc.soam
    • For bash, enter

      . profile.soam
  3. Compile with the Makefile or with the Ant build file.
    • Compile with the Makefile:

      Change to the $SOAM_HOME/4.0/samples/Java/SharingData directory and run the make command:
      make
    • Compile with the Ant build file:

      Change to the $SOAM_HOME/4.0/samples/Java/SharingData directory and run the build command:
      ant

Package the sample service

You must package the files required by your service to create a service package. When you built the sample, the service package was automatically created for you.

Your service package SampleServiceJavaPackage.jar is in the following directory:
cd %SOAM_HOME%\5.0\samples\Java\SharingData

Add the application

When you add an application through the DE PMC, you must use the Add Application wizard. This wizard defines a consumer location to associate with your application, deploys your service package, and registers your application. After completing the steps with the wizard, your application should be ready to use.

  1. In the DE PMC, click Symphony Workload > Configure Applications.

    The Applications page displays.

  2. Select Global Actions > Add/Remove Applications.

    The Add/Remove Application page displays.

  3. Select Add an application, then click Continue.

    The Adding an Application page displays.

  4. Select Use existing profile and add application wizard. Click Browse and navigate to your application profile.
  5. Select your application profile xml file, then click Continue

    For SampleApp, you can find your profile in the following location:

    • Java

      • Windows—%SOAM_HOME%\5.0\samples\Java\SharingData\SharingDataJava.xml

      • Linux—$SOAM_HOME/5.0/samples/Java/SharingData/SharingDataJava.xml

    The Service Package location window displays.

  6. Browse to the created service package and select it, then, select Continue.
    • Java

      • Windows—%SOAM_HOME%\5.0\samples\Java\SharingData\SharingDataServiceJavaPackage.jar

      • Linux—$SOAM_HOME/5.0/samples/Java/SharingData/SharingDataServiceJavaPackage.zip

    The Confirmation window displays.

  7. Review your selections, then click Confirm.

    The window displays indicating progress. Your application is ready to use.

  8. Click Close.

    The window closes and you are now back in the Platform Management Console. Your new application is displayed as enabled.

Run the sample client and service

On Windows

To run the service, you run the client application. The service that a client application uses is specified in the application profile.

Run the client application:
  • From the command-line:

%SOAM_HOME%\5.0\samples\Java\SharingData\RunSharingDataClient.bat

You should see output as work is submitted to the system.

The client starts and the system starts the corresponding service. The client displays messages indicating that it is running.

On Linux

To run the service, you run the client application. The service a client application uses is specified in the application profile.

Run the client application:

$SOAM_HOME/5.0/samples/Java/SharingData/RunSharingDataClient.sh

You should see output as work is submitted to the system.

The client starts and the system starts the corresponding service. The client displays messages indicating that it is running.

Walk through the code

Review the sample code to learn how you can create a client and service that uses data.

Locate the code samples


Operating System

Files

Location of Code Sample

Windows

Client

%SOAM_HOME%\5.0\samples\Java\SharingData\src\com\platform\symphony\samples\SharingData\client\SharingDataClient.java

Input, output, and data objects

%SOAM_HOME%\5.0\samples\Java\SharingData\src\com\platform\symphony\samples\SharingData\common\MyInput.java

%SOAM_HOME%\5.0\samples\Java\SharingData\src\com\platform\symphony\samples\SharingData\common\MyOutput.java

%SOAM_HOME%\5.0\samples\Java\SharingData\src\com\platform\symphony\samples\SharingData\common\MyCommonData.java

Service

%SOAM_HOME%\5.0\samples\Java\SharingData\src\com\platform\symphony\samples\SharingData\service\SharingDataService.java

Application profile

The service required to compute the input data along with additional application parameters are defined in the application profile:

%SOAM_HOME%\5.0\samples\Java\SharingData\sharingDataJava.xml

Output directory

%SOAM_HOME%\5.0\samples\Java\SharingData

Linux

Client

$SOAM_HOME/5.0/samples/Java/SharingData/src/com/platform/symphony/samples/SharingData/client/SharingDataClient.java

Input, output, and data objects

$SOAM_HOME/5.0/samples/Java/SharingData/src/com/platform/symphony/samples/SharingData/common/MyInput.java

$SOAM_HOME/5.0/samples/Java/SharingData/src/com/platform/symphony/samples/SharingData/common/MyOutput.java

$SOAM_HOME/5.0/samples/Java/SharingData/src/com/platform/symphony/samples/SharingData/common/MyCommonData.java

Service

$SOAM_HOME/5.0/samples/Java/SharingData/src/com/platform/symphony/samples/SharingData/service/SharingDataService.java

Application profile

The service required to compute the input data along with additional application parameters are defined in the application profile:

$SOAM_HOME/5.0/samples/Java/SharingData/sharingDataJava.xml

Output directory

$SOAM_HOME/5.0/samples/Java/SharingData


Prerequisites

  • Ensure you have installed and started Symphony Developer Edition.

  • You should also have completed the following tutorials:

    • Your First Synchronous Symphony Java Client

    • Your First Symphony Java Service

What the sample does

The client creates a session with common data, sends 10 input messages with "Hello Grid!!" through Symphony to the service and retrieves the output synchronously.

The service accesses the common data in onSessionEnter() and stores it in the service container to be accessed during each task invocation. The service then takes input data sent by the client and returns the input data along with "Hello Client !!".

When to use common data

Use common data when the same data is shared among all tasks in a session. You only need to store the data once, and all tasks in a session can access it.

Common data is useful for passing data from a client to a service. The service loads the data when the session is created.

Symphony attempts to use the same service instance for all tasks in a session. A service instance is made available to other sessions only when session workload completes, a session is closed or aborted, or when another session of higher priority is assigned the service instance.

Prepare common data in your client

Declare and implement the Message object

In this tutorial, different classes represent input and output. In addition, we are using an additional class to represent common data.

Use the common data object when creating a session

As in the synchronous client tutorial, initialize the client and connect to the application. Then, create your session to group tasks.

When creating a session, use the common data object to pass data from the client application to the service.

In SharingDataClient.java, we create a session and pass in the session attributes including the common data object.

...
// Set up our common data to be shared by all task invocations within this session
                MyCommonData commonData = new MyCommonData("Common Data To Be Shared");
                // Set up session attributes
                   SessionCreationAttributes attributes = new SessionCreationAttributes();
                attributes.setSessionName("mySession");
                attributes.setSessionType("ShortRunningTasks");
                attributes.setSessionFlags(Session.SYNC);
                attributes.setCommonData(commonData);
                                // Create a synchronous session
                Session session = null;
                try
                {
                    session = connection.createSession(attributes);
...

Continue with your client as usual

Now you can proceed the same way as in the synchronous client tutorial:

  • Send input data to be processed

  • Retrieve output

  • Close the session

  • Close the connection

  • Catch exceptions

  • Uninitialize

Access common data in your service

Define a service container and get data from the session

As in the basic service tutorial, first define a service container. Then retrieve the common data from the session sent by the client by implementing onSessionEnter() before your invoke call.

onSessionEnter() is called once for the duration of the session. The corresponding pair is onSessionLeave().

In SharingDataService.java, we inherited from the ServiceContainer class, and implemented onSessionEnter() to get common data and store it for later use with the session context.

...
public class SharingDataService extends ServiceContainer
{
    SharingDataService()
    {
        super();
    }
    /**
     * The middleware triggers the invocation of this handler to bind the Service 
     * Instance to its owning session when common data is provided by the Client.
     * 
     * If any common data is available for the associated session, it
     * should be accessed in the developer's implementation of this method.
     * Default implementation of this handler does nothing.
     */
    public void onSessionEnter(SessionContext sessionContext) throws SoamException
    {
        // get the current session ID (if needed)
        m_currentSID = sessionContext.getSessionId();
        
        // populate our common data object
        m_commonData = (MyCommonData)sessionContext.getCommonData();
    }
...

Process the input

In this example, we use the common data in our invoke call by formatting the output string. We then set our output message as usual to send common data back with each of the replies.

...
public void onInvoke (TaskContext taskContext) throws SoamException
    {
        // We simply echo the data back to the client
        MyOutput myOutput = new MyOutput();
        // estimate and set our runtime
        Date date = new Date();
        myOutput.setRunTime(date.toString());
        // get the input that was sent from the client
        MyInput myInput = (MyInput)taskContext.getTaskInput();
        // echo the ID
        myOutput.setId(myInput.getId());
        // setup a reply to the client
        StringBuffer sb = new StringBuffer();
                sb.append("Client sent : ");
        sb.append(myInput.getString());
        sb.append("\nSymphony replied : Hello Client !! with common data (\"");
        sb.append(m_commonData.getString());
        sb.append("\") for session(");
        sb.append(m_currentSID);
        sb.append(")");
        myOutput.setString(sb.toString());
        // set our output message
        taskContext.setTaskOutput(myOutput);
    }
...

Perform any data cleanup

After processing the input, use the onSessionLeave() call to free the data for the session. onSessionLeave() is called once for every session that is created. In this example, we do not perform any operations in onSessionLeave().

...
public void onSessionLeave() throws SoamException
    { 
        // We get a chance to do any cleanup for anything we may have done 
        // in the onSessionEnter( ) method
    }
...

Run the container and catch exceptions

As with the basic service, run the container in the service main and catch exceptions.

...
 public static void main(String args[])
    {
        // Return value of our service program
        int retVal = 0;
        try
        {
            // Create the container and run it
            SharingDataService myContainer = new SharingDataService();
            myContainer.run();
        }
        catch (Exception ex)
        {
            // Report exception
            System.out.println("Exception caught:");
            System.out.println(ex.toString());
            retVal = -1;
        }
        // NOTE: Although our service program will return an overall 
        // failure or success code it will always be ignored in the 
        // current revision of the middleware. 
        // The value being returned here is for consistency.
        System.exit(retVal);
    } 
...