org.glite.security.voms.request
Class Request

java.lang.Object
  extended byorg.glite.security.voms.request.Request
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
AutomaticRequest, BrokenRequest, CheckedRequest

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

An abstract class representing a request submitted by a user.

This abstract request type predefines three states that are likely to be useful in derived classes: Request.DoneState, Request.TimedOutState and Request.DeletedState. (They are not enough to make a complete state machine, so Request itself is not usable as a request type.)

Author:
Karoly Lorentey
See Also:
Serialized Form

Nested Class Summary
static class Request.ChronicleEntry
          A simple class describing entries in the chronicle.
 class Request.DeletedState
          The standard state of a deleted request which has not yet been purged from the database.
 class Request.DoneState
          The standard state of an accepted and successfully processed request.
 class Request.State
          An abstract class representing a request state.
 class Request.TimedOutState
          The standard state of a request that has timed out.
 
Field Summary
protected  Action action
          The action that is requested.
protected  java.util.List chronicle
          A list of ChronicleEntries describing the history of this request.
protected  java.util.List notifications
          A list of notification entries.
protected  java.util.Map parameters
          A storage area for optional parameters.
protected  Request.State state
          The current state.
 
Constructor Summary
protected Request(Action action)
          Protected constructior without the optional parameters.
protected Request(Action action, java.lang.String[] parameters)
          Protected constructor; allocates a new id for this request.
protected Request(long id, long requester, Action action)
          Protected constructor that allows to set an id explicitly.
 
Method Summary
 void addNotification(Notification note)
          Adds a notification to the request (sent or pending).
 void addParameter(java.lang.String key, java.lang.String value)
          Add a parameter to the optional parameters.
 void addParameters(java.lang.String[] params)
          Adds an even sized string array to the optional parameters.
protected  void chronicle(java.lang.String description)
          Add a new entry to the chronicle.
protected  void chronicle(java.lang.String description, java.lang.String comment)
           
 void delete()
          Delete this Request object from the database.
 Action getAction()
          Return the action wrapped into this request.
 java.util.List getChronicle()
          Return a copy of the chronicle.
 Request.State getDeletedState()
          Return a new instance of Request.DeletedState.
 DetailedRequest getDetailedRequest()
           
 Request.State getDoneState()
          Return a new instance of Request.DoneState.
 long getId()
          Return the id of this request.
static Request getInstance(long id)
          Return the request with the given id by looking it up in the database.
 java.util.List getNotifications()
          Return a copy of the notifications.
 java.util.Map getParameters()
          Return a read-only view of the parameters.
 DBAdmin getRequester()
          Return the client who submitted this request.
 long getRequesterId()
          Return the id of the client who submitted this request.
static long[] getRequests(DBAdmin requester, java.lang.Boolean complete, java.lang.String type, java.lang.String container, java.lang.String state)
          Get the ids of all requests with the given requester, type, container and/or state.
 ShortRequest getShortRequest()
           
static ShortRequest[] getShortRequests(DBAdmin requester, java.lang.Boolean complete, java.lang.String type, java.lang.String container, java.lang.String state)
          Get the short SOAP form of all requests with the given requester, type, container and/or state.
 java.lang.String getStateDescription()
          Return a short description of the state that this request is in.
 java.lang.String getStateName()
          Return the name of the state that this request is in.
 Request.State getTimedOutState()
          Return a new instance of Request.TimedOutState.
 boolean isComplete()
          Return whether the request is in a final state.
static boolean isInDatabase(long id)
          Returns true if there is a request in the database with the given id.
 boolean isPendingNotification()
          Returns true, if there is any pending notification attached to this request.
 void printChronicle()
          Helper method for writing the chronicle to the log.
 void processEvent(Event e)
          Process the given event.
 void sendPendingNotifications()
          Sends out pending notifications.
 void store()
          Save this Request object in the database.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

action

protected Action action
The action that is requested.


chronicle

protected java.util.List chronicle
A list of ChronicleEntries describing the history of this request.


notifications

protected java.util.List notifications
A list of notification entries.


parameters

protected java.util.Map parameters
A storage area for optional parameters. These are such as phone, institute, URL for an action on the web interface, etc.


state

