org.biomoby.shared
Interface Central

All Known Subinterfaces:

CentralAll, CentralCached

All Known Implementing Classes:

CentralCachedCallsImpl, CentralDigestCachedImpl, CentralDigestCachedSimpleImpl, CentralDigestImpl, CentralImpl

public interface Central

An interface to the Moby Registry.

The Moby Registry (or Moby Central) is used to do various transactions, including registering new Data and Service types, querying for these types, registering new Services, or querying for available services given certain input/output or service type constraints.

The main purpose of this interface is to express the Moby Registry functionality in Java language, and to hide complexity of the parameters required by the Moby Registry. The Moby Registry gets most parameters as small XML documents while this interface defines the same parameters as various Java method signatures.

For details describing and explaining the methods see the original documentation at http://biomoby.org.

Version:

$Id: Central.java,v 1.17 2008/10/30 02:33:25 gordonp Exp $

Author:

Martin Senger

Field Summary

static String	DATA_TYPES_RESOURCE_NAME A name of an ontology describing registered data types.
static String	FULL_RESOURCE_NAME A name of an ontology describing all registered entities.
static String	HAS A relationship type expressing a contaiment (as string).
static String	HASA A relationship type expressing a contaiment (as string).
static int	iHAS A relationship type expressing a contaiment (as integer).
static int	iHASA A relationship type expressing a contaiment (as integer).
static int	iISA A relationship type expressing a straight inheritance (as integer).
static String	ISA A relationship type expressing a straight inheritance (as string).
static String	NAMESPACES_RESOURCE_NAME A name of an ontology describing registered service types.
static String	SERVICE_INSTANCES_RESOURCE_NAME A name of an ontology describing registered service types.
static String	SERVICE_TYPES_RESOURCE_NAME A name of an ontology describing registered service types.

Method Summary

