Changeset 13954 for trunk/gsdl3/docs

Timestamp:

2007-03-01T12:03:51+13:00 (17 years ago)

Author:

kjdon

Message:

added a little bit of stuff about creating new services

Location:

trunk/gsdl3/docs/manual

Files:

• manual.pdf (modified) ( previous)
• manual.tex (modified) (1 diff)

trunk/gsdl3/docs/manual/manual.tex

@@ -2023 +2023 @@
 [TODO: finish this section ]
 
-\subsection{Creating new services}\label{sec:new-services}
-
-*inherit from ServiceRack - abstract base class. this handles the main process method, determines the service name and request type. if request type is describe, and to is empty, it returns a list of services (short\_service\_info) which is initialized in the configure method. a describe request to a particular service results in getServiceDescription being called, which must be supplied by the subclass.
-other request types (process) get sent to processXXX methods, where XXX is the service name.
-
-* what methods are expected
-
-*service type responses expected
-
-*a browse type service must also implement servicenameMetadataRetrieve service.
-
-* should a metadata retrieval service advertise what metadata is available??
-
-standard service type vs new service type - standard needs some xml response syntax.
+\subsection{Creating and using new services}\label{sec:new-services}
+
+There are three parts to adding new services to \gsiii: defining the new service, specifying that it should be loaded, and using it. If you are talking to \gs\ using the SOAP interface, then the firsttwo  parts are all that need to be done. If you are using the Greenstone servlet interface, then you may need to do work for the third part, depending on what kind of new service it is.
+If you are adding a service of a type that is already present, for example, a new query service, then the query action can just use your new service as is (assuming it is set up in the same way as the standard query services).
+However, if it is a new type of service that the interface and actions don't know about, you willl need to add a new action or modify an existing one so that your service is actually used.
+
+\subsubsection{Creating the service}
+
+You will need to write a new Java class which inherits from \gst{org.greenstone.gsdl3.service.ServiceRack} (or a subclass of this). The class will need to implement at least the \gst{configure}, \gst{process<ServiceName>} and \gst{getServiceDescription} methods. There is a dummy class called \gst{MyNewServicesTemplate.java} in \gst{greenstone3/resources/java} which describes these methods and what needs to be done.
+
+\gst{ServiceRack.java} handles the main \gst{process} method. If the request type is 'describe', then it will send back a copy of short\_service\_info, which contains a list of services. If there request type is describe, but for a particular service, then it will call \gst{getServiceDescroption} for that service. For a format request, it will send any format element found in format\_info\_map for that service. For a processing request to a service, then the \gst{process<ServiceName>} method will be called.
+
+Once the class is written, it needs to be compiled up and either included in one of the existing jar files, or added in as a jar file to \gst{greenstone3/web/WEB-INF/lib} or a class file to \gst{greenstone3/web/WEB-INF/classes}.
+
+\subsubsection{Loading the service}
+
+To have the library load in your new service, it needs to be specified in a configuration file somewhere. For a collection service, add a new \gst{<serviceRack>} element to the collection's \gst{buildConfig.xml} file. This element should contain any information that the class needs to configure its service(s). For a site-wide service, add the \gst{<serviceRack>} element to the site's \gst{siteConfig.xml} file, either in the \gst{serviceRackList} or as part of a \gst{serviceCluster}.
+
+\subsubsection{Using the service}
+
+If you are using the SOAP web service, then you can send an XML request directly to the service. The 'address' of the request will be the service name if it is a site-wide service, cluster-name/service-name if it is site-wide but belonging to a cluster, or collection-name/service-name if it belongs to a collection. You will need to know the format of the XML request and response that the service expects and returns.
+
+If you want to access your new service through the current servlet interface that uses actions, then whether you need to do more work or not depends on whatkind of service you have implemented. If you have written a new query or browse service, for example, that has teh same request and response format as the existing services, then you don't need to do anything else. Your collection can just use the new query service straight away.
+If the service is of an existing type, but needs soemthing different in the request/response format, then you may need to modify an existing action to supply or use the new information.
+If the service is of a completely new type, then you will probably need a new action to talk to the service and display the results.
+
 
 \subsection{creating new actions/pages}\label{sec:new-pages}