Changeset 13954


Ignore:
Timestamp:
2007-03-01T12:03:51+13:00 (15 years ago)
Author:
kjdon
Message:

added a little bit of stuff about creating new services

Location:
trunk/gsdl3/docs/manual
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/gsdl3/docs/manual/manual.tex

    r13920 r13954  
    20232023[TODO: finish this section ]
    20242024
    2025 \subsection{Creating new services}\label{sec:new-services}
    2026 
    2027 *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.
    2028 other request types (process) get sent to processXXX methods, where XXX is the service name.
    2029 
    2030 * what methods are expected
    2031 
    2032 *service type responses expected
    2033 
    2034 *a browse type service must also implement servicenameMetadataRetrieve service.
    2035 
    2036 * should a metadata retrieval service advertise what metadata is available??
    2037 
    2038 standard service type vs new service type - standard needs some xml response syntax.
     2025\subsection{Creating and using new services}\label{sec:new-services}
     2026
     2027There 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.
     2028If 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).
     2029However, 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.
     2030
     2031\subsubsection{Creating the service}
     2032
     2033You 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.
     2034
     2035\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.
     2036
     2037Once 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}.
     2038
     2039\subsubsection{Loading the service}
     2040
     2041To 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}.
     2042
     2043\subsubsection{Using the service}
     2044
     2045If 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.
     2046
     2047If 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.
     2048If 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.
     2049If 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.
     2050
    20392051
    20402052\subsection{creating new actions/pages}\label{sec:new-pages}
Note: See TracChangeset for help on using the changeset viewer.