com.oakgrovesystems.reactor.requests
Class ReactorRequest

java.lang.Object
  |
  +--com.oakgrovesystems.reactor.requests.ReactorRequest
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
AddStatus, CloneInstance, Create, Delete, Get, GetOperandIdsByLabelAndValue, GetProcessIdsForOperandsByLabelAndValue, LockingBase, Login, Logout, QueryGeneral, QueryRequest, RemoveStatus, SetACL, SetObjects, Start, Stop

public abstract class ReactorRequest
extends java.lang.Object
implements java.io.Serializable

The superclass of the helper objects used to facilitate creation and fulfillment of requests to the Reactor system.

Requests to the Reactor system are composed of a request type, an authentication token, and a set of request-specific named parameters.

The request type indicates what kind of request is to be fulfilled. For example, the request type 'authentication_login' indicates that the request is a login request. The request type 'process_command_start' indicates that a Reactor Process is to be started.

The authentication token is a String that identifies the requester as an authenticated Reactor user. Authentication tokens are generated by the Reactor system in response to successful authentication requests. An authentication token is required for most types of requests to the Reactor system; the obvious exception being a login request. Authentication tokens may expire after a reasonable period of time.

The request parameters store details necessary for the fulfillment of the request. For example, a login request requires a username and password; a start request requires the identifier of the Process to start.

Subclasses of ReactorRequest make configuring requests easy by automatically setting the request type to the appropriate value and providing type-safe helper methods to use to set request-specific parameters.

