ClientChannel (OBCOM NetClient v2.138)

java.lang.Object
- cl.obcom.netclient.ClientChannel

```
public final class ClientChannel
extends Object
```
Communication channel between a client application and the OBCOM NetServer. Through this channel, an application can send transactions, receive multicast data, and request other services from the NetServer or other custom made servers (see ServerChannel for details about building custom servers). This communication channel is established as late as possible. Yet, once established, it is kept running until a system operator executes the "kill client" command in an NetServer Console. If the communication channel is lost for any other reason, it is automatically re-established as soon as possible.

In order to maximize reusability and to reduce the number of physical network connections, the ClientChannel is implemented as a shared (multiplexed) channel (socket). For this reason, a client application cannot use a ClientChannel directly, but it has to acquire a ClientSlot instance using the newSlot method. It is through this ClientSlot that the client application communicates with the NetServer environment.

The following example uses a ClientChannel named JCLIENT to obtain the date from a server called ACASER. This is accomplished by sending a transaction named ACA-TIME to the ACASER server. If an error occurs while processing this transaction, the reply code of the reply message will not be Message.Reply#ACK ACK. In this case, an exception is thrown with a message obtained from the data of the reply message. If successful, the ClientSlot is released and the server's date is retrieved from a field called ACC_FECHA of the reply message and displayed in the system console.
```
 import cl.obcom.netclient.*;

 public class JClient
 {
     public static void main(String[] args)
     {
         // Create an NetServer client named "JCLIENT"
         LayoutManager layouts = new LayoutManager("http://localhost/recs/*.asp");
         ClientChannel channel = ClientChannel.create("JCLIENT", "net://localhost:10104", layouts);

         // Send transaction to "ACASER" server using a "JCLIENT" channel slot
         ClientSlot slot = channel.newSlot();
         Message reply = slot.sendTransaction("ACASER.ACA-TIME", null);
         if (reply.getReplyCode() != Message.Reply.ACK)
             throw new NetException(reply.getData());
         slot.release();

         // Display the date contained in the "ACASER" reply message
         System.out.println("The reply date is " + reply.getDate("ACC_FECHA"));
     }
 }
```
See Also:

