com.ge.research.acuity
Class ControllerInterface

java.lang.Object
  com.ge.research.acuity.ControllerInterface

public class ControllerInterface

extends java.lang.Object

Utility class that acts as an interface between an ACUITy UI application and an ACUITy ontology. Provides convienence methods to: - Process the current contents of the Frame as returned by an AcuityController, and convert those contents into UI objects to be rendered by a client application - Process the missing information of the AcuityController, Frame, and Vantage, as returned by the AcuityController, and converts those contents into UI objects to be rendered by a client application - Update the ontology with new information acquired from a client application

Version:

$Revision: 1.5 $ $Date: 2007/05/19 13:50:31 $

Author:

garbiras

Created on:

Feb 21, 2005

Field Summary

protected java.text.DateFormat

processTimeFormat Format to use to log process times to the console

Constructor Summary

ControllerInterface(AcuityController controller)
Default constructor.

Method Summary

protected com.hp.hpl.jena.rdf.model.StmtIterator	ask(java.lang.String sName, java.lang.String pName, java.lang.String oName) Provides transparent access to the AcuityController.ask(java.lang.String, java.lang.String, java.lang.String) method
protected void	checkController() Checks to see if this class contains a reference to a valid AcuityController
java.util.Map	createHighlightRegionChoiceMap() Creates a choice map associating all known highlight regions with their regions.
PresentationObject	createHighlightRegions(java.util.Map paramsToValues) Iterates over the keys of the paramsToValues Map, for highlight region commands which it uses to create and update individuals in the ontology and session cache.
void	finalize() Releases the references to the InterfaceAdapters and AcuityController for garbage collection.
boolean	focusVantageEstablished() Informs as to whether or not the current session has a current focus vantage
boolean	focusVantageRemoveable() Informs as to whether or not the current focus vantage can be removed from the frame
java.lang.Object[]	getContextInformationAbout(java.lang.String uri)
protected com.hp.hpl.jena.ontology.Individual	getCurrentFocusVantage() Provides transparent access to the AcuityController.getFocusVantageOfFrame(com.hp.hpl.jena.ontology.Individual) method, using the current frame as the argument.
protected com.hp.hpl.jena.ontology.Individual	getCurrentFrame() Provides transparent access to the AcuityController.getFrame() method.
java.lang.String	getCurrentVantage()
java.lang.String	getFrameName()
protected java.lang.String	getFrameProperty(java.lang.String property) Convienence method to retrieve property information from the current frame.
protected java.lang.String	getIndividualProperty(java.lang.String individualURI, java.lang.String property) Convienence method to retrieve property information from the current focus vantage.
protected java.lang.String	getLabel(com.hp.hpl.jena.ontology.Individual resource) Convience method to retrieve the label property value for a given instance.
protected PresentationObject	getPresentationObjectForIndividual(java.lang.String uri) Looks in the session cache for a PresentationObject associated with the individual uri passed in.
protected PresentationObject	getPresentationObjectFromCache(java.lang.String identifier) Looks in the session cache for a PresentationObject identified by its client session identifier.
protected java.lang.String	getVantageProperty(java.lang.String property) Convienence method to retrieve property information from the current focus vantage.
boolean	logProcessTimes() Returns the logProcessTimes value.
java.util.List[]	processFrame() Acquires the current contents of the Frame and Focus Vantage from the controller and converts the ontological representation into UI objects for rendering
java.util.List[]	processFrame(boolean override) Acquires the current contents of the Frame and Focus Vantage from the controller and converts the ontological representation into UI objects for rendering
void	save() Persists the information of the current user session.
void	save(java.lang.String frameName) Persists the information of the current user session.
void	setLogProcessTimes(boolean logProcessTimes) Sets the logProcessTimes attribute
void	setUser(java.lang.String userId) Sets up the information about the current user for the AcuityController session.
void	tell(java.util.Map paramsToValues) Iterates over the keys of the paramsToValues Map, for each parameter attempting to find a corresponding ontology identifier from the internal lookup map, which it uses to update the value of the property with the new value(s) contained in the paramsToValues Map.
protected void	tell(java.lang.String parameter, java.lang.String[] values, boolean updateCacheOnly) Attempts to find a corresponding ontology identifier from the internal lookup map for the parameter, which it uses to update the value of the property with the new values.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

processTimeFormat

