info.sswap.api.model
Interface SSWAPModel

All Known Subinterfaces:
PDG, RDG, RIG, RQG, RRG, SourceModel, SSWAPDatatype, SSWAPDocument, SSWAPElement, SSWAPGraph, SSWAPIndividual, SSWAPList, SSWAPLiteral, SSWAPNode, SSWAPObject, SSWAPPredicate, SSWAPProperty, SSWAPProtocol, SSWAPProvider, SSWAPResource, SSWAPSubject, SSWAPType
All Known Implementing Classes:
DatatypeImpl, ElementImpl, EmpireGeneratedNodeImpl, GraphImpl, IndividualImpl, ListImpl, Literal, ModelImpl, NodeImpl, NonEmpireIndividual, ObjectImpl, PDGImpl, PredicateImpl, PropertyImpl, ProtocolImpl, ProviderImpl, RDGImpl, ResourceImpl, RIGImpl, RQGImpl, RRGImpl, SourceModelImpl, SubjectImpl, TranslatedSubjectImpl, TypeImpl

public interface SSWAPModel

The most abstract interface in the SSWAP Java API. Represents any fragment represented by the underlying RDF data (model). When created, a SSWAPModel may represent only the URI to a concept (e.g., a URI to a resource) rather than the actual RDF data stored at that URI. Such a SSWAPModel is called "not dereferenced" (i.e., its isDereferenced() method returns false). In order to actually retrieve the data and populate the model, it is necessary to call the dereference() method. This is usually done automatically by the API when it first uses a non-dereferenced model to satisfy a particular task.

For objects that are not dereferenced, the only available methods are getURI(), isDereferenced(), and dereference(). All other methods should not be called (there is no data for them yet), and in general, most of them will return null in such a case.

It is possible for a SSWAP model to be already dereferenced when created. This typically occurs when an underlying source has already been dereferenced (e.g., a PDG), and then a method to retrieve an object within that source of data is called (e.g., getProvider() to get provider data that is already present within that PDG).

Author:
Blazej Bulka

Method Summary
 void addImport(java.net.URI uri)
          Adds an import to the list of OWL imports of this model.
 boolean checkProfile(Expressivity expressivity)
          Checks whether the model fits a particular expressivity profile (e.g., OWL2 DL)
 void dereference()
          If the object is not dereferenced, it dereferences it.
 void dereference(java.io.InputStream is)
          Dereferences the object (if it is not yet dereferenced) but it reads the data from the given stream, rather than trying to to retrieve the URI of this object.
 int doClosure()
          For every URI in the model, do successive HTTP GETs and read in the model.
 SSWAPDocument getDocument()
          Retrieves the document that contains this SSWAPModel
 java.util.Collection<java.lang.String> getImports()
          Gets the list of OWL imports in this model (the top-level only).
 java.io.InputStream getInputStream()
          Get input stream suitable for reading the serialized model.
 java.util.Map<java.lang.String,java.lang.String> getNsPrefixMap()
          Gets the map of currently defined namespace prefixes.
 ReasoningService getReasoningService()
          Gets the reasoning service associated with the underlying RDF data
 java.util.Collection<java.net.URI> getTypeSignature(java.net.URI type)
          Get the terms that comprise the definition of a URI term.
 java.net.URI getURI()
          Get the URI.
 boolean isDereferenced()
          Returns whether this object represents a dereferenced content stored under the URI, or is it just the URI.
 void removeImport(java.net.URI uri)
          Removes an import from the list of imports
 void removeNsPrefix(java.lang.String prefix)
          Removes a namespace prefix.
 void serialize(java.io.OutputStream os)
          Serializes the contents of this object to the specified stream as RDF/XML.
 void serialize(java.io.OutputStream os, RDFRepresentation representation, boolean commentedOutput)
          Serializes the contents of this object to the specified stream.
 void setNsPrefix(java.lang.String prefix, java.net.URI uri)
          Sets a namespace prefix that will be used in serialization of this model.
 void validate()
          Verifies whether the underlying RDF data conforms to SSWAP syntax and requirements.
 

Method Detail

getURI

java.net.URI getURI()
Get the URI. For RDGs, RIGs, and RRGs, return the URI of the sswapResource (for RQGs, leave undefined for now). For PDGs return the URI of the sswapProvider. Return null on failure.

Returns:
the URI, such that if the model is serialized and hosted on the web, when dereferenced retrieves the model

isDereferenced

boolean isDereferenced()
Returns whether this object represents a dereferenced content stored under the URI, or is it just the URI. For objects that have not been dereferenced, the only valid methods are getURI(), isDereferenced(), and dereference().

