Package com.kristensoft.kdc

Class Client

java.lang.Object

com.kristensoft.kdc.Client

All Implemented Interfaces:

Closeable, AutoCloseable, Runnable

Direct Known Subclasses:

KristenHttpClient, MulticastClient, TcpClient, UdpClient

public abstract class Client
extends Object
implements Runnable, Closeable

Abstract base class that provides common functionality for KDC client implementations. Clients provide the communication interface used to send agents and internally process agents received using a specific protocol.

Applications may access a client through an Agent, but client implementations are created and managed by KDC.

A client may receive multiple Reply objects in response to sent agents. Replies are retained in a reply queue and may be accessed using nextReply(), peekReply(), pollReply(), and replyAvailable().

Author:

Charles B. Kozoyed

See Also:

CommsEntity, TcpClient, UdpClient, MulticastClient, KristenHttpClient

Method Summary

Modifier and Type	Method	Description
abstract void	close()	Closes the networking resources associated with this client.
void	flushMetrics()	Flushes the accumulated latency metrics for this communication entity.
AgentSerializer	getAgentSerializer()	Returns the agent serializer used by this communication entity.
ClientParameters	getClientParameters()	Gets the parameters associated with this client.
Hub	getServerHub()	Gets the server hub associated with this client.
void	halt()	Halts this client by closing its networking resources and stopping its receiver thread.
boolean	isRunning()	Determines whether this communication entity is currently running.
Reply	nextReply()	Waits for and returns the next reply received by this client.
Reply	peekReply()	Returns the next reply received by this client without removing it from the reply queue.
Reply	pollReply()	Returns and removes the next reply received by this client.
Reply	pollReply(long timeout, TimeUnit timeUnit)	Waits up to the specified timeout for a reply and removes it from this client's reply queue.
boolean	replyAvailable()	Determines whether a reply is currently available for this client.
void	run()	Runs the client receiver thread.
void	sendAsync(Agent agent)	Sends an agent asynchronously to the receiver.
void	start()	Starts this client's receiver thread.
void	stop()	Stops this client's receiver thread and removes the client from its associated server hub, if applicable.
Reply	takeReply()	Waits for and removes the next reply from this client's reply queue.

Methods inherited from class java.lang.Object

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

Method Detail

getClientParameters

public ClientParameters getClientParameters()

Gets the parameters associated with this client.

Returns:

the client parameters.

getServerHub

public Hub getServerHub()

Gets the server hub associated with this client.

Returns:

the server hub, or null if this client is not associated with a server hub.

close

public abstract void close()

Closes the networking resources associated with this client.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

run

public void run()

Runs the client receiver thread. Incoming replies are placed on the reply queue, while other received agents are queued for processing.

Specified by:

run in interface Runnable

sendAsync

public void sendAsync(Agent agent)
               throws IOException,
                      KristenCommsException

Sends an agent asynchronously to the receiver. This method returns after the agent is sent and does not wait for a reply.

Parameters:

agent - the agent to send.

Throws:

IllegalArgumentException - if agent is null.

IOException - if an I/O error occurs while sending the agent.

KristenCommsException - if a KDC communications error occurs.

See Also:

Agent.getClient()

nextReply

public Reply nextReply()
                throws InterruptedException

Waits for and returns the next reply received by this client.

Returns:

the next received reply.

Throws:

InterruptedException - if the thread is interrupted while waiting for a reply.

peekReply

public Reply peekReply()

Returns the next reply received by this client without removing it from the reply queue.

Returns:

the next received reply, or null if no reply is available.

pollReply

public Reply pollReply()

Returns and removes the next reply received by this client.

Returns:

the next received reply, or null if no reply is available.

pollReply

public Reply pollReply(long timeout,
                       TimeUnit timeUnit)
                throws InterruptedException

Waits up to the specified timeout for a reply and removes it from this client's reply queue.

If a reply is already available, this method returns immediately. Otherwise, it waits until a reply becomes available, the timeout expires, or the calling thread is interrupted. A timeout does not indicate that the server has finished sending replies.

Example:

 try {
     client.sendAsync(agent);

     while (true) {
 
         Reply reply = client.pollReply(5, TimeUnit.SECONDS);
 
         if (reply == null) {
             // No reply yet; continue waiting.
             continue;
         }

         processReply(reply);

         if (reply.isLastReply()) {
             break;
         }
     }
 } catch (InterruptedException e) {
     Thread.currentThread().interrupt();
 }
 

Parameters:

timeout - the maximum time to wait; a value less than or equal to zero causes this method to return without waiting

timeUnit - the time unit of the timeout

Returns:

the next reply removed from the queue, or null if the timeout expires before a reply becomes available

Throws:

InterruptedException - if the calling thread is interrupted while waiting

NullPointerException - if timeUnit is null

See Also:

pollReply(), takeReply()

replyAvailable

public boolean replyAvailable()

Determines whether a reply is currently available for this client.

Returns:

true if a reply is available; false otherwise.

takeReply

public Reply takeReply()
                throws InterruptedException

Waits for and removes the next reply from this client's reply queue. Blocks until a reply becomes available or the calling thread is interrupted. This method has no timeout.

Replies are received independently of this method and remain queued until consumed. An empty queue does not indicate that the server has finished sending replies.

For a sequence of replies, the caller can continue taking replies until the server marks a reply as the last reply. The final reply should also be processed.

Example:

 try {

     client.sendAsync(agent);
     Reply reply;

     do {

         reply = client.takeReply();
         processReply(reply);

     } while (!reply.isLastReply());

 } catch (InterruptedException e) {
     Thread.currentThread().interrupt();
 }
 

Run this code on a background thread when the calling thread must remain responsive.

Returns:

the next reply removed from the queue

Throws:

InterruptedException - if the calling thread is interrupted while waiting

See Also:

pollReply()

halt

public void halt()

Halts this client by closing its networking resources and stopping its receiver thread.

start

public void start()

Starts this client's receiver thread. If the client is already running, this method has no effect.

stop

public void stop()

Stops this client's receiver thread and removes the client from its associated server hub, if applicable.

isRunning

public boolean isRunning()

Determines whether this communication entity is currently running.

Returns:

true if this communication entity is running; false otherwise

flushMetrics

public void flushMetrics()

Flushes the accumulated latency metrics for this communication entity.

This method may be used to report any currently accumulated metrics without waiting for the configured latency reporting interval.

getAgentSerializer

public AgentSerializer getAgentSerializer()

Returns the agent serializer used by this communication entity.

The serializer may be used to inspect or modify serialization settings at runtime, including compression and encryption settings.

Returns:

the agent serializer used by this communication entity