galaxy.server
Class Environment

java.lang.Object
  |
  +--galaxy.server.Environment

public class Environment
extends java.lang.Object

The class encapsulates the environment of the current execution context. This includes methods for dispatching frames to a Hub (with and without support for continuation) and methods for sending replies to a Hub.


Constructor Summary
Environment()
          Creates an empty environment.
Environment(GFrame frame, GalaxyInputStream in, GalaxyOutputStream out)
          Creates an environmens for use by handshake code (i.e., not associated with a server or dispatch function).
Environment(GFrame frame, Server server)
          Creates an environment for use by a server when processing calls to its dispatch functions.
 
Method Summary
 void deleteServerProperties(java.lang.String[] keys)
          Deletes the specified server properties.
 void deleteSessionProperties(java.lang.String[] keys)
          Deletes the specified session properties.
 void destroyToken()
          Sends a "destroy token" reply.
 GFrame dispatchFrame(GFrame frame)
          Dispatches a frame to the Hub.
 GFrame dispatchFrameToProvider(GFrame frame, java.lang.String providerID)
          Dispatches a frame to the Hub.
 boolean dispatchFrameToProviderWithContinuation(GFrame frame, Continuation continuation, java.lang.Object continuationState, java.lang.String providerID)
          Dispatches a frame to the Hub, and tells the Hub that the reply does not have to be sent immediately.
 boolean dispatchFrameWithContinuation(GFrame frame, Continuation continuation, java.lang.Object continuationState)
          Dispatches a frame to the Hub, and tells the Hub that the reply does not have to be sent immediately.
 void error(java.lang.String description)
          Sends an error reply.
 void error(java.lang.String description, int errno)
          Sends an error reply.
 GFrame getHubOpaqueData()
          Returns the opaque Hub data associated with this environment.
 GalaxyInputStream getInputStream()
          Returns the input stream associated with this environment.
 java.lang.String getMsgName()
          Returns the message name associated with this environment.
 GalaxyMessage getNextMessage()
          Returns the next message on the queue of unprocessed messages encountered during calls to dispatchFrame.
 java.lang.String getOpName()
          Returns the operation name associated with this environment.
 java.lang.String getOriginatingProvider()
          Returns the id of the originating server associated with the message that created this environment.
 GalaxyOutputStream getOutputStream()
          Returns the output stream associated with this environment.
 GFrame getServerProperties(java.lang.String[] keys)
          Gets the specified server properties.
 java.lang.String getSessionId()
          Returns the session id associated with this environment.
 GFrame getSessionProperties(java.lang.String[] keys)
          Gets the specified session properties.
 int getTidx()
          Returns the token index associated with this environment.
 double getTokenTimestamp()
          Returns the timestamp associated with this environment.
 void inheritTokenTimestamp()
          Inherits the current token timestamp and sends that timestamp with all new messages.
 void modifyServerProperties(GFrame props, java.lang.String[] keys)
          Modifies the specified server properties.
 void modifySessionProperties(GFrame props, java.lang.String[] keys)
          Modifies the specified session properties.
 void postponeReply()
          Sends a "postpone" reply.
 void reply(GFrame frame)
          Sends a normal reply.
 void setServerProperties(GFrame props)
          Sets the specified server properties.
 void setSessionId(java.lang.String sessionId, int lockInfo)
          Sets the session id and informs the Hub.
 void setSessionProperties(GFrame props)
          Sets the specified session properties.
 void updateSessionId(java.lang.String sessionId)
          Sets the session id local to this environment.
 void writeFrame(GFrame frame)
          Writes a new frame to the Hub.
 void writeFrameToProvider(GFrame frame, java.lang.String providerID)
          Writes a new frame to the Hub.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Environment

public Environment(GFrame frame,
                   GalaxyInputStream in,
                   GalaxyOutputStream out)
Creates an environmens for use by handshake code (i.e., not associated with a server or dispatch function).
Parameters:
frame - GFrame of the current execution context
in - input stream associated with the current execution context
out - output stream associated with the current execution context

Environment

public Environment(GFrame frame,
                   Server server)
Creates an environment for use by a server when processing calls to its dispatch functions.
Parameters:
frame - GFrame of the current execution context
server - Server that created this environment

Environment

public Environment()
Creates an empty environment.
Method Detail

getTidx

public int getTidx()
Returns the token index associated with this environment.
Returns:
the index or -1 if is was not set

