SampleApp: Your first Symphony Java service

Goal

This tutorial walks you through the sample service code, then guides you through the process of building and running a service.

You learn the minimum amount of code that you need to create a service.

At a glance

  1. Build the sample client and service

  2. Package and deploy the sample service

  3. Run the sample client and service

  4. 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.1\samples\Java\SampleApp 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.1\samples\Java\SampleApp 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.1/samples/Java/SampleApp directory and run the make command:
      make
    • Compile with the Ant build file:

      Change to the $SOAM_HOME/4.1/samples/Java/SampleApp 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:
%SOAM_HOME%\4.1\samples\Java\SampleApp

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%\4.1\samples\Java\SampleApp\SampleAppJava.xml

      • Linux—$SOAM_HOME/4.1/samples/Java/SampleApp/SampleAppJava.xml

    The Service Package location window displays.

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

      • Windows—%SOAM_HOME%\4.1\samples\Java\SampleApp\SampleServiceJavaPackage.jar

      • Linux—$SOAM_HOME/4.1/samples/Java/SampleApp/SampleServiceJavaPackage.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%\4.1\samples\Java\SampleApp\RunSyncClient.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 that a client application uses is specified in the application profile.

Run the client application:

$SOAM_HOME/4.1/samples/Java/SampleApp/RunSyncClient.sh

You should see output on the command line 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 service code to learn how you can create a service.

Locate the code samples


Operating System

Files

Location of Code Sample

Windows

Client

%SOAM_HOME%\4.1\samples\Java\SampleApp\src\com\platform\symphony\samples\SampleApp\client\SyncClient.java

Input and output objects

%SOAM_HOME%\4.1\samples\Java\SampleApp\src\com\platform\symphony\samples\SampleApp\common\MyInput.java

%SOAM_HOME%\4.1\samples\Java\SampleApp\src\com\platform\symphony\samples\SampleApp\common\MyOutput.java

Service code

%SOAM_HOME%\4.1\samples\Java\SampleApp\src\com\platform\symphony\samples\SampleApp\service\MyService.java

Application profile

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

%SOAM_HOME%\4.1\samples\Java\SampleApp\SampleAppJava.xml

Output directory

%SOAM_HOME%\4.1\samples\Java\SampleApp\

Linux

Client

$SOAM_HOME/4.1/samples/Java/SampleApp/src/com/platform/symphony/samples/SampleApp/client/SyncClient.java

Input and output objects

$SOAM_HOME/4.1/samples/Java/SampleApp/src/com/platform/symphony/samples/SampleApp/common/MyInput.java

$SOAM_HOME/4.1/samples/Java/SampleApp/src/com/platform/symphony/samples/SampleApp/common/MyOutput.java

Service code

$SOAM_HOME/4.1/samples/Java/SampleApp/src/com/platform/symphony/samples/SampleApp/service/MyService.java

Application profile

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

$SOAM_HOME/4.1/samples/Java/SampleApp/SampleAppJava.xml

Output directory

$SOAM_HOME/4.1/samples/Java/SampleApp/


What the sample does

The service takes input data sent by the client and returns the input data with the additional "Hello Client !!".

Define a service container

For a service to be managed by Symphony, it needs to be in a container object. This is the service container.

In MyService.java, MyService inherits (extends) the ServiceContainer class. Once you inherit from the ServiceContainer class, implement handlers so that the service can function properly.

...
public class MyService extends ServiceContainer
...

Process the input

Symphony calls onInvoke() on the service container once per task. This is where the calculation is performed.

To gain access to the data set from the client, you call the getTaskInput() method on the taskContext. The middleware is responsible for placing the input into the taskContext object.

The task context contains all information and functionality that is available to the service during an onInvoke() call in relation to the task that is being processed.

Important:

Services are virtualized. As a result, a service should not read from stdin or write to stdout. Services can, however, read from and write to files that are accessible to all compute hosts.

...
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 !!");
        myOutput.setString(sb.toString());
        // set our output message
        taskContext.setTaskOutput(myOutput);
         }
...

Run the container

Create an instance of the service container and run it within the main function.

...
public static void main(String args[])
    {
        // Return value of our service program
        int retVal = 0;
        try
        {
            // Create the service container and run it
            MyService myContainer = new MyService();
            myContainer.run();
        }
...

Catch exceptions

Catch exceptions in case the container fails to start running.

...
catch (Exception ex)
        {
            // Report exception
            System.out.println("Exception caught:");
            System.out.println(ex.toString());
            retVal = -1;
                      }
...