protected final java.text.DateFormat processTimeFormat

Format to use to log process times to the console

Constructor Detail

ControllerInterface

public ControllerInterface(AcuityController controller)
                    throws java.lang.IllegalArgumentException

Default constructor. Sets the AcuityController to use, and initializes the internal lookup information.

Parameters:

controller - the AcuityController to use

Throws:

java.lang.IllegalArgumentException - If the controller is null

Method Detail

createHighlightRegions

public final PresentationObject createHighlightRegions(java.util.Map paramsToValues)
                                                throws AcuityException,
                                                       java.lang.IllegalStateException

Iterates over the keys of the paramsToValues Map, for highlight region commands which it uses to create and update individuals in the ontology and session cache.

Parameters:

paramsToValues - the set of client interface requests. The Map keys are expected to be Strings, and the Map values are expected to be of the type String[]

Returns:

The enclosing PresentationObject to use to set up the properties to present to a client application for defining new highlight region to be created; or null if the create or share command was processed instead of the setup command.

Throws:

AcuityException - If the controller throws such an exception creating individuals and/or updating the contents of the current frame

java.lang.IllegalStateException - If no valid AcuityController is found to use

See Also:

HighlightRegionIA.processHighlightRegionRequests(java.util.Map, java.util.List)

createHighlightRegionChoiceMap

public final java.util.Map createHighlightRegionChoiceMap()

Creates a choice map associating all known highlight regions with their regions.

Returns:

A map of region localnames as keys, mapped to their corresponding highlight region URIs

See Also:

HighlightRegionIA.createHighlightRegionChoiceMap()

focusVantageEstablished

public final boolean focusVantageEstablished()

Informs as to whether or not the current session has a current focus vantage

Returns:

true if a focus vantage exists for the session; false otherwise.

focusVantageRemoveable

public final boolean focusVantageRemoveable()

Informs as to whether or not the current focus vantage can be removed from the frame

Returns:

true if a focus vantage can be removed; false otherwise.

getContextInformationAbout

public java.lang.Object[] getContextInformationAbout(java.lang.String uri)
                                              throws AcuityException

Throws:

AcuityException

getCurrentVantage

public java.lang.String getCurrentVantage()
                                   throws AcuityException,
                                          java.lang.IllegalStateException

Throws:

AcuityException

java.lang.IllegalStateException

getFrameName

public final java.lang.String getFrameName()
                                    throws AcuityException,
                                           java.lang.IllegalStateException

Throws:

AcuityException

java.lang.IllegalStateException

logProcessTimes

public final boolean logProcessTimes()

Returns the logProcessTimes value.

Returns:

The logProcessTimes value.

processFrame

public final java.util.List[] processFrame()
                                    throws AcuityException,
                                           java.lang.IllegalStateException

Acquires the current contents of the Frame and Focus Vantage from the controller and converts the ontological representation into UI objects for rendering

Returns:

An array, of size 3, of Lists. The first element in the array is a List of IndependentDisplayPO objects to render for the current frame. The second element in the array is a List of "missing property" InteractionObjects of the current frame. The third element in the array is a List of "errors" IndependentDisplayPOs of the current frame.

Throws:

AcuityException - If the controller throws such an exception processing the contents of the current frame

java.lang.IllegalStateException - If no valid AcuityController is found to use

See Also:

processFrame(boolean)

processFrame

public final java.util.List[] processFrame(boolean override)
                                    throws AcuityException,
                                           java.lang.IllegalStateException

Acquires the current contents of the Frame and Focus Vantage from the controller and converts the ontological representation into UI objects for rendering

Parameters:

override - flag indicating whether or not to override the current state of the refreshNeeded state flag. If true, then the information is refreshed from the ontology, regardless of the refreshNeeded state flag. If false, then only if the refreshNeeded flag is true is the information refreshed from the ontology. Otherwise the current session information is returned.

Returns:

An array, of size 3, of Lists. The first element in the array is a List of IndependentDisplayPO objects to render for the current frame. The second element in the array is a List of "missing property" InteractionObjects of the current frame. The third element in the array is a List of "errors" IndependentDisplayPOs of the current frame.

Throws:

AcuityException - If the controller throws such an exception processing the contents of the current frame

java.lang.IllegalStateException - If no valid AcuityController is found to use

save

