cl.obcom.netclient

Class ClientSlot

java.lang.Object

cl.obcom.netclient.ClientSlot

public final class ClientSlot
extends Object

Implements a sub channel within a ClientChannel TCP/IP communication channel.

A client application uses a ClientSlot to send transactions, receive multicast data, and request other services from an NetServer or other custom made servers (see ServerChannel for details about building custom servers).

A ClientSlot can only be created using the newSlot method of a ClientChannel.

See Also:

ClientChannel, ClientChannel.newSlot()

Method Summary

Modifier and Type	Method and Description
void	disableMulticast(String name) Disables the reception of multicast messages identified by the specified name.
void	enableMulticast(String name, MulticastListener listener) Enables the reception of multicast messages identified by the specified name.
boolean	getAlwaysEncrypt() Returns true if messages are always sent encrypted to OBCOM NetServer.
ClientChannel	getChannel() Returns the ClientChannel that owns this ClientSlot.
int	getID() Returns the ID of this ClientSlot.
Layout	getLayout(String layoutName) Returns the message layout identified by the supplied layoutName.
LayoutManager	getLayoutManager() Returns the LayoutManager associatted with this ClientSlot.
String	getName() Returns the name of this ClientSlot.
String	getTimestamp() Returns an OBCOM NetServer timestamp.
boolean	isAlive() Returns true if this ClientSlot is alive.
void	release() Releases this ClientSlot and free allocated resources.
Message	sendTransaction(String service, Object request) Sends a transaction request to a service using the supplied request data.
Message	sendTransaction(String service, Object request, boolean encrypted) Sends a transaction request to a service using the supplied request data and encryption option.
Message	sendTransaction(String service, Object request, boolean encrypted, boolean signed) Sends a transaction request to a service using the supplied request data, encryption and signature options.
Message	sendTransaction(String service, Object request, boolean encrypted, boolean signed, long timeout) Sends a transaction request to a service using the supplied request data, encryption, signature and timeout options.
void	setAlwaysEncrypt(boolean value) Changes whether messages are always sent encrypted to OBCOM NetServer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

release

public void release()

Releases this ClientSlot and free allocated resources. No other method of this ClientSlot instance can be used after this method has been issued. Calling this method more than once is allowed but has no effect after the first invocation.

getName

public String getName()

Returns the name of this ClientSlot.

Returns:

the name of this ClientSlot.

getID

public int getID()

Returns the ID of this ClientSlot.

Returns:

the ID of this ClientSlot.

isAlive

public boolean isAlive()

Returns true if this ClientSlot is alive. A ClientSlot becomes dead when a system operator executes the "kill client" command in an NetServer Console.

Returns:

true if this ClientSlot is alive.

getChannel

public ClientChannel getChannel()

Returns the ClientChannel that owns this ClientSlot. If this ClientSlot has been released, it throws an exception.

Returns:

the ClientChannel that owns this ClientSlot.

Throws:

NetException - if this ClientSlot has been released.

getLayoutManager

public LayoutManager getLayoutManager()

Returns the LayoutManager associatted with this ClientSlot.

Returns:

the LayoutManager associatted with this ClientSlot.

getAlwaysEncrypt

public boolean getAlwaysEncrypt()

Returns true if messages are always sent encrypted to OBCOM NetServer.

Returns:

true if messages are always sent encrypted.

See Also:

setAlwaysEncrypt(boolean)

setAlwaysEncrypt

public void setAlwaysEncrypt(boolean value)

Changes whether messages are always sent encrypted to OBCOM NetServer. 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 are always sent encrypted.

See Also:

getAlwaysEncrypt(), sendTransaction(String, Object, boolean, boolean, long)

getLayout

public Layout getLayout(String layoutName)

Returns the message layout identified by the supplied layoutName. If the message layout is not available in the LayoutManager cache, it is (down)loaded, compiled, stored in the cache and returned back to the caller of this method.

Parameters:

layoutName - the name of the required message layout.

Returns:

the requested message layout.

See Also:

ClientChannel, LayoutManager, Layout, Message

sendTransaction

public Message sendTransaction(String service,
                               Object request)

Sends a transaction request to a service using the supplied request data. See sendTransaction for further details, because this is just a convenience method implemented by the following trivial statement:

sendTransaction(service, request, false, false, 0);

Parameters:

service - name of the service host.server.transaction.

request - the input request data sent to the service.

Returns:

Message containing the service output reply data.

See Also:

sendTransaction(String, Object, boolean, boolean, long)

