Configuration Platform SDK 7.6 API Reference

com.genesyslab.platform.commons.protocol
Class DuplexChannel

java.lang.Object
  extended bycom.genesyslab.platform.commons.protocol.AbstractChannel
      extended bycom.genesyslab.platform.commons.protocol.DuplexChannel
All Implemented Interfaces:
AsyncChannel, AsyncInvokerSupport, Channel, ChannelListenerSupport, ConfigurationSupport, ConnectionInvokerSupport, EndpointSupport, InputChannel, InterceptorSupport, MessageReceiver, MessageReceiverManagement, OutputChannel, ProtocolDescriptionSupport, Receiver, ReceiverManagement
Direct Known Subclasses:
ClientChannel

public class DuplexChannel
extends AbstractChannel
implements InputChannel, OutputChannel, InterceptorSupport, MessageReceiverManagement, ProtocolDescriptionSupport

Allows for asynchronous two-way communication between a Platform SDK application and a server. It is the parent class of ClientChannel.



Please note that instances of this class require some explicit lifecycle management. You have to do your best to ensure that channel is closed whenever it's not used any more — for example, on application exit. Do not rely on GC for this. Although the finalizer will try to close the underlying connection, finalizers by their very nature cannot guarantee proper resource deallocation.



Also note that the channel performs some of its operations in a thread that is different from the one the operation was called in. These asynchronous operations are beginOpen(), beginClose(), and all event-firing operations.



By default, such asynchronous operations are performed using the default invoker, which uses a single deamon thread for all channels of "this VM". So, if you are writing a of server application which uses a lot of channels and open and closes them with async operations, consider using a more sophisticated invoker. Otherwise, your open and close requests would be queued in line for completion and some of them might possibly time out.

There are two ways to configure the channel. First is AbstractChannel.configure(com.genesyslab.platform.commons.connection.ConnectionConfiguration) method. Another is to pass configuration parametrs in the URL. Second way will work only if first one wasn't used.

For Genesys internal use only.


Field Summary
 
Fields inherited from interface com.genesyslab.platform.commons.protocol.Channel
DEFAULT_TIMEOUT, INFINITE_TIMEOUT
 
Fields inherited from interface com.genesyslab.platform.commons.protocol.Receiver
DEF_INPUT_SIZE
 
Constructor Summary
DuplexChannel(Endpoint endpoint, ProtocolFactory protocolFactory)
          Create channel.
DuplexChannel(Endpoint endpoint, ProtocolFactory protocolFactory, long timeout)
          Create channel.
 
Method Summary
 void beginClose()
          Method is asynchronous.
 void beginOpen()
          Method is asynchronous.
 void clearInput()
          Clears input queue of the channel.
 void close()
           
 void close(long timeout)
           
 int getInputSize()
          Return the amount of messages this Receiver can hold before start to "forget stale messages"
 com.genesyslab.platform.commons.connection.interceptor.Interceptor getInterceptor()
          Return interceptor of the connection behind this channel.
 ProtocolDescription getProtocolDescription()
           
 void open()
          Open the channel by opening underlying connection.
 void open(long timeout)
          Open connection.
 Message receive()
          This synchronous method blocks until it receives a message from the server.
 Message receive(long timeout)
          This synchronous method blocks until it receives a message from the server or until it reaches the length of the designated timeout.
 void releaseReceivers()
          Notify receivers (threads waiting on receive() methods) they should stop waiting and return null.
 void resetReceiver()
          Reset receiver for this channel to default.
 void send(Message message)
          Send message to remote party.
 void setConnectionInvoker(AsyncInvoker connectionInvoker)
          Set AsyncInvoker to be used by underlying connection layer.
 void setInputSize(int inputSize)
          Set the amount of messages this Receiver can hold before start to "forget stale messages"
 void setReceiver(MessageReceiverSupport receiver)
          Set receiver for this channel.
 java.lang.String toString()
           
 
