info.sswap.api.model
Class SSWAP

java.lang.Object
  extended by info.sswap.api.model.SSWAP

public class SSWAP
extends java.lang.Object

Main factory for the creation of SSWAP objects (most elements in the API are just interfaces).

Note about naming of the methods: all the create*() methods create objects without accessing the Internet or dereferencing URIs; e.g., the createRDG method creates a new Resource Description Graph (RDG) ready to be hosted on the web. All get*() methods attempt to dereference argument URIs as appropriate and return objects that reflect the existing representation on the web. For example, the getRDG method attempts to return an object that corresponds to an RDG hosted at its URI. In case the underlying data does not exist, the behavior of a get*() method depends on the specific method. Methods like getRDG or getPDG will always return an object if possible (if undereferenced and there is no underlying data a later dereference() will fail).

Most methods will throw a runtime DataAccessException if the requested class cannot be instantiated, for example due to an I/O or parsing error. As in all Java, other runtime exceptions are possible. Common practice is to catch all runtime exceptions in an outermost main program try/catch block to handle unexpected runtime errors.

Lower-level objects are created by their super class, e.g., see SSWAPDocument.

Author:
Blazej Bulka
See Also:
SSWAPProtocol, SSWAPDocument, DataAccessException

Field Summary
private static APIProvider apiProvider
          The current provider of the API.
 
Constructor Summary
SSWAP()
           
 
Method Summary
static PDG createPDG(java.net.URI providerURI, java.lang.String name, java.lang.String oneLineDescription)
          Creates a PDG with the specified values.
static SSWAPProvider createProvider(java.net.URI providerURI)
          Creates an object representing a SSWAPProvider.
static RDG createRDG(java.net.URI resourceURI, java.lang.String name, java.lang.String oneLineDescription, SSWAPProvider provider)
          Creates a new RDG
static RDG createRDG(java.net.URI resourceURI, java.lang.String name, java.lang.String oneLineDescription, java.net.URI providerURI)
          Creates a new RDG
static SSWAPResource createResource(java.net.URI resourceURI)
          Gets a SSWAPResource that is defined in the RDG that exists at the specified URI (the resource should have the same URI as the RDG).
static RQG createRQG(java.net.URI resourceURI)
          Creates a basic RQG from scratch.
static SSWAPDocument createSSWAPDocument()
          Creates an empty SSWAPDocument.
static SSWAPDocument createSSWAPDocument(java.net.URI uri)
          Creates an empty SSWAPModel.
static Cache getCache()
          Gets a cache used to store ontology terms that were retrieved from the network.
static PDG getPDG(java.net.URI providerURI)
          Creates an object representing an PDG.
static RDG getRDG(java.net.URI uri)
          Creates an object representing an RDG.
static
<T extends SSWAPDocument>
T
getResourceGraph(java.io.InputStream is, java.lang.Class<T> clazz)
          Creates a SSWAPDocument graph from its serialization in an input stream.
static
<T extends SSWAPDocument>
T
getResourceGraph(java.io.InputStream is, java.lang.Class<T> clazz, java.net.URI uri)
          Creates a SSWAPDocument graph from its serialization in an input stream.
static RQG getRQG(java.io.InputStream is)
          Reads an RQG from an input stream.
static VersionInformation getVersionInformation()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

apiProvider

private static APIProvider apiProvider
The current provider of the API. The actual creation of the objects is delegated to that provider. (This allows the API to be pluggable; that is, to easily switch the implementations.) As a general rule, the objects created by two different providers should not be mixed together (e.g., a SSWAPProvider created by one provider should not be added to a PDG created by another provider).

Constructor Detail

SSWAP

public SSWAP()
Method Detail

createRDG

public static RDG createRDG(java.net.URI resourceURI,
                            java.lang.String name,
                            java.lang.String oneLineDescription,
                            java.net.URI providerURI)
                     throws DataAccessException
Creates a new RDG

Parameters:
resourceURI - the URI of the SSWAPResource (and the RDG itself)
name - the name of the resource
oneLineDescription - the one line description of the resource
providerURI - the URI of the provider
Returns:
the newly created RDG object
Throws:
DataAccessException - runtime error if the class cannot be created

createRDG

public static RDG createRDG(java.net.URI resourceURI,
                            java.lang.String name,
                            java.lang.String oneLineDescription,
                            SSWAPProvider provider)
                     throws DataAccessException
Creates a new RDG

Parameters:
resourceURI - the URI of the SSWAPResource (and the RDG itself)
name - the name of the resource
oneLineDescription - the one line description of the resource
provider - the SSWAPProvider for this RDG
Returns:
the newly created RDG object
Throws:
DataAccessException - runtime error if the class cannot be created

createResource

public static SSWAPResource createResource(java.net.URI resourceURI)
                                    throws DataAccessException
Gets a SSWAPResource that is defined in the RDG that exists at the specified URI (the resource should have the same URI as the RDG).

Parameters:
resourceURI - the URI of the resource (and the containing RDG)
Returns:
the SSWAPResource
Throws:
DataAccessException - runtime error if the class cannot be created

getRDG

public static RDG getRDG(java.net.URI uri)
                  throws DataAccessException
Creates an object representing an RDG. The returned object is dereferenced.