So to make a request of the Reactor system, follow the steps below:

  1. Create an instance of the subclass of ReactorRequest corresponding to the type of request you wish to make.
  2. Call setAuthToken() on your ReactorRequest (unless you don't have an authentication token and are sending a login request).
  3. Call the setter methods for the parameters specific to that request.
  4. Call the send() method of your ReactorRequest.

See Also:
Serialized Form

Field Summary
protected  com.oakgrovesystems.reactor.processMediation.xml.OperandOutputter operandOutputter
           
protected  com.oakgrovesystems.reactor.processMediation.xml.PolicyOutputter policyOutputter
           
protected  com.oakgrovesystems.reactor.processMediation.xml.ProcessOutputter processOutputter
           
protected  com.oakgrovesystems.reactor.processMediation.xml.StatusOutputter statusOutputter
           
 
Constructor Summary
ReactorRequest()
           
 
Method Summary
 void configureFromXML(com.oakgrovesystems.xml.XMLObject request)
          configures this ReactorRequest from its XML representation
 void configureFromXML(com.oakgrovesystems.xml.XMLObject request, com.oakgrovesystems.reactor.LabelPathToIdMapper mapper)
          configures this ReactorRequest from its XML representation
 com.oakgrovesystems.xml.XMLObject createResponseXML(com.oakgrovesystems.reactor.ReactorResponse response)
          Creates the XML representation of a response from its ReactorResponse Java representation.
 com.oakgrovesystems.xml.XMLObject createResponseXML(com.oakgrovesystems.reactor.ReactorResponse response, com.oakgrovesystems.reactor.IdToLabelPathMapper mapper)
          Creates the XML representation of a response from its ReactorResponse Java representation.
protected static org.jdom.Element createReturnValuesElem(java.lang.String[][] returns)
          Creates a 'return_values' JDOM Element from the given array of key-value pairs.
protected  org.jdom.Element createRtnValXML(com.oakgrovesystems.reactor.ReactorResponse response, com.oakgrovesystems.reactor.IdToLabelPathMapper mapper)
          This (superclass) implementation simply returns null, which is perfect for requests that don't have return values.
 java.lang.String getAuthToken()
          Gets the authentication token for this request.
protected static com.oakgrovesystems.reactor.LabelPath getLabelPath(org.jdom.Element parent)
          If the Element specified has an 'object_reference' child and that child has a 'label_path' child, then the method returns a ReactorObjectId instantiated from the 'label_path' Element.
protected static com.oakgrovesystems.reactor.ReactorObjectId getObjectId(org.jdom.Element parent)
          If the Element specified has an 'object_reference' child and that child has an 'id' child, then the method returns a ReactorObjectId instantiated from the text content of the 'id' Element.
 java.lang.Object getParameter(java.lang.String name)
          Returns the value of the named request parameter.
 java.lang.Object getParameter(java.lang.String name, java.lang.Class type)
          Returns the value of the named request parameter if the value is assignment compatible with the given class.
 java.util.Set getParameterNames()
          returns a set containing the names of the request parameters that have been set.
 java.lang.String getRequestType()
          Gets the request type for this request.
protected  java.lang.String makeAuthTokenXML(java.lang.String token)
           
protected  org.jdom.Element makeObjectElement(java.lang.Object obj)
           
protected  org.jdom.Element makeOperandElement(com.oakgrovesystems.reactor.processMediation.Operand obj)
           
protected  org.jdom.Element makePolicyElement(com.oakgrovesystems.reactor.processMediation.Policy obj)
           
protected  org.jdom.Element makeProcessElement(com.oakgrovesystems.reactor.processMediation.Process obj)
           
protected  org.jdom.Element makeReferenceElement(com.oakgrovesystems.reactor.ReactorObjectId id, com.oakgrovesystems.reactor.LabelPath labelPath)
           
protected  org.jdom.Element makeStatusElement(com.oakgrovesystems.reactor.processMediation.Status obj)
           
protected abstract  java.util.List paramsToXML()
          Returns a List of Elements representing the parameters of the request
protected abstract  void parseParameters(org.jdom.Element params, com.oakgrovesystems.reactor.LabelPathToIdMapper mapper)
          Configures the parameters from the XML representation
 com.oakgrovesystems.reactor.ReactorResponse parseResponse(com.oakgrovesystems.xml.XMLObject xml)
          Parses an XML response to this ReactorRequest.
protected abstract  com.oakgrovesystems.reactor.ReactorResponse parseReturnValues(org.jdom.Element returnValues)
           
 com.oakgrovesystems.reactor.ReactorResponse send()
          Sends the request to Reactor to be fulfilled.
 com.oakgrovesystems.xml.XMLObject sendAsXML(java.net.URL xmlServerURL)
          Sends the request to Reactor's XML Front Desk servlet for fulfillment.
 com.oakgrovesystems.reactor.ReactorResponse sendViaHttp(java.net.URL xmlServerURL)
          Sends the request to Reactor's XML Front Desk servlet for fulfillment, and then parses the XML response into a ReactorResponse.
 void setAuthToken(java.lang.String authToken)
          Sets the authentication token for this request.
protected  void setParameter(java.lang.String name, java.lang.Object value)
          sets a request parameter for this request
protected  void setRequestType(java.lang.String requestType)
          Sets the type of request.
 java.lang.String toString()
          Returns a String representation of this ReactorRequest
 com.oakgrovesystems.xml.XMLObject toXML()
          Creates an XML representation of this request suitable for sending to Reactor's XML Front Desk servlet.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

processOutputter

protected com.oakgrovesystems.reactor.processMediation.xml.ProcessOutputter processOutputter

operandOutputter

protected com.oakgrovesystems.reactor.processMediation.xml.OperandOutputter operandOutputter

statusOutputter

protected com.oakgrovesystems.reactor.processMediation.xml.StatusOutputter statusOutputter

policyOutputter

protected com.oakgrovesystems.reactor.processMediation.xml.PolicyOutputter policyOutputter
Constructor Detail

ReactorRequest

public ReactorRequest()
Method Detail

getRequestType

public java.lang.String getRequestType()
Gets the request type for this request.

Returns:
the request type for this request

setRequestType

protected void setRequestType(java.lang.String requestType)
Sets the type of request. Examples of request types are 'authentication_login' (a login request) and 'process_command_start' (a request to start a Process) Each request type has its own subclass of ReactorRequest. This method is called by the subclass.

Parameters:
requestType - the type of this request

getAuthToken

public java.lang.String getAuthToken()
Gets the authentication token for this request. Authentication tokens are Strings that are used to identify the requestor as an authenticated user of Reactor. They are generated by the Reactor system in response to successful login attempts. Authentication tokens may expire after a certain amount of time elapses.

Returns:
the authentication token for this request.

setAuthToken

public void setAuthToken(java.lang.String authToken)
Sets the authentication token for this request. May be null in the case of an authentication request. Authentication tokens are Strings that are used to identify the requestor as an authenticated user of Reactor. They are generated by the Reactor system in response to successful login attempts. Authentication tokens may expire after a certain amount of time elapses.


getParameter

public java.lang.Object getParameter(java.lang.String name,
                                     java.lang.Class type)
Returns the value of the named request parameter if the value is assignment compatible with the given class.

Parameters:
name - the name of the parameter to get
type - the Class of the value of the named parameter
Returns:
the value of the named parameter if the value is assignment compatible with the given class. Null if the parameter does not exist or is not assignment compatible with the given class.

getParameter

public java.lang.Object getParameter(java.lang.String name)
Returns the value of the named request parameter. Does not provide the type checking that getParameter(String,Class) provides. Use getParameter(String,Class) where possible.

Parameters:
name - the name of the parameter to get
Returns:
the value of the named parameter

getParameterNames

public java.util.Set getParameterNames()
returns a set containing the names of the request parameters that have been set.

Returns:
a set containing the names of the request parameters that have been set.

setParameter

protected void setParameter(java.lang.String name,
                            java.lang.Object value)
sets a request parameter for this request

Parameters:
name - the name of the parameter to set
value - the value to which the named parameter should be set

toString

public java.lang.String toString()
Returns a String representation of this ReactorRequest

Overrides:
toString in class java.lang.Object
Returns:
a String representation of this ReactorRequest

send

public com.oakgrovesystems.reactor.ReactorResponse send()
Sends the request to Reactor to be fulfilled. Uses Reactor's EJB interface (a.k.a. the stateless session EJB called "ReactorEJBFrontDesk").

Returns:
A Response Object that indicates the success or failure of the attempt to fulfill the request, as well as any return values resulting from successful fulfillment of the request.

sendViaHttp

public com.oakgrovesystems.reactor.ReactorResponse sendViaHttp(java.net.URL xmlServerURL)
                                                        throws java.io.IOException
Sends the request to Reactor's XML Front Desk servlet for fulfillment, and then parses the XML response into a ReactorResponse.

Parameters:
xmlServerURL - The URL of the Reactor XML Front Desk servlet.
Returns:
a response object indicating the success or failure of the request, as well as any values returned from a successful request.
Throws:
java.io.IOException - if an IO error occurs

sendAsXML

public com.oakgrovesystems.xml.XMLObject sendAsXML(java.net.URL xmlServerURL)
                                            throws java.io.IOException,
                                                   FailedRequestException
Sends the request to Reactor's XML Front Desk servlet for fulfillment.

Parameters:
xmlServerURL - The URL of the Reactor XML Front Desk servlet.
Returns:
The XML response from Reactor's XML Front Desk
Throws:
java.io.IOException - if an IO error occurs
FailedRequestException

createResponseXML

public com.oakgrovesystems.xml.XMLObject createResponseXML(com.oakgrovesystems.reactor.ReactorResponse response)
Creates the XML representation of a response from its ReactorResponse Java representation.

Parameters:
response - the ReactorResponse to translate to XML
Returns:
the XML representation of the response

createResponseXML

public com.oakgrovesystems.xml.XMLObject createResponseXML(com.oakgrovesystems.reactor.ReactorResponse response,
                                                           com.oakgrovesystems.reactor.IdToLabelPathMapper mapper)
Creates the XML representation of a response from its ReactorResponse Java representation.

Parameters:
response - the ReactorResponse to translate to XML
mapper - object to convert IDs to label paths in return values
Returns:
the XML representation of the response

createRtnValXML

protected org.jdom.Element createRtnValXML(com.oakgrovesystems.reactor.ReactorResponse response,
                                           com.oakgrovesystems.reactor.IdToLabelPathMapper mapper)
                                    throws FailedRequestException
This (superclass) implementation simply returns null, which is perfect for requests that don't have return values. Subclass implementations should override this method if they have return values. This method should return a 'return_values' Element or null if there are no return values. A precondition of this method is that the ReactorResponse parameter is not a failure.

Parameters:
response - the ReactorResponse to translate to XML.
mapper - object to convert IDs to label paths in return values
Returns:
the XML representation of the return values
Throws:
FailedRequestException - if the return values Element can't be created

parseResponse

public com.oakgrovesystems.reactor.ReactorResponse parseResponse(com.oakgrovesystems.xml.XMLObject xml)
                                                          throws FailedRequestException
Parses an XML response to this ReactorRequest. This (superclass) implementation only parses the elements of a response that are common to all requests. subclasses can override this method to parse return values. Used by sendViaHttp().

Throws:
FailedRequestException - if there is an error parsing the XML

parseReturnValues

protected abstract com.oakgrovesystems.reactor.ReactorResponse parseReturnValues(org.jdom.Element returnValues)
                                                                          throws FailedRequestException
FailedRequestException

toXML

public com.oakgrovesystems.xml.XMLObject toXML()
                                        throws FailedRequestException
Creates an XML representation of this request suitable for sending to Reactor's XML Front Desk servlet. Used by sendViaHtttp() and sendAsXML()

Returns:
an XML representation of this request
FailedRequestException

paramsToXML

protected abstract java.util.List paramsToXML()
                                       throws FailedRequestException
Returns a List of Elements representing the parameters of the request

Returns:
a List of Elements representing the parameters of the request
FailedRequestException

configureFromXML

public void configureFromXML(com.oakgrovesystems.xml.XMLObject request)
                      throws FailedRequestException
configures this ReactorRequest from its XML representation

Parameters:
request - the XML request to parse and use to configure this request
Throws:
FailedRequestException - if the request type is not appropriate for this subclass of ReactorRequest or if there is an error parsing the XML.

configureFromXML

public void configureFromXML(com.oakgrovesystems.xml.XMLObject request,
                             com.oakgrovesystems.reactor.LabelPathToIdMapper mapper)
                      throws FailedRequestException
configures this ReactorRequest from its XML representation

Parameters:
request - the XML request to parse and use to configure this request
mapper - object to convert label paths to IDs in response XML
Throws:
FailedRequestException - if the request type is not appropriate for this subclass of ReactorRequest or if there is an error parsing the XML.

parseParameters

protected abstract void parseParameters(org.jdom.Element params,
                                        com.oakgrovesystems.reactor.LabelPathToIdMapper mapper)
                                 throws FailedRequestException
Configures the parameters from the XML representation

Parameters:
params - the 'parameters' Element of the request
Throws:
FailedRequestException - if the parameters can't be configured from the XML.

getObjectId

protected static com.oakgrovesystems.reactor.ReactorObjectId getObjectId(org.jdom.Element parent)
If the Element specified has an 'object_reference' child and that child has an 'id' child, then the method returns a ReactorObjectId instantiated from the text content of the 'id' Element. returns null otherwise. For use in subclasses' parseParameters() implementations


getLabelPath

protected static com.oakgrovesystems.reactor.LabelPath getLabelPath(org.jdom.Element parent)
If the Element specified has an 'object_reference' child and that child has a 'label_path' child, then the method returns a ReactorObjectId instantiated from the 'label_path' Element. returns null otherwise. For use in subclasses' parseParameters() implementations


createReturnValuesElem

protected static org.jdom.Element createReturnValuesElem(java.lang.String[][] returns)
Creates a 'return_values' JDOM Element from the given array of key-value pairs. For use in subclass implementations of createRtnValXML.

Parameters:
returns - an array of key-value pairs.
Returns:
a 'return_values' Element

makeAuthTokenXML

protected java.lang.String makeAuthTokenXML(java.lang.String token)
Returns:
authentication_token element (or empty string if token is null or empty)

makeReferenceElement

protected org.jdom.Element makeReferenceElement(com.oakgrovesystems.reactor.ReactorObjectId id,
                                                com.oakgrovesystems.reactor.LabelPath labelPath)
                                         throws FailedRequestException
FailedRequestException

makeObjectElement

protected org.jdom.Element makeObjectElement(java.lang.Object obj)
                                      throws FailedRequestException
FailedRequestException

makeProcessElement

protected org.jdom.Element makeProcessElement(com.oakgrovesystems.reactor.processMediation.Process obj)

makeOperandElement

protected org.jdom.Element makeOperandElement(com.oakgrovesystems.reactor.processMediation.Operand obj)

makeStatusElement

protected org.jdom.Element makeStatusElement(com.oakgrovesystems.reactor.processMediation.Status obj)

makePolicyElement

protected org.jdom.Element makePolicyElement(com.oakgrovesystems.reactor.processMediation.Policy obj)


Copyright (c) 1999-2004 Oak Grove Systems. All Rights Reserved.