You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ps...@apache.org on 2003/12/30 08:11:58 UTC
cvs commit: jakarta-commons-sandbox/uid/src/java/org/apache/commons/uid/uuid UuidClock.java
psteitz 2003/12/29 23:11:58
Modified: uid/src/java/org/apache/commons/uid/uuid UuidClock.java
Log:
Added IETF copyright notice, formatting changes.
Revision Changes Path
1.2 +250 -224 jakarta-commons-sandbox/uid/src/java/org/apache/commons/uid/uuid/UuidClock.java
Index: UuidClock.java
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/uid/src/java/org/apache/commons/uid/uuid/UuidClock.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- UuidClock.java 24 Dec 2003 08:59:45 -0000 1.1
+++ UuidClock.java 30 Dec 2003 07:11:58 -0000 1.2
@@ -1,224 +1,250 @@
-/*
- * $Header$
- * ====================================================================
- *
- * The Apache Software License, Version 1.1
- *
- * Copyright (c) 2001-2003 The Apache Software Foundation. All rights
- * reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * 1. Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *
- * 2. Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in
- * the documentation and/or other materials provided with the
- * distribution.
- *
- * 3. The end-user documentation included with the redistribution, if
- * any, must include the following acknowledgement:
- * "This product includes software developed by the
- * Apache Software Foundation (http://www.apache.org/)."
- * Alternately, this acknowledgement may appear in the software itself,
- * if and wherever such third-party acknowledgements normally appear.
- *
- * 4. The names "The Jakarta Project", "Commons", and "Apache Software
- * Foundation" must not be used to endorse or promote products derived
- * from this software without prior written permission. For written
- * permission, please contact apache@apache.org.
- *
- * 5. Products derived from this software may not be called "Apache"
- * nor may "Apache" appear in their names without prior written
- * permission of the Apache Software Foundation.
- *
- * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
- * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
- * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
- * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
- * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
- * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
- * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- * SUCH DAMAGE.
- * ====================================================================
- *
- * This software consists of voluntary contributions made by many
- * individuals on behalf of the Apache Software Foundation. For more
- * information on the Apache Software Foundation, please see
- * <http://www.apache.org/>.
- *
- */
-
-package org.apache.commons.uid.uuid;
-
-/**
- * UuidClock.java 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
- *
- * For more information regarding the IETF Draft Uuid specification
- * see http://www.ietf.org/internet-drafts/draft-mealling-uuid-urn-01.txt
- *
- * Selected segements of Draft 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).
- *
- * Clock Adjustment
- * UUIDs may be created at a rate greater than the system clock resolution.
- * Therefore, the system must also maintain an adjustment value to be added to
- * the lower-order bits of the time. Logically, each time the system clock
- * ticks, the adjustment value is cleared. Every time a UUID is generated,
- * the current adjustment value is read and incremented atomically, then added
- * to the UTC time field of the UUID.
- *
- * Clock Overrun
- * The 100 nanosecond granularity of time should prove sufficient even for
- * bursts of UUID creation in the next generation of high-performance
- * multiprocessors. If a system overruns the clock adjustment by requesting
- * too many UUIDs within a single system clock tick, the UUID service may
- * raise an exception, handled in a system or process-dependent manner
- * either by:
- * terminating the request
- * reissuing the request until it succeeds
- * stalling the UUID generator until the system clock catches up.
- *
- * If the processors overrun the UUID generation frequently, additional node
- * identifiers and clocks may need to be added.
- * ====================================================================
- *
- * @version $Revision$ $Date$
- * @author Tim Reilly
- */
-
-public class UuidClock extends Thread {
-
- /** Default life of the UuidClock thread in milliseconds */
- public static final long DEFAULT_THREAD_LIFE = 200;
-
- /** Offset from GregorianCalendar Change over to Jan 1 1970 00:00:00.00 */
- public static final long GREGORIAN_CHANGE_OFFSET = 12219292800000L;
-
- /** Maximum ticks per millisecond interval */
- public static final long TICKS_PER_MILLI = 10000L;
-
- /** Life time of the clock thread in milliseconds */
- private static long threadLife = DEFAULT_THREAD_LIFE;
-
- /** Singleton instance of the UuidClock */
- private static UuidClock clock = null;
-
- /** The counter for nanoseconds generated during this system interval(ms) */
- private int generatedThisMilli;
-
- /** The current time in milliseconds held in this clock thread. */
- private long currentTimeMillis;
-
- /** Time when the clock thread should die */
- private long expires = threadLife;
-
- /**
- * Private constructor for clock implementation. Utilizes a single thread to
- * increment the clock every milli seconds this should be more
- * accurate than System.currentTimeMillis() as described in
- * the javaworld article:
- * http://www.javaworld.com/javaworld/javaqa/2003-01/01-qa-0110-timing.html
- */
-
- private UuidClock() {
- setDaemon(true);
- setPriority(Thread.MAX_PRIORITY);
- currentTimeMillis = System.currentTimeMillis();
- start();
- }
-
- /**
- * Returns the thread life in milliseconds. If the clock thread is not
- * accessed within this time span the thread will die off.
- *
- * @return thread life time span in milliseconds
- */
- public static long getThreadLife() {
- return UuidClock.threadLife;
- }
-
- /**
- * @param threadLife milliseconds this thread should live for. Each
- * call to getCurrentTime resets the expiration time value.
- */
- public static void setThreadLife(long threadLife) {
- UuidClock.threadLife = threadLife;
- }
-
- /**
- * Threads run method that increments the clock and resets the generated
- * nano seconds counter.
- */
- public void run() {
- try {
- while (--expires >= 0) {
- Thread.sleep(1);
- currentTimeMillis++;
- generatedThisMilli = 1;
- }
- } catch (InterruptedException e) {
- System.out.println("UuidClock thread interrupted");
- }
- }
-
- /**
- * Returns the internal time milliseconds for the UuidClock instance
- * @return the clock threads current time in milliseconds
- */
- private long getCurrentTimeMillis() {
- return currentTimeMillis;
- }
-
- /**
- * Returns the current time as described in the clock resolution and
- * timestamp sections of the uuid specification.
- *
- * @return the current time in 100-nano second intervals (simulated)
- */
- private long currentTime() {
- this.expires = threadLife;
- // Stall until counter is reset to limit only 10000 intervals per
- // millisecond interval
- while (generatedThisMilli > TICKS_PER_MILLI) {
- //wait for thread to reset
- }
-
- long currentTime =
- ((currentTimeMillis + GREGORIAN_CHANGE_OFFSET) * TICKS_PER_MILLI);
-
- return currentTime + (generatedThisMilli++);
- }
-
- /**
- * Static method returns the clocks current time in 100-nanosecond intervals
- * since the Gregorian calander change. Calendar.GREGORIAN_OFFSET
- *
- * @return Coordinated Universal Time (UTC) as a count of 100- nanosecond
- * intervals since 00:00:00.00, 15 October 1582
- */
- public static synchronized long getCurrentTime() {
- if (clock == null || !clock.isAlive()) {
- clock = null;
- clock = new UuidClock();
- }
- return clock.currentTime();
- }
-
-}
+/*
+ * $Header$
+ * ====================================================================
+ * The Apache Software License, Version 1.1
+ *
+ * Copyright (c) 2002-2003 The Apache Software Foundation. All rights
+ * reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in
+ * the documentation and/or other materials provided with the
+ * distribution.
+ *
+ * 3. The end-user documentation included with the redistribution, if
+ * any, must include the following acknowledgement:
+ * "This product includes software developed by the
+ * Apache Software Foundation (http://www.apache.org/)."
+ * Alternately, this acknowledgement may appear in the software itself,
+ * if and wherever such third-party acknowledgements normally appear.
+ *
+ * 4. The names "The Jakarta Project", "Commons", and "Apache Software
+ * Foundation" must not be used to endorse or promote products derived
+ * from this software without prior written permission. For written
+ * permission, please contact apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache"
+ * nor may "Apache" appear in their names without prior written
+ * permission of the Apache Software Foundation.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation. For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ */
+
+package org.apache.commons.uid.uuid;
+
+/**
+ * <p>UuidClock.java provides a timing mechanism for returning the current time in
+ * 100-nano second intervals since 00:00:00.00, 15 October 1582.</p>
+ *
+ * <p>As described below this is useful for generating Version 1 UUIDs.</p>
+ *
+ * <p>For more information regarding the IETF Draft Uuid specification
+ * see http://www.ietf.org/internet-drafts/draft-mealling-uuid-urn-01.txt</p>
+ *
+ * <p>Selected segements of Draft pertaining to this class:</p>
+ * <pre>
+ * ====================================================================
+ * 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).
+ *
+ * Clock Adjustment
+ * UUIDs may be created at a rate greater than the system clock resolution.
+ * Therefore, the system must also maintain an adjustment value to be added to
+ * the lower-order bits of the time. Logically, each time the system clock
+ * ticks, the adjustment value is cleared. Every time a UUID is generated,
+ * the current adjustment value is read and incremented atomically, then added
+ * to the UTC time field of the UUID.
+ *
+ * Clock Overrun
+ * The 100 nanosecond granularity of time should prove sufficient even for
+ * bursts of UUID creation in the next generation of high-performance
+ * multiprocessors. If a system overruns the clock adjustment by requesting
+ * too many UUIDs within a single system clock tick, the UUID service may
+ * raise an exception, handled in a system or process-dependent manner
+ * either by:
+ * terminating the request
+ * reissuing the request until it succeeds
+ * stalling the UUID generator until the system clock catches up.
+ *
+ * If the processors overrun the UUID generation frequently, additional node
+ * identifiers and clocks may need to be added.
+ * ====================================================================
+ *
+ * The quotations above are protected under the following copyright notice:
+ *
+ * Copyright (C) The Internet Society (2003). All Rights Reserved.
+ *
+ * This document and translations of it may be copied and furnished to
+ * others, and derivative works that comment on or otherwise explain it
+ * or assist in its implementation may be prepared, copied, published
+ * and distributed, in whole or in part, without restriction of any
+ * kind, provided that the above copyright notice and this paragraph are
+ * included on all such copies and derivative works. However, this
+ * document itself may not be modified in any way, such as by removing
+ * the copyright notice or references to the Internet Society or other
+ * Internet organizations, except as needed for the purpose of
+ * developing Internet standards in which case the procedures for
+ * copyrights defined in the Internet Standards process must be
+ * followed, or as required to translate it into languages other than
+ * English.
+ *
+ * The limited permissions granted above are perpetual and will not be
+ * revoked by the Internet Society or its successors or assignees.
+ *
+ * This document and the information contained herein is provided on an
+ * "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ * TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ * BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ *
+ * </pre>
+ *------------------------------------------------------------------------
+ *
+ * @author Commons-Uid team
+ * @version $Revision$ $Date$
+ */
+
+public class UuidClock extends Thread {
+
+ /** Default life of the UuidClock thread in milliseconds */
+ public static final long DEFAULT_THREAD_LIFE = 200;
+
+ /** Offset from GregorianCalendar Change over to Jan 1 1970 00:00:00.00 */
+ public static final long GREGORIAN_CHANGE_OFFSET = 12219292800000L;
+
+ /** Maximum ticks per millisecond interval */
+ public static final long TICKS_PER_MILLI = 10000L;
+
+ /** Life time of the clock thread in milliseconds */
+ private static long threadLife = DEFAULT_THREAD_LIFE;
+
+ /** Singleton instance of the UuidClock */
+ private static UuidClock clock = null;
+
+ /** The counter for nanoseconds generated during this system interval(ms) */
+ private int generatedThisMilli;
+
+ /** The current time in milliseconds held in this clock thread. */
+ private long currentTimeMillis;
+
+ /** Time when the clock thread should die */
+ private long expires = threadLife;
+
+ /**
+ * Private constructor for clock implementation. Utilizes a single thread to
+ * increment the clock every milli seconds this should be more
+ * accurate than System.currentTimeMillis() as described in
+ * the javaworld article:
+ * http://www.javaworld.com/javaworld/javaqa/2003-01/01-qa-0110-timing.html
+ */
+
+ private UuidClock() {
+ setDaemon(true);
+ setPriority(Thread.MAX_PRIORITY);
+ currentTimeMillis = System.currentTimeMillis();
+ start();
+ }
+
+ /**
+ * Returns the thread life in milliseconds. If the clock thread is not
+ * accessed within this time span the thread will die off.
+ *
+ * @return thread life time span in milliseconds
+ */
+ public static long getThreadLife() {
+ return UuidClock.threadLife;
+ }
+
+ /**
+ * @param threadLife milliseconds this thread should live for. Each
+ * call to getCurrentTime resets the expiration time value.
+ */
+ public static void setThreadLife(long threadLife) {
+ UuidClock.threadLife = threadLife;
+ }
+
+ /**
+ * Threads run method that increments the clock and resets the generated
+ * nano seconds counter.
+ */
+ public void run() {
+ try {
+ while (--expires >= 0) {
+ Thread.sleep(1);
+ currentTimeMillis++;
+ generatedThisMilli = 1;
+ }
+ } catch (InterruptedException e) {
+ System.out.println("UuidClock thread interrupted");
+ }
+ }
+
+ /**
+ * Returns the internal time milliseconds for the UuidClock instance
+ * @return the clock threads current time in milliseconds
+ */
+ private long getCurrentTimeMillis() {
+ return currentTimeMillis;
+ }
+
+ /**
+ * Returns the current time as described in the clock resolution and
+ * timestamp sections of the uuid specification.
+ *
+ * @return the current time in 100-nano second intervals (simulated)
+ */
+ private long currentTime() {
+ this.expires = threadLife;
+ // Stall until counter is reset to limit only 10000 intervals per
+ // millisecond interval
+ while (generatedThisMilli > TICKS_PER_MILLI) {
+ //wait for thread to reset
+ }
+
+ long currentTime =
+ ((currentTimeMillis + GREGORIAN_CHANGE_OFFSET) * TICKS_PER_MILLI);
+
+ return currentTime + (generatedThisMilli++);
+ }
+
+ /**
+ * Static method returns the clocks current time in 100-nanosecond intervals
+ * since the Gregorian calander change. Calendar.GREGORIAN_OFFSET
+ *
+ * @return Coordinated Universal Time (UTC) as a count of 100- nanosecond
+ * intervals since 00:00:00.00, 15 October 1582
+ */
+ public static synchronized long getCurrentTime() {
+ if (clock == null || !clock.isAlive()) {
+ clock = null;
+ clock = new UuidClock();
+ }
+ return clock.currentTime();
+ }
+}
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org