getHubOpaqueData

public GFrame getHubOpaqueData()
Returns the opaque Hub data associated with this environment.
Returns:
the opaque Hub data or null if it was not set

getSessionId

public java.lang.String getSessionId()
Returns the session id associated with this environment.
Returns:
the session id or null if it was not set

getOpName

public java.lang.String getOpName()
Returns the operation name associated with this environment.
Returns:
the operation name or null if it was not set

getMsgName

public java.lang.String getMsgName()
Returns the message name associated with this environment.
Returns:
the message name or null if it was not set

getInputStream

public GalaxyInputStream getInputStream()
Returns the input stream associated with this environment.
Returns:
the input stream or null if it was not set

getOutputStream

public GalaxyOutputStream getOutputStream()
Returns the output stream associated with this environment.
Returns:
the output stream or null if it was not set

getTokenTimestamp

public double getTokenTimestamp()
Returns the timestamp associated with this environment.
Returns:
the timestamp or -1 if it is not available

inheritTokenTimestamp

public void inheritTokenTimestamp()
Inherits the current token timestamp and sends that timestamp with all new messages.

getOriginatingProvider

public java.lang.String getOriginatingProvider()
Returns the id of the originating server associated with the message that created this environment.
Returns:
the id (may be null)

getNextMessage

public GalaxyMessage getNextMessage()
Returns the next message on the queue of unprocessed messages encountered during calls to dispatchFrame.
Returns:
the next message on the queue or null if the queue is empty

dispatchFrame

public GFrame dispatchFrame(GFrame frame)
                     throws DispatchError
Dispatches a frame to the Hub. This adds the keys GFrame.GAL_ROUND_TRIP_FRAME_KEY (value of 1) and GFrame.GAL_SERVER_TOKEN_INDEX_FRAME_KEY (set to next server index value) to the frame before it is sent.
Parameters:
frame - the frame to dispatch
Returns:
the reply frame sent from the Hub
Throws:
DispatchError - exception if it reads an error back from the Hub

dispatchFrameToProvider

public GFrame dispatchFrameToProvider(GFrame frame,
                                      java.lang.String providerID)
                               throws DispatchError
Dispatches a frame to the Hub. This adds the keys GFrame.GAL_ROUND_TRIP_FRAME_KEY (value of 1) and GFrame.GAL_SERVER_TOKEN_INDEX_FRAME_KEY (set to next server index value) to the frame before it is sent.
Parameters:
frame - the frame to dispatch
providerID - the id of the target service provider. If null, it is ignored.
Returns:
the reply frame sent from the Hub
Throws:
DispatchError - exception if it reads an error back from the Hub

writeFrame

public void writeFrame(GFrame frame)
                throws java.io.IOException
Writes a new frame to the Hub. Note that this method does not return anything as it does not wait for a reply from the Hub as does dispatchFrame. The session ID (if it is set) of the current call environment is added to incoming frame before it is written to the Hub.
Parameters:
frame - the frame to write
Throws:
IOException - exception if there is an error writing to the Hub

writeFrameToProvider

public void writeFrameToProvider(GFrame frame,
                                 java.lang.String providerID)
                          throws java.io.IOException
Writes a new frame to the Hub. Note that this method does not return anything as it does not wait for a reply from the Hub as does dispatchFrame. The session ID (if it is set) of the current call environment is added to incoming frame before it is written to the Hub.
Parameters:
frame - the frame to write
providerID - the id of the targer service provider. If null, it is ignored.
Throws:
IOException - exception if there is an error writing to the Hub

dispatchFrameWithContinuation

public boolean dispatchFrameWithContinuation(GFrame frame,
                                             Continuation continuation,
                                             java.lang.Object continuationState)
Dispatches a frame to the Hub, and tells the Hub that the reply does not have to be sent immediately. This allows the Hub to invoke other dispatch functions on the server associated with this environment. When the reply to the frame dispatched by this server does arrive, it will be processed using the continuation information supplied to the call to this method. This method adds the keys GFrame.GAL_ROUND_TRIP_FRAME_KEY (value of 1) and GFrame.GAL_SERVER_TOKEN_INDEX_FRAME_KEY (set to next server index value) to the frame before it is sent.
Parameters:
frame - the frame to dispatch
continuation - defines the action to take once the reply to this dispatch arrives at the server
continuationState - state information used to process the reply
Returns:
true if the frame was sent or false if there was an error while sending the frame

