Module cl.netswitch.lib
Package cl.netswitch.lib.server

Class RequestEvent

java.lang.Object
java.util.EventObject
cl.netswitch.lib.server.RequestEvent
All Implemented Interfaces:
Serializable
public final class RequestEvent extends EventObject
RequestEvent is used to notify that a request message has arrived.
See Also:

  • Constructor Details

    • RequestEvent

      public RequestEvent(ServerChannel channel, Message message)
      Constructs a new RequestEvent instance.
      Parameters:
      channel - the object on which the event occurred.
      message - the request message received by the channel.
      Throws:
      NullPointerException - if an argument is null.

  • Method Details

    • getServerChannel

      public ServerChannel getServerChannel()
      Returns the server channel of this RequestEvent.
      Returns:
      the server channel of this RequestEvent.

    • getDestination

      public String getDestination()
      Returns the destination of this RequestEvent.
      Returns:
      the destination of this RequestEvent.

    • getServiceName

      public String getServiceName()
      Returns the service name of this RequestEvent.
      Returns:
      the service name of this RequestEvent.

    • getMessage

      public Message getMessage()
      Returns the request message of this RequestEvent.
      Returns:
      the request message of this RequestEvent.

    • getReplyPath

      public String getReplyPath()
      Returns the reply path of this RequestEvent.
      Returns:
      the reply path or null if none defined.

    • getRequestId

      public String getRequestId()
      Returns the request ID of this RequestEvent.
      Returns:
      the request ID or null if none defined.

    • getTimeout

      public int getTimeout()
      Returns the timeout of this RequestEvent. The returned value is a non-negative value indicating the maximum number of milliseconds the sender of this request will wait for the reply. If the returned value is zero (0), the sender will wait forever.
      Returns:
      the timeout of this RequestEvent (milliseconds).

    • getAuthType

      public String getAuthType()
      Returns the authentication type (BASIC,DIGEST) or null.
      Returns:
      the authentication type or null if not authenticated.

    • getAuthUser

      public String getAuthUser()
      Returns the name of the authenticated user or null.
      Returns:
      the user name or null if not authenticated.

    • isUserInRole

      public boolean isUserInRole(String roleName)
      Returns true if the authenticated user is included in a role.
      Parameters:
      roleName - the name of the role to be checked.
      Returns:
      true if user included in role; otherwise false.
      Throws:
      NullPointerException - if roleName is null.

    • hasSentReply

      public boolean hasSentReply()
      Returns true if a reply has already been sent.
      Returns:
      true if a reply has already been sent.

    • getErrorListener

      public RequestErrorListener getErrorListener()
      Returns the request error listener of this RequestEvent.
      Returns:
      the listener or null if none defined.

    • setErrorListener

      public void setErrorListener(RequestErrorListener listener)
      Changes the request error listener of this RequestEvent.
      Parameters:
      listener - the new request error listener (can be null).

    • runAsyncTask

      public <T> void runAsyncTask(Callable<T> task, TaskResultListener<T> listener)
      Executes the supplied task in a separate thread. It calls the listener when the task returns the computed value, or when the task throws an exception.
      Type Parameters:
      T - the type of the value returned by the task.
      Parameters:
      task - the task to be executed in a separate thread.
      listener - called when the task returns the value or throws an exception.
      Throws:
      NullPointerException - if an argument is null.

    • getObject

      public <T extends Serializable> T getObject(Class<T> type) throws Exception
      Returns the object contained in the message of this RequestEvent.

      Warning: to reduce memory consumption, this method returns a reference to (not a copy of) the mutable object stored in the request message. If the returned object is later modified, the request message object will be modified.

      Type Parameters:
      T - the type of the returned object.
      Parameters:
      type - the class of the returned object.
      Returns:
      a typed object or null if not defined.
      Throws:
      NullPointerException - if type is null.
      ClassCastException - if object is not an instance of type.
      Exception - if the required object cannot be unmarshalled.

    • sendErrorReply

      public void sendErrorReply(String text, Object... args) throws Exception
      Sends an ERROR reply message built using the supplied text format and optional arguments. If a reply message has already been sent, this method does nothing.
      Parameters:
      text - the text format used to build the reply message.
      args - an array with optional format arguments.
      Throws:
      NullPointerException - if text is null.
      IllegalFormatException - if text format is invalid.
      Exception - if an unexpected error occurs.

    • sendErrorReply

      public void sendErrorReply(Throwable thrown) throws Exception
      Sends an ERROR reply message built using the message of the supplied throwable. If a reply message has already been sent, this method does nothing.

      If the message of the throwable is null or empty, the string returned by the toString method will be used to build the error message.

      If thrown is an instance of ServiceException, the error message will include the user message and the error code provided by thrown.

      Parameters:
      thrown - the throwable describing the error.
      Throws:
      NullPointerException - if thrown is null.
      Exception - if an unexpected error occurs.

    • sendErrorReply

      public void sendErrorReply(Serializable data) throws Exception
      Sends a ERROR reply message built using the supplied data. If a reply message has already been sent, this method does nothing.

      This convenience method produces the same result as the following invocation:

      sendReply(data, Message.ERROR);
      Parameters:
      data - the data to include in the reply message (can be null).
      Throws:
      Exception - if an unexpected error occurs.

    • sendReply

      public void sendReply(String text, Object... args) throws Exception
      Sends a SUCCESS reply message built using the supplied text format and optional arguments. If a reply message has already been sent, this method does nothing.
      Parameters:
      text - the text format used to build the reply message.
      args - an array with optional format arguments.
      Throws:
      NullPointerException - if text is null.
      IllegalFormatException - if text format is invalid.
      Exception - if an unexpected error occurs.

    • sendReply

      public void sendReply(Serializable data) throws Exception
      Sends a SUCCESS reply message built using the supplied data. If a reply message has already been sent, this method does nothing.

      This convenience method produces the same result as the following invocation:

      sendReply(data, Message.SUCCESS);
      Parameters:
      data - the data to include in the reply message (can be null).
      Throws:
      Exception - if an unexpected error occurs.

    • sendReply

      public void sendReply(Serializable data, int status) throws Exception
      Sends a reply message built using the supplied data and completion status. If a reply message has already been sent, this method does nothing.

      The completion status indicates whether the request terminated successfully (zero or positive status) or with error (negative status).

      Parameters:
      data - the data to include in the reply message (can be null).
      status - the reply completion status.
      Throws:
      Exception - if an unexpected error occurs.

    • sendNullReply

      public void sendNullReply() throws Exception
      Marks the request as having sent a reply, and therefore will not fail with a "Reply Not Sent" expection. If a reply message has already been sent, this method does nothing.

      This method is used when a request sender is not expecting a reply message, or when the reply message will be sent later by another instance of the server.

      Throws:
      Exception - if an unexpected error occurs.

    • sendSubRequest

      public void sendSubRequest(String destination, Serializable data, ReplyListener listener) throws Exception
      Sends a subrequest message to a destination and then calls listener when the asynchronous reply message is received. This method waits forever for the reply.

      This convenience method produces the same result as the following invocation:

      sendSubRequest(destination, data, listener, 0);
      Parameters:
      destination - the destination of the subrequest message.
      data - the data to include in the subrequest message (can be null).
      listener - listener called with the asynchronous reply message.
      Throws:
      NullPointerException - if an argument is null.
      IllegalStateException - if the server channel is not executing.
      Exception - if another error occurs.

    • sendSubRequest

      public void sendSubRequest(String destination, Serializable data, ReplyListener listener, int timeout) throws Exception
      Sends a subrequest message to a destination and then calls listener when the asynchronous reply message is received. Argument timeout specifies the amount of time to wait for the asynchronous reply message.

      This convenience method produces the same result as the following invocation:

      sendSubRequest(destination, data, listener, timeout, null);
      Parameters:
      destination - the destination of the subrequest message.
      data - the data to include in the subrequest message (can be null).
      listener - listener called with the asynchronous reply message.
      timeout - the maximum time to wait for the reply (milliseconds).
      Throws:
      NullPointerException - if an argument is null.
      IllegalArgumentException - if timeout is negative.
      IllegalStateException - if the server channel is not executing.
      Exception - if another error occurs.

    • sendSubRequest

      public void sendSubRequest(String destination, Serializable data, ReplyListener listener, int timeout, String replyKey) throws Exception
      Sends a subrequest message to a destination and then calls listener when the asynchronous reply is received.

      Argument destination must have the following format: 

      [SwitchName:]ServerName[.ServiceName]
      where optional items are shown within "[" and "]" brackets, and the characters ":" and "." stand for themselves. If the optional SwitchName is not specified, the message is sent to the connected switch. ServerName is the name of a server, a listener or a connector. The optional ServiceName is the name of a service provided by the server, or the name of a channel of a listener. The following are examples of valid destinations: 
       POS_DEVICE
 SWITCH.LOG_ERROR
 HUB:IMSER.ADD_CONTACT
      Argument timeout specifies the amount of time to wait for the asynchronous reply message. If timeout expires while waiting for the reply, the listener is called with a null message, indicating a timeout event. If timeout is zero (0), the listener may never get called.

      Optional argument replyKey provides a globally unique identifier of the reply. When the reply is later received by some other channel, this replyKey must be provided to dispatchReply to dispatch the reply to the listener.

      Parameters:
      destination - the destination of the subrequest message.
      data - the data to include in the subrequest message (can be null).
      listener - listener called with the asynchronous reply message.
      timeout - the maximum time to wait for the reply (milliseconds).
      replyKey - a globally unique ID of the reply (can be null).
      Throws:
      NullPointerException - if an argument is null.
      IllegalArgumentException - if timeout is negative.
      IllegalStateException - if the server channel is not executing.
      Exception - if another error occurs.

    • dispatchReply

      public boolean dispatchReply(String replyKey, Serializable data) throws Exception
      Dispatches supplied reply data to the pending reply listener indexed by given key.
      Parameters:
      replyKey - the globally unique identifier of the reply message.
      data - the data to include in the reply message (can be null).
      Returns:
      true if the reply listener was called (not timeout).
      Throws:
      NullPointerException - if replyKey is null.
      Exception - if an error occurs calling the reply listener.

    • sendSubRequest

      public Message sendSubRequest(String destination, Serializable data) throws Exception
      Sends a subrequest message to a destination and then blocks forever waiting for the reply.

      This convenience method produces the same result as the following invocation:

      sendSubRequest(destination, data, 0);
      Parameters:
      destination - the destination of the subrequest message.
      data - the data to include in the subrequest message (can be null).
      Returns:
      the reply message returned from destination.
      Throws:
      NullPointerException - if destination is null.
      IllegalStateException - if the server channel is not executing.
      Exception - if another error occurs.

    • sendSubRequest

      public Message sendSubRequest(String destination, Serializable data, int timeout) throws SocketTimeoutException, Exception
      Sends a subrequest message to a destination and then blocks waiting for the reply until timeout.

      Argument destination must have the following format: 

      [SwitchName:]ServerName[.ServiceName]
      where optional items are shown within "[" and "]" brackets, and the characters ":" and "." stand for themselves. If the optional SwitchName is not specified, the message is sent to the connected switch. ServerName is the name of a server, a listener or a connector. The optional ServiceName is the name of a service provided by the server, or the name of a channel of a listener. The following are examples of valid destinations: 
       POS_DEVICE
 SWITCH.LOG_ERROR
 HUB:IMSER.ADD_CONTACT
      Argument timeout specifies the amount of time to wait for the reply message. A SocketTimeoutException is thrown if timeout expires while waiting for the reply. If timeout is zero (0), the call blocks forever.
      Parameters:
      destination - the destination of the subrequest message.
      data - the data to include in the subrequest message (can be null).
      timeout - the maximum time to wait for a reply (in milliseconds).
      Returns:
      the reply message returned from destination.
      Throws:
      NullPointerException - if an argument is null.
      IllegalArgumentException - if timeout is negative.
      SocketTimeoutException - if timeout expired while waiting for reply.
      IllegalStateException - if the server channel is not executing.
      Exception - if another error occurs.

    • isLoggable

      public boolean isLoggable(Level level)
      Returns true if the given message level is being logged.
      Parameters:
      level - a message logging level.
      Returns:
      true if the given message level is being logged.
      Throws:
      NullPointerException - if level is null.

    • fine

      public void fine(String message, Object... args)
      Logs a fine message with supplied format and arguments.
      Parameters:
      message - the text of the message or format.
      args - an array of optional format arguments.

    • info

      public void info(String message, Object... args)
      Logs an information message with supplied format and arguments.
      Parameters:
      message - the text of the message or format.
      args - an array of optional format arguments.

    • warning

      public void warning(String message, Object... args)
      Logs a warning message with supplied format and arguments.
      Parameters:
      message - the text of the message or format.
      args - an array of optional format arguments.

    • severe

      public void severe(String message, Object... args)
      Logs a severe message with supplied format and arguments.
      Parameters:
      message - the text of the message or format.
      args - an array of optional format arguments.

    • severe

      public void severe(Throwable thrown, String message, Object... args)
      Logs a severe message with supplied throwable, format and arguments.
      Parameters:
      thrown - the associatted throwable instance.
      message - the text of the message or format.
      args - an array of optional format arguments.