String	call(String methodName, String inputXML) Call Moby registry's method with given XML as input and return whatever you get back.
MobyService[]	findService(MobyService pattern) Find services matching whatever is non-empty in the given 'pattern'.
MobyService[]	findService(MobyService pattern, String[] keywords) Find service matching both all non-empty fields in the 'pattern' and the 'keywords'.
MobyService[]	findService(MobyService pattern, String[] keywords, boolean includeChildrenServiceTypes, boolean includeParentDataTypes) Find service matching both all non-empty fields in the 'pattern' and the 'keywords', and take into account also the whole ontology tree.
MobyService[]	findService(String serviceType) Find services of the given type and its sub-types.
MobyService[]	findService(String[] keywords) Find services by given keywords.
boolean	getCacheMode() Reports whether server responses are being cached or not.
MobyDataType	getDataType(String dataTypeName) Get definition of the given data type.
Map<String,String>	getDataTypeNames() Get the list of all registered data types.
Map<String,String>	getDataTypeRelationships(String dataTypeName) Get all relationships of the given 'dataTypeName'.
String[]	getDataTypeRelationships(String dataTypeName, String relationshipType) Get all relationships of type 'relationshipType' for the given 'dataTypeName'.
MobyDataType[]	getDataTypes()
MobyNamespace[]	getFullNamespaces() Get the list of all registered namespaces, with all their attributes.
Map<String,String>	getNamespaces() Deprecated. Replaced by getFullNamespaces() that gives more information for the same price.
String[]	getProviders() Get the list of all providers (each provider is represented by an authority's URI.
String	getRegistryEndpoint() Return an endpoint (a stringified URL) representing a Moby registry that an instance of this implementation is connected to.
String	getRegistryNamespace() Return a namespace (a URI) used by a Moby registry that an instance of this implementation is connected to.
InputStream	getResource(String resourceName) First get (from a BioMoby registry) a URL for the given 'resourceName' and then retrieve a document from this URL.
MobyResourceRef[]	getResourceRefs() Get URLs (and content types) of RDF documents describing various BioMoby ontologies.
Map<String,String>	getServiceNames() Deprecated. Replaced by getServiceNamesByAuthority(). The reason is that this method returns a random result if there are more services with the same name but belonging to different authorities.
Map<String,String[]>	getServiceNamesByAuthority() Get a list of all authorities - and for each of them a list of their registered service names.
String[]	getServiceTypeRelationships(String serviceTypeName, boolean expand) Get all ISA relationships of the given 'serviceTypeName'.
Map<String,String>	getServiceTypes() Get the list of all registered service types.
String	getServiceWSDL(String serviceName) Get WSDL defining a service given by its name.
String	getServiceWSDL(String serviceName, String authority) Get WSDL defining a service given by its name and its authority.
void	registerDataType(MobyDataType dataType) Register new data type.
void	registerNamespace(MobyNamespace namespace) Register new namespace.
void	registerService(MobyService service) Register a new service.
void	registerServiceType(MobyServiceType serviceType) Register new service type.
void	setCacheMode(boolean shouldCache) Set whether the server responses should cached or not to speedup multiple calls for the same data.
boolean	setDebug(boolean enabled) Ask the implementation to create more verbose logs or messages about what is going on.
void	unregisterDataType(MobyDataType dataType) Unregister given Moby data type.
void	unregisterNamespace(MobyNamespace namespace) Unregister given Moby namespace.
void	unregisterService(MobyService service) Unregister given Moby service.
void	unregisterServiceType(MobyServiceType serviceType) Unregister given Moby service type.

Field Detail

ISA

static final String ISA

A relationship type expressing a straight inheritance (as string). If Object_A ISA Object_B then all attributes of Object_B are guaranteed to be present in Object_A.

See Also:

Constant Field Values

HASA

static final String HASA

A relationship type expressing a contaiment (as string). If Object_A HASA Object_B then Object_B is an object inside of Object_A in one copy only.

See Also:

Constant Field Values

HAS

static final String HAS

A relationship type expressing a contaiment (as string). If Object_A HAS Object_B then Object_B is an object inside of Object_A in one or more copies.

See Also:

Constant Field Values

iISA

static final int iISA

A relationship type expressing a straight inheritance (as integer). If Object_A ISA Object_B then all attributes of Object_B are guaranteed to be present in Object_A.

See Also:

Constant Field Values

iHASA

static final int iHASA

A relationship type expressing a contaiment (as integer). If Object_A HASA Object_B then Object_B is an object inside of Object_A in one copy only.

See Also:

Constant Field Values

iHAS

static final int iHAS

A relationship type expressing a contaiment (as integer). If Object_A HAS Object_B then Object_B is an object inside of Object_A in one or more copies.

See Also:

Constant Field Values

SERVICE_TYPES_RESOURCE_NAME

static final String SERVICE_TYPES_RESOURCE_NAME

A name of an ontology describing registered service types. The name is used in a hash table returned by the getResourceRefs().

See Also:

Constant Field Values

SERVICE_INSTANCES_RESOURCE_NAME

static final String SERVICE_INSTANCES_RESOURCE_NAME

A name of an ontology describing registered service types. The name is used in a hash table returned by the getResourceRefs().

See Also:

Constant Field Values

DATA_TYPES_RESOURCE_NAME

static final String DATA_TYPES_RESOURCE_NAME

A name of an ontology describing registered data types. The name is used in a hash table returned by the getResourceRefs().

See Also:

Constant Field Values

NAMESPACES_RESOURCE_NAME

static final String NAMESPACES_RESOURCE_NAME

A name of an ontology describing registered service types. The name is used in a hash table returned by the getResourceRefs().

See Also:

Constant Field Values

FULL_RESOURCE_NAME

static final String FULL_RESOURCE_NAME

A name of an ontology describing all registered entities. The name is used in a hash table returned by the getResourceRefs(). The contents returned by this method for this ontology name is a concatenation of all other ontologies.

See Also:

Constant Field Values

Method Detail

getServiceNames

Map<String,String> getServiceNames()
                                   throws MobyException

Deprecated. Replaced by getServiceNamesByAuthority(). The reason is that this method returns a random result if there are more services with the same name but belonging to different authorities.

Get a (redundant) list of all registered service names.

Returns:

a hash table where keys are names of services while values are their authorities

Throws:

MobyException - if communication with the Moby Registry fails

getServiceNamesByAuthority

Map<String,String[]> getServiceNamesByAuthority()
                                                throws MobyException

Get a list of all authorities - and for each of them a list of their registered service names.

This method is a better replacement for the deprecated method getServiceNames().

Returns:

a hash table where keys are authority names and values are arrays of service names provided by each authority

Throws:

MobyException - if communication with the Moby Registry fails

getProviders

String[] getProviders()
                      throws MobyException

Get the list of all providers (each provider is represented by an authority's URI.

Throws:

MobyException - if communication with the Moby Registry fails

getServiceTypes

Map<String,String> getServiceTypes()
                                   throws MobyException

Get the list of all registered service types.

Returns:

a hash table where keys are names of service types while values are their descriptions

Throws:

MobyException - if communication with the Moby Registry fails

getServiceTypeRelationships

String[] getServiceTypeRelationships(String serviceTypeName,
                                     boolean expand)
                                     throws MobyException

Get all ISA relationships of the given 'serviceTypeName'.

Parameters:

serviceTypeName - is a service type name whose relationships should be looked at

expand - 'true' causes that all related type names are returned, 'false' means that only first-level neighbour is returned

Returns:

an array of service type names representing all parents (direct or indirect) of the given 'serviceTypeName'

Throws:

MobyException - if communication with the Moby Registry fails

getNamespaces

Map<String,String> getNamespaces()
                                 throws MobyException

Deprecated. Replaced by getFullNamespaces() that gives more information for the same price.

Get the list of all registered namespaces.

Returns:

a hash table where keys are names of namespaces while values are their descriptions

Throws:

MobyException - if communication with the Moby Registry fails

getFullNamespaces

MobyNamespace[] getFullNamespaces()
                                  throws MobyException

Get the list of all registered namespaces, with all their attributes.

Returns:

array of namespaces

Throws:

MobyException - if communication with the Moby Registry fails

getDataTypeNames

Map<String,String> getDataTypeNames()
                                    throws MobyException

Get the list of all registered data types.

Returns:

a hash table where keys are names of data types while values are their descriptions

Throws:

MobyException - if communication with the Moby Registry fails

getDataType

MobyDataType getDataType(String dataTypeName)
                         throws MobyException,
                                NoSuccessException

Get definition of the given data type.

Throws:

MobyException - if communication with the Moby Registry fails

NoSuccessException - if 'dataTypeName' was not found

getDataTypes

MobyDataType[] getDataTypes()
                            throws MobyException,
                                   NoSuccessException

Throws:

MobyException

NoSuccessException

getDataTypeRelationships

Map<String,String> getDataTypeRelationships(String dataTypeName)
                                            throws MobyException

Get all relationships of the given 'dataTypeName'.

Parameters:

dataTypeName - is an ontology term specifying whose relationships should be looked at

Returns:

a Map of ontology terms defining all relationships of the given 'dataTypeName'. The keys (of type String) are from the set ISA, HASA, and HAS. The values (of type String) are data type names.

Throws:

MobyException - if communication with the Moby Registry fails

getDataTypeRelationships

String[] getDataTypeRelationships(String dataTypeName,
                                  String relationshipType)
                                  throws MobyException

Get all relationships of type 'relationshipType' for the given 'dataTypeName'.

Parameters:

dataTypeName - is an ontology term specifying whose relationships should be looked at

relationshipType - is one from the set ISA, HASA, and HAS.

Returns:

an array of names specifying all related types (of the given type and for the given data type)

Throws:

MobyException - if communication with the Moby Registry fails

getServiceWSDL

String getServiceWSDL(String serviceName,
                      String authority)
                      throws MobyException,
                             NoSuccessException

Get WSDL defining a service given by its name and its authority.

Throws:

MobyException - if communication with the Moby Registry fails

NoSuccessException - if such service was not found

getServiceWSDL

String getServiceWSDL(String serviceName)
                      throws MobyException,
                             NoSuccessException

Get WSDL defining a service given by its name. The method asks for all services first and then uses the first one matches the given name.

Throws:

MobyException - if communication with the Moby Registry fails

NoSuccessException - if such service was not found

See Also:

getServiceWSDL(String,String)

registerDataType

void registerDataType(MobyDataType dataType)
                      throws MobyException,
                             NoSuccessException,
                             PendingCurationException

Register new data type.

If the same data type is already registered, it is overwritten.

Throws:

MobyException - if communication with the Moby Registry fails

NoSuccessException - if registration failed

PendingCurationException

unregisterDataType

void unregisterDataType(MobyDataType dataType)
                        throws MobyException,
                               NoSuccessException,
                               PendingCurationException

Unregister given Moby data type.

Throws:

MobyException - if communication with the Moby Registry fails

NoSuccessException - if unregistration failed

PendingCurationException

registerServiceType

void registerServiceType(MobyServiceType serviceType)
                         throws MobyException,
                                NoSuccessException,
                                PendingCurationException

Register new service type.

If the same service type is already registered, it is not overwritten but an exception is raised.

Throws:

MobyException - if communication with the Moby Registry fails

NoSuccessException - if registration failed

PendingCurationException

unregisterServiceType

void unregisterServiceType(MobyServiceType serviceType)
                           throws MobyException,
                                  NoSuccessException,
                                  PendingCurationException

Unregister given Moby service type.

Throws:

MobyException - if communication with the Moby Registry fails

NoSuccessException - if unregistration failed

PendingCurationException

registerNamespace

void registerNamespace(MobyNamespace namespace)
                       throws MobyException,
                              NoSuccessException,
                              PendingCurationException

Register new namespace.

If the same namespace is already registered, it is overwritten.

Throws:

MobyException - if communication with the Moby Registry fails

NoSuccessException - if registration failed

PendingCurationException

unregisterNamespace

void unregisterNamespace(MobyNamespace namespace)
                         throws MobyException,
                                NoSuccessException,
                                PendingCurationException

Unregister given Moby namespace.

Throws:

MobyException - if communication with the Moby Registry fails

NoSuccessException - if unregistration failed

PendingCurationException

registerService

void registerService(MobyService service)
                     throws MobyException,
                            NoSuccessException,
                            PendingCurationException

Register a new service.

If the same service type is already registered, it is not overwritten but an exception is raised.

Throws:

MobyException - if communication with the Moby Registry fails

NoSuccessException - if registration failed

PendingCurationException

unregisterService

void unregisterService(MobyService service)
                       throws MobyException,
                              NoSuccessException,
                              PendingCurationException

Unregister given Moby service.

Throws:

MobyException - if communication with the Moby Registry fails

NoSuccessException - if unregistration failed

PendingCurationException

findService

MobyService[] findService(String serviceType)
                          throws MobyException

Find services of the given type and its sub-types.

Returns:

services of the given type and all sub-typesd, or an empty array if none was found

Throws:

MobyException - if communication with the Moby Registry fails

findService

MobyService[] findService(String[] keywords)
                          throws MobyException

Find services by given keywords. More keywords are treated as logical OR.

Returns:

services containing given keywords, or an empty array if none was found

Throws:

MobyException - if communication with the Moby Registry fails

findService

MobyService[] findService(MobyService pattern)
                          throws MobyException

Find services matching whatever is non-empty in the given 'pattern'. If more fields are given the logical AND is applied on them.

Throws:

MobyException - if communication with the Moby Registry fails

findService

MobyService[] findService(MobyService pattern,
                          String[] keywords)
                          throws MobyException

Find service matching both all non-empty fields in the 'pattern' and the 'keywords'.

Throws:

MobyException

findService

MobyService[] findService(MobyService pattern,
                          String[] keywords,
                          boolean includeChildrenServiceTypes,
                          boolean includeParentDataTypes)
                          throws MobyException

Find service matching both all non-empty fields in the 'pattern' and the 'keywords', and take into account also the whole ontology tree.

Parameters:

includeChildrenServiceTypes - - if true (which is default) then it discovers also services that are child types (more specific) than the service type in 'pattern'

includeParentDataTypes - - if true (which is default) then it finds services that operate not only on the input/output data types defined in 'pattern', but also any ontolological parent types of that data types

Throws:

MobyException

call

String call(String methodName,
            String inputXML)
            throws MobyException

Call Moby registry's method with given XML as input and return whatever you get back. If 'inputXML' is null or empty, the method is called without any parameters.

Meant for debugging and may be deprecated anytime...

Throws:

MobyException

setDebug

boolean setDebug(boolean enabled)

Ask the implementation to create more verbose logs or messages about what is going on. The behaviour is completely implementation dependent.

Parameters:

enabled - true if debug mode should be enabled, false otherwise

Returns:

the previous value of the debug mode

setCacheMode

void setCacheMode(boolean shouldCache)

Set whether the server responses should cached or not to speedup multiple calls for the same data.

Parameters:

shouldCache - if set to false, any previously cached documents should be deleted

getCacheMode

boolean getCacheMode()

Reports whether server responses are being cached or not.

getRegistryEndpoint

String getRegistryEndpoint()

Return an endpoint (a stringified URL) representing a Moby registry that an instance of this implementation is connected to.

getRegistryNamespace

String getRegistryNamespace()

Return a namespace (a URI) used by a Moby registry that an instance of this implementation is connected to.

getResourceRefs

MobyResourceRef[] getResourceRefs()
                                  throws MobyException

Get URLs (and content types) of RDF documents describing various BioMoby ontologies. These RDF documents are yet another form how to get information about registered entities in the BioMoby registry.

There are five possible ontology names: SERVICE_TYPES_RESOURCE_NAME, DATA_TYPES_RESOURCE_NAME, NAMESPACES_RESOURCE_NAME, SERVICE_INSTANCES_RESOURCE_NAME, FULL_RESOURCE_NAME.

Returns:

an array of references to RDF documents; some elements of this array may refer to the same resources but stored/available in a different content type (this mostly means that some of them may be compressed to get them faster)

Throws:

MobyException - if communication with the Moby Registry fails

getResource

InputStream getResource(String resourceName)
                        throws MobyException

First get (from a BioMoby registry) a URL for the given 'resourceName' and then retrieve a document from this URL. If the resource is available in a compressed format, return it uncompressed.

The document is in RDF and represents some (or all) entities registered in the BioMoby registry.

Parameters:

resourceName - is an ontology name (must be one of these: SERVICE_TYPES_RESOURCE_NAME, DATA_TYPES_RESOURCE_NAME, NAMESPACES_RESOURCE_NAME, SERVICE_INSTANCES_RESOURCE_NAME, FULL_RESOURCE_NAME)

Returns:

an input stream that contains an RDF document

Throws:

MobyException - if communication with the Moby Registry fails, or if communication with the resource URL fails