LayoutManager, ClientSlot, Message, create

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static ClientChannel`	`create(String channelName, String netserURI, LayoutManager layouts)` Returns a `ClientChannel` named `channelName` with `netserURI` and `layouts`.
`static ClientChannel`	`create(String channelName, String netserURI, LayoutManager layouts, ClientListener listener)` Returns a `ClientChannel` named `channelName` with `netserURI`, `layouts` and `listener`.
`static ClientChannel`	`create(String channelName, String netserURI, String layoutsURI)` Returns a `ClientChannel` named `channelName` with `netserURI` and `layoutsURI`.
`static ClientChannel`	`create(String channelName, String netserURI, String layoutsURI, ClientListener listener)` Returns a `ClientChannel` named `channelName` with `netserURI`, `layoutsURI` and `listener`.
`static ClientChannel`	`delete(String channelName)` Deletes a `ClientChannel` named `channelName`.
`static boolean`	`exists(String channelName)` Returns `true` if a `ClientChannel` named `channelName` is defined.
`boolean`	`getAlwaysEncrypt()` Returns `true` if messages sent to the NetServer are always encrypted.
`ClientListener`	`getClientListener()` Returns the `ClientListener` associatted with this `ClientChannel`.
`Layout`	`getLayout(String layoutName)` Returns the layout identified by the supplied `layoutName`.
`LayoutManager`	`getLayoutManager()` Returns the `LayoutManager` associatted with this `ClientChannel`.
`String`	`getName()` Returns the name of this `ClientChannel`.
`URI`	`getNetServerURI()` Returns the NetServer URI (protocol, host and port).
`String`	`getStationKey()` Returns the station key of this `ClientChannel`.
`String`	`getVersion()` Returns the implementation version of this `ClientChannel`.
`boolean`	`isAlive()` Returns `true` if this `ClientChannel` is alive.
`static Properties`	`loadProperties(String fileName)` Returns the properties contained in the file `fileName`.
`static ClientChannel`	`lookup(String channelName)` Returns a `ClientChannel` named `channelName`, or `null` if the `ClientChannel` is not defined.
`ClientSlot`	`newSlot()` Returns a new `ClientSlot` for this `ClientChannel`.
`void`	`setAlwaysEncrypt(boolean value)` Changes whether messages sent to the NetServer are always encrypted.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getName
```
public String getName()
```
    Returns the name of this ClientChannel.
    
    Returns:
    
    the name of this ClientChannel.
  - getNetServerURI
```
public URI getNetServerURI()
```
    Returns the NetServer URI (protocol, host and port).
    
    Returns:
    
    the NetServer URI (protocol, host and port).
  - getLayoutManager
```
public LayoutManager getLayoutManager()
```
    Returns the LayoutManager associatted with this ClientChannel.
    
    Returns:
    
    the LayoutManager associatted with this ClientChannel.
  - getClientListener
```
public ClientListener getClientListener()
```
    Returns the ClientListener associatted with this ClientChannel.
    
    Returns:
    
    the ClientListener associatted with this ClientChannel.
  - getStationKey
```
public String getStationKey()
```
    Returns the station key of this ClientChannel.
    
    Returns:
    
    the station key of this ClientChannel.
  - isAlive
```
public boolean isAlive()
```
    Returns true if this ClientChannel is alive. A ClientChannel becomes dead when a system operator executes the "kill client" command in an NetServer Console.
    
    Returns:
    
    true if this ClientChannel is alive.
  - getAlwaysEncrypt
```
public boolean getAlwaysEncrypt()
```
    Returns true if messages sent to the NetServer are always encrypted.
    
    Returns:
    
    true if messages sent to the NetServer are encrypted.
    
    See Also:
    
    setAlwaysEncrypt(boolean)
  - setAlwaysEncrypt
```
public void setAlwaysEncrypt(boolean value)
```
    Changes whether messages sent to the NetServer are always encrypted. If the parameter value is true then messages will always be encrypted. Otherwise messages will be encrypted only if the parameter encrypted of the sendTransaction method is true.
    
    Parameters:
    
    value - if true messages sent to the NetServer will always be encrypted.
    
    See Also:
    
    getAlwaysEncrypt()
  - getVersion
```
public String getVersion()
```
    Returns the implementation version of this ClientChannel. The returned string consists of four decimal integers separated by periods ".", for example "1.9.2042.25539". These four integers represent the major, minor, build and revision version numbers, respectively.
    
    Returns:
    
    the implementation version of this ClientChannel.
  - getLayout
```
public Layout getLayout(String layoutName)
```
    Returns the layout identified by the supplied layoutName.
    
    Parameters:
    
    layoutName - the name of the required layout
    
    Returns:
    
    the required layout.
  - newSlot
```
public ClientSlot newSlot()
```
    Returns a new ClientSlot for this ClientChannel.
    
    Returns:
    
    a new ClientSlot for this ClientChannel.
  - create
```
public static ClientChannel create(String channelName,
                                   String netserURI,
                                   String layoutsURI)
```
    Returns a ClientChannel named channelName with netserURI and layoutsURI. See create(String, String, LayoutManager, ClientListener) for further details, because this is just a convenience method implemented by the following call statement:
```
create(channelName, netserURI, new LayoutManager(layoutsURI), null);
```
    Parameters:
    
    channelName - the name of a ClientChannel.
    
    netserURI - the NetServer URI as "protocol://host:port".
    
    layoutsURI - a URI used to create a LayoutManager.
    
    Returns:
    
    an existing or newly created ClientChannel instance.
    
    See Also:
    
    create(String, String, LayoutManager, ClientListener)
  - create
```
public static ClientChannel create(String channelName,
                                   String netserURI,
                                   LayoutManager layouts)
```
    Returns a ClientChannel named channelName with netserURI and layouts. See create(String, String, LayoutManager, ClientListener) for further details, because this is just a convenience method implemented by the following call statement:
```
create(channelName, netserURI, layouts, null);
```
    Parameters:
    
    channelName - the name of a ClientChannel.
    
    netserURI - the NetServer URI as "protocol://host:port".
    
    layouts - a LayoutManager used to load and cache layouts.
    
    Returns:
    
    an existing or newly created ClientChannel instance.
    
    See Also:
    
    create(String, String, LayoutManager, ClientListener)
  - create
```
public static ClientChannel create(String channelName,
                                   String netserURI,
                                   String layoutsURI,
                                   ClientListener listener)
