FileDocCategorySizeDatePackage
CommonClock.javaAPI DocAndroid 5.1 API16623Thu Mar 12 22:22:10 GMT 2015android.os

CommonClock

public class CommonClock extends Object
Used for accessing the android common time service's common clock and receiving notifications about common time synchronization status changes.
hide

Fields Summary
public static final long
TIME_NOT_SYNCED
Sentinel value returned by {@link #getTime()} and {@link #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
Sentinel value returned by {@link #getTimelineId()} when the common time service is not currently synced to any timeline.
public static final int
ERROR_ESTIMATE_UNKNOWN
Sentinel value returned by {@link #getEstimatedError()} when the common time service is not currently synced to any timeline.
public static final int
STATE_INVALID
Value used by {@link #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
Value used by {@link #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 {@link #STATE_CLIENT} if it finds an active master, or to {@link #STATE_MASTER} if no active master is found and this client becomes the master of a new timeline.
public static final int
STATE_CLIENT
Value used by {@link #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
Value used by {@link #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
Value used by {@link #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 {@link #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 {@link #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
Value used by {@link #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 {@link #STATE_CLIENT} state. If no new master announces itself within the timeout threshold, the time service will transition back to the {@link #STATE_RONIN} state in order to restart the election.
public static final String
SERVICE_NAME
Name of the underlying native binder service
private final Object
mListenerLock
private OnTimelineChangedListener
mTimelineChangedListener
private OnServerDiedListener
mServerDiedListener
private android.os.IBinder
mRemote
private String
mInterfaceDesc
private android.os.CommonTimeUtils
mUtils
private IBinder.DeathRecipient
mDeathHandler
private TimelineChangedListener
mCallbackTgt
private static final int
METHOD_IS_COMMON_TIME_VALID
private static final int
METHOD_COMMON_TIME_TO_LOCAL_TIME
private static final int
METHOD_LOCAL_TIME_TO_COMMON_TIME
private static final int
METHOD_GET_COMMON_TIME
private static final int
METHOD_GET_COMMON_FREQ
private static final int
METHOD_GET_LOCAL_TIME
private static final int
METHOD_GET_LOCAL_FREQ
private static final int
METHOD_GET_ESTIMATED_ERROR
private static final int
METHOD_GET_TIMELINE_ID
private static final int
METHOD_GET_STATE
private static final int
METHOD_GET_MASTER_ADDRESS
private static final int
METHOD_REGISTER_LISTENER
private static final int
METHOD_UNREGISTER_LISTENER
private static final int
METHOD_CBK_ON_TIMELINE_CHANGED
Constructors Summary
public CommonClock()
Class constructor.

throws
android.os.RemoteException


             
     
      
        mRemote = ServiceManager.getService(SERVICE_NAME);
        if (null == mRemote)
            throw new RemoteException();

        mInterfaceDesc = mRemote.getInterfaceDescriptor();
        mUtils = new CommonTimeUtils(mRemote, mInterfaceDesc);
        mRemote.linkToDeath(mDeathHandler, 0);
        registerTimelineChangeListener();
Methods Summary
public static android.os.CommonClockcreate()
Handy class factory method.

        CommonClock retVal;

        try {
            retVal = new CommonClock();
        }
        catch (RemoteException e) {
            retVal = null;
        }

        return retVal;
protected voidfinalize()

 release();
public intgetEstimatedError()
Gets the current estimation of common clock's synchronization accuracy from the common time service.

return
a signed 32-bit value representing the common time service's estimation of synchronization accuracy in microseconds, or the special value {@link #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)
throws
android.os.RemoteException

        throwOnDeadServer();
        return mUtils.transactGetInt(METHOD_GET_ESTIMATED_ERROR, ERROR_ESTIMATE_UNKNOWN);
public java.net.InetSocketAddressgetMasterAddr()
Gets the IP address and UDP port of the current timeline master.

return
an InetSocketAddress containing the IP address and UDP port of the current timeline master, or null if there is no current master.
throws
android.os.RemoteException

        throwOnDeadServer();
        return mUtils.transactGetSockaddr(METHOD_GET_MASTER_ADDRESS);
public intgetState()
Gets the current state of this clock's common time service in the the master election algorithm.

return
a integer indicating the current state of the this clock's common time service in the master election algorithm or {@link #STATE_INVALID} if there is an internal error.
throws
android.os.RemoteException

        throwOnDeadServer();
        return mUtils.transactGetInt(METHOD_GET_STATE, STATE_INVALID);
public longgetTime()
Gets the common clock's current time.

return
a signed 64-bit value representing the current common time in microseconds, or the special value {@link #TIME_NOT_SYNCED} if the common time service is currently not synchronized.
throws
android.os.RemoteException

        throwOnDeadServer();
        return mUtils.transactGetLong(METHOD_GET_COMMON_TIME, TIME_NOT_SYNCED);
public longgetTimelineId()
Gets the ID of the timeline the common time service is currently synchronizing its clock to.

return
a long representing the unique ID of the timeline the common time service is currently synchronizing with, or {@link #INVALID_TIMELINE_ID} if the common time service is currently not synchronized.
throws
android.os.RemoteException

        throwOnDeadServer();
        return mUtils.transactGetLong(METHOD_GET_TIMELINE_ID, INVALID_TIMELINE_ID);
private voidregisterTimelineChangeListener()


         
        if (null != mCallbackTgt)
            return;

        boolean success = false;
        android.os.Parcel data  = android.os.Parcel.obtain();
        android.os.Parcel reply = android.os.Parcel.obtain();
        mCallbackTgt = new TimelineChangedListener();

        try {
            data.writeInterfaceToken(mInterfaceDesc);
            data.writeStrongBinder(mCallbackTgt);
            mRemote.transact(METHOD_REGISTER_LISTENER, data, reply, 0);
            success = (0 == reply.readInt());
        }
        catch (RemoteException e) {
            success = false;
        }
        finally {
            reply.recycle();
            data.recycle();
        }

        // Did we catch a remote exception or fail to register our callback target?  If so, our
        // object must already be dead (or be as good as dead).  Clear out all of our state so that
        // our other methods will properly indicate a dead object.
        if (!success) {
            mCallbackTgt = null;
            mRemote = null;
            mUtils = null;
        }
public voidrelease()
Release all native resources held by this {@link android.os.CommonClock} instance. Once resources have been released, the {@link android.os.CommonClock} instance is disconnected from the native service and will throw a {@link android.os.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.

        unregisterTimelineChangeListener();
        if (null != mRemote) {
            try {
                mRemote.unlinkToDeath(mDeathHandler, 0);
            }
            catch (NoSuchElementException e) { }
            mRemote = null;
        }
        mUtils = null;
public voidsetServerDiedListener(android.os.CommonClock$OnServerDiedListener listener)
Registers an OnServerDiedListener interface.

Call this method with a null listener to stop receiving server death notifications.

        synchronized (mListenerLock) {
            mServerDiedListener = listener;
        }
public voidsetTimelineChangedListener(android.os.CommonClock$OnTimelineChangedListener listener)
Registers an OnTimelineChangedListener interface.

Call this method with a null listener to stop receiving server death notifications.

        synchronized (mListenerLock) {
            mTimelineChangedListener = listener;
        }
private voidthrowOnDeadServer()

        if ((null == mRemote) || (null == mUtils))
            throw new RemoteException();
private voidunregisterTimelineChangeListener()

        if (null == mCallbackTgt)
            return;

        android.os.Parcel data  = android.os.Parcel.obtain();
        android.os.Parcel reply = android.os.Parcel.obtain();

        try {
            data.writeInterfaceToken(mInterfaceDesc);
            data.writeStrongBinder(mCallbackTgt);
            mRemote.transact(METHOD_UNREGISTER_LISTENER, data, reply, 0);
        }
        catch (RemoteException e) { }
        finally {
            reply.recycle();
            data.recycle();
            mCallbackTgt = null;
        }