sendTransaction

public Message sendTransaction(String service,
                               Object request,
                               boolean encrypted)

Sends a transaction request to a service using the supplied request data and encryption option. See sendTransaction for further details, because this is just a convenience method implemented by the following trivial statement:

sendTransaction(service, request, encrypted, false, 0);

Parameters:

service - name of the service host.server.transaction.

request - the input request data sent to the service.

encrypted - if true request data will be sent encrypted.

Returns:

Message containing the service output reply data.

See Also:

sendTransaction(String, Object, boolean, boolean, long)

sendTransaction

public Message sendTransaction(String service,
                               Object request,
                               boolean encrypted,
                               boolean signed)

Sends a transaction request to a service using the supplied request data, encryption and signature options. See sendTransaction for further details, because this is just a convenience method implemented by the following trivial statement:

sendTransaction(service, request, encrypted, signed, 0);

Parameters:

service - name of the service host.server.transaction.

request - the input request data sent to the service.

encrypted - if true request data will be sent encrypted.

signed - if true request data will be sent digitally signed.

Returns:

Message containing the service output reply data.

See Also:

sendTransaction(String, Object, boolean, boolean, long)

sendTransaction

public Message sendTransaction(String service,
                               Object request,
                               boolean encrypted,
                               boolean signed,
                               long timeout)

Sends a transaction request to a service using the supplied request data, encryption, signature and timeout options. If encrypted is true the request data will be sent encrypted. If signed is true the request data will be sent digitally signed. The request data is converted to a String using the standard method toString, hence any Java Object can be used as request data. The service argument has one of the following formats:

 {HostName.}ServerName.TranName
 {HostName.}ServerName.[TranCode]

where optional items are shown within "{" and "}" brackets, and the characters ".", "[" and "]" stand for themselves. If the optional HostName is not specified, then the NetServer Default Host will be used. TranName is the name of the requested transaction, while TranCode is and alternative one-character identification of the same transaction. Either TranName or TranCode must be specified. Some examples:

 ECUSER.[!]
 ACASER.ACA-TIME
 HUB.IMSER.AddContact

The timeout argument specifies the amount of milliseconds to wait (more or less) for the reply message. If timeout is zero, however, the call simply waits forever for the reply message.

Parameters:

service - name of the service host.server.transaction.

request - the transaction request data for the service.

encrypted - if true request data will be sent encrypted.

signed - if true request data will be sent digitally signed.

timeout - the maximum time to wait for a reply (milliseconds).

Returns:

the reply message of the transaction request.

Throws:

ConnectException - when the connection to the NetServer fails.

TimeoutException - when timeout expired while waiting for the reply.

getTimestamp

public String getTimestamp()

Returns an OBCOM NetServer timestamp. An OBCOM NetServer timestamp is a string that identifies a unique point in time. Each time an OBCOM NetServer returns a timestamp, it's value is guaranteed to be different (bigger) than the previous timestamp returned. An OBCOM NetServer timestamp is a 26 character string with the following format:

yyyy-MM-dd:HH:mm:ss.cccccc

Returns:

an OBCOM NetServer timestamp string.

Throws:

NetException - if the operation fails.

enableMulticast

public void enableMulticast(String name,
                            MulticastListener listener)

Enables the reception of multicast messages identified by the specified name. Multicast messages are generated by OBCOM NetServer when particular event occurs (e.g., the price of a stock has reached a certain limit). When a multicast message arrives, the processMulticast method of supplied listener will be called. The name argument has the following format:

{HostName.}MulticastName

with an optional HostName. If no HostName is specified, the OBCOM NetServer Local Host name is used. The MulticastName is requiered and has a maximum length of 10 chars.

Parameters:

name - name of the multicast messages to enable.

listener - the listener for multicast messages.

Throws:

NullPointerException - if listener is null.

NetException - if the NetServer registration fails.

See Also:

disableMulticast(String)

disableMulticast

public void disableMulticast(String name)

Disables the reception of multicast messages identified by the specified name. Multicast messages are generated by NetServers when particular event occurs (e.g., the price of a stock has reached a certain limit). The name argument has the following format:

{HostName.}MulticastName

with an optional HostName. If no HostName is specified, the NetServer Local Host name value will be used. The MulticastName is requiered and has a maximum length of 10 chars. If the name argument 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 to disable.

Throws:

NullPointerException - if name is null or empty.

IllegalArgumentException - if name is invalid.

NetException - if the NetServer unregistration fails.

See Also:

enableMulticast(String, MulticastListener)