Changes between Initial Version and Version 1 of DevelopingServices


Ignore:
Timestamp:
08/09/06 15:07:40 (15 years ago)
Author:
sauermann
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DevelopingServices

    v1 v1  
     1[[TracNav]] 
     2[[PageOutline]] 
     3 
     4= How to create a gnowsis service? = 
     5 
     6by Andreas Lauer. 
     7 
     8OUTDATED: this was for the 0.8 version. It has to be updated. 
     9 
     10How to create your own workspace service that is started by EPOSBackbone, our service framework. 
     11 
     12== Step 1: Create an appropriate eclipse project == 
     13 * The name of the project will be the id of the new service 
     14 * Edit the project's java build path (Project->Properties->Java Build Path ->  Projects-tab): 
     15   * add dependencies to {{{gnowsis}}} 
     16         
     17== alternative step 1 == 
     18 * create a subfolder in SemanticDesktop/services  
     19        (folder name will be the id of the new service) 
     20         
     21== Step 2: create service directory structure == 
     22{{{ 
     23 <project folder/service folder> 
     24   +-- WEB-INF 
     25             +-- src      <-- put your service sources here (change project source path accordingly) 
     26             +-- lib 
     27             +-- classes  <-- set your project's output folder to this directory 
     28}}} 
     29 
     30== Step 3: Create service declaration file "service.xml" == 
     31 The service declaration file contains the complete information the  
     32 system needs to run the services. 
     33   
     34 * depending on the type of service you want to use  
     35   * copy  SemanticDesktop/default/service/xmlrpc_service.xml  or    SemanticDesktop/default/service/external_service.xml into your WEB-INF folder. 
     36 * Rename it to "service.xml".     
     37 * Edit service.xml 
     38  * description 
     39  * init-parameters 
     40  * api declarations (fill in the names of the operationalizing classes, see step 4.) 
     41                 
     42see "service.xml" and step 4 for more information 
     43 
     44 
     45== Step 4: Write your service classes (for each API of the service) == 
     46 
     47 * interface class (for XML-RPC services only) 
     48  
     49This interface defines the methods the service offers.  
     50         
     51{{{public interface Api 
     52{ 
     53 void hello( String sayIt ); 
     54} 
     55}}} 
     56         
     57 * implementation class (for XML-RPC services only) 
     58   * This class must have a public constructor (with no arguments), not allowed: non-static inner classes 
     59   * It has to implement the LifeCycle interface.  
     60   * Initialization is done in a special method: init( ServiceContext ). 
     61   * Cleanup in case of service shutdown can be put into the destroy()-method. 
     62     * Use the AbstractServiceImplementation helper-class to create your implementation: 
     63         
     64 * Special issues: 
     65  * Resource loading: use Class.getResource to access for example images. 
     66{{{  
     67URL   url = getClass().getResource( FILENAME ); 
     68Image img = toolkit.createImage( url ); 
     69}}}    
     70 * File access: use FileAccess.std() to resolve relative path names 
     71{{{String filename = FileAccess.std().getAbsoluteFilename( FILENAME );}}} 
     72 * remote client class (optional). As with the implementation class the following requirements hold:  
     73   * This class must have a public constructor (with no arguments), not allowed: non-static inner classes 
     74   * It has to implement the interface class.  
     75   * Initialization is done in a special method: init( ServiceContext ). 
     76   * Cleanup in case of service shutdown can be put into the destroy()-method. 
     77 
     78Use the helper-class AbstractServiceClient to create your XML-RPC-based remote client 
     79(AbstractServiceClient contains support for handling XML-RPC calls.  
     80The client is automatically connected to the implementation part of the service!!) 
     81{{{      
     82public static class RemoteClient  
     83                        extends AbstractServiceClient  
     84                        implements Api 
     85            { 
     86                public final static MethodSignature HELLO_SIG = new MethodSignature( Api.class, "hello" ); 
     87                 
     88                public void init( ServiceContext c ) { /*extra initialization code goes here*/ } 
     89                public void destroy() { /*extra cleanup code goes here*/ } 
     90                 
     91                public void hello( String s ) 
     92                { 
     93                    MethodCall call = prepareCall( HELLO_SIG ); 
     94                    try 
     95                    { 
     96                        call.addParameter( s ); 
     97                        invoke( call ); 
     98                    } 
     99                    catch( Exception e ) 
     100                    { 
     101                        log( "hello(): ", e ); 
     102                    } 
     103                } 
     104            } 
     105 }}} 
     106         
     107         
     108== Step 5: Test your service (write a service client) == 
     109 ------------------------------------------------ 
     110  
     111 * write a class with a main-method 
     112   
     113{{{ 
     114                public class ServiceTesterTemplate 
     115                { 
     116                    public static void main( String[] args ) 
     117                        throws Exception 
     118                    { 
     119                        //request a backbone instance 
     120                        Backbone backbone = StartClientBackbone.startup( args ); 
     121                         
     122                        //get the service api interface(s) and do some calls on it 
     123                        DemoService.Api demoApi = (DemoService.Api)backbone.accessAPI( DemoService.SERVICE_ID, DemoService.Api.NAME ); 
     124                        demoApi.hello( "sayIt " ); 
     125                    } 
     126                } 
     127}}} 
     128 
     129== Step 6: Prepare workspace start == 
     130 * running workspace in gnowsis context: configuration files are located in $user.home/.gnowsis_beta 
     131  * (relative paths are resolved against this base directory, e.g. config/workspace.xml is resolved to $user.home/.gnowsis_beta/config/services.xml) 
     132 * running workpace standalone: configuration files are located in the eclipse project where the service tester is started. 
     133  
     134== Step 6: Configure workspace with configuration GUI == 
     135 * not implemented yet. 
     136  
     137  
     138== Step 7: Run your workspace == 
     139 * with gnowsis:  
     140  * add project dependency of the gnowsis-server project to your new service project 
     141  * start gnowiss 
     142 * standalone: 
     143  * create a launch configuration for your service tester. 
     144  * add the path to your workspace.xml as application parameter 
     145  * make sure, the workspace config file is accessible 
     146  * start tester  (the workspace will be started, and the test code will be executed) 
     147