1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.id.uuid.clock;
19
20
21 /**
22 * <p>Provides a timing mechanism for returning the current time in
23 * 100-nano second intervals since 00:00:00.00, 15 October 1582.</p>
24 *
25 * <p>As described below this is useful for generating Version 1 UUIDs</p>
26 *
27 * <p>See the <a href="ftp://ftp.rfc-editor.org/in-notes/rfc4122.txt">RFC 4122:
28 * A Universally Unique IDentifier (UUID) URN Namespace</a>
29 * for more information.</p>
30 *
31 * <p>Selected quotes from IETF document pertaining to this class:</p>
32 *
33 * <p>====================================================================</p>
34 * <dl>
35 * <dt>Timestamp</dt>
36 * <dd>"The timestamp is a 60 bit value. For UUID version 1, this is
37 * represented by Coordinated Universal Time (UTC) as a count of 100-
38 * nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of
39 * Gregorian reform to the Christian calendar)."</dd>
40 *
41 * <dt>System Clock Resolution</dt>
42 * <dd>"If a system overruns the generator by requesting too many UUIDs
43 * within a single system time interval, the UUID service MUST either
44 * return an error, or stall the UUID generator until the system clock
45 * catches up.<br>
46 * <br>
47 * A high resolution timestamp can be simulated by keeping a count of
48 * the number of UUIDs that have been generated with the same value of
49 * the system time, and using it to construct the low order bits of the
50 * timestamp. The count will range between zero and the number of
51 * 100-nanosecond intervals per system time interval.<br>
52 * <br>
53 * Note: If the processors overrun the UUID generation frequently,
54 * additional node identifiers can be allocated to the system, which
55 * will permit higher speed allocation by making multiple UUIDs
56 * potentially available for each time stamp value."</dd>
57 *
58 * <p>The above quotations are protected under the following copyright notice </p>
59 * <p><code>Copyright (C) The Internet Society (2005).<br>
60 * <br>
61 * This document is subject to the rights, licenses and restrictions
62 * contained in BCP 78, and except as set forth therein, the authors
63 * retain all their rights.<br>
64 * <br>
65 * This document and the information contained herein are provided on an
66 * "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
67 * OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
68 * ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
69 * INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
70 * INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
71 * WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
72 * </code></p>
73 *
74 * ====================================================================
75 *
76 * @author Commons-Id Team
77 * @version $Revision: 480488 $ $Date: 2006-11-29 08:57:26 +0000 (Wed, 29 Nov 2006) $
78 *
79 */
80
81 public interface Clock {
82 /** The default Clock implementation if not configured */
83 String DEFAULT_CLOCK_IMPL = "org.apache.commons.id.uuid.clock.SystemClockImpl";
84
85 /** Offset from GregorianCalendar Change over to Jan 1 1970 00:00:00.00 */
86 long GREGORIAN_CHANGE_OFFSET = 12219292800000L;
87
88 /** Maximum ticks per millisecond interval (1 millisecond = 1 000 000 nanoseconds) / 100 */
89 long INTERVALS_PER_MILLI = 10000L;
90
91 /**
92 * <p>Returns the current time.</p>
93 *
94 * @return the current time in 100-nano second intervals since 00:00:00.00,
95 * 15 October 1582 UTC.
96 *
97 * @throws OverClockedException an Exception raised if the number of calls
98 * in a system time interval exceeds the number of 100-nanosecond intervals
99 * allowed.
100 */
101 long getUUIDTime() throws OverClockedException;
102 }