public final void save()
                throws AcuityException,
                       java.lang.IllegalStateException

Persists the information of the current user session. The session is identified by the system default identifier.

Throws:

AcuityException - If the controller throws such an exception persisting the information of the current session

java.lang.IllegalStateException - If no valid AcuityController is found to use

save

public final void save(java.lang.String frameName)
                throws AcuityException,
                       java.lang.IllegalStateException

Persists the information of the current user session. The session is identified by the supplied identifier, or the system default identifier if the supplied identifier is null.

Parameters:

frameName - the name by which to identify this session

Throws:

AcuityException - If the controller throws such an exception persisting the information of the current session

java.lang.IllegalStateException - If no valid AcuityController is found to use

setLogProcessTimes

public final void setLogProcessTimes(boolean logProcessTimes)

Sets the logProcessTimes attribute

Parameters:

logProcessTimes - the logProcessTimes to set.

setUser

public final void setUser(java.lang.String userId)
                   throws AcuityException,
                          java.lang.IllegalStateException

Sets up the information about the current user for the AcuityController session.

Throws:

AcuityException - If the controller throws such an exception setting up the information about the current AcuityController user

java.lang.IllegalStateException - If no valid AcuityController is found to use

tell

public final void tell(java.util.Map paramsToValues)
                throws AcuityException,
                       java.lang.IllegalStateException

Iterates over the keys of the paramsToValues Map, for each parameter attempting to find a corresponding ontology identifier from the internal lookup map, which it uses to update the value of the property with the new value(s) contained in the paramsToValues Map.

Parameters:

paramsToValues - the set of client interface requests. The Map keys are expected to be Strings, and the Map values are expected to be of the type String[]

Throws:

AcuityException - If the controller throws such an exception updating the contents of the current frame

java.lang.IllegalStateException - If no valid AcuityController is found to use

See Also:

tell(java.lang.String, java.lang.String[], boolean), InteractionContentIA.processAnswer(java.lang.String, java.lang.String[], boolean), HighlightRegionIA.processHighlightRegionRequests(java.util.Map, java.util.List), CloningIA.processCloneRequests(java.util.Map, boolean, java.util.List), RemovalIA.processRemoveRequests(java.util.Map, java.util.List, boolean, java.util.List), FormProcessingIA.process(com.ge.research.acuity.ui.DisplayGroupPO, java.util.Map, java.util.List)

finalize

public void finalize()

Releases the references to the InterfaceAdapters and AcuityController for garbage collection.

ask

protected final com.hp.hpl.jena.rdf.model.StmtIterator ask(java.lang.String sName,
                                                           java.lang.String pName,
                                                           java.lang.String oName)
                                                    throws AcuityException,
                                                           java.lang.IllegalStateException

Provides transparent access to the AcuityController.ask(java.lang.String, java.lang.String, java.lang.String) method

Parameters:

sName - the name (URI) of the subject of the question or null if the subject is unspecified

pName - the name (URI) of the predicate of the question or null if the predicate is unspecified

oName - the String identifying the object of the question or null if the object is unspecified

Returns:

An iterator over the set of Statements which match the inputs

Throws:

AcuityException - If the controller throws such an exception querying the ontology

java.lang.IllegalStateException - If no valid AcuityController is found to use

See Also:

AcuityController.ask(java.lang.String, java.lang.String, java.lang.String)

checkController

protected final void checkController()
                              throws java.lang.IllegalStateException

Checks to see if this class contains a reference to a valid AcuityController

Throws:

java.lang.IllegalStateException - If the class reference to the AcuityController is null.

getCurrentFocusVantage

protected final com.hp.hpl.jena.ontology.Individual getCurrentFocusVantage()
                                                                    throws AcuityException,
                                                                           java.lang.IllegalStateException

Provides transparent access to the AcuityController.getFocusVantageOfFrame(com.hp.hpl.jena.ontology.Individual) method, using the current frame as the argument.

Returns:

The current focus vantage of the current frame being used

Throws:

AcuityException - If the controller throws such an exception getting the current frame or its focus vantage

java.lang.IllegalStateException - If no valid AcuityController is found to use

See Also:

getCurrentFrame(), AcuityController.getFocusVantageOfFrame(com.hp.hpl.jena.ontology.Individual)

getCurrentFrame

