setCredentials must then be called before any call to logon.
* @param runQueue a RunQueue that can be used to process incoming events.
*/
public Client (Credentials creds, RunQueue runQueue)
{
_creds = creds;
_runQueue = runQueue;
}
/**
* Registers the supplied observer with this client. While registered the observer will receive
* notifications of state changes within the client. The function will refuse to register an
* already registered observer.
*
* @see ClientObserver
* @see SessionObserver
*/
public void addClientObserver (SessionObserver observer)
{
synchronized (_observers) {
_observers.add(observer);
}
}
/**
* Unregisters the supplied observer. Upon return of this function, the observer will no longer
* receive notifications of state changes within the client.
*/
public void removeClientObserver (SessionObserver observer)
{
synchronized (_observers) {
_observers.remove(observer);
}
}
/**
* Checks whether or not this client is operating in a standalone mode.
*/
public boolean isStandalone ()
{
return _standalone;
}
/**
* Configures the client to communicate with the server on the supplied hostname and set of
* ports (which will be tried in succession).
*
* @see #logon
* @see #moveToServer
*/
public void setServer (String hostname, int[] ports)
{
setServer(hostname, ports, new int[0]);
}
/**
* Configures the client to communicate with the server on the supplied hostname, set of
* ports (which will be tried in succession), and datagram ports.
*
* @see #logon
* @see #moveToServer
*/
public void setServer (String hostname, int[] ports, int[] datagramPorts)
{
_hostname = hostname;
_ports = ports;
_datagramPorts = datagramPorts;
}
/**
* Returns the RunQueue in use by this client. This can be used to queue up event dispatching
* stints.
*/
public RunQueue getRunQueue ()
{
return _runQueue;
}
/**
* Returns the hostname of the server to which this client is currently configured to connect.
*/
public String getHostname ()
{
return _hostname;
}
/**
* Returns the port on which this client is currently configured to connect to the server.
*/
public int[] getPorts ()
{
return _ports;
}
/**
* Returns the ports on the server to which the client can send datagrams. Returns an empty
* array if datagrams are not supported.
*/
public int[] getDatagramPorts ()
{
return _datagramPorts;
}
/**
* Returns the credentials with which this client is currently configured to connect to the
* server.
*/
public Credentials getCredentials ()
{
return _creds;
}
/**
* Sets the credentials that will be used by this client to authenticate with the server. This
* should be done before any call to logon.
*/
public void setCredentials (Credentials creds)
{
_creds = creds;
}
/**
* Returns the version string configured for this client.
*/
public String getVersion ()
{
return _version;
}
/**
* Sets the version string reported to the server during authentication. Some server
* implementations may wish to refuse connections by old or invalid client versions.
*/
public void setVersion (String version)
{
_version = version;
}
/**
* Configures the client with a custom class loader which will be used when reading objects off
* of the network.
*/
public void setClassLoader (ClassLoader loader)
{
_loader = loader;
if (_comm != null) {
_comm.setClassLoader(loader);
}
}
/**
* Returns the data associated with our authentication response. Users of the Presents system
* may wish to communicate authentication related information to their client by extending and
* augmenting {@link AuthResponseData}.
*/
public AuthResponseData getAuthResponseData ()
{
return _authData;
}
/**
* Returns the distributed object manager associated with this session. This reference is only
* valid for the duration of the session and a new reference must be obtained if the client
* disconnects and reconnects to the server.
*
* @return the dobjmgr in effect or null if we have no established connection to the server.
*/
public DObjectManager getDObjectManager ()
{
return _omgr;
}
/**
* Instructs the distributed object manager associated with this client to allow objects of the
* specified class to linger around the specified number of milliseconds after their last
* subscriber has been removed before the client finally removes its object proxy and flushes
* the object. Normally, objects are flushed immediately following the removal of their last
* subscriber.
*
* Note: the delay will be applied to derived classes as well as exact
* matches. Note also: this method cannot be called until after the client has
* established a connection with the server and the distributed object manager is available.
*/
public void registerFlushDelay (Class objclass, long delay)
{
ClientDObjectMgr omgr = (ClientDObjectMgr)getDObjectManager();
omgr.registerFlushDelay(objclass, delay);
}
/**
* Returns the unique id of the client's connection to the server. It is only valid for the
* duration of the session.
*/
public int getConnectionId ()
{
return _connectionId;
}
/**
* Returns the oid of the client object associated with this session. It is only valid for the
* duration of the session.
*/
public int getClientOid ()
{
return _cloid;
}
/**
* Returns a reference to the client object associated with this session. It is only valid for
* the duration of the session.
*/
public ClientObject getClientObject ()
{
return _clobj;
}
/**
* Returns the invocation director associated with this session. This reference is only valid
* for the duration of the session.
*/
public InvocationDirector getInvocationDirector ()
{
return _invdir;
}
/**
* Marks this client as interested in the specified bootstrap services group. Any services
* registered as bootstrap services with the supplied group name will be included in this
* clients bootstrap services set. This must be called before {@link #logon}.
*/
public void addServiceGroup (String group)
{
if (isLoggedOn()) {
throw new IllegalStateException("Service groups must be registered prior to logon.");
}
_bootGroups.add(group);
}
/**
* Returns the set of bootstrap service groups needed by this client.
*/
public String[] getBootGroups ()
{
return _bootGroups.toArray(new String[_bootGroups.size()]);
}
/**
* Returns the first bootstrap service that could be located that implements the supplied
* {@link InvocationService} derivation. If we fail to connect to the new server, the client will not be automatically
* reconnected to the old server. It will be in a logged off state. However, it will be
* reconfigured with the hostname and ports of the old server so that the caller can notify the
* user of the failure and then simply call {@link #logon} to attempt to reconnect to the old
* server.
*
* @param observer an observer that will be notified when we have successfully logged onto the
* other server, or if the move failed.
*/
public void moveToServer (String hostname, int[] ports, InvocationService.ConfirmListener obs)
{
moveToServer(hostname, ports, new int[0], obs);
}
/**
* Transitions a logged on client from its current server to the specified new server.
* Currently this simply logs the client off of its current server (if it is logged on) and
* logs it onto the new server, but in the future we may aim to do something fancier.
*
* If we fail to connect to the new server, the client will not be automatically
* reconnected to the old server. It will be in a logged off state. However, it will be
* reconfigured with the hostname and ports of the old server so that the caller can notify the
* user of the failure and then simply call {@link #logon} to attempt to reconnect to the old
* server.
*
* @param observer an observer that will be notified when we have successfully logged onto the
* other server, or if the move failed.
*/
public void moveToServer (
String hostname, int[] ports, int[] datagramPorts, InvocationService.ConfirmListener obs)
{
// the server switcher will take care of everything for us
new ServerSwitcher(hostname, ports, datagramPorts, obs).switchServers();
}
/**
* Requests that the client log off of the server to which it is connected.
*
* @param abortable If true, the client will call null is returned if no such service
* could be found.
*/
public clientWillDisconnect on all of
* the client observers and abort the logoff process if any of them return false. If false,
* clientWillDisconnect will not be called at all.
*
* @return true if the logoff succeeded, false if it failed due to a disagreeable observer.
*/
public boolean logoff (boolean abortable)
{
// if we have no communicator, we're not logged on anyway
if (_comm == null) {
log.warning("Ignoring request to logoff because we're not logged on.");
return true;
}
// if the request is abortable, let's run it past the observers before we act upon it
if (abortable && notifyObservers(CLIENT_WILL_LOGOFF, null)) {
return false;
}
// kill our tick interval
_tickInterval.cancel();
_tickInterval = null;
// ask the communicator to send a logoff message and disconnect from the server
_comm.logoff();
return true;
}
/**
* Prepares the client for a standalone mode logon. Returns the set of bootstrap service groups
* that should be supplied to the invocation manager to create our fake bootstrap record.
*/
public String[] prepareStandaloneLogon ()
{
_standalone = true;
notifyObservers(CLIENT_WILL_LOGON, null);
return getBootGroups();
}
/**
* Logs this client on in standalone mode with the faked bootstrap data and shared local
* distributed object manager.
*/
public void standaloneLogon (BootstrapData data, DObjectManager omgr)
{
if (!_standalone) {
throw new IllegalStateException("Must call prepareStandaloneLogon() first.");
}
gotBootstrap(data, omgr);
}
/**
* For standalone mode, this notifies observers that the client has logged off and cleans up.
*/
public void standaloneLogoff ()
{
notifyObservers(CLIENT_DID_LOGOFF, null);
cleanup(null); // this will set _standalone to false
}
/**
* Called by the {@link ClientDObjectMgr} when our bootstrap notification arrives. If the
* client and server are being run in "merged" mode in a single JVM, this is how the client is
* configured with the server's distributed object manager and provided with bootstrap data.
*/
protected void gotBootstrap (BootstrapData data, DObjectManager omgr)
{
if (debugLogMessages()) {
log.info("Got bootstrap " + data + ".");
}
// keep these around for interested parties
_bstrap = data;
_omgr = omgr;
// extract bootstrap information
_connectionId = data.connectionId;
_cloid = data.clientOid;
// notify the communicator that we got our bootstrap data (if we have one)
if (_comm != null) {
_comm.gotBootstrap();
}
// initialize our invocation director
_invdir.init(omgr, _cloid, this);
// send a few pings to the server to establish the clock offset between this client and
// server standard time
establishClockDelta(System.currentTimeMillis());
// we can't quite call initialization completed at this point because we need for the
// invocation director to fully initialize (which requires a round trip to the server)
// before turning the client loose to do things like request invocation services
}
/**
* If this client is being used to proxy events from another server, this method can be
* overridden to adjust the event in any way needed prior to dispatching the event.
*/
protected void convertFromRemote (DObject target, DEvent event)
{
// nothing by default
}
/**
* Creates the communicator that this client will use to send and receive messages.
*/
protected Communicator createCommunicator ()
{
return new ClientCommunicator(this);
}
/**
* Called every five seconds; ensures that we ping the server if we haven't communicated in a
* long while and periodically resyncs the client and server clock deltas.
*/
protected void tick ()
{
// if we're not connected, skip it
if (_comm == null) {
return;
}
long now = RunAnywhere.currentTimeMillis();
if (_dcalc != null) {
// if our current calculator is done, clear it out
if (_dcalc.isDone()) {
if (debugLogMessages()) {
log.info("Time offset from server: " + _serverDelta + "ms.");
}
_dcalc = null;
} else if (_dcalc.shouldSendPing()) {
// otherwise, send another ping
PingRequest req = new PingRequest();
_comm.postMessage(req);
_dcalc.sentPing(req);
}
} else if (now - _comm.getLastWrite() > PingRequest.PING_INTERVAL) {
// if we haven't sent anything over the network in a while, we ping the server to let
// it know that we're still alive
_comm.postMessage(new PingRequest());
} else if (now - _lastSync > CLOCK_SYNC_INTERVAL) {
// resync our clock with the server
establishClockDelta(now);
}
}
/**
* Called during initialization to initiate a sequence of ping/pong messages which will be used
* to determine (with "good enough" accuracy) the difference between the client clock and the
* server clock so that we can later interpret server timestamps.
*/
protected void establishClockDelta (long now)
{
if (_comm != null) {
// create a new delta calculator and start the process
_dcalc = new DeltaCalculator();
PingRequest req = new PingRequest();
_comm.postMessage(req);
_dcalc.sentPing(req);
_lastSync = now;
}
}
/**
* Called by the {@link Communicator} if it is experiencing trouble logging on but is still
* trying fallback strategies.
*/
protected void reportLogonTribulations (final LogonException cause)
{
_runQueue.postRunnable(new Runnable() {
public void run () {
notifyObservers(CLIENT_FAILED_TO_LOGON, cause);
}
});
}
/**
* Called by the invocation director when it successfully subscribes to the client object
* immediately following logon.
*/
protected void gotClientObject (ClientObject clobj)
{
// keep this around
_clobj = clobj;
// let the client know that logon has now fully succeeded
notifyObservers(CLIENT_DID_LOGON, null);
}
/**
* Called by the invocation director if it fails to subscribe to the client object after logon.
*/
protected void getClientObjectFailed (Exception cause)
{
// pass the buck onto the listeners
notifyObservers(CLIENT_FAILED_TO_LOGON, cause);
}
/**
* Called by the invocation director when it discovers that the client object has changed.
*/
protected void clientObjectDidChange (ClientObject clobj)
{
_clobj = clobj;
_cloid = _clobj.getOid();
// report to our observers
notifyObservers(CLIENT_OBJECT_CHANGED, null);
}
protected boolean notifyObservers (int code, Exception cause)
{
final Notifier noty = new Notifier(code, cause);
Runnable unit = new Runnable() {
public void run () {
synchronized (_observers) {
_observers.apply(noty);
}
}
};
// we need to run immediately if this is WILL_LOGON, WILL_LOGOFF or if we have no RunQueue
// (which currently only happens in some really obscure circumstances where we're using a
// Client instance on the server so that we can sort of pretend to be a real client)
if (code == CLIENT_WILL_LOGON || code == CLIENT_WILL_LOGOFF || _runQueue == null) {
unit.run();
return noty.getRejected();
} else {
// otherwise we can queue this notification up with our RunQueue and ensure that it's
// run on the proper thread
_runQueue.postRunnable(unit);
return false;
}
}
protected synchronized void cleanup (final Exception logonError)
{
// we know that prior to the call to this method, the observers were notified with
// CLIENT_DID_LOGOFF; that may not have been invoked yet, so we don't want to clear out our
// communicator reference immediately; instead we queue up a runnable unit to do so to
// ensure that it won't happen until CLIENT_DID_LOGOFF was dispatched
_runQueue.postRunnable(new Runnable() {
public void run () {
// tell the object manager that we're no longer connected to the server
if (_omgr instanceof ClientDObjectMgr) {
((ClientDObjectMgr)_omgr).cleanup();
}
// clear out our references
_comm = null;
_omgr = null;
_clobj = null;
_connectionId = _cloid = -1;
_standalone = false;
// and let our invocation director know we're logged off
_invdir.cleanup();
// if we were cleaned up due to a failure to logon, we can report the logon error
// now that the communicator is cleaned up; this allows a logon failure listener to
// immediately try another logon (hopefully with something changed like the server
// or port)
if (logonError != null) {
notifyObservers(CLIENT_FAILED_TO_LOGON, logonError);
} else {
notifyObservers(CLIENT_DID_CLEAR, null);
}
}
});
}
/**
* Called when we receive a pong packet. We may be in the process of calculating the client/
* server time differential, or we may have already done that at which point we ignore pongs.
*/
protected void gotPong (PongResponse pong)
{
// if we're not currently calculating our delta, then we can throw away the pong
if (_dcalc != null) {
// we update the delta after every receipt so as to immediately obtain an estimate of
// the clock delta and then refine it as more packets come in
_dcalc.gotPong(pong);
_serverDelta = _dcalc.getTimeDelta();
}
}
/**
* Whether or not to log low-level debug messages. This is used by the communicator as well
* which may be running on the server as a peer client, so we want to avoid constructing log
* messages when we're not logging and thus need to use this pattern rather than just
* log.fine.
*/
protected boolean debugLogMessages ()
{
return false;
}
/**
* Used to notify client observers of events.
*/
protected class Notifier
implements ObserverList.ObserverOp