View Javadoc

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 }