info.sswap.api.model
Interface RIG

All Superinterfaces:
SSWAPDocument, SSWAPModel, SSWAPProtocol

public interface RIG
extends SSWAPProtocol

A Resource Invocation Graph (RIG) is for invocation of a SSWAP semantic web service. An RIG is sent by a client to a SSWAP Resource to invoke the service as described by its Resource Description Graph (RDG). Clients (agents invoking a service) make an RIG by augmenting the RDG of a service with the client's actual invocation values--i.e., the "data"--by adding or editing the SSWAPSubjects. Providers (agents delivering a service) accept RIGs and change them (according to the contract of their RDG into a Resource Response Graph (RRG).

For more on the protocol, see SSWAP Protocol.

Author:
Blazej Bulka , Damian Gessler
See Also:
PDG, RDG, RRG, RQG, SSWAPResource, SSWAPSubject

Method Summary
 RRG getRRG()
          Gets the RRG that can be used to create a response to the RIG.
 RRG getRRG(java.io.InputStream is)
          Creates an RRG based on the serialized RRG data (e.g., sent by a provider of the service in response to this RIG having been sent to the provider).
 SSWAPResource getTranslatedResource()
          Returns a read-only copy of the SSWAPResource with properties and types of this RIG translated into the vocabulary of the RDG.
 java.util.Collection<SSWAPSubject> getTranslatedSubjects()
          Returns a read-only copy of the SSWAPSubject from all matching SSWAPGraphs with properties and types of this RIG translated into the vocabulary of the RDG.
 HTTPProvider.RRGResponse invoke()
          Invokes the service with this RIG, blocks until the service responds, and reads back the RRG.
 HTTPProvider.RRGResponse invoke(long timeout)
          Invokes the service with this RIG, blocks until the service responds, and reads back the RRG
<T extends SSWAPNode>
T
translate(T node)
          Translates a SSWAPNode in this RIG to the vocabulary used by the RDG (the translation only makes sense for SSWAPResources and SSWAPSubjects; for all others the nodes are returned unmodified).
 
Methods inherited from interface info.sswap.api.model.SSWAPProtocol
createGraph, createObject, createObject, createSubject, createSubject, getMappings, getProvider, getResource, isMultiGraphs, isPattern
 
Methods inherited from interface info.sswap.api.model.SSWAPDocument
createAnonymousDatatype, createAnonymousType, createIndividual, createIndividual, createIntersectionOf, createList, createLiteral, createTypedLiteral, createUnionOf, getDatatype, getPredicate, getType, newIndividual, newIndividual
 
Methods inherited from interface info.sswap.api.model.SSWAPModel
addImport, checkProfile, dereference, dereference, doClosure, getDocument, getImports, getInputStream, getNsPrefixMap, getReasoningService, getTypeSignature, getURI, isDereferenced, removeImport, removeNsPrefix, serialize, serialize, setNsPrefix, validate
 

Method Detail

translate

<T extends SSWAPNode> T translate(T node)
Translates a SSWAPNode in this RIG to the vocabulary used by the RDG (the translation only makes sense for SSWAPResources and SSWAPSubjects; for all others the nodes are returned unmodified). The translated node contains only properties that are described in the RDG (this includes using the name of a superproperty, if the RIG used a subproperty with respect to the RDG), and types defined in the RDG.

Parameters:
node - the node that must belong to this RIG
Returns:
a translated node, or null if the node does not belong to this RIG

getRRG

RRG getRRG()
           throws DataAccessException,
                  ValidationException
Gets the RRG that can be used to create a response to the RIG. This method need not be called by clients (creators of the RIG), but is called by providers after they have mutated an incoming RIG so as to create a response. This method enforces that the RIG--as a putative RRG--is validated against the contract of the RDG. Additionally, if the RIG is OWL DL, the RRG must also be OWL DL.

Returns:
the RRG for the RIG.
Throws:
DataAccessException - if an error should occur while accessing the data in the RIG to create the RRG
ValidationException - if the RRG is not valid with respect to the RIG invoking the service

getRRG

RRG getRRG(java.io.InputStream is)
           throws DataAccessException,
                  ValidationException
Creates an RRG based on the serialized RRG data (e.g., sent by a provider of the service in response to this RIG having been sent to the provider).

Parameters:
is - the input stream from which the serialized RRG data can be read
Returns:
the created RRG
Throws:
DataAccessException - if an error should occur while reading the data (either an I/O error or problem parsing the data)
ValidationException - if the RRG is not valid with respect to the RIG for invoking service

invoke

HTTPProvider.RRGResponse invoke()
Invokes the service with this RIG, blocks until the service responds, and reads back the RRG.

Returns:
the returned RRG, if available, and response information from the invocation call

invoke

HTTPProvider.RRGResponse invoke(long timeout)
Invokes the service with this RIG, blocks until the service responds, and reads back the RRG

Parameters:
timeout - connect and read timeout in milliseconds; if communication with the service should stall for more than the specified time the call will be interrupted and the returned RRGResponse will contain the error code.
Returns:
the returned RRG, if available, and response information from the invocation call

getTranslatedResource

SSWAPResource getTranslatedResource()
Returns a read-only copy of the SSWAPResource with properties and types of this RIG translated into the vocabulary of the RDG.

The translated resource contains only properties that are described in the RDG (this includes using the name of a super-property, if the RIG used a subproperty with respect to the RDG), and types defined in the RDG.

Given the translated copy returned by the method, use ExtensionAPI.getUntranslatedNode(SSWAPNode) to retrieve this source individual.

Returns:
a translated resource
See Also:
ExtensionAPI.getUntranslatedNode(SSWAPNode)

getTranslatedSubjects

java.util.Collection<SSWAPSubject> getTranslatedSubjects()
Returns a read-only copy of the SSWAPSubject from all matching SSWAPGraphs with properties and types of this RIG translated into the vocabulary of the RDG. The translated subjects contain only properties that are described in the RDG (this includes using the name of a super-property, if the RIG used a subproperty with respect to the RDG ), and types defined in the RDG.

The special case of SSWAPSubject.addObject(SSWAPObject) and its set() variants are not read-only and changes the underlying SSWAPSubject.

Given the translated copy returned by the method, use ExtensionAPI.getUntranslatedNode(SSWAPNode) to retrieve this source individual.

Returns:
a collection of translated subjects
See Also:
ExtensionAPI.getUntranslatedNode(SSWAPNode)


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