Class ServerChannel

java.lang.Object
cl.netswitch.lib.aio.ChannelBase
cl.netswitch.lib.server.ServerChannel
All Implemented Interfaces:
JschServices, MailServices, SocketServices, SQLServices
public class ServerChannel extends ChannelBase implements SQLServices, SocketServices, JschServices, MailServices
Communication channel between a server application and a NetSwitch server. Once the communcation is established, the server application is able to receive requests, send requests or multicasts, and provide other services to client applications.

A ServerChannel can establish a secure or a non-secure communication channel. Secure channels use the Transport Layer Security (TLS) protocol, which ensures privacy between communicating applications. When a server and client communicate, TLS ensures that no third party may eavesdrop or tamper with any message.

The following example uses ServerChannel to implement a server application called "SAMPLESER". This server is very small: it just implements a trivial "HELLO" service: 

import cl.netswitch.lib.server.*;

public class SampleServer extends ServerChannel implements RequestListener
{
    @Override
    public void handleRequest(RequestEvent request) throws Exception
    {
        String name = request.getMessage().getText();
        request.sendReply("HELLO to you too, %s", name);
    }

    public static void main(String[] args) throws Exception
    {
        SampleServer server = new SampleServer();
        server.addRequestListener("HELLO", server);
        server.execute("SAMPLESER", "tcp://localhost:20101");
    }
}
 
