Module cl.netswitch.lib
Package cl.netswitch.lib.client

Class ClientChannel

java.lang.Object
cl.netswitch.lib.aio.ChannelBase
cl.netswitch.lib.client.ClientChannel
All Implemented Interfaces:
AutoCloseable
public final class ClientChannel extends ChannelBase implements AutoCloseable
Communication channel between a client application and the NetSwitch server. Through this channel, an application can send service requests, receive multicasts, and obtain other services.

The communication channel is established as late as possible. Yet, once established, it is kept running until an operator executes a " stop" console command. If the communication channel is lost for any other reason, it is automatically re-established as soon as requiered.

The following example uses a ClientChannel named SAMPLECLI to send a request to a server named SAMPLESER. If the reply message status is not SUCCESS an exception is thrown with the returned error. If successful, the reply message data is displayed. 

 import cl.netswitch.lib.client.ClientChannel;
 import cl.netswitch.lib.message.Message;

 public class SampleClient
 {
     public static void main(String[] args)
         throws Exception
     {
         // Create a client channel named "SAMPLECLI"
         ClientChannel channel = new ClientChannel();
         channel.connect("SAMPLECLI", "tcp://localhost:20102");

         // Request "HELLO" service from "SAMPLESER" server
         Message reply = channel.sendRequest("SAMPLESER.HELLO", "Hello world!!");
         if (reply.getStatus() != Message.SUCCESS)
             throw new Exception(reply.getText());

         // Display the reply returned from "SAMPLESER" server
         System.out.println("The reply data: " + reply.getText());
     }
 }
 
Property Description Type Default
netswitch.client.«name».channel.password Password use to authenticate the client channel String none
netswitch.client.«name».compression.threshold Minimum size that a message must have before it is compressed (bytes) Integer 0 (disabled)
netswitch.client.«name».keep.alive Enable or disable the socket SO_KEEPALIVE option Boolean false
netswitch.client.«name».reply.timeout Maximum time to wait for reply of connect message (milliseconds) Integer 10000
netswitch.client.«name».reader.buffer.free Free size of the reader buffer (bytes) Integer 4096
netswitch.client.«name».reader.buffer.max Maximum size of the reader buffer (bytes) Integer 0 (unbounded)
netswitch.client.«name».reader.buffer.min Minimum size of the reader buffer (bytes) Integer 8192
netswitch.client.«name».reader.buffer.warn Warning size of the reader buffer (bytes) Integer 8192
netswitch.client.«name».switch.uri Protocol, address and port of the NetSwitch server String NETSWITCH
netswitch.client.«name».tcp.nodelay Enable or disable the socket TCP_NODELAY option Boolean true
netswitch.client.«name».trace Trace inbound and outbound messages (for debugging) Boolean false
netswitch.client.«name».trust.store Path of the JKS trust store file used for SSL connections String none
netswitch.client.«name».user.name Username used to login the channel with the NetSwitch server String none
netswitch.client.«name».user.password Password used to login the channel with the NetSwitch server String none
netswitch.client.«name».writer.queue.size Maximum size of the writer queue (messages) Integer 64

  • Constructor Details

    • ClientChannel

      public ClientChannel()
      Constructs a new ClientChannel instance.

  • Method Details

    • getName

      public String getName()
      Returns the name of this ClientChannel, or null if this ClientChannel is not connected.
      Returns:
      the name or null if not connected.

    • getNetSwitchName

      public String getNetSwitchName()
      Returns the name of the switch connected to this ClientChannel, or null if this ClientChannel is not connected.
      Returns:
      the name or null if not connected.

    • getNetSwitchVersion

      public String getNetSwitchVersion()
      Returns the version of the switch connected to this ClientChannel, or null if this ClientChannel is not connected.
      Returns:
      the version or null if not connected.

    • getNetSwitchURI

      public URI getNetSwitchURI()
      Returns the connection URI of this ClientChannel, or null if this ClientChannel is not connected.
      Returns:
      the connection URI or null if not connected.

    • getVersion

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

    • getUnexpectedReplyListener

      public ReplyListener getUnexpectedReplyListener()
      Returns the unexpected reply listener of this ClientChannel.
      Returns:
      the unexpected reply listener or null if none defined.

    • setUnexpectedReplyListener

      public void setUnexpectedReplyListener(ReplyListener listener)
      Changes the unexpected reply listener of this ClientChannel.
      Parameters:
      listener - the new unexpected reply listener (can be null).

    • 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.

    • sendMulticast

      public 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.

    • enableMulticast

      public void enableMulticast(String name, MulticastListener listener) throws Exception
      Enables the reception of multicast messages identified by name. Multicast messages are generated when particular event occurs (e.g., the price of a stock has reached a certain limit). When a multicast message arrives, the handleMulticast method of supplied listener will be called.
      Parameters:
      name - name of the multicast message.
      listener - the listener of multicast messages.
      Throws:
      NullPointerException - if an argument is null.
      Exception - if another error occurs.

    • disableMulticast

      public 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.

    • sendRequest

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

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

      sendRequest(destination, data, 0);
      Parameters:
      destination - the request destination switch:server.service.
      data - the data to include in the request message (can be null).
      Returns:
      the reply message returned from the switch server.
      Throws:
      NullPointerException - if destination is null.
      Exception - if another error occurs.

    • sendRequest

      public 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 message for at most timeout milliseconds. 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
 NETSWITCH.LOG_ERROR
 HUB:IMSER.ADD_CONTACT
      Argument timeout specifies the amount of time to wait for the synchronous reply message. If timeout is zero (0), the call waits forever for the reply message.
      Parameters:
      destination - the request destination switch:server.service.
      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 the switch server.
      Throws:
      NullPointerException - if destination is null.
      IllegalArgumentException - if timeout is negative.
      IllegalStateException - if already waiting for a reply message.
      SocketTimeoutException - if timeout expired while waiting for reply.
      Exception - if another error occurs.

    • sendMessage

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

    • connect

      public void connect(String name, Properties properties) throws Exception
      Connects this ClientChannel to the switch server using supplied name and properties. The name is used to identify this client channel with the switch. The properties provide the connection and configuration parameters of the client.
      Parameters:
      name - the name of this client channel.
      properties - the properties of this client channel.
      Throws:
      NullPointerException - if an argument is null.
      IllegalStateException - if the client is already connected.
      Exception - if another error occurs.

    • connect

      public void connect(String name, String nameOrUri, String username, String password) throws Exception
      Connects this ClientChannel to a switch server using supplied arguments. The name identifies this ClientChannel with the switch server. Argument nameOrURI specifies the protocol, address and listen port of the Switch. Arguments username and password provide the credentials of a switch user.
      Parameters:
      name - the name of this client channel.
      nameOrUri - an environment name or connection URI.
      username - the name of a user of the switch server.
      password - the password of a user of the switch server.
      Throws:
      NullPointerException - if an argument is null.
      IllegalStateException - if the client is already connected.
      Exception - if another error occurs.

    • connect

      public void connect(String name, String nameOrUri) throws Exception
      Connects this ClientChannel to a switch server using supplied name and nameOrUri. The name identifies this ClientChannel with the switch server. Argument nameOrURI specifies the protocol, address and listen port of the switch server.
      Parameters:
      name - the name of this client channel.
      nameOrUri - an environment name or connection URI.
      Throws:
      NullPointerException - if an argument is null.
      IllegalStateException - if the client is already connected.
      Exception - if another error occurs.

    • close

      public void close()
      Close this channel, relinquishing any underlying resources.
      Specified by:
      close in interface AutoCloseable
      Overrides:
      close in class ChannelBase