net.sf.eBus.client

Class ERemoteApp

java.lang.Object

net.sf.eBus.client.ERemoteApp

All Implemented Interfaces:

EObject, EPublisher, EReplier, ERequestor, ESubscriber

public final class ERemoteApp
extends Object
implements EPublisher, ESubscriber, EReplier, ERequestor

This class encapsulates a connection between eBus applications. A ERemoteApp instance is created by either:

• openConnection: Establishes a connection from this process to a remote application at the specified Internet address.
• EServer: Accepts a connection from a remote application and encapsulates the accepted socket.

The ERemoteApp instance is responsible for forwarding advertisements, subscriptions, requests and replies to the remote application.

An application can track ERemoteApp events for all connections by subscribing to the message key net.sf.eBus.client.ConnectionMessage:/eBus. The ConnectionMessage contains the remote eBus socket address and whether the remote eBus is logged on or logged off. If logged off, an optional reason is provided for why the eBus logged off. Unsubscribe to stop receiving these updates. Note: this message key is published locally and cannot be accessed by remote eBus applications.

Only one connection may exist between any two eBus processes, independent of which process established the first connection. This means that an eBus process may not connect to itself.

Author:

Charles Rapp

Field Summary

Fields

Modifier and Type	Field and Description
static EMessageKey	CONNECTION_UPDATE_KEY eBus connection updates are reported using ConnectionMessage and the subject "/eBus".
static int	NO_ID Used to specify that the feed identifier is not set.
static String	NORMAL_LOGOFF When a remote eBus disconnects by sending a logoff message, then the reason is set to "logged off".

Method Summary

Modifier and Type	Method and Description
InetSocketAddress	address() Returns the host and port of the remote eBus engine to which this client is connected.
void	cancelRequest(EReplyFeed.ERequest request) Forward this cancel request to the remote eBus application if that remote application acknowledged the request.
static void	closeAllConnections() Closes all currently open connections.
static void	closeConnection(InetSocketAddress address) Closes a currently open remote eBus client referenced by the Internet address.
static void	configure(EConfigure config) Opens the remote eBus connections as per EConfigure.remoteConnections().
static int	connectionCount() Returns the number of remote connections.
static Collection<InetSocketAddress>	connections() Returns a copy of the existing remote eBus application connections.
void	feedStatus(EFeedState feedState, ERequestFeed feed) Ignores request feed state changes.
void	feedStatus(EFeedState feedState, IESubscribeFeed feed) Forwards the subscribe feed state to the remote eBus application if the feed is still in place.
boolean	isConnected() Returns true if connected and logged on to the remote eBus application and false otherwise.
static boolean	isConnected(InetSocketAddress a) Returns true if there is a connection to the remote eBus application at the given Internet address and false otherwise.
void	notify(ENotificationMessage msg, IESubscribeFeed feed) Forwards the message to the remote eBus application if the subscription is still in place.
static ERemoteApp	openConnection(EConfigure.RemoteConnection config) Opens a client socket connection to the remote eBus at the specified host and port and binding the local Internet address to local port.
void	publishStatus(EFeedState feedState, IEPublishFeed feed) This callback means that there is or is not a local subscriber for the remote publisher.
void	reply(int remaining, EReplyMessage reply, ERequestFeed.ERequest request) Forwards the remaining replier count and reply message to the remote eBus application.
void	request(EReplyFeed.ERequest request) Assigns a locally unique identifier to this request and forwards the request to the remote eBus application.
String	toString()
boolean	willReconnect() Returns true if the connection is automatically re-established when lost; false otherwise.

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.eBus.client.EObject

shutdown, startup

Field Detail

NO_ID

public static final int NO_ID

Used to specify that the feed identifier is not set.

See Also:

Constant Field Values

CONNECTION_UPDATE_KEY

public static final EMessageKey CONNECTION_UPDATE_KEY

eBus connection updates are reported using ConnectionMessage and the subject "/eBus".

NORMAL_LOGOFF

public static final String NORMAL_LOGOFF

When a remote eBus disconnects by sending a logoff message, then the reason is set to "logged off".

See Also:

Constant Field Values

Method Detail

publishStatus

public void publishStatus(EFeedState feedState,
                          IEPublishFeed feed)

This callback means that there is or is not a local subscriber for the remote publisher. Convert this into a remote subscription message, passing along the given feed state.

Specified by:

publishStatus in interface EPublisher

Parameters:

feedState - subscribe to or unsubscribe from the remote publisher.

feed - the publish feed.

feedStatus

public void feedStatus(EFeedState feedState,
                       IESubscribeFeed feed)

Forwards the subscribe feed state to the remote eBus application if the feed is still in place.