Returns:
true if the object has already been dereferenced

getInputStream

java.io.InputStream getInputStream()
Get input stream suitable for reading the serialized model.

Returns:
An input stream suitable for reading

serialize

void serialize(java.io.OutputStream os)
Serializes the contents of this object to the specified stream as RDF/XML.

Parameters:
os - output stream

serialize

void serialize(java.io.OutputStream os,
               RDFRepresentation representation,
               boolean commentedOutput)
Serializes the contents of this object to the specified stream.

Parameters:
os - output stream
representation - the representation, in which the contents should be written (e.g., RDF/XML).
commentedOutput - true, if the output should contain comments about various standard sections of an RDG (valid only for RDF/XML)

dereference

void dereference()
                 throws java.lang.IllegalStateException,
                        java.lang.IllegalArgumentException,
                        DataAccessException
If the object is not dereferenced, it dereferences it. This involves retrieving the underlying RDF data, and may result in a network connection.

Throws:
java.lang.IllegalStateException - if the object has already been dereferenced.
java.lang.IllegalArgumentException - if this object does not have an URI, or the URI does not form a valid URL
DataAccessException - if an error occurred while trying to read the data (e.g., the data source is unavailable or it is impossible to parse)

dereference

void dereference(java.io.InputStream is)
                 throws java.lang.IllegalStateException,
                        java.lang.IllegalArgumentException,
                        DataAccessException
Dereferences the object (if it is not yet dereferenced) but it reads the data from the given stream, rather than trying to to retrieve the URI of this object. (Avoids network connectivity.)

Parameters:
is - the input stream from which the data should be read instead of establishing a network connection
Throws:
java.lang.IllegalStateException - if the object has already been dereferenced.
java.lang.IllegalArgumentException - if this object does not have an URI, or the URI does not form a valid URL
DataAccessException - if an error occurred while trying to read the data (e.g., the data source is unavailable or it is impossible to parse)

doClosure

int doClosure()
For every URI in the model, do successive HTTP GETs and read in the model. Assume RDF/XML. Closure obeys rules of self-definition. Dereferencing is limited by depth and response time, such that performing a closure results in many HTTP GET calls; the result of which may differ depending on network conditions and third-party server response.

Returns:
the highest (deepest) level of closure achieved.

validate

void validate()
              throws ValidationException
Verifies whether the underlying RDF data conforms to SSWAP syntax and requirements.

Throws:
ValidationException - if the data violates SSWAP syntax or requirements

checkProfile

boolean checkProfile(Expressivity expressivity)
Checks whether the model fits a particular expressivity profile (e.g., OWL2 DL)

Parameters:
expressivity - expressivity profile
Returns:
true if the model fits the specified expressivity

getReasoningService

ReasoningService getReasoningService()
Gets the reasoning service associated with the underlying RDF data

Returns:
the reasoning service

setNsPrefix

void setNsPrefix(java.lang.String prefix,
                 java.net.URI uri)
Sets a namespace prefix that will be used in serialization of this model.

Parameters:
prefix - the prefix
uri - the corresponding URI

removeNsPrefix

void removeNsPrefix(java.lang.String prefix)
Removes a namespace prefix. (The prefixes are used in serialization of this model.)

Parameters:
prefix - the prefix to be removed.

getNsPrefixMap

java.util.Map<java.lang.String,java.lang.String> getNsPrefixMap()
Gets the map of currently defined namespace prefixes. (These prefixes are used in serialization of this model.)

Returns:
the map mapping prefixes to corresponding URIs

getImports

java.util.Collection<java.lang.String> getImports()
Gets the list of OWL imports in this model (the top-level only).

Returns:
a collection of uris of the imports

addImport

void addImport(java.net.URI uri)
Adds an import to the list of OWL imports of this model. Adding a URI to the list of imports does not trigger the import itself (use doClosure()) for that purpose.

Parameters:
uri - the URI of the import to be added

removeImport

void removeImport(java.net.URI uri)
Removes an import from the list of imports

Parameters:
uri - the import to be removed

getDocument

SSWAPDocument getDocument()
Retrieves the document that contains this SSWAPModel

Returns:
SSWAPDocument

getTypeSignature

java.util.Collection<java.net.URI> getTypeSignature(java.net.URI type)
Get the terms that comprise the definition of a URI term. Results may be returned for any URI, but expected use is for cases where the URI is an OWL class (or type).

Parameters:
type - URI to a resource or subject of RDF statements
Returns:
For named (non-anonymous) types, return a Collection of solely the type itself; for anonymous types, return a Collection of all terms used to define the type (.e.g, terms used within owl:Restriction, etc.).


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