Methods inherited from class com.genesyslab.platform.commons.protocol.AbstractChannel
addChannelListener, configure, getConfiguration, getEndpoint, getState, getTimeout, removeChannelListener, setEndpoint, setInvoker, setTimeout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.genesyslab.platform.commons.protocol.Channel
getTimeout, setTimeout
 
Methods inherited from interface com.genesyslab.platform.commons.protocol.AsyncChannel
getState
 
Methods inherited from interface com.genesyslab.platform.commons.protocol.ChannelListenerSupport
addChannelListener, removeChannelListener
 

Constructor Detail

DuplexChannel

public DuplexChannel(Endpoint endpoint,
                     ProtocolFactory protocolFactory)
Create channel. Timeout can be set to following values:

Parameters:
endpoint - Parameters of the connection to create
protocolFactory - Factory to create messages.

DuplexChannel

public DuplexChannel(Endpoint endpoint,
                     ProtocolFactory protocolFactory,
                     long timeout)
Create channel. Timeout can be set to following values:

Parameters:
endpoint - Parameters of the connection to create
protocolFactory - Factory to create messages.
timeout - timeout to waitResponse for message in receive() or open() method
Method Detail

open

public void open()
          throws ProtocolException,
                 java.lang.InterruptedException,
                 java.lang.IllegalStateException
Open the channel by opening underlying connection. This method will block until connection is opened or detects an error condition, possibly forever. Use open(long) method to set timeouts.

Specified by:
open in interface Channel
Throws:
ProtocolException - if there is problems opening the connection
java.lang.InterruptedException
java.lang.IllegalStateException

open

public void open(long timeout)
          throws ProtocolException,
                 java.lang.InterruptedException,
                 java.lang.IllegalStateException
Open connection. Timeout can be set to following values:

Specified by:
open in interface Channel
Parameters:
timeout - time to waitResponse for the connection
Throws:
ProtocolException - if there is problems oening the connection
java.lang.InterruptedException
java.lang.IllegalStateException

beginOpen

public void beginOpen()
               throws ProtocolException
Description copied from interface: AsyncChannel
Method is asynchronous. It will start connection sequence and return. Whether connection is established on return is not specified.

Specified by:
beginOpen in interface AsyncChannel
Throws:
ProtocolException - in case of problems establishing connection

close

public void close()
           throws ProtocolException,
                  java.lang.InterruptedException,
                  java.lang.IllegalStateException
Specified by:
close in interface Channel
Throws:
ProtocolException
java.lang.InterruptedException
java.lang.IllegalStateException

close

public void close(long timeout)
           throws ProtocolException,
                  java.lang.InterruptedException,
                  java.lang.IllegalStateException
Specified by:
close in interface Channel
Throws:
ProtocolException
java.lang.InterruptedException
java.lang.IllegalStateException

beginClose

public void beginClose()
                throws java.lang.IllegalStateException
Description copied from interface: AsyncChannel
Method is asynchronous. It will start disconnection and return. Whether connection is closed on return is not specified.

Specified by:
beginClose in interface AsyncChannel
Throws:
java.lang.IllegalStateException

receive

public Message receive()
                throws java.lang.InterruptedException
This synchronous method blocks until it receives a message from the server. It can be used after the send method to wait for the response. It can also be used on its own, in which case it will wait for the next event from the server that is directed at the issuing application.

Here is a sample of how to use the send and receive methods:


 interactionServerProtocol.send(requestAgentLogin);
 Message response = interactionServerProtocol.receive();
 

You can also use receive on its own, like this:


 Message unsolicitedEvent = interactionServerProtocol.receive();
 

Note, that when the channel is closed for any reason it tries to "release" all receive() methods that are currently waiting, which causes them to return null. If this method is called during that process than this or some another receive() won't be released. So, its strongly recommended to avoid calling it during the close process.

