info.sswap.api.servlet
Class MapsTo

java.lang.Object
  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
private SimpleSSWAPServlet	servlet
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, java.net.URI uri, SSWAPObject sswapObject) If the argument URI is different from the sswapObject URI, then schedule to assignObject(SSWAPSubject,URI) and unassignObject(SSWAPSubject,SSWAPObject).
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

servlet

private SimpleSSWAPServlet servlet

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)

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.

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