wiki:DevelopingServices

Version 1 (modified by sauermann, 18 years ago) (diff)

--

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)