/*
*Central.java
*/
package org.biomoby.registry.Central;
/**
* An interface that outlines the methods needed to query a Moby central
* registry. To fully implement a Mobycentral registry, {@link org.biomoby.registry.Central Registry}
* must also be implemented.
*
* @author Eddie created Nov 30, 2005
*/
public interface Central {
/**
* Locate a service instance, matching various characteristics, such as the
* provider name, the kind of input expected by the service, the kind of
* output it provides, etc.
*
* @param serviceQueryObject
* a service query object like the following:
*
*
* <findService>
* <!-- Service Query Object -->
* </findService>
*
* where a Service Query Object contains a Query Object that allows a user
* to query Moby Central.
*
* To query MOBY Central, you fill out the relevant elements of a Query
* Object. These include the input and/or output data Classes (by name
* from the Class ontology), the Service-type (by name from the Service-type
* ontology), the authority (service provider URI), or any number of
* keywords that must appear in the service description.
*
* * MOBY Central finds all services which match the contents of
* the Query Object.
* * All elements are optional, however at least one must be
* present.
* * All elements present are considered to be increasingly
* limiting on the search (i.e. "AND").
* * keywords are:
* o one keyword or fragment per keyword element
* o wildcard "*" is allowed in combination with
* keyword fragments and or sentence fragments
* (lone "*" is meaningless and ignored)
* o multiple keywords are considered joined by
* "AND".
*
* In addition to the search parameters, there are three
* "flags" that can be set in the Query object:
*
* 1. expandServices: when TRUE, this flag will cause MOBY Central
* to traverse the Service ontology and discover services that
* are child types (more specific) than the Service-type you
* requested. For example, you might request
* "alignment", and it would discover services such as
* "Blast", "Smith Waterman",
* "Needleman Wunsch".
* 2. expandObjects: when TRUE, this flag will cause MOBY Central to
* traverse the Class ontology to find services that operate not
* only on the Object Class you are querying, but also any
* ontolological parent types of that Object Class. For example,
* if you request services that work on AnnotatedSequence Objects
* this flag will also return services that work on Sequence
* objects, since AnnotatedSequence objects inherit from Sequence
* objects.
* 3. authoritative: When this boolean flag is TRUE, only services
* that report themselves to be "authoritative" for a
* particular transformation will be discovered. When set to any
* other value both authoritative and non-authoritative services
* will be discovered.
*
* The Query object structure is as follows:
*
* <inputObjects>
* <Input>
* <!-- one or more Simple or Collection articles -->
* </Input>
* </inputObjects>
* <outputObjects>
* <Output>
* <!-- one or more Simple or Collection articles -->
* </Output>
* </outputObjects>
* <serviceType>ServiceTypeTerm</serviceType>
* <Protocol>moby</Protocol>
* <authURI>desired.service.provider</authURI>;
* <serviceName>MyServiceName</serviceName>;
* <expandObjects>1|0</expandObjects>
* <expandServices>1|0</expandServices>
* <authoritative>1|0</authoritative>
* <keywords>
* <keyword>something</keyword>
* ....
* ....
* </keywords>
*
*
* @return a string containing the XML for the Service List response whichis
* as follows:
*
*
* <Services>
* <Service authURI="authority.URI.here" serviceName="MyService" lsid='urn:lsid:authority.uri:serviceinstance:id'>
* <serviceType lsid='urn:lsid:authority.uri:servicetype:OntologyTerm'>Ontology_Term</serviceType>
* <authoritative>1</authoritative>
* <Category>moby</Category> <!-- 'moby' or 'cgi' or 'soap' -->
* <Description><![CDATA[free text description here]]></Description>
* <contactEmail>your@email.addy.here</contactEmail>
* <URL>http://service.endpoint.here/scriptname</URL>
* <Input>
* <!-- zero or more Simple and/or Collection articles -->
* </Input>
* <Output>
* <!-- zero or more Simple and/or Collection articles -->
* </Output>
* <secondaryArticles>
* <!-- zero or more Secondary (Parameter) articles -->
* </secondaryArticles>
* </Service>
* ...
* <!-- one or more Service blocks may be returned -->
* ...
* ...
* </Services>
*
*/
public String findService(String serviceQueryObject);
/**
* Retrieve the definition for a service instance, as specified in WSDL
* format. This information is used by the client to compose queries.
*
* @param query
* a string of XML similar to the following
*
*
* <retrieveService>
* <Service authURI="authority.URI.here" serviceName="MyService"/>
* <retrieveService>
*
*
* Note: AuthURI and serviceName attributes are sufficient
* to identify a unique service, and both are required in the element.
*
* @return a string of XML, for example
*
*
* * moby
* <Service authURI="authority.URI.here" serviceName="MyService" lsid='urn:lsid:authority.uri:serviceinstance:id'>
* <![CDATA[WSDL document here]]
* </Service>
*
* * cgi
* <Service>
* <serviceName>NameOfService</serviceName>
* <URL>http://service.url.here</URL>;
* <GETstring>sprintf_formatted_GET_string</GETstring>
* <Description>
* <![CDATA[human readable description here]]>
* </Description>
* </Service>
*
*
* * soap
* UNKNOWN AT THIS TIME
*
*
* Note: The WSDL that is returned is not currently valid.
* It will only become valid once we have the ability to convert our class
* ontology into an XML schema. In addition, the WSDL that is returned does
* not necessarily describe the actual interface of the service. In the
* BioMOBY system, you are allowed to pass more complex objects to a
* service, and the service is allowed to pass more complex objects back to
* you, so long as they obey the parentage rules of the class ontology. As
* such, the WSDL that you receive is the minimal interface for the service,
* not necessarily the actual interface.
*
* The use of WSDL in the BioMOBY system is subject to change in future
* revisions, and is provided at this time only to facilitate the creation
* of service stubs on the client side using the commonly available WSDL
* parsers
*/
public String retrieveService(String query);
/**
* Retrieve the URLs of all registered services.
*
* @return a string of XML, for example
*
*
* <resourceURLs>
* <Resource name="ServiceInstance" url="http://biomoby.org/RESOURCES/MOBY-S/ServiceInstances>
* <Resource name="Object" url="http://biomoby.org/RESOURCES/MOBY-S/Objects"/>
* <Resource name="Namespace" url="http://biomoby.org/RESOURCES/MOBY-S/Namespaces"/>
* <Resource name="Service" url="http://biomoby.org/RESOURCES/MOBY-S/Services/Services"/>
* <Resource name="Full" url="http://biomoby.org/RESOURCES/MOBY-S/Services/FULL"/>
* </resourceURLs>
*
*
* Note: Finds the URL from which the RDF of a MOBY
* Ontology can be retrieved by HTTP GET. There are five possible ontology
* names: "Service", "Object", "Namespace", "ServiceInstance", or "Full"
* (Full retrieves all of the ontologies)
*
*
*/
public String retrieveResourceURLs();
/**
* Retrieve the names of all registered service providers. This allows you
* to see what sites are providing MOBY services.
*
* @return a string of output XML, for example:
*
*
* <serviceTypes>
* <serviceType name="serviceName" lsid='urn:lsid:authority.uri:servicetype:id'>
* <Description><![CDATA[free text description here]]></Description>
* <contactEmail>email@address here</contactEmail>
* <authURI>authority.uri.here</authURI>
* </serviceType>
* ...
* </serviceTypes>
*
*
*/
public String retrieveServiceProviders();
/**
* Retrieve the names of all registered services. The service name, service
* provider and service lsid are all returned.
*
* @return a string of output XML, for example:
*
*
* <serviceNames>
* <serviceName name="serviceName" authURI='authority.info.here' lsid='urn:lsid:authority.uri:namespace:id'/>
* ...
* </serviceNames>
*
*/
public String retrieveServiceNames();
/**
* Retrieve the definitions and registration details of all registered
* service types.
*
* @return a string of output XML, for example:
*
*
* <serviceTypes>
* <serviceType name="serviceName" lsid='urn:lsid:authority.uri:servicetype:id'>
* <Description><![CDATA[free text description here]]></Description>
* <contactEmail>email@address here</contactEmail>
* <authURI>authority.uri.here</authURI>
* </serviceType>
* ...
* </serviceTypes>
*
*
*/
public String retrieveServiceTypes();
/**
* Retrieve the definitions and registration details of all registered
* object types.
*
* @return a string of output XML, for example:
*
*
* <objectNames>
* <Object name="objectName" lsid='urn:lsid:authority.uri:namespace:id'>
* <Description><![CDATA[free text description here]]></Description>
* </Object>
* ...
* </objectNames>
*
*/
public String retrieveObjectNames();
/**
* Retrieve the class definition, in the form of the full registration
* details for the class type specified by the input XML.
*
* @param query
* input XML, for example:
*
*
* <retrieveObjectDefinition>
* <objectType>ExistingObjectClassname</objectType>
* </retrieveObjectDefinition>
*
*
*
* @return a string of XML that represents the full declaration of the
* object, as defined by the XML used to register it. For example:
*
*
* <retrieveObjectDefinition>
* <objectType lsid='urn:lsid:authority.uri:namespace:id'>ObjectClassName</objectType>
* <Description><![CDATA[
* human readable description
* of data type]]>
* </Description>
* <Relationship relationshipType="RelationshipOntologyTerm"
* lsid='urn:lsid:authority.uri:namespace:id'>
* <objectType articleName="SomeName" lsid='urn:lsid:authority.uri:namespace:id'>ExistingObjectType</objectType>
* </Relationship>
* ...
* <authURI>owner.URI.here</authURI>
* <contactEmail>owner@their.address.com</contactEmail>
* </retrieveObjectDefinition>
*
*/
public String retrieveObjectDefinitions(String query);
/**
* Retrieve a list of all registered namespaces
*
* @return a string of XML, for example:
*
*
* <Namespaces>
* <Namespace name="namespace" lsid='urn:lsid:authority.uri:namespace:id'>
* <Description><![CDATA[free text description here]]></Description>
* <contactEmail>email@address here</contactEmail>
* <authURI>authority.uri.here</authURI>
* </Namespace>
* ...
* </Namespaces>
*
*/
public String retrieveNamespaces();
/**
* Retrieve an XML schema representation of a particular object class. This
* is currently not implemented since it appears to be impossible to
* represent MOBY Objects in XML Schema due to limitations of XML Schema
*
* @param query
* a string of XML, for example:
*
*
* <retrieveObjectSchema>
* <objectType>ObjectType | all</objectType>
* </retrieveObjectSchema>
*
*
* @return a string of XML that encapsulates the schema. For example:
*
*
* <Objects>
* <Object name="ObjectOntologyTerm" lsid='urn:lsid:authority.uri:namespace:id'>
* <Schema><![CDATA[
* <XSD schema here>]]>
* </Schema>
* </Object>
* ...
* </Objects>
*
*/
public String retrieveObjectSchema(String query);
/**
* Retrieve a list of MOBY object classes having a specified relationship
* with the given class
*
* @param query
* a string of XML, for example:
*
*
* <Relationship>
* [ <objectType>OntologyTerm</objectType> |
* <serviceType>OntologyTerm</serviceType> ]
* <relationshipType>RelationshipOntologyTerm1</relationshipType>
* <relationshipType>RelationshipOntologyTerm2</relationshipType>
* ...
* <expandRelationship>1|0</expandRelationship>
* <Relationship>
*
*
* @return a string of XML, for example:
*
*
* <Relationships>
* <Relationship relationshipType="RelationshipOntologyTerm1"
* lsid='urn:lsid:authority.uri:namespace:id'>
* [ <objecctType lsid='...' articleName='foo'>OntologyTerm</objectType> |
* <serviceType lsid='...'>OntologyTerm</serviceType> ]
* ...
* </Relationship>
* ...
* </Relationships>
*
*
* Note: Unless the expandRelationships flag is set, it
* will return only the first-level objects in that relationship (i.e. take
* one step up the Ontology hierarchy). If the flag is set, MOBY Central
* will traverse the ontology right back to its root as a flattened list
*
*/
public String Relationships(String query);
}