Changes between Initial Version and Version 1 of DevelopingServices

Timestamp:

08/09/06 15:07:40 (18 years ago)

Author:

sauermann

Comment:

--

DevelopingServices

@@ +1 @@
+[[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)
+