dispatchFrameToProviderWithContinuation

public boolean dispatchFrameToProviderWithContinuation(GFrame frame,
                                                       Continuation continuation,
                                                       java.lang.Object continuationState,
                                                       java.lang.String providerID)
Dispatches a frame to the Hub, and tells the Hub that the reply does not have to be sent immediately. This allows the Hub to invoke other dispatch functions on the server associated with this environment. When the reply to the frame dispatched by this server does arrive, it will be processed using the continuation information supplied to the call to this method. This method adds the keys GFrame.GAL_ROUND_TRIP_FRAME_KEY (value of 1) and GFrame.GAL_SERVER_TOKEN_INDEX_FRAME_KEY (set to next server index value) to the frame before it is sent.
Parameters:
frame - the frame to dispatch
continuation - defines the action to take once the reply to this dispatch arrives at the server
continuationState - state information used to process the reply
providerID - the id of the target service provider. If null, it is ignored.
Returns:
true if the frame was sent or false if there was an error while sending the frame

postponeReply

public void postponeReply()
                   throws java.io.IOException
Sends a "postpone" reply.

destroyToken

public void destroyToken()
                  throws java.io.IOException
Sends a "destroy token" reply.

error

public void error(java.lang.String description)
           throws java.io.IOException
Sends an error reply.
Parameters:
description - textual error message (error number is set to galaxy.lang.ErrorMessage.GAL_APPLICATION_ERROR)

error

public void error(java.lang.String description,
                  int errno)
           throws java.io.IOException
Sends an error reply.
Parameters:
description - textual error message
errno - error number as defined in galaxy.lang.ErrorMessage

reply

public void reply(GFrame frame)
           throws java.io.IOException
Sends a normal reply.
Parameters:
frame - the frame to send in the reply

getSessionProperties

public GFrame getSessionProperties(java.lang.String[] keys)
                            throws DispatchError
Gets the specified session properties.
Parameters:
keys - the keys of the properties to get
Returns:
the reply frame with the session property information

setSessionProperties

public void setSessionProperties(GFrame props)
                          throws java.io.IOException
Sets the specified session properties.
Parameters:
props - the properties to set
Throws:
IOException - exception if there is an error writing to the Hub

deleteSessionProperties

public void deleteSessionProperties(java.lang.String[] keys)
                             throws java.io.IOException
Deletes the specified session properties.
Parameters:
keys - the keys of the properties to delete
Throws:
IOException - exception if there is an error writing to the Hub

modifySessionProperties

public void modifySessionProperties(GFrame props,
                                    java.lang.String[] keys)
                             throws java.io.IOException
Modifies the specified session properties.
Parameters:
props - the properties to set
keys - the keys of the properties to delete
Throws:
IOException - exception if there is an error writing to the Hub

getServerProperties

public GFrame getServerProperties(java.lang.String[] keys)
                           throws DispatchError
Gets the specified server properties.
Parameters:
keys - the keys of the properties to get
Returns:
the reply frame with the server property information

setServerProperties

public void setServerProperties(GFrame props)
                         throws java.io.IOException
Sets the specified server properties.
Parameters:
props - the properties to set
Throws:
IOException - exception if there is an error writing to the Hub

deleteServerProperties

public void deleteServerProperties(java.lang.String[] keys)
                            throws java.io.IOException
Deletes the specified server properties.
Parameters:
keys - the keys of the properties to delete
Throws:
IOException - exception if there is an error writing to the Hub

modifyServerProperties

public void modifyServerProperties(GFrame props,
                                   java.lang.String[] keys)
                            throws java.io.IOException
Modifies the specified server properties.
Parameters:
props - the properties to set
keys - the keys of the properties to delete
Throws:
IOException - exception if there is an error writing to the Hub

updateSessionId

public void updateSessionId(java.lang.String sessionId)
Sets the session id local to this environment. The Hub is not informed.
Parameters:
sessionId - the new session id

setSessionId

public void setSessionId(java.lang.String sessionId,
                         int lockInfo)
                  throws java.io.IOException
Sets the session id and informs the Hub.
Parameters:
sessionId - the new session id
lockInfo - the locking information (OR'ed combination of GFrame server/session lock values)
Throws:
IOException - exception if there is an error writing to the Hub