org.apache.commons.id.uuid.clock
Interface Clock

All Known Implementing Classes:

SystemClockImpl, ThreadClockImpl

public interface Clock

Provides a timing mechanism for returning the current time in 100-nano second intervals since 00:00:00.00, 15 October 1582.

As described below this is useful for generating Version 1 UUIDs

See the RFC 4122: A Universally Unique IDentifier (UUID) URN Namespace for more information.

Selected quotes from IETF document pertaining to this class:

====================================================================

Timestamp

"The timestamp is a 60 bit value. For UUID version 1, this is represented by Coordinated Universal Time (UTC) as a count of 100- nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of Gregorian reform to the Christian calendar)."

System Clock Resolution

"If a system overruns the generator by requesting too many UUIDs within a single system time interval, the UUID service MUST either return an error, or stall the UUID generator until the system clock catches up.

A high resolution timestamp can be simulated by keeping a count of the number of UUIDs that have been generated with the same value of the system time, and using it to construct the low order bits of the timestamp. The count will range between zero and the number of 100-nanosecond intervals per system time interval.

Note: If the processors overrun the UUID generation frequently, additional node identifiers can be allocated to the system, which will permit higher speed allocation by making multiple UUIDs potentially available for each time stamp value."

The above quotations are protected under the following copyright notice

Copyright (C) The Internet Society (2005).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

====================================================================

Version:

$Revision: 480488 $ $Date: 2006-11-29 08:57:26 +0000 (Wed, 29 Nov 2006) $

Author:

Commons-Id Team

Field Summary

static java.lang.String	DEFAULT_CLOCK_IMPL The default Clock implementation if not configured
static long	GREGORIAN_CHANGE_OFFSET Offset from GregorianCalendar Change over to Jan 1 1970 00:00:00.00
static long	INTERVALS_PER_MILLI Maximum ticks per millisecond interval (1 millisecond = 1 000 000 nanoseconds) / 100

Method Summary

long	getUUIDTime() Returns the current time.

Field Detail

DEFAULT_CLOCK_IMPL

static final java.lang.String DEFAULT_CLOCK_IMPL

The default Clock implementation if not configured

See Also:

Constant Field Values

GREGORIAN_CHANGE_OFFSET

static final long GREGORIAN_CHANGE_OFFSET

Offset from GregorianCalendar Change over to Jan 1 1970 00:00:00.00

See Also:

Constant Field Values

INTERVALS_PER_MILLI

static final long INTERVALS_PER_MILLI

Maximum ticks per millisecond interval (1 millisecond = 1 000 000 nanoseconds) / 100

See Also:

Constant Field Values

Method Detail

getUUIDTime

long getUUIDTime()
                 throws OverClockedException

Returns the current time.

Returns:

the current time in 100-nano second intervals since 00:00:00.00, 15 October 1582 UTC.

Throws:

OverClockedException - an Exception raised if the number of calls in a system time interval exceeds the number of 100-nanosecond intervals allowed.