Specified by:

feedStatus in interface ESubscriber

Parameters:

feedState - the updated subscription state.

feed - the state change applies to this subscribe feed. This is an ESubscribeFeed instance since multi-key feeds cannot be transmitted to remote applications.

See Also:

ESubscriber.notify(ENotificationMessage, IESubscribeFeed)

notify

public void notify(ENotificationMessage msg,
                   IESubscribeFeed feed)

Forwards the message to the remote eBus application if the subscription is still in place.

Specified by:

notify in interface ESubscriber

Parameters:

msg - forward this message.

feed - subscription feed posting this callback. This is an ESubscribeFeed instance since multi-key feeds cannot be transmitted to remote applications.

See Also:

ESubscriber.feedStatus(EFeedState, IESubscribeFeed)

request

public void request(EReplyFeed.ERequest request)

Assigns a locally unique identifier to this request and forwards the request to the remote eBus application. The remote eBus application uses the assigned request identifier to match this request to the remote request feed.

Specified by:

request in interface EReplier

Parameters:

request - the request instance.

See Also:

EReplier.cancelRequest(EReplyFeed.ERequest)

cancelRequest

public void cancelRequest(EReplyFeed.ERequest request)

Forward this cancel request to the remote eBus application if that remote application acknowledged the request. If not yet acknowledged, then sends the cancel request message upon acknowledgment.

Specified by:

cancelRequest in interface EReplier

Parameters:

request - cancel this request.

See Also:

EReplier.request(EReplyFeed.ERequest)

feedStatus

public void feedStatus(EFeedState feedState,
                       ERequestFeed feed)

Ignores request feed state changes.

Specified by:

feedStatus in interface ERequestor

Parameters:

feedState - the latest request feed state.

feed - feed state applies to this feed.

See Also:

ERequestor.reply(int, EReplyMessage, ERequestFeed.ERequest)

reply

public void reply(int remaining,
                  EReplyMessage reply,
                  ERequestFeed.ERequest request)

Forwards the remaining replier count and reply message to the remote eBus application.

This method and remoteRequest(EMessageHeader) are synchronized to protect against the reply delivery prior to storing the request information. If not synchronized, the reply would appear to be for an unknown request.

Specified by:

reply in interface ERequestor

Parameters:

remaining - number of repliers still actively replying.

reply - the reply message.

request - reply is for this request.

See Also:

ERequestor.feedStatus(EFeedState, ERequestFeed)

toString

public String toString()

Overrides:

toString in class Object

address

public InetSocketAddress address()

Returns the host and port of the remote eBus engine to which this client is connected.

Returns:

the host and port of the remote eBus engine to which this client is connected.

willReconnect

public boolean willReconnect()

Returns true if the connection is automatically re-established when lost; false otherwise.

Returns:

true if the connection is automatically re-established when lost; false otherwise.

isConnected

public boolean isConnected()

Returns true if connected and logged on to the remote eBus application and false otherwise.

Returns:

true if connected and logged on to the remote eBus application and false otherwise.

connectionCount

public static int connectionCount()

Returns the number of remote connections.

Returns:

the number of remote connections.

connections

public static Collection<InetSocketAddress> connections()

Returns a copy of the existing remote eBus application connections.

Returns:

a copy of the existing remote eBus application connections.

isConnected

public static boolean isConnected(InetSocketAddress a)

Returns true if there is a connection to the remote eBus application at the given Internet address and false otherwise.

Parameters:

a - find a connection to this Internet address.

Returns:

true if there is a connection to the remote eBus application at the given Internet address and false otherwise.

openConnection

public static ERemoteApp openConnection(EConfigure.RemoteConnection config)

Opens a client socket connection to the remote eBus at the specified host and port and binding the local Internet address to local port. If a connection to the given host and type already exists then throws an IllegalStateException and does nothing else.

If the bind port is zero, then the local Internet address is bound to any available port.

Only one connection is allowed between eBus engines regardless of which engine initiated the connection. An eBus engine is also precluded from connecting to itself.

Parameters:

config - remote connection configuration.

Returns:

the remote eBus connection instance.

Throws:

NullPointerException - if config is null.

closeConnection

public static void closeConnection(InetSocketAddress address)

Closes a currently open remote eBus client referenced by the Internet address. Does nothing if no such client currently exists.

Parameters:

address - close the connection to this eBus host and serverPort.

closeAllConnections

public static void closeAllConnections()

Closes all currently open connections.

configure

public static void configure(EConfigure config)

Opens the remote eBus connections as per EConfigure.remoteConnections().

Parameters:

config - contains the remote eBus connection configuration.