Specified by:
receive in interface MessageReceiver
Returns:
Message from the channel or null if the channel is "empty"
Throws:
java.lang.InterruptedException - if thread is interrupted during this method execution

receive

public Message receive(long timeout)
                throws java.lang.InterruptedException
This synchronous method blocks until it receives a message from the server or until it reaches the length of the designated timeout. See receive().

See Channel for the meaning of the timeout values.

Specified by:
receive in interface MessageReceiver
Parameters:
timeout - timeout to waitResponse for message
Returns:
Message from the channel or null if the channel is "empty"
Throws:
java.lang.InterruptedException - if thread is interrupted during this method execution

send

public void send(Message message)
          throws ProtocolException,
                 java.lang.IllegalStateException
Description copied from interface: OutputChannel
Send message to remote party. This method is usually asynchronous, so not every problem that occures during send operation is thrown as exception. Detected problem may lead to error handler execution or even connection termination.

Specified by:
send in interface OutputChannel
Parameters:
message - Message to send
Throws:
ProtocolException - some generic problems
java.lang.IllegalStateException

getInputSize

public int getInputSize()
Description copied from interface: Receiver
Return the amount of messages this Receiver can hold before start to "forget stale messages"

Specified by:
getInputSize in interface Receiver
Returns:
maximum count of messages stored in receiver

setInputSize

public void setInputSize(int inputSize)
Description copied from interface: Receiver
Set the amount of messages this Receiver can hold before start to "forget stale messages"

Specified by:
setInputSize in interface Receiver
Parameters:
inputSize - maximum count of messages stored in receiver

releaseReceivers

public void releaseReceivers()
Description copied from interface: Receiver
Notify receivers (threads waiting on receive() methods) they should stop waiting and return null.

Specified by:
releaseReceivers in interface Receiver

getInterceptor

public com.genesyslab.platform.commons.connection.interceptor.Interceptor getInterceptor()
Return interceptor of the connection behind this channel. You can use that interceptor to reconfigure it or to issue special command on it. One example of such interceptor is ADDP. Note, that by default connection has no interceptor, so this method can return null. Interceptors are created using ConnectionConfiguration class and AbstractChannel.configure( com.genesyslab.platform.commons.connection.ConnectionConfiguration) method.

Specified by:
getInterceptor in interface InterceptorSupport
Returns:
interceptor for this channel or null if there is no interceptor configured.

clearInput

public void clearInput()
Clears input queue of the channel. Please note, that there is no strict guaranties that input queue will be empty after this method has returned, the messages could be put into the queue by another thread.

Specified by:
clearInput in interface Receiver

setReceiver

public void setReceiver(MessageReceiverSupport receiver)
Set receiver for this channel. Please note, that some channel parameters related to receiver (e.g. inputSize) can be changed by this call.

Specified by:
setReceiver in interface MessageReceiverManagement
Parameters:
receiver - new Receiver

resetReceiver

public void resetReceiver()
Reset receiver for this channel to default. Please note, that some channel parameters related to receiver (e.g. inputSize) can be set to default values by this call.

Specified by:
resetReceiver in interface ReceiverManagement

setConnectionInvoker

public void setConnectionInvoker(AsyncInvoker connectionInvoker)
Description copied from class: AbstractChannel
Set AsyncInvoker to be used by underlying connection layer. please be sure you have a good uderstanding of ways the connection layer works before you use this method.

Specified by:
setConnectionInvoker in interface ConnectionInvokerSupport
Overrides:
setConnectionInvoker in class AbstractChannel
Parameters:
connectionInvoker - invoker for connection layer

getProtocolDescription

public ProtocolDescription getProtocolDescription()
Specified by:
getProtocolDescription in interface ProtocolDescriptionSupport

toString

public java.lang.String toString()

Configuration Platform SDK 7.6 API Reference

Send comments on this topic.
Copyright © 2006–2008 Genesys Telecommunication Laboratories, Inc. All rights reserved.