protected final com.hp.hpl.jena.ontology.Individual getCurrentFrame()
                                                             throws AcuityException,
                                                                    java.lang.IllegalStateException

Provides transparent access to the AcuityController.getFrame() method.

Returns:

The current frame being used

Throws:

AcuityException - If the controller throws such an exception getting the current frame

java.lang.IllegalStateException - If no valid AcuityController is found to use

See Also:

AcuityController.getFrame()

getFrameProperty

protected final java.lang.String getFrameProperty(java.lang.String property)
                                           throws AcuityException,
                                                  java.lang.IllegalStateException

Convienence method to retrieve property information from the current frame. The supplied property should be an OntProperty for a Frame.

Parameters:

property - the OntProperty of the current frame, to find the value of

Returns:

The current value of the frame property

Throws:

AcuityException - If the controller throws such an exception getting the current frame, or getting the property of the current frame

java.lang.IllegalStateException - If no valid AcuityController is found to use

See Also:

getCurrentFrame(), getIndividualProperty(java.lang.String, java.lang.String)

getIndividualProperty

protected final java.lang.String getIndividualProperty(java.lang.String individualURI,
                                                       java.lang.String property)
                                                throws AcuityException,
                                                       java.lang.IllegalStateException

Convienence method to retrieve property information from the current focus vantage. The supplied property should be an OntProperty for a Vantage.

Parameters:

individualURI - the URI of the individual, to find the property value of

property - the OntProperty of the individual, to find the value of

Returns:

The current value of the property for the individual

Throws:

AcuityException - If the controller throws such an exception getting getting the property of the individual

java.lang.IllegalStateException - If no valid AcuityController is found to use

See Also:

ask(java.lang.String, java.lang.String, java.lang.String)

getLabel

protected final java.lang.String getLabel(com.hp.hpl.jena.ontology.Individual resource)
                                   throws AcuityException

Convience method to retrieve the label property value for a given instance.

Parameters:

resource - the individual to retrieve the label property for

Returns:

The label property for the individual

Throws:

AcuityException - If the controller throws such an exception getting the current focus vantage, or getting the property of the vantage

See Also:

AcuityController.getIndividualLabel(java.lang.String), AcuityController.getIndividualLocalName(com.hp.hpl.jena.ontology.Individual)

getPresentationObjectFromCache

protected final PresentationObject getPresentationObjectFromCache(java.lang.String identifier)

Looks in the session cache for a PresentationObject identified by its client session identifier. If found it is returned, else returns null.

Parameters:

identifier - the client session identifier for the PresentationObject desired

Returns:

The PresentationObject asscoiated with the identifier, or null if no match is found.

getPresentationObjectForIndividual

protected final PresentationObject getPresentationObjectForIndividual(java.lang.String uri)
                                                               throws AcuityException

Looks in the session cache for a PresentationObject associated with the individual uri passed in. If found it is returned, else returns null.

Parameters:

uri - the uri of the individual to find the PresentationObject for

Returns:

The PresentationObject for the individual, or null if no match is found.

Throws:

AcuityException

getVantageProperty

protected final java.lang.String getVantageProperty(java.lang.String property)
                                             throws AcuityException,
                                                    java.lang.IllegalStateException

Convienence method to retrieve property information from the current focus vantage. The supplied property should be an OntProperty for a Vantage.

Parameters:

property - the OntProperty of the current focus vantage, to find the value of

Returns:

The current value of the vantage property

Throws:

AcuityException - If the controller throws such an exception getting the current focus vantage, or getting the property of the vantage

java.lang.IllegalStateException - If no valid AcuityController is found to use

See Also:

getCurrentFocusVantage(), getIndividualProperty(java.lang.String, java.lang.String)

tell

protected final void tell(java.lang.String parameter,
                          java.lang.String[] values,
                          boolean updateCacheOnly)
                   throws AcuityException

Attempts to find a corresponding ontology identifier from the internal lookup map for the parameter, which it uses to update the value of the property with the new values.

Parameters:

parameter - the ParameterLookupInfo and property identifier, which yields the property of the PresentationParameterMap to be updated in the ontology.

values - the list of values for the property, as returned by the client application

updateCacheOnly - flag indicating whether or not the ontology is updated with this new value; true does not update the ontology, only the ui object cache; false updates the ontology as well as the ui object cache.

Throws:

AcuityException - If the controller throws such an exception updating the contents of the current frame