SampleApp: Your first IBM Spectrum Symphony Java service

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.

1. Build the sample client and service.

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

   1. Build the sample client and service on Windows:
      1. Compile with the .bat file by changing to the %SOAM_HOME%\version\samples\Java\SampleApp directory under IBM® Spectrum Symphony Developer Edition and running the .bat file:

         build.bat

      2. Compile with the Ant build file.
         Note: IBM Spectrum Symphony supports Ant 1.6.0 or higher for building Java™ samples in the IBM Spectrum Symphony Developer Edition package.
         Change to the %SOAM_HOME%\version\samples\Java\SampleApp directory and run the command:

         ant

      3. Compile in Eclipse.

         To compile in Eclipse, see Using Eclipse as your development environment.

   2. Build the sample client and service on Linux®:
      1. Change to the conf directory under the directory in which you installed IBM Spectrum Symphony Developer Edition.
      2. Set the environment:
         • (csh) source cshrc.soam
         • (bash) . profile.soam
      3. Compile with the Makefile or with the Ant build file:
         • To compile with the Makefile, change to the $SOAM_HOME/version/samples/Java/SampleApp directory and run the make command:

           make

         • To Compile with the Ant build file, change to the $SOAM_HOME/version/samples/Java/SampleApp directory and run the build command:

           ant

           Note: IBM Spectrum Symphony supports Ant 1.6.0 or higher for building Java samples in the IBM Spectrum Symphony Developer Edition package.
2. Package and deploy 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 %SOAM_HOME%\version\samples\Java\SampleApp directory:

3. Add the application.

   When you add an application through the IBM Spectrum Symphony Developer Edition cluster management console, 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 cluster management console, 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:

      • Windows: %SOAM_HOME%\version\samples\Java\SampleApp\SampleAppJava.xml
      • Linux: $SOAM_HOME/version/samples/Java/SampleApp/SampleAppJava.xml

      The Service Package location window displays.

   6. Browse to the created service package and select it, then, select Continue.
      • Windows: %SOAM_HOME%\version\samples\Java\SampleApp\SampleServiceJavaPackage.jar
      • Linux: $SOAM_HOME/version/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 cluster management console. Your new application is displayed as enabled.

4. Run the sample client and service:

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

   1. Run the sample client and service on Windows, run the client application from the command line:

      %SOAM_HOME%\version\samples\Java\SampleApp\RunSyncClient.bat

   2. Run the sample client and service on Linux.
      Run the client application:

      $SOAM_HOME/version/samples/Java/SampleApp/RunSyncClient.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.

5. Walk through the code.

   Review the sample service code to learn how you can create a service.

   1. Locate the code samples:

      Table 1. Code samples

      Operating system	Files	Location of code sample
      Windows	Client	%SOAM_HOME%\version\samples\Java\SampleApp\src\com\platform\symphony\samples\SampleApp\client\SyncClient.java
      	Input and output objects	%SOAM_HOME%\version\samples\Java\SampleApp\src\com\platform\symphony\samples\SampleApp\common\MyInput.java %SOAM_HOME%\version\samples\Java\SampleApp\src\com\platform\symphony\samples\SampleApp\common\MyOutput.java
      	Service code	%SOAM_HOME%\version\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%\version\samples\Java\SampleApp\SampleAppJava.xml
      	Output directory	%SOAM_HOME%\version\samples\Java\SampleApp\
      Linux	Client	$SOAM_HOME/version/samples/Java/SampleApp/src/com/platform/symphony/samples/SampleApp/client/SyncClient.java
      	Input and output objects	$SOAM_HOME/version/samples/Java/SampleApp/src/com/platform/symphony/samples/SampleApp/common/MyInput.java $SOAM_HOME/version/samples/Java/SampleApp/src/com/platform/symphony/samples/SampleApp/common/MyOutput.java
      	Service code	$SOAM_HOME/version/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/version/samples/Java/SampleApp/SampleAppJava.xml
      	Output directory	$SOAM_HOME/version/samples/Java/SampleApp/

   2. Understand what the sample does.

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

   3. Define a service container.
      For a service to be managed by IBM Spectrum 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
      ...
      

   4. Process the input.

      IBM Spectrum 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);
         }
      ...
      

   5. 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();
              }
      ...
      

   6. 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;
            }
      ...