protected transient Request.State state
The current state. Note that this is declared transient because serializing instances of non-static inner classes could cause interoperability problems and other Java nastiness. getInstance() takes care of initializing this field in deserialized instances (the State's class name is stored before serialization in the (private) stateClassName).

Constructor Detail

Request

protected Request(Action action,
                  java.lang.String[] parameters)
           throws VOMSException
Protected constructor; allocates a new id for this request. This constructor is to be used only for creating new requests. Old requests are normally instantiated by deserialization from database BLOBs.


Request

protected Request(Action action)
           throws VOMSException
Protected constructior without the optional parameters.

See Also:
Request(Action,String[])

Request

protected Request(long id,
                  long requester,
                  Action action)
Protected constructor that allows to set an id explicitly. Useful in BrokenRequest, but nowhere else.

Throws:
java.lang.NullPointerException - when the action parameter is null.
Method Detail

getId

public long getId()
Return the id of this request.


getRequesterId

public long getRequesterId()
Return the id of the client who submitted this request.


getAction

public Action getAction()
Return the action wrapped into this request.


getRequester

public DBAdmin getRequester()
                     throws GeneralDatabaseException
Return the client who submitted this request.

Throws:
GeneralDatabaseException

getChronicle

public java.util.List getChronicle()
Return a copy of the chronicle.


chronicle

protected void chronicle(java.lang.String description)
                  throws GeneralDatabaseException
Add a new entry to the chronicle.

Throws:
GeneralDatabaseException

chronicle

protected void chronicle(java.lang.String description,
                         java.lang.String comment)
                  throws GeneralDatabaseException
Throws:
GeneralDatabaseException

printChronicle

public void printChronicle()
                    throws VOMSException
Helper method for writing the chronicle to the log. (Used by the unit tests; not useful anywhere else.)

Throws:
VOMSException

getNotifications

public java.util.List getNotifications()
Return a copy of the notifications.


sendPendingNotifications

public void sendPendingNotifications()
Sends out pending notifications.


isPendingNotification

public boolean isPendingNotification()
Returns true, if there is any pending notification attached to this request.


addNotification

public void addNotification(Notification note)
Adds a notification to the request (sent or pending). The requests are periodically tested, if they have pending notifications, so they will be delivered sooner or later.

If a message was sent, then this list preserves it for archival.


getParameters

public java.util.Map getParameters()
Return a read-only view of the parameters.


addParameter

public void addParameter(java.lang.String key,
                         java.lang.String value)
                  throws ArgumentException
Add a parameter to the optional parameters. The size of the key and value is checked, so we will not create oversized requests in the database. If either the key or the value is too long an ArgumentException is thrown.

Throws:
ArgumentException

addParameters

public void addParameters(java.lang.String[] params)
                   throws ArgumentException
Adds an even sized string array to the optional parameters. The keys should be at odd, the values at even positions. If any of these constraints doesn't hold an ArgumentException is thrown.

Throws:
ArgumentException

getStateName

public java.lang.String getStateName()
Return the name of the state that this request is in.


getStateDescription

public java.lang.String getStateDescription()
Return a short description of the state that this request is in.


isComplete

public boolean isComplete()
Return whether the request is in a final state.


getDoneState

public Request.State getDoneState()
Return a new instance of Request.DoneState.

Calling these get*State() functions is the only accepted method of creating state objects. By overriding these methods, derived classes may replace entire states with a new implementation without changing code in any of the neighbouring states.


getTimedOutState

public Request.State getTimedOutState()
Return a new instance of Request.TimedOutState.

Calling these get*State() functions is the only accepted method of creating state objects. By overriding these methods, derived classes may replace entire states with a new implementation without changing code in any of the neighbouring states.


getDeletedState

public Request.State getDeletedState()
Return a new instance of Request.DeletedState.

Calling these get*State() functions is the only accepted method of creating state objects. By overriding these methods, derived classes may replace entire states with a new implementation without changing code in any of the neighbouring states.


processEvent

public void processEvent(Event e)
                  throws VOMSException
Process the given event. The method simply passes the event to the current state. The state returned by the current state becomes the new current state. Finally, the request is saved in the database.

Throws:
VOMSException

getInstance

public static Request getInstance(long id)
                           throws GeneralDatabaseException
Return the request with the given id by looking it up in the database. This is a standard way to get existing request instances.

If the deserialization fails for any reason, this function returns a BrokenRequest instance instead of throwing an exception.

Returns:
the desired deserialized request instance.
Throws:
NotInDatabase - when there is no request with the given id in the database.
GeneralDatabaseException

isInDatabase

public static boolean isInDatabase(long id)
                            throws GeneralDatabaseException
Returns true if there is a request in the database with the given id.

Throws:
GeneralDatabaseException

store

public void store()
           throws VOMSException
Save this Request object in the database.

Throws:
VOMSException

delete

public void delete()
            throws VOMSException
Delete this Request object from the database.

Throws:
VOMSException

toString

public java.lang.String toString()

getShortRequest

public ShortRequest getShortRequest()
                             throws GeneralDatabaseException
Throws:
GeneralDatabaseException

getDetailedRequest

public DetailedRequest getDetailedRequest()
                                   throws GeneralDatabaseException
Throws:
GeneralDatabaseException

getShortRequests

public static ShortRequest[] getShortRequests(DBAdmin requester,
                                              java.lang.Boolean complete,
                                              java.lang.String type,
                                              java.lang.String container,
                                              java.lang.String state)
                                       throws GeneralDatabaseException
Get the short SOAP form of all requests with the given requester, type, container and/or state. Any or all of these parameters may be null, which means that any value is acceptable.

Throws:
GeneralDatabaseException

getRequests

public static long[] getRequests(DBAdmin requester,
                                 java.lang.Boolean complete,
                                 java.lang.String type,
                                 java.lang.String container,
                                 java.lang.String state)
                          throws GeneralDatabaseException
Get the ids of all requests with the given requester, type, container and/or state. Any or all of these parameters may be null, which means that any value is acceptable.

Throws:
GeneralDatabaseException