[[TracNav]]
[[PageOutline]]

= 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)