Changes between Initial Version and Version 1 of DevelopingServices


Ignore:
Timestamp:
Aug 9, 2006, 3:07:40 PM (20 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