Changeset 13954

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

added a little bit of stuff about creating new services

2 edited


  • trunk/gsdl3/docs/manual/manual.tex

    r13920 r13954  
    20232023[TODO: finish this section ]
    2025 \subsection{Creating new services}\label{sec:new-services}
    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.
    2030 * what methods are expected
    2032 *service type responses expected
    2034 *a browse type service must also implement servicenameMetadataRetrieve service.
    2036 * should a metadata retrieval service advertise what metadata is available??
    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}
     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.
     2031\subsubsection{Creating the service}
     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{} in \gst{greenstone3/resources/java} which describes these methods and what needs to be done.
     2035\gst{} 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.
     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}.
     2039\subsubsection{Loading the service}
     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}.
     2043\subsubsection{Using the service}
     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.
     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.
    20402052\subsection{creating new actions/pages}\label{sec:new-pages}
Note: See TracChangeset for help on using the changeset viewer.