```
    Returns a ClientChannel named channelName with netserURI, layoutsURI and listener. See create(String, String, LayoutManager, ClientListener) for further details, because this is just a convenience method implemented by the following call statement:
```
create(channelName, netserURI, new LayoutManager(layoutsURI), listener);
```
    Parameters:
    
    channelName - the name of a ClientChannel.
    
    netserURI - the NetServer URI as "protocol://host:port".
    
    layoutsURI - a URI used to create a LayoutManager.
    
    listener - a ClientListener called on special events.
    
    Returns:
    
    an existing or newly created ClientChannel instance.
    
    See Also:
    
    create(String, String, LayoutManager, ClientListener)
  - create
```
public static ClientChannel create(String channelName,
                                   String netserURI,
                                   LayoutManager layouts,
                                   ClientListener listener)
```
    Returns a ClientChannel named channelName with netserURI, layouts and listener. If the ClientChannel does not exist, it creates a new ClientChannel instance with the supplied arguments. The channelName argument is the name of the ClientChannel.
    The netserURI argument must have the form "protocol://address:port", where address is the host name or IP address of the NetServer listening on the specified port. The protocol can be "net" for classic connections, or "nets" for SSL/TLS connections.
    The layouts argument provides a LayoutManager used to load and cache layouts. The listener argument provides an optional ClientListener that is be called when special events occur to the ClientChannel.
    
    Parameters:
    
    channelName - the name of a ClientChannel.
    
    netserURI - the NetServer URI as "protocol://host:port".
    
    layouts - a LayoutManager used to load and cache layouts.
    
    listener - a ClientListener called on special events.
    
    Returns:
    
    an existing or newly created ClientChannel instance.
    
    Throws:
    
    NullPointerException - if an argument is null or empty.
    
    IllegalArgumentException - if an argument is invalid.
    
    See Also:
    
    lookup(String), exists(String), delete(String)
  - lookup
```
public static ClientChannel lookup(String channelName)
```
    Returns a ClientChannel named channelName, or null if the ClientChannel is not defined.
    
    Parameters:
    
    channelName - the name of a ClientChannel.
    
    Returns:
    
    a ClientChannel instance or null.
    
    Throws:
    
    NullPointerException - if channelName is null or empty.
    
    See Also:
    
    create(String, String, LayoutManager, ClientListener), exists(String), delete(String)
  - exists
```
public static boolean exists(String channelName)
```
    Returns true if a ClientChannel named channelName is defined.
    
    Parameters:
    
    channelName - the name of a ClientChannel.
    
    Returns:
    
    true if a ClientChannel is defined.
    
    Throws:
    
    NullPointerException - if channelName is null or empty.
    
    See Also:
    
    create(String, String, LayoutManager, ClientListener), lookup(String), delete(String)
  - delete
```
public static ClientChannel delete(String channelName)
```
    Deletes a ClientChannel named channelName. Nothing happens if the ClientChannel is not defined.
    
    Parameters:
    
    channelName - the name of a ClientChannel.
    
    Returns:
    
    the ClientChannel that was deleted or null if channelName is not defined.
    
    Throws:
    
    NullPointerException - if channelName is null or empty.
    
    See Also:
    
    create(String, String, LayoutManager, ClientListener), lookup(String), exists(String)
  - loadProperties
```
public static Properties loadProperties(String fileName)
```
    Returns the properties contained in the file fileName. If fileName does not specify a full path, then the current working directory of the application will be used to resolve the locatation of the property file.
    
    Parameters:
    
    fileName - the name of the property file.
    
    Returns:
    
    the properties loaded from the file.
    
    Throws:
    
    NullPointerException - if fileName is null or empty.
    
    NetException - if fileName could not be found or read.

Class ClientChannel

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getName

getNetServerURI

getLayoutManager

getClientListener

getStationKey

isAlive

getAlwaysEncrypt

setAlwaysEncrypt

getVersion

getLayout

newSlot

create

create

create

create

lookup

exists

delete

loadProperties