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 [EMAIL PROTECTED] - * - * 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 [EMAIL PROTECTED] + * + * 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]