/* *Registry.java */ package org.biomoby.registry.Central; /** * An interface that outlines the methods needed to implement a Moby Registry. * You may optionally implement a method DUMP that outputs the contents * of the registries and registerServiceWSDL that registers a service * based on a wsdl document. To fully implement a Mobycentral registry, the * interface {@link org.biomoby.registry.Central Central} must also be * implemented. * @author Eddie * created Dec 1, 2005 */ public interface Registry { /** * Register a new object class. This is useful if you want to add to MOBY's * object ontology, by creating a new data type. * * @param registrationObject * an XML string with the following structure: * * 
	 *               <registerObjectClass>
	 *                   <objectType>NewObjectType</objectType>
	 *                   <Description><![CDATA[
	 *                           human readable description
	 *                           of data type]]>
	 *                   </Description>
	 *                   <Relationship relationshipType="RelationshipOntologyTerm">
	 *                      <objectType articleName="SomeName">ExistingObjectType</objectType>
	 *                      ...
	 *                   </Relationship>
	 *                   ...
	 *                   <authURI>Your.URI.here</authURI>
	 *                   <contactEmail>You@your.address.com</contactEmail>
	 *               </registerObjectClass>
	 *               
	 *       o Class names are unique within the ontology, and there is only one 
	 *         canonical MOBY Class ontology.
	 *       o You can envision this as simply registering a new node into the
	 *         class ontology graph, and creating the primary connections from
	 *         that node.
	 *       o MOBY, by default, supports three types of class relationships: ISA,
	 *         HAS, and HASA (these are the relationship ontology terms)
	 *       
	 *           * foo ISA bar is a straight inheritence, where all attributes of
	 *             bar are guaranteed to be present in foo.
	 *           * foo HAS bar is a container type, where bar is an object inside
	 *             of foo in one or more copies.
	 *           * foo HASA bar is a container type, where bar is an object inside
	 *             of foo in one copy only
	 *       
	 *       o Notice that, in a HAS and HASA relationships, it is necessary to
	 *         indicate an article name for each contained object type. Thus,
	 *         for example, you could have a sequence object that contained a
	 *         String object with name "nucleotideSequence" and an
	 *         Integer object with the name "sequenceLength".
	 *
* * @return a string of XML, for example: * * 
	 *                   <MOBYRegistration>
	 *                      <success> <!-- 1 | 0 | -1 --> </success>
	 *                      <id> <!-- some id number for your registration --> </id>  
	 *                      <message> <![CDATA[message here]]> </message>
	 *                   </MOBYRegistration>
	 *
* *

* The content of message will contain any extra information, for * example, the reason for failure, etc. *

* success is 0 (failure), 1 (success) or -1 (pending) *

* id, not used anymore, but could potentially be a place for an lsid * (unofficial) */ public String registerObjectClass(String registrationObject); /** * Deregister a deprecated object class. If your object is no longer useful, * you can remove it from the ontology with this procedure. * * @param deregistrationObject * a string of XML, with the following structure: * * 

	 *             <deregisterObjectClass>
	 *               <objectType>ObjectOntologyTermToRemove</objectType>
	 *             </deregisterObjectClass>
	 *
* *

* Notes: * * 

	 *            
	 *     * You may only deregister classes that you yourself registered!
	 *     * You may not deregister object classes that are being used as input or output by any service
	 *     * You may not deregister object classes that are in a ISA or HASA relationship to any other object class. 
	 *
* * @return a string of XML, for example: * * 
	 *                    <MOBYRegistration>
	 *                       <success> <!-- 1 | 0 | -1 --> </success>
	 *                       <id> <!-- some id number for your registration --> </id>  
	 *                       <message> <![CDATA[message here]]> </message>
	 *                       <RDF><![CDATA[ the RDF of your service instance here (if applicable) ]]></RDF>
	 *                    </MOBYRegistration>
	 *
* *

* The content of message will contain any extra information, for * example, the reason for failure, etc. *

* success is 0 (failure), 1 (success) or -1 (pending) *

* id, not used anymore, but could potentially be a place for an lsid * (unofficial) */ public String deregisterObjectClass(String deregistrationObject); /** * Register a new service type. MOBY's service ontology (we need a link) is * pretty small (most services are of type 'Retrieval'). If you need to * expand the ontology, this procedure does it. * * @param registrationObject * an XML string with the following structure: * * 

	 *              <registerServiceType>
	 *               <serviceType>NewServiceType</serviceType>
	 *               <contactEmail>your_name@contact.address.com</contactEmail>
	 *               <authURI>Your.URI.here</authURI>
	 *               <Description>
	 *                 <![CDATA[ human description of service type here]]>
	 *               </Description>
	 *               <Relationship relationshipType="RelationshipOntologyTerm">
	 *                 <serviceType>ExistingServiceType</serviceType>
	 *                 <serviceType>ExistingServiceType</serviceType>
	 *               </Relationship>
	 *              </registerServiceType>
	 *              
	 *          * serviceTypes are unique within the service ontology, and there
	 *            is only one canonical MOBY service ontology.
	 *          * The only relationship ontology type currently supported by
	 *            MOBY is the "ISA" relationship.
	 *          * Services described to be in ISA relationship with the
	 *            new service type must exist or this registration will fail.
	 *          * All parameters are required.
	 *          * Email must be a valid address.
	 *
* * @return a string of XML, for example: * * 
	 *                   <MOBYRegistration>
	 *                      <success> <!-- 1 | 0 | -1 --> </success>
	 *                      <id> <!-- some id number for your registration --> </id>  
	 *                      <message> <![CDATA[message here]]> </message>
	 *                   </MOBYRegistration>
	 *
* *

* The content of message will contain any extra information, for * example, the reason for failure, etc. *

* success is 0 (failure), 1 (success) or -1 (pending) *

* id, not used anymore, but could potentially be a place for an lsid * (unofficial) */ public String registerServiceType(String registrationObject); /** * Deregister a deprecated service type. * * @param deregistrationObject * a string of XML with the following structure: * * 

	 *           <deregisterServiceType>
	 *             <serviceType>ServiceOntologyTermToRemove</serviceType>
	 *           </deregisterServiceType>
	 *           
	 *       * Will fail if any current services are instances of that service type
	 *       * Will fail if any other service types inherit from that service type. 
	 *
* * @return a string of XML, for example: * * 
	 *                     <MOBYRegistration>
	 *                        <success> <!-- 1 | 0 | -1 --> </success>
	 *                        <id> <!-- some id number for your registration --> </id>  
	 *                        <message> <![CDATA[message here]]> </message>
	 *                     </MOBYRegistration>
	 *
* *

* The content of message will contain any extra information, for * example, the reason for failure, etc. *

* success is 0 (failure), 1 (success) or -1 (pending) *

* id, not used anymore, but could potentially be a place for an lsid * (unofficial) */ public String deregisterServiceType(String deregistrationObject); /** * Register a new namespace. MOBY has a pretty large set of namespacesneeds * a link * * @param registrationObject * a string of XML with the following structure: * * 

	 *            <registerNamespace>
	 *               <namespaceType>NewNamespaceHere</namespaceType>
	 *               <contactEmail>your_name@contact.address.com</contactEmail>
	 *               <authURI>Your.URI.here</authURI>
	 *               <Description>
	 *                  <![CDATA[human readable description]]>
	 *               </Description>
	 *            </registerNamespace>
	 *    	 * All fields are required.
	 *        * Namespaces are unique within the namespace vocabulary and there is only one canonical MOBY namespace controlled vocabulary.
	 *        * contactEmail must be a valid email address.
	 *        * authURI must be a valid URI
	 *    
	 *
* * @return a string of XML, for example: * * 
	 *                   <MOBYRegistration>
	 *                      <success> <!-- 1 | 0 | -1 --> </success>
	 *                      <id> <!-- some id number for your registration --> </id>  
	 *                      <message> <![CDATA[message here]]> </message>
	 *                   </MOBYRegistration>
	 *
* *

* The content of message will contain any extra information, for * example, the reason for failure, etc. *

* success is 0 (failure), 1 (success) or -1 (pending) *

* id, not used anymore, but could potentially be a place for an lsid * (unofficial) */ public String registerNamespace(String registrationObject); /** * Deregister a deprecated namespace term * * @param deregistrationObject * a string of XML with the following structure: * * 

	 *          <deregisterNamespace>
	 *             <namespaceType>MyNamespaceToRemove</namespaceType>
	 *          </deregisterNamespace>
	 *  
	 *  * Will fail if that namespace is being used by any services
	 *
* * @return a string of XML, for example: * * 
	 *                      <MOBYRegistration>
	 *                         <success> <!-- 1 | 0 | -1 --> </success>
	 *                         <id> <!-- some id number for your registration --> </id>  
	 *                         <message> <![CDATA[message here]]> </message>
	 *                      </MOBYRegistration>
	 *
* *

* The content of message will contain any extra information, for * example, the reason for failure, etc. *

* success is 0 (failure), 1 (success) or -1 (pending) *

* id, not used anymore, but could potentially be a place for an lsid * (unofficial) */ public String deregisterNamespace(String deregistrationObject); /** * Register a new service instance. You have a new service you'd like to * share with the world. (There's a tutorial to show you how to do it with * Perl.) * * @param registrationObject * a string of XML with the following structure: * * 

	 *       <registerService>
	 *          <Category>moby</Category> <!-- one of 'moby', 'cgi', 'soap' -->
	 *          <serviceName>YourServiceNameHere</serviceName>
	 *          <serviceType>TypeOntologyTerm</serviceType>
	 *          <authURI>your.URI.here</authURI>
	 *          <signatureURL> http://some.URL.org/path/to/RDF/file </signatureURL>
	 *          <URL>http://URL.to.your/Service.script</URL>;
	 *          <contactEmail>your_name@contact.address.com</contactEmail>
	 *          <authoritativeService>1 | 0 </authoritativeService>
	 *          <Description><![CDATA[
	 *                human readable COMPREHENSIVE description of your service]]>
	 *          </Description>
	 *          <Input>
	 *               <!-- zero or more Primary (Simple and/or Collection) articles -->
	 *               <!-- each of these articles will appear EXACTLY ONCE in the input to the service -->
	 *          </Input>
	 *          <secondaryArticles>
	 *               <!-- zero or more INPUT Secondary (Parameter) articles -->
	 *               <!-- each of these articles will appear EXACTLY ONCE in the output from the service -->
	 *          </secondaryArticles>
	 *          <Output>
	 *               <!-- zero or more Primary (Simple and/or Collection) articles --> 
	 *          </Output>
	 *       </registerService>
	 * 
	 *     * All elements are required
	 *     * A service must have at least one Input OR Output Object Class.
	 *     * serviceName must comply with rules for method names of a web 
	 *       service. i.e. must be include only characters [A-Za-z0-9_] and
	 *       begin with a letter.
	 *     * The object classes, namespaces, and service types must all exist
	 *       for the registration to be successful, so make sure you register 
	 *       these first, or ensure that they already exist in their respective 
	 *       ontologies.
	 *     * The authoritativeService tag is used to indicate whether or not the
	 *       registered service is "authoritative" for that transformation. i.e.
	 *       if you are "authoritative" anyone else performing the same transformation
	 *       would have to have obtained the information/code to do so from you. This
	 *       is similar to, but not necessarily identical to, mirroring someone elses
	 *       data, since the data in question may not exist prior to service
	 *       invocation.
	 *     * Only input secondary articles are defined during registration;
	 *       output secondary objects are entirely optional and may or may not
	 *       be interpreted client-side using their articleName tags.
	 *     * When registering a service, the registration object that you are returned
	 *       contains an extra XML element with the RDF tag. Inside of this element is
	 *       the RDF document corresponding to your service signature. MOBY Central
	 *       will expect to be able to recover that RDF document when it calls a GET
	 *       on the URL that you provide in the signatureURL element of the
	 *       registerService XML below. An agent will call this document on a
	 *       regular basis, and update your registered service with whatever
	 *       it finds there. If you wish to de-register your service, just remove
	 *       that document (or the portion of that document corresponding to your
	 *       service).
	 * 
	 *
* * @return a string of XML, for example: * * 
	 *                    <MOBYRegistration>
	 *                       <success> <!-- 1 | 0 | -1 --> </success>
	 *                       <id> <!-- some id number for your registration --> </id>  
	 *                       <message> <![CDATA[message here]]> </message>
	 *                       <RDF><![CDATA[ the RDF of your service instance here ]]></RDF>
	 *                    </MOBYRegistration>
	 *
* *

* The content of message will contain any extra information, for * example, the reason for failure, etc. *

* success is 0 (failure), 1 (success) or -1 (pending) *

* id, not used anymore, but could potentially be a place for an lsid * (unofficial) */ public String registerService(String registrationObject); /** * Deregister a service instance. * * @deprecated * @param deregistrationObject * a string of XML, for example, * * 

	 *                   <deregisterService>
	 *                      <authURI>service.provider.uri</authURI>
	 *                      <serviceName>serviceName</serviceName>
	 *                   </deregisterService>
	 *
* * @return a string of XML, for example: * * 
	 *                      <MOBYRegistration>
	 *                         <success> <!-- 1 | 0 | -1 --> </success>
	 *                         <id> <!-- some id number for your registration --> </id>  
	 *                         <message> <![CDATA[message here]]> </message>
	 *                         <RDF><![CDATA[ the RDF of your service instance here ]]></RDF>
	 *                      </MOBYRegistration>
	 *
* *

* The content of message will contain any extra information, for * example, the reason for failure, etc. *

* success is 0 (failure), 1 (success) or -1 (pending) *

* id, not used anymore, but could potentially be a place for an lsid * (unofficial) */ public String deregisterService(String deregistrationObject); }