TracNav?

How to create a gnowsis service?

by Andreas Lauer.

OUTDATED: this was for the 0.8 version. It has to be updated.

How to create your own workspace service that is started by EPOSBackbone, our service framework.

Step 1: Create an appropriate eclipse project

• The name of the project will be the id of the new service
• Edit the project's java build path (Project->Properties->Java Build Path -> Projects-tab):
  • add dependencies to gnowsis

alternative step 1

• create a subfolder in SemanticDesktop/services

(folder name will be the id of the new service)

Step 2: create service directory structure

 <project folder/service folder>
   +-- WEB-INF
	     +-- src      <-- put your service sources here (change project source path accordingly)
	     +-- lib
	     +-- classes  <-- set your project's output folder to this directory

Step 3: Create service declaration file "service.xml"

The service declaration file contains the complete information the system needs to run the services.

• depending on the type of service you want to use
  • copy SemanticDesktop/default/service/xmlrpc_service.xml or SemanticDesktop/default/service/external_service.xml into your WEB-INF folder.
• Rename it to "service.xml".
• Edit service.xml
  • description
  • init-parameters
  • api declarations (fill in the names of the operationalizing classes, see step 4.)

see "service.xml" and step 4 for more information

Step 4: Write your service classes (for each API of the service)

• interface class (for XML-RPC services only)

This interface defines the methods the service offers. {{{public interface Api {

void hello( String sayIt );

} }}}

• implementation class (for XML-RPC services only)
  • This class must have a public constructor (with no arguments), not allowed: non-static inner classes
  • It has to implement the LifeCycle interface.
  • Initialization is done in a special method: init( ServiceContext ).
  • Cleanup in case of service shutdown can be put into the destroy()-method.
    • Use the AbstractServiceImplementation helper-class to create your implementation:

• Special issues:
  • Resource loading: use Class.getResource to access for example images.

    URL   url = getClass().getResource( FILENAME );
    Image img = toolkit.createImage( url );
    

• File access: use FileAccess.std() to resolve relative path names

String filename = FileAccess.std().getAbsoluteFilename( FILENAME );

• remote client class (optional). As with the implementation class the following requirements hold:
  • This class must have a public constructor (with no arguments), not allowed: non-static inner classes
  • It has to implement the interface class.
  • Initialization is done in a special method: init( ServiceContext ).
  • Cleanup in case of service shutdown can be put into the destroy()-method.

Use the helper-class AbstractServiceClient to create your XML-RPC-based remote client (AbstractServiceClient contains support for handling XML-RPC calls. The client is automatically connected to the implementation part of the service!!)

public static class RemoteClient 
	    		extends AbstractServiceClient 
	    		implements Api
	    {
	        public final static MethodSignature HELLO_SIG = new MethodSignature( Api.class, "hello" );
	        
	        public void init( ServiceContext c ) { /*extra initialization code goes here*/ }
	        public void destroy() { /*extra cleanup code goes here*/ }
	        
	        public void hello( String s )
	        {
	            MethodCall call = prepareCall( HELLO_SIG );
	            try
	            {
	                call.addParameter( s );
	                invoke( call );
	            }
	            catch( Exception e )
	            {
	                log( "hello(): ", e );
	            }
	        }
	    }

Step 5: Test your service (write a service client)

------------------------------------------------

• write a class with a main-method

		public class ServiceTesterTemplate
		{
		    public static void main( String[] args )
		        throws Exception
		    {
                        //request a backbone instance
                        Backbone backbone = StartClientBackbone.startup( args );
		        
		        //get the service api interface(s) and do some calls on it
		        DemoService.Api demoApi = (DemoService.Api)backbone.accessAPI( DemoService.SERVICE_ID, DemoService.Api.NAME );
		        demoApi.hello( "sayIt " );
		    }
		}

Step 6: Prepare workspace start

• running workspace in gnowsis context: configuration files are located in $user.home/.gnowsis_beta
  • (relative paths are resolved against this base directory, e.g. config/workspace.xml is resolved to $user.home/.gnowsis_beta/config/services.xml)
• running workpace standalone: configuration files are located in the eclipse project where the service tester is started.

Step 6: Configure workspace with configuration GUI

• not implemented yet.

Step 7: Run your workspace

• with gnowsis:
  • add project dependency of the gnowsis-server project to your new service project
  • start gnowiss
• standalone:
  • create a launch configuration for your service tester.
  • add the path to your workspace.xml as application parameter
  • make sure, the workspace config file is accessible
  • start tester (the workspace will be started, and the test code will be executed)