Parameters:
uri - the URI of the RDG
Returns:
an RDG that is not dereferenced
Throws:
DataAccessException - runtime error if the class cannot be created

getRQG

public static RQG getRQG(java.io.InputStream is)
                  throws DataAccessException
Reads an RQG from an input stream.

Parameters:
is - the input stream containing the representation of the RQG
Returns:
the RQG
Throws:
DataAccessException - runtime error if the class cannot be created (e.g., I/O error or malformed data that cannot be parsed)

createRQG

public static RQG createRQG(java.net.URI resourceURI)
                     throws DataAccessException
Creates a basic RQG from scratch. The created RQG contains only SSWAPResource.

Parameters:
resourceURI - the URI of the resource in the RQG; may be null for anonymous resources
Returns:
the RQG with a SSWAPResource
Throws:
DataAccessException - runtime error if the class cannot be created

getResourceGraph

public static <T extends SSWAPDocument> T getResourceGraph(java.io.InputStream is,
                                                           java.lang.Class<T> clazz)
                                                throws DataAccessException
Creates a SSWAPDocument graph from its serialization in an input stream. The SSWAPResource will be a blank node. This is usually inappropriate for anything other than a RQG; for other graphs see getResourceGraph(InputStream, Class, URI).

Type Parameters:
T - the template parameter that specifies the type of SSWAPDocument graph to be created (e.g., RQG).
Parameters:
is - the input stream from which the contents of the graph should be read
clazz - the Java Class object that identifies the type of SSWAPDocument graph (and provides the instantiation for the template parameter; e.g., RQG.class)
Returns:
the created SSWAPDocument graph
Throws:
DataAccessException - runtime error if the class cannot be created (including I/O error or malformed data that cannot be parsed)
See Also:
getResourceGraph(InputStream, Class, URI)

getResourceGraph

public static <T extends SSWAPDocument> T getResourceGraph(java.io.InputStream is,
                                                           java.lang.Class<T> clazz,
                                                           java.net.URI uri)
                                                throws DataAccessException
Creates a SSWAPDocument graph from its serialization in an input stream. The SSWAPResource is set to the URI argument.

Type Parameters:
T - the template parameter that specifies the type of SSWAPDocument graph to be created (e.g., PDG, RDG, RIG, or RRG. .
Parameters:
is - the input stream from which the contents of the graph should be read
clazz - the Java Class object that identifies the type of SSWAPDocument graph (and provides the instantiation for the template parameter; e.g., RDG.class, RIG.class, etc.)
uri - the URI to dereference to obtain the graph
Returns:
the created SSWAPDocument graph
Throws:
DataAccessException - runtime error if the class cannot be created (including I/O error or malformed data that cannot be parsed)

getPDG

public static PDG getPDG(java.net.URI providerURI)
                  throws DataAccessException
Creates an object representing an PDG. Initially, the returned object is not dereferenced, and it contains only the URI. Actual retrieval of the contents in the PDG occurs, when dereference() method is called.

Parameters:
providerURI - the URI of the PDG
Returns:
a PDG that is not dereferenced
Throws:
DataAccessException - runtime error if the class cannot be created

createPDG

public static PDG createPDG(java.net.URI providerURI,
                            java.lang.String name,
                            java.lang.String oneLineDescription)
                     throws DataAccessException
Creates a PDG with the specified values.

Parameters:
providerURI - the URI of the provider
name - the name of the provider
oneLineDescription - a one-line description of the PDG
Returns:
the created PDG
Throws:
DataAccessException - runtime error if the class cannot be created

createProvider

public static SSWAPProvider createProvider(java.net.URI providerURI)
                                    throws DataAccessException
Creates an object representing a SSWAPProvider. Initially, the returned object is not dereferenced, and it contains only the URI. When the dereference() method is called on this SSWAPProvider, it will retrieve the contents of the PDG for that SSWAPProvider, and populate the object with the provider data.

Parameters:
providerURI - URI of the SSWAPProvider (and at the same time of the PDG for that SSWAPProvider)
Returns:
an SSWAPProvider that is not dereferenced
Throws:
DataAccessException - runtime error if the class cannot be created

createSSWAPDocument

public static SSWAPDocument createSSWAPDocument()
                                         throws DataAccessException
Creates an empty SSWAPDocument. This method can be used to contain other SSWAPDocuments if it is undesirable to create a full protocol graph or a PDG.

Returns:
the newly created SSWAPDocument
Throws:
DataAccessException - runtime error if the class cannot be created

createSSWAPDocument

public static SSWAPDocument createSSWAPDocument(java.net.URI uri)
                                         throws DataAccessException
Creates an empty SSWAPModel. This method can be used to contain other SSWAPModels if it is undesirable to create a full protocol graph or a PDG.

Parameters:
uri - the URI of the SSWAP model
Returns:
an empty SSWAP model
Throws:
DataAccessException - runtime error if the class cannot be created

getVersionInformation

public static VersionInformation getVersionInformation()

getCache

public static Cache getCache()
Gets a cache used to store ontology terms that were retrieved from the network. This method can be used to control cache features like the time-to-live of entries in the cache or clearing the cache.

Returns:
the cache for ontology terms


Copyright (c) 2011, iPlant Collaborative, University of Arizona, Cold Spring Harbor Laboratories, University of Texas at Austin.