info.sswap.api.servlet
Class MapsTo

java.lang.Object
  extended by info.sswap.api.servlet.MapsTo

public abstract class MapsTo
extends java.lang.Object

A helper class that allows the mapping of subjects to objects without the complexities of servlet programming. This class is instantiated anew for each request, so unlike servlet programming, instance variables in the class are not shared across requests (there is no danger of one request reading or writing to a non-static variable of another request). To use, extend this class to perform the mapping; e.g.,:

 public class MyService extends MapsTo {
 
   @Override
   protected void mapsTo(SSWAPSubject translatedSubject) {
 
    // inspect the subject and edit/add its objects
   }
 }
 
Then connect MyService to a servlet launcher via a class extending SimpleSSWAPServlet.

This class handles processing the RIG; each translated subject will be passed to mapsTo, which will be called once for each valid subject in the RIG.

Author:
Damian Gessler
See Also:
SimpleSSWAPServlet

Field Summary
protected  RIG rig
           
protected  java.util.Set<SSWAPObject> sswapObjects
           
 
Constructor Summary
MapsTo()
           
 
Method Summary
 SSWAPObject assignObject(SSWAPSubject sswapSubject)
          A convenience method for assignObject(SSWAPSubject, URI) for an anonymous sswapObject (URI == null).
 SSWAPObject assignObject(SSWAPSubject sswapSubject, java.net.URI uri)
          An efficient manner to create a new URI SSWAPObject and schedule it for adding to the translatedSubject.
protected  void finalizeRequest(java.lang.Exception exception)
          This method is called once, at the end of the request.
 SimpleSSWAPServlet getServlet()
          The servlet for which this service class is performing.
protected  void initializeRequest(RIG rig)
          This method is called once, at the beginning of the request.
protected abstract  void mapsTo(SSWAPSubject translatedSubject)
          Define this method to perform the mapping from the translated subject to its objects.
 SSWAPObject replaceObject(SSWAPSubject sswapSubject, SSWAPObject sswapObject, java.net.URI uri)
          If the argument URI is different from the sswapObject URI, then schedule to assignObject(SSWAPSubject,URI) and unassignObject(SSWAPSubject,SSWAPObject).
 SSWAPObject replaceObject(SSWAPSubject sswapSubject, java.net.URI uri, SSWAPObject sswapObject)
          Deprecated. Use replaceObject(SSWAPSubject,SSWAPObject,URI) instead
 void setRIG(RIG rig)
          The RIG for this mapping; this should be set at the first opportunity (e.g. in initializeRequest.
protected  void setServlet(SimpleSSWAPServlet servlet)
           
 void unassignObject(SSWAPSubject sswapSubject, SSWAPObject sswapObject)
          Schedules a sswapObject to be unassigned (removed) from a mapping to the sswapSubject.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

rig

protected RIG rig

sswapObjects

protected java.util.Set<SSWAPObject> sswapObjects
Constructor Detail

MapsTo

public MapsTo()
Method Detail

setRIG

public void setRIG(RIG rig)
The RIG for this mapping; this should be set at the first opportunity (e.g. in initializeRequest. This is a convenience setter; there is no getter: subclasses can access the instance variable rig directly.

Parameters:
rig - RIG for the mapping. All subsequent SSWAPSubjects and SSWAPObjects should be from this rig.

getServlet

public SimpleSSWAPServlet getServlet()
The servlet for which this service class is performing.

Returns:
the super class, which may be down-cast to the specific servlet type

setServlet

protected void setServlet(SimpleSSWAPServlet servlet)

initializeRequest

protected void initializeRequest(RIG rig)
                          throws java.lang.Exception
This method is called once, at the beginning of the request. By default, it is empty; override to do operations (e.g., open a database connection).

Parameters:
rig - the Resource Invocation Graph (RIG) of the request
Throws:
java.lang.Exception - any exception thrown from the overridden method

finalizeRequest

protected void finalizeRequest(java.lang.Exception exception)
                        throws java.lang.Exception
This method is called once, at the end of the request. By default (e.g. either not overriding or by calling super(exception)), it rethrows the exception (if not null); override to do operations (e.g., close a database connection).

On success, exception will be null; on entering this method because of a thrown exception, the exception will be passed and may be consumed or rethrown. Rethrown exceptions are wrapped as RuntimeExceptions and passed up to the caller.

Parameters:
exception - exception thrown by initializeRequest(RIG) or mapsTo(SSWAPSubject); null on success
Throws:
java.lang.Exception - any exception thrown from the overridden method, or the argument exception if not overridden and not null

mapsTo

protected abstract void mapsTo(SSWAPSubject translatedSubject)
                        throws java.lang.Exception
Define this method to perform the mapping from the translated subject to its objects.

In general, if the operation on the object is the same for any object, then inspect the subject's objects and edit them as appropriate. If it is a 1:many mapping, where each object gets a different state, then if there are no matching objects, build new objects for the subject via newObject() to complete the mapping.

Parameters:
translatedSubject - SSWAPSubject after ontology reasoning so that the properties and types of the subject are in the vocabularies of the RDG
Throws:
java.lang.Exception - thrown exception will be passed to finalizeRequest(java.lang.Exception)
See Also:
assignObject(SSWAPSubject), assignObject(SSWAPSubject,URI), RIG.getTranslatedSubjects()

assignObject

public SSWAPObject assignObject(SSWAPSubject sswapSubject)
A convenience method for assignObject(SSWAPSubject, URI) for an anonymous sswapObject (URI == null).

Parameters:
sswapSubject - subject of the mapping
Returns:
a new SSWAPObject ready for editing
See Also:
RIG.getTranslatedSubjects()

assignObject

public SSWAPObject assignObject(SSWAPSubject sswapSubject,
                                java.net.URI uri)
An efficient manner to create a new URI SSWAPObject and schedule it for adding to the translatedSubject. This method is preferred over those in SSWAPProtocol and SSWAPSubject when adding many SSWAPObjects to a single SSWAPSubject (1:many mapping) repetitively in a loop. Assignment to the SSWAPSubject is delayed until mapsTo(SSWAPSubject) is completed. Add/set properties and types to this object to complete it.

Parameters:
sswapSubject - subject of the mapping
uri - URI of the SSWAPObject; null for a blank node
Returns:
a new SSWAPObject ready for editing
See Also:
RIG.getTranslatedSubjects()

unassignObject

public void unassignObject(SSWAPSubject sswapSubject,
                           SSWAPObject sswapObject)
Schedules a sswapObject to be unassigned (removed) from a mapping to the sswapSubject. The object does not have to be first assigned by assignObject(SSWAPSubject,URI), but may be any SSWAPObject of the sswapSubject. Actual removal is delayed until the completion of mapsTo(SSWAPSubject).

Parameters:
sswapSubject - subject of the mapping
sswapObject - object to schedule for removal

replaceObject

public SSWAPObject replaceObject(SSWAPSubject sswapSubject,
                                 java.net.URI uri,
                                 SSWAPObject sswapObject)
Deprecated. Use replaceObject(SSWAPSubject,SSWAPObject,URI) instead

If the argument URI is different from the sswapObject URI, then schedule to assignObject(SSWAPSubject,URI) and unassignObject(SSWAPSubject,SSWAPObject). A null argument URI always results in a scheduled replacement.

In the act of replacing the sswapObject with a new object (at the URI), the new object will include the types and properties of the source object.

Parameters:
sswapSubject - subject of the mapping
sswapObject - object to schedule for possible replacement (unassignment)
uri - URI of the new SSWAPObject; null for a blank node
Returns:
a new SSWAPObject ready for editing, or null if nothing was scheduled

replaceObject

public SSWAPObject replaceObject(SSWAPSubject sswapSubject,
                                 SSWAPObject sswapObject,
                                 java.net.URI uri)
If the argument URI is different from the sswapObject URI, then schedule to assignObject(SSWAPSubject,URI) and unassignObject(SSWAPSubject,SSWAPObject). A null argument URI always results in a scheduled replacement.

In the act of replacing the sswapObject with a new object (at the URI), the new object will include the types and properties of the source object.

Parameters:
sswapSubject - subject of the mapping
sswapObject - object to schedule for possible replacement (unassignment)
uri - URI of the new SSWAPObject; null for a blank node
Returns:
a new SSWAPObject ready for editing, or null if nothing was scheduled


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