Property Description Type Default
netswitch.uri Protocol, address and port of the NetSwitch server String NETSWITCH
netswitch.password Password use to authenticate the server channel String none
«name».server.compression.threshold Minimum size that a message must have before it is compressed (bytes) Integer 0 (disabled)
«name».server.keep.alive Enable or disable the socket SO_KEEPALIVE option Boolean false
«name».server.reader.buffer.free Free size of the reader buffer (bytes) Integer 4096
«name».server.reader.buffer.max Maximum size of the reader buffer (bytes) Integer 0 (unbounded)
«name».server.reader.buffer.min Minimum size of the reader buffer (bytes) Integer 8192
«name».server.reader.buffer.warn Warning size of the reader buffer (bytes) Integer 8192
«name».server.reply.timeout Maximum time to wait for a NetSwitch reply (milliseconds) Integer 800
«name».server.tcp.nodelay Enable or disable the socket TCP_NODELAY option Boolean true
«name».server.trace Trace inbound and outbound messages (for debugging) Boolean false
«name».server.trust.store Path of the JKS trust store file used for SSL connections String none
«name».server.use.caller.name Use caller name to identify execute methods Boolean false
«name».server.user.name Username used to login the channel with the NetSwitch server String none
«name».server.user.password Password used to login the channel with the NetSwitch server String none
«name».server.writer.queue.size Maximum size of the writer queue (messages) Integer 64

  • Constructor Details

    • ServerChannel

      public ServerChannel()
      Constructs a new ServerChannel instance.

  • Method Details

    • getArguments

      public final String[] getArguments()
      Returns the command arguments supplied to the main() method of this ServerChannel. Returns null if this ServerChannel is not executing, or if it was executed with no command arguments.
      Returns:
      the command arguments or null if none available.

    • getName

      public final String getName()
      Returns the name of this ServerChannel. Returns null if this ServerChannel is not executing.
      Returns:
      the name or null if not executing.

    • getNetSwitchURI

      public final URI getNetSwitchURI()
      Returns the connection URI of this ServerChannel. Returns null if this ServerChannel is not executing.
      Returns:
      the connection URI or null if not executing.

    • getNetSwitchName

      public final String getNetSwitchName()
      Returns the switch name of this ServerChannel. This value is assigned to this server by the switch server. Returns null if this ServerChannel is not executing.
      Returns:
      the name or null if not executing.

    • getNetSwitchVersion

      public final String getNetSwitchVersion()
      Returns the switch version of this ServerChannel. This value is assigned to this server by the switch server. Returns null if this ServerChannel is not executing.
      Returns:
      the version or null if not executing.

    • getUniqueName

      public final String getUniqueName()
      Returns the unique name of this ServerChannel. This value is assigned to this server by the switch server. Returns null if this ServerChannel is not executing.
      Returns:
      the name or null if not executing.

    • isExecuting

      public final boolean isExecuting()
      Returns true if this ServerChannel is executing.
      Returns:
      true if this ServerChannel is executing.

    • isServerThread

      public final boolean isServerThread()
      Returns true if running on the ServerChannel Thread.
      Returns:
      true if running on the ServerChannel Thread.

    • getVersion

      public final String getVersion()
      Returns the implementation version of this ServerChannel.
      Returns:
      the implementation version of this ServerChannel.

    • handleInbound

      protected void handleInbound(Message inbound) throws Exception
      Handles an inbound message received by this connector.
      Specified by:
      handleInbound in class ChannelBase
      Parameters:
      inbound - the inbound message to be handled.
      Throws:
      NullPointerException - if inbound is null.
      Exception - if another error occurs.

    • decodePassword

      public String decodePassword(String encoded, String username, String type) throws Exception
      Decodes an encoded password using supplied arguments.
      Parameters:
      encoded - the password to be decoded.
      username - the username used to encoded the password.
      type - the type used to encoded the password.
      Returns:
      the password decoded using supplied arguments.
      Throws:
      NullPointerException - if an argument is null.
      Exception - if another error occurs.

    • getSharedBoolean

      public final SharedBoolean getSharedBoolean(String name, boolean inival)
      Returns the SharedBoolean indexed by specified name. If the SharedBoolean does not exists, a new instance is created with the specified initial value. An exception is thrown if a shared value exists that is not an instance of SharedBoolean.
      Parameters:
      name - the name of the required SharedValue.
      inival - the value used when SharedValue is created.
      Returns:
      the SharedBoolean indexed by supplied name.
      Throws:
      NullPointerException - if name is null.
      ClassCastException - if a shared value exists with wrong type.

    • getSharedInteger

      public final SharedInteger getSharedInteger(String name, int inival)
      Returns the SharedInteger indexed by specified name. If the SharedInteger does not exists, a new instance is created with the specified initial value. An exception is thrown if a shared value exists that is not an instance of SharedInteger.
      Parameters:
      name - the name of the required SharedValue.
      inival - the value used when SharedValue is created.
      Returns:
      the SharedInteger indexed by supplied name.
      Throws:
      NullPointerException - if name is null.
      ClassCastException - if a shared value exists with wrong type.

    • getSharedLong

      public final SharedLong getSharedLong(String name, long inival)
      Returns the SharedLong indexed by specified name. If the SharedLong does not exists, a new instance is created with the specified initial value. An exception is thrown if a shared value exists that is not an instance of SharedLong.
      Parameters:
      name - the name of the required SharedValue.
      inival - the value used when SharedValue is created.
      Returns:
      the SharedLong indexed by supplied name.
      Throws:
      NullPointerException - if name is null.
      ClassCastException - if a shared value exists with wrong type.

    • getSharedString

      public final SharedString getSharedString(String name, String inival)
      Returns the SharedString indexed by specified name. If the SharedString does not exists, a new instance is created with the specified initial value. An exception is thrown if a shared value exists that is not an instance of SharedString.
      Parameters:
      name - the name of the required SharedValue.
      inival - the value used when SharedValue is created.
      Returns:
      the SharedString indexed by supplied name.
      Throws:
      NullPointerException - if name is null.
      ClassCastException - if a shared value exists with wrong type.

    • getProperty

      public final String getProperty(String name, String defval)
      Returns the value of the property indexed by specified name. If the property is not defined, it returns the supplied default value.
      Parameters:
      name - the name of the required property.
      defval - default value returned if the property is not defined.
      Returns:
      the value of the property or default value defval.
      Throws:
      NullPointerException - if name is null.

    • getProperty

      public final String getProperty(String name)
      Returns the value of the property indexed by specified name. If the property is not defined, it returns null.
      Parameters:
      name - the name of the required property.
      Returns:
      the value of the property or null if not defined.
      Throws:
      NullPointerException - if name is null.

    • getProperties

      public final Map<String,String> getProperties()
      Returns an unmodifiable map with all the properties of this ServerChannel.
      Returns:
      an unmodifiable map with all the properties of this ServerChannel.

    • runAsyncTask

      public final <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 a value or throws an exception.
      Throws:
      NullPointerException - if an argument is null.
      IllegalStateException - if the server channel is not executing.

    • executeSQL

      public final <T> T executeSQL(SQLExecutor<T> executor) throws SQLException, Exception
      Allocates a connection from the default pool and executes the supplied SQL executor.

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

      executeSQL("default", executor, null);
      Specified by:
      executeSQL in interface SQLServices
      Type Parameters:
      T - the type of the value returned by the executor.
      Parameters:
      executor - an SQL statement executor.
      Returns:
      the value returned by the executor.
      Throws:
      NullPointerException - if executor is null.
      SQLException - if an SQL error occurs.
      Exception - if another error occurs.

    • executeSQL

      public final <T> T executeSQL(SQLExecutor<T> executor, String execName) throws SQLException, Exception
      Allocates a connection from the default pool and executes the supplied SQL executor.

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

      executeSQL("default", executor, tag);
      Specified by:
      executeSQL in interface SQLServices
      Type Parameters:
      T - the type of the value returned by the executor.
      Parameters:
      executor - an SQL statement executor.
      execName - the name of the executor (can be null).
      Returns:
      the value returned by the executor.
      Throws:
      NullPointerException - if executor is null.
      SQLException - if an SQL error occurs.
      Exception - if another error occurs.

    • executeSQL

      public final <T> T executeSQL(String poolName, SQLExecutor<T> executor) throws SQLException, Exception
      Allocates a connection from the specified pool and then executes the supplied SQL executor.

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

      executeSQL(poolName, executor, null);
      Specified by:
      executeSQL in interface SQLServices
      Type Parameters:
      T - the type of the execution result.
      Parameters:
      poolName - the name of the connection pool.
      executor - an SQL statement executor.
      Returns:
      the value returned by the executor.
      Throws:
      NullPointerException - if an argument is null.
      SQLException - if an SQL error occurs.
      Exception - if another error occurs.

    • executeSQL

      public final <T> T executeSQL(String poolName, SQLExecutor<T> executor, String execName) throws SQLException, Exception
      Allocates a connection from the specified pool and then executes the supplied SQL executor. If the SQL executor returns normally, the connection is committed. If the SQL executor throws an exception, the connection is rollback. In any event, the connection is returned to the pool.
      Specified by:
      executeSQL in interface SQLServices
      Type Parameters:
      T - the type of the value returned by the executor.
      Parameters:
      poolName - the name of the connection pool.
      executor - an SQL statement executor.
      execName - the name of the executor (can be null).
      Returns:
      the value returned by the executor.
      Throws:
      NullPointerException - if an argument is null.
      SQLException - if an SQL error occurs.
      Exception - if another error occurs.

    • executeJsch

      public final <T> T executeJsch(JschExecutor<T> executor) throws Exception
      Allocates a connected Jsch (Java Secure Channel) session from the default pool and then executes the supplied executor.

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

      executeJsch("default", executor, null);
      Specified by:
      executeJsch in interface JschServices
      Type Parameters:
      T - the type of the value returned by the executor.
      Parameters:
      executor - the Jsch executor to be executed.
      Returns:
      the value returned by the executor.
      Throws:
      NullPointerException - if executor is null.
      Exception - if another error occurs.

    • executeJsch

      public final <T> T executeJsch(JschExecutor<T> executor, String execName) throws Exception
      Allocates a connected Jsch (Java Secure Channel) session from the default pool and then executes the supplied executor.

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

      executeJsch("default", executor, tag);
      Specified by:
      executeJsch in interface JschServices
      Type Parameters:
      T - the type of the value returned by the executor.
      Parameters:
      executor - the Jsch executor to be executed.
      execName - the name of the executor (can be null).
      Returns:
      the value returned by the executor.
      Throws:
      NullPointerException - if executor is null.
      Exception - if another error occurs.

    • executeJsch

      public final <T> T executeJsch(String poolName, JschExecutor<T> executor) throws Exception
      Allocates a connected Jsch (Java Secure Channel) session from the specified pool and then executes the supplied executor.

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

      executeJsch(poolName, executor, null);
      Specified by:
      executeJsch in interface JschServices
      Type Parameters:
      T - the type of the value returned by the executor.
      Parameters:
      poolName - the name of the Jsch (Java Secure Channel) pool.
      executor - the Jsch executor to be executed.
      Returns:
      the value returned by the executor.
      Throws:
      NullPointerException - if an argument is null.
      Exception - if another error occurs.

    • executeJsch

      public final <T> T executeJsch(String poolName, JschExecutor<T> executor, String execName) throws Exception
      Allocates a connected Jsch (Java Secure Channel) session from the specified pool and then executes the supplied executor. If the Jsch executor throws an exception, the Jsch session is closed and not returned to the pool.
      Specified by:
      executeJsch in interface JschServices
      Type Parameters:
      T - the type of the value returned by the executor.
      Parameters:
      poolName - the name of the Jsch (Java Secure Channel) pool.
      executor - the Jsch executor to be executed.
      execName - the name of the executor (can be null).
      Returns:
      the value returned by the executor.
      Throws:
      NullPointerException - if an argument is null.
      Exception - if another error occurs.

    • executeSocket

      public final <T> T executeSocket(SocketExecutor<T> executor) throws IOException, Exception
      Allocates a socket from the default pool and executes the supplied socket executor.

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

      executeSocket("default", executor, null);
      Specified by:
      executeSocket in interface SocketServices
      Type Parameters:
      T - the type of the execution result.
      Parameters:
      executor - the socket executor to be executed.
      Returns:
      the value returned by the executor.
      Throws:
      NullPointerException - if executor is null.
      IOException - if an I/O error occurs.
      Exception - if another error occurs.

    • executeSocket

      public final <T> T executeSocket(SocketExecutor<T> executor, String execName) throws IOException, Exception
      Allocates a socket from the default pool and executes the supplied socket executor.

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

      executeSocket("default", executor, tag);
      Specified by:
      executeSocket in interface SocketServices
      Type Parameters:
      T - the type of the execution result.
      Parameters:
      executor - the socket executor to be executed.
      execName - the name of the executor (can be null).
      Returns:
      the value returned by the executor.
      Throws:
      NullPointerException - if executor is null.
      IOException - if an I/O error occurs.
      Exception - if another error occurs.

    • executeSocket

      public final <T> T executeSocket(String poolName, SocketExecutor<T> executor) throws IOException, Exception
      Allocates a socket from the specified pool and then executes the supplied socket executor.

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

      executeSocket(poolName, executor, null);
      Specified by:
      executeSocket in interface SocketServices
      Type Parameters:
      T - the type of the execution result.
      Parameters:
      poolName - the name of the socket pool.
      executor - the socket executor to be executed.
      Returns:
      the value returned by the executor.
      Throws:
      NullPointerException - if an argument is null.
      IOException - if an I/O error occurs.
      Exception - if another error occurs.

    • executeSocket

      public final <T> T executeSocket(String poolName, SocketExecutor<T> executor, String execName) throws IOException, Exception
      Allocates a socket from the specified pool and then executes the supplied socket executor. If the socket executor throws an IOException, the socket is closed and not returned to the pool. If the socket executor terminates successfully, or if it throws any other exception, the socket is returned to the pool.
      Specified by:
      executeSocket in interface SocketServices
      Type Parameters:
      T - the type of the execution result.
      Parameters:
      poolName - the name of the socket pool.
      executor - the socket executor to be executed.
      execName - the name of the executor (can be null).
      Returns:
      the value returned by the executor.
      Throws:
      NullPointerException - if an argument is null.
      IOException - if an I/O error occurs.
      Exception - if another error occurs.

    • executeTask

      public final <T> T executeTask(Callable<T> task) throws Exception
      Executes supplied task mantaining statistics.

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

      executeTask(task, null);
      Type Parameters:
      T - the type of the value returned by the task.
      Parameters:
      task - the task callable to be executed.
      Returns:
      the value returned by the task.
      Throws:
      NullPointerException - if task is null.
      Exception - if an error occurs executing task.

    • executeTask

      public final <T> T executeTask(Callable<T> task, String taskName) throws Exception
      Executes supplied task mantaining statistics with optional taskName.
      Type Parameters:
      T - the type of the value returned by the task.
      Parameters:
      task - the task callable to be executed.
      taskName - the name of the task (can be null).
      Returns:
      the value returned by the task.
      Throws:
      NullPointerException - if task is null.
      Exception - if an error occurs executing task.

    • sendMail

      public void sendMail(String subject, String text) throws Exception
      Sends a mail message using the "default" SMTP mail session.

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

      sendMail("default", subject, text);
      Specified by:
      sendMail in interface MailServices
      Parameters:
      subject - the subject of the mail message.
      text - the text of the mail message.
      Throws:
      NullPointerException - if an argument is null.
      Exception - if another error occurs.

    • sendMail

      public void sendMail(String sessionName, String subject, String text) throws Exception
      Sends a mail message using the specified SMTP mail session.
      Specified by:
      sendMail in interface MailServices
      Parameters:
      sessionName - the name of the mail session.
      subject - the subject of the mail message.
      text - the text of the mail message.
      Throws:
      NullPointerException - if an argument is null.
      Exception - if another error occurs.

    • enableMulticast

      public final void enableMulticast(String name, MulticastListener listener) throws Exception
      Enables the reception of multicast messages identified by name. When a multicast message arrives, it will be dispatched calling the listener.handleMulticast method.
      Parameters:
      name - name of the multicast messages.
      listener - the listener of multicast messages.
      Throws:
      NullPointerException - if an argument is null.
      Exception - if another error occurs.

    • disableMulticast

      public final void disableMulticast(String name) throws Exception
      Disables the reception of multicast messages identified by name. If name has the special value "*", then this method disables the reception of all multicast messages that have been enabled using the enableMulticast method.
      Parameters:
      name - name of the multicast messages or "*".
      Throws:
      NullPointerException - if name is null.
      Exception - if another error occurs.

    • sendMulticast

      public final void sendMulticast(String name, Serializable data) throws Exception
      Sends an multicast message built using the supplied name and data. The message will be dispatched to all client and/or server applications that have enabled the reception of multicast messages with the specified name.
      Parameters:
      name - the name of the multicast message.
      data - data to include in the multicast message (can be null).
      Throws:
      NullPointerException - if name is null.
      Exception - if another error occurs.

    • sendRequest

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

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

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

    • sendRequest

      public final void sendRequest(String destination, Serializable data, ReplyListener listener, int timeout) throws Exception
      Sends a request message to a destination and then calls listener when the asynchronous reply 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:

      sendRequest(destination, data, listener, timeout, null);
      Parameters:
      destination - the destination of the request message.
      data - the data to include in the request 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 a required argument is null.
      IllegalArgumentException - if timeout is negative.
      IllegalStateException - if the server channel is not executing.
      Exception - if another error occurs.

    • sendRequest

      public final void sendRequest(String destination, Serializable data, ReplyListener listener, int timeout, String replyKey) throws Exception
      Sends a request 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 request message.
      data - the data to include in the request 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 a required argument is null.
      IllegalArgumentException - if timeout is negative.
      IllegalStateException - if the server channel is not executing.
      Exception - if another error occurs.

    • sendRequest

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

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

      sendRequest(destination, data, 0);
      Parameters:
      destination - the destination of the request message.
      data - the data to include in the request 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.

    • sendRequest

      public final Message sendRequest(String destination, Serializable data, int timeout) throws SocketTimeoutException, Exception
      Sends a request message to a destination and then blocks waiting for the reply until timeout. The value of 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 request message.
      data - the data to include in the request 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 destination 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.

    • sendMessage

      public final void sendMessage(String destination, Serializable data) throws Exception
      Sends a message to the specified destination. The value of 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
      Parameters:
      destination - the destination of the request message.
      data - the data to include in the message (can be null).
      Throws:
      NullPointerException - if destination is null.
      IllegalStateException - if the server channel is not executing.
      Exception - if another error occurs.

    • sendMessage

      public final void sendMessage(Message message) throws Exception
      Sends the supplied message to the output stream of a channel.
      Parameters:
      message - the message to be written to the stream.
      Throws:
      NullPointerException - if message is null.
      IllegalStateException - if the server channel is not executing.
      Exception - if another error occurs.

    • addRequestListener

      public final void addRequestListener(String name, RequestListener listener)
      Registers a listener for request identified by name. If a listener for name was already registered, its definition will be replaced by this new one. The handleRequest method of this listener will be called whenever a request identified by name arrives.
      Parameters:
      name - the name of the request to register.
      listener - the listener of request messages.
      Throws:
      NullPointerException - if an argument isnull.

    • removeRequestListener

      public final void removeRequestListener(String name)
      Unregisters the request listener identified by name. If no such listener exists, then nothing happens. If a request identified by name later arrives, an error reply will be sent to the service caller.
      Parameters:
      name - the name of the request to unregister.
      Throws:
      NullPointerException - if name is null.

    • handleInitialize

      protected void handleInitialize() throws Exception
      Called just after this channel connects to the switch server. This event occurs only once in the life cycle of a server channel.

      This method is meant to be overridden by classes that extend ServerChannel. This default implementation does nothing.

      Throws:
      Exception - if an error occurs.

    • handleReinitialize

      protected void handleReinitialize() throws Exception
      Called just after a console REINIT command is executed. This event may occur several times in the life cycle of a server channel.

      Before this method is called, the properties of this server channel are cleared and then reloaded from the properties file, if that file still exists and is readable.

      This method is meant to be overridden by classes that extend ServerChannel. This default implementation does nothing.

      Throws:
      Exception - if an error occurs.

    • requestReceived

      protected void requestReceived(RequestEvent request) throws Exception
      Called after a request message has been received and before it is processed by a handleRequest method.

      This method should execute initialization logic common to all requests, such as starting a database transaction.

      This method is meant to be overridden by classes that extend ServerChannel. This default implementation does nothing.

      Parameters:
      request - describes the request event.
      Throws:
      NullPointerException - if request is null.
      Exception - if another error occurs.
      See Also:

    • requestCompleted

      protected void requestCompleted(RequestEvent request) throws Exception
      Called after a request message has been successfully processed by a handleRequest method.

      This method should execute termination logic common to all successful requests, such performing a database commit.

      This method is meant to be overridden by classes that extend ServerChannel. This default implementation does nothing.

      Parameters:
      request - describes the request event.
      Throws:
      NullPointerException - if request is null.
      Exception - if another error occurs.
      See Also:

    • requestError

      protected void requestError(RequestEvent request, Throwable thrown) throws Exception
      Called after an exception is thrown while processing a request message. The exception could have been be thrown by either requestReceived, handleRequest or requestCompleted.

      This method should execute termination logic common to all failed requests, such as performing a database rollback.

      This method is meant to be overridden by classes that extend ServerChannel. This default implementation uses the sendError method to send a reply message containing the message of the throwable.

      Parameters:
      request - describes the request event.
      thrown - the error thrown during request processing.
      Throws:
      NullPointerException - if an argument is null.
      Exception - if another error occurs.
      See Also:

    • logRequestError

      protected void logRequestError(RequestEvent request, Throwable thrown) throws Exception
      Logs the error that was thrown while processing a request message. The exception could have been be thrown by either requestReceived, handleRequest or requestCompleted.

      This method should log the information of the supplied throwable. The log record usually includes the message and stack trace of the throwable, but the server is free to choose the format and/or contents to be logged.

      This method is meant to be overridden by classes that extend ServerChannel. This default implementation logs the message and stack trace of the supplied throwable, unless the throwable is an instance of ServerException, in which case it uses a compact format that includes only the message but not the stack trace.

      Parameters:
      request - describes the request event.
      thrown - the error thrown during request processing.
      Throws:
      NullPointerException - if an argument is null.
      Exception - if another error occurs.
      See Also:

    • replyReceived

      protected void replyReceived(ReplyEvent reply) throws Exception
      Called after an asynchronous reply message has been received and before it is processed by a handleReply method.

      This method should execute initialization logic common to all replies, such as starting a database transaction.

      This method is meant to be overridden by classes that extend ServerChannel. This default implementation does nothing.

      Parameters:
      reply - describes the reply event.
      Throws:
      NullPointerException - if reply is null.
      Exception - if another error occurs.
      See Also:

    • replyCompleted

      protected void replyCompleted(ReplyEvent reply) throws Exception
      Called after an asynchronous reply message has been successfully processed by a handleReply method.

      This method should execute termination logic common to all successful replies, such performing a database commit.

      This method is meant to be overridden by classes that extend ServerChannel. This default implementation does nothing.

      Parameters:
      reply - describes the reply event.
      Throws:
      NullPointerException - if reply is null.
      Exception - if another error occurs.
      See Also:

    • replyError

      protected void replyError(ReplyEvent reply, Throwable thrown) throws Exception
      Called after an exception is thrown while processing an asynchronous reply message. The exception could have been be thrown by either replyReceived, handleReply or replyCompleted.

      This method should execute termination logic common to all failed replies, such as performing a database rollback.

      This method is meant to be overridden by classes that extend ServerChannel. This default implementation calls the requestError method with the request of the reply event and the supplied throwable.

      Parameters:
      reply - describes the reply event.
      thrown - the error thrown during reply processing.
      Throws:
      NullPointerException - if an argument is null.
      Exception - if another error occurs.
      See Also:

    • runLater

      public final void runLater(Runnable runnable)
      Run supplied runnable on the server's thread at some time in the future. If this method is called from the server's thread, the runnable will still be queued for execution after all pending server events have been processed.
      Parameters:
      runnable - a runnable to be run later on the server's thread.
      Throws:
      NullPointerException - if runnable is null.

    • startTimer

      public final void startTimer(int period)
      Schedules the execution of the handleTimer method at regular intervals. If the supplied period is zero (0), the current timer (if any) is cancelled.
      Parameters:
      period - time between successive executions of the handleTimer method (milliseconds).
      Throws:
      IllegalArgumentException - if period is negative.
      IllegalStateException - if the server channel is not executing.

    • cancelTimer

      public final void cancelTimer()
      Cancels the execution of the handleTimer method. If the method is running when this call occurs, the method will run to completion, but will never run again until a call to the startTimer is executed.

    • handleTimer

      protected void handleTimer() throws Exception
      Called when a timer event occurs. A timer event occurs when the sever's timer interval period expires. This interval period is defined using the startTimer method.

      This method is meant to be overridden by classes that extend ServerChannel. This default implementation calls cancelTimer to stop the generation of timer events.

      Throws:
      Exception - if an error occurs.

    • getIdleTimeout

      public final int getIdleTimeout()
      Returns the server's idle timeout. If the value returned is zero (0), the server blocks forever waiting for events. If the value returned is positive, the server will call the method handleIdle everytime the idle timeout expires while waiting for an event.
      Returns:
      the server's idle timeout (milliseconds).

    • setIdleTimeout

      public final void setIdleTimeout(int timeout)
      Changes the server's idle timeout. If the value of timeout is zero (0), the server will block forever waiting for the next event. If the value of timeout is positive, the server will call the method handleIdle everytime the timeout expires while waiting for an event.
      Parameters:
      timeout - maximum time to wait for an event (milliseconds).
      Throws:
      IllegalArgumentException - if timeout is negative.

    • handleIdle

      protected void handleIdle() throws Exception
      Called when a idle event occurs. An idle event occurs when the sever's timeout expires. The server's timeout is defined using the setIdleTimeout method.

      This method is meant to be overridden by classes that extend ServerChannel. This default implementation calls setIdleTimeout(0) to stop the generation of idle events.

      Throws:
      Exception - if an error occurs.

    • stop

      public final void stop()
      Stops the execution of this ServerChannel. The communication channel is closed, and all resources are released. If this ServerChannel is not executing, this method does nothing.

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

      stop("Method stop called");

    • stop

      public final void stop(String reason)
      Stops the execution of this ServerChannel with a reason. The communication channel is closed, and all resources are released. If this ServerChannel is not executing, this method does nothing.
      Parameters:
      reason - the reason why the server channel is stopping (can be null).

    • handleStop

      protected void handleStop(String reason) throws Exception
      Called when a stop message is received. A stop message is sent just before the communication channel is closed. After processing this message, the execute method unblocks and returns to it's caller. This usually results in the end of the execution of this server.

      This method is meant to be overridden by classes that extend ServerChannel. This default implementation does nothing.

      Parameters:
      reason - describes the reason why the server is being stopped.
      Throws:
      NullPointerException - if reason is null.
      Exception - if another error occurs.

    • getSwitchReplyTimeout

      public final int getSwitchReplyTimeout()
      Returns the maximum time to wait for a RunStart reply. If the value returned is zero (0), this server blocks forever waiting for the reply.
      Returns:
      the RunStart reply timeout (milliseconds).

    • setSwitchReplyTimeout

      public final void setSwitchReplyTimeout(int timeout)
      Changes the maximum time to wait for a RunStart reply. If the value of timeout is zero (0), this server will block forever waiting for the reply.
      Parameters:
      timeout - maximum time to wait for a RunStart reply (milliseconds).
      Throws:
      IllegalArgumentException - if timeout is negative.

    • execute

      public final void execute(String name, Properties properties, ServerContext context) throws Exception
      Starts the execution of this ServerChannel. The specified channel name must be registered with the switch. Argument properties provides the connection and configuration parameters of the server channel.

      After validating the arguments, this method connects to the switch server and sends a registration message with the name and credentials of this server. It then waits for messages to arrive and dispatches them to the corresponding "handleEvent" methods.

      This method returns to its caller when the ServerChannel has been stopped, or when the stop method is called, or when an unrecoverable error occurs. To remotely stop this server, an administrator needs to issue the " stop" command using the Console.

      Parameters:
      name - the name of this server channel.
      properties - the properties of this server channel.
      context - the server context of this server channel.
      Throws:
      NullPointerException - if an argument is null.
      Exception - if another error occurs.

    • execute

      @Deprecated public final void execute(String[] args, String defaultName) throws Exception
      Deprecated.
      Use method execute(String, Properties, ServerContext).
      Starts the execution of this ServerChannel. Argument args is an array with command line arguments. Argument defaultName provides the default name of the server.

      IMPORTANT: This method is no longer implemented, and throws an exception if invoked. It's kept because some servers still reference it, but never invoke it.

      Parameters:
      args - array with command line arguments.
      defaultName - the default name of the server.
      Throws:
      NullPointerException - if an argument is null.
      Exception - if another error occurs.

    • close

      public final void close()
      Close this channel, relinquishing any underlying resources.
      Overrides:
      close in class ChannelBase