public class CommonClock extends Object
Modifier and Type | Class and Description |
---|---|
static interface |
CommonClock.OnServerDiedListener
The OnServerDiedListener interface defines a method called by the
CommonClock instance to indicate that the connection to the native media
server has been broken and that the CommonClock instance will need to be
released and re-created. |
static interface |
CommonClock.OnTimelineChangedListener
The OnTimelineChangedListener interface defines a method called by the
CommonClock instance to indicate that the time synchronization service has
either synchronized with a new timeline, or is no longer a member of any timeline. |
Modifier and Type | Field and Description |
---|---|
static int |
ERROR_ESTIMATE_UNKNOWN
Sentinel value returned by
getEstimatedError() when the common time service is not
currently synced to any timeline. |
static long |
INVALID_TIMELINE_ID
Sentinel value returned by
getTimelineId() when the common time service is not
currently synced to any timeline. |
static String |
SERVICE_NAME
Name of the underlying native binder service
|
static int |
STATE_CLIENT
Value used by
getState() to indicate that the common time service is in its client
state and is synchronizing its time to a different timeline master on the network. |
static int |
STATE_INITIAL
Value used by
getState() to indicate that the common time service is in its initial
state and attempting to find the current timeline master, if any. |
static int |
STATE_INVALID
Value used by
getState() to indicate that there was an internal error while
attempting to determine the state of the common time service. |
static int |
STATE_MASTER
Value used by
getState() to indicate that the common time service is in its master
state and is serving as the timeline master for other common time service clients on the
network. |
static int |
STATE_RONIN
Value used by
getState() to indicate that the common time service is in its Ronin
state. |
static int |
STATE_WAIT_FOR_ELECTION
Value used by
getState() to indicate that the common time service is waiting for a
master election to conclude and for the new master to announce itself before transitioning to
the STATE_CLIENT state. |
static long |
TIME_NOT_SYNCED
Sentinel value returned by
getTime() and getEstimatedError() when the
common time service is not able to determine the current common time due to a lack of
synchronization. |
Constructor and Description |
---|
CommonClock()
Class constructor.
|
Modifier and Type | Method and Description |
---|---|
static CommonClock |
create()
Handy class factory method.
|
protected void |
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
int |
getEstimatedError()
Gets the current estimation of common clock's synchronization accuracy from the common time
service.
|
InetSocketAddress |
getMasterAddr()
Gets the IP address and UDP port of the current timeline master.
|
int |
getState()
Gets the current state of this clock's common time service in the the master election
algorithm.
|
long |
getTime()
Gets the common clock's current time.
|
long |
getTimelineId()
Gets the ID of the timeline the common time service is currently synchronizing its clock to.
|
void |
release()
Release all native resources held by this
CommonClock instance. |
void |
setServerDiedListener(CommonClock.OnServerDiedListener listener)
Registers an OnServerDiedListener interface.
|
void |
setTimelineChangedListener(CommonClock.OnTimelineChangedListener listener)
Registers an OnTimelineChangedListener interface.
|
public static final long TIME_NOT_SYNCED
getTime()
and getEstimatedError()
when the
common time service is not able to determine the current common time due to a lack of
synchronization.public static final long INVALID_TIMELINE_ID
getTimelineId()
when the common time service is not
currently synced to any timeline.public static final int ERROR_ESTIMATE_UNKNOWN
getEstimatedError()
when the common time service is not
currently synced to any timeline.public static final int STATE_INVALID
getState()
to indicate that there was an internal error while
attempting to determine the state of the common time service.public static final int STATE_INITIAL
getState()
to indicate that the common time service is in its initial
state and attempting to find the current timeline master, if any. The service will
transition to either STATE_CLIENT
if it finds an active master, or to
STATE_MASTER
if no active master is found and this client becomes the master of a
new timeline.public static final int STATE_CLIENT
getState()
to indicate that the common time service is in its client
state and is synchronizing its time to a different timeline master on the network.public static final int STATE_MASTER
getState()
to indicate that the common time service is in its master
state and is serving as the timeline master for other common time service clients on the
network.public static final int STATE_RONIN
getState()
to indicate that the common time service is in its Ronin
state. Common time service instances in the client state enter the Ronin state after their
timeline master becomes unreachable on the network. Common time services who enter the Ronin
state will begin a new master election for the timeline they were recently clients of. As
clients detect they are not the winner and drop out of the election, they will transition to
the STATE_WAIT_FOR_ELECTION
state. When there is only one client remaining in the
election, it will assume ownership of the timeline and transition to the
STATE_MASTER
state. During the election, all clients will allow their timeline to
drift without applying correction.public static final int STATE_WAIT_FOR_ELECTION
getState()
to indicate that the common time service is waiting for a
master election to conclude and for the new master to announce itself before transitioning to
the STATE_CLIENT
state. If no new master announces itself within the timeout
threshold, the time service will transition back to the STATE_RONIN
state in order
to restart the election.public static final String SERVICE_NAME
public CommonClock() throws RemoteException
RemoteException
public static CommonClock create()
public void release()
CommonClock
instance. Once
resources have been released, the CommonClock
instance is disconnected from
the native service and will throw a RemoteException
if any of its
methods are called. Clients should always call release on their client instances before
releasing their last Java reference to the instance. Failure to do this will cause
non-deterministic native resource reclamation and may cause the common time service to remain
active on the network for longer than it should.public long getTime() throws RemoteException
TIME_NOT_SYNCED
if the common time service is currently not
synchronized.RemoteException
public int getEstimatedError() throws RemoteException
ERROR_ESTIMATE_UNKNOWN
if the common time service is currently not synchronized.
Negative values indicate that the local server estimates that the nominal common time is
behind the local server's time (in other words, the local clock is running fast) Positive
values indicate that the local server estimates that the nominal common time is ahead of the
local server's time (in other words, the local clock is running slow)RemoteException
public long getTimelineId() throws RemoteException
INVALID_TIMELINE_ID
if the common time service is
currently not synchronized.RemoteException
public int getState() throws RemoteException
STATE_INVALID
if there is an internal error.RemoteException
public InetSocketAddress getMasterAddr() throws RemoteException
RemoteException
public void setTimelineChangedListener(CommonClock.OnTimelineChangedListener listener)
Call this method with a null listener to stop receiving server death notifications.
public void setServerDiedListener(CommonClock.OnServerDiedListener listener)
Call this method with a null listener to stop receiving server death notifications.
protected void finalize() throws Throwable
Object
finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the JavaTM virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.