psteitz 2004/01/11 01:10:19
Added: id/src/java/org/apache/commons/id/uuid UUIDClock.java
id/src/test/org/apache/commons/id/uuid UUIDClockTest.java
Log:
Renamed UuidClock to UUIDClock
Revision Changes Path
1.1
jakarta-commons-sandbox/id/src/java/org/apache/commons/id/uuid/UUIDClock.java
Index: UUIDClock.java
===================================================================
/*
* $Header:
/home/cvs/jakarta-commons-sandbox/id/src/java/org/apache/commons/id/uuid/UUIDClock.java,v
1.1 2004/01/11 09:10:18 psteitz Exp $
* ====================================================================
* 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.id.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: 1.1 $ $Date: 2004/01/11 09:10:18 $
*/
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();
}
}
1.1
jakarta-commons-sandbox/id/src/test/org/apache/commons/id/uuid/UUIDClockTest.java
Index: UUIDClockTest.java
===================================================================
/*
*===================================================================
* 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 acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Apache" and "Apache Software Foundation" and
* "Apache Geronimo" 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",
* "Apache Geronimo", nor may "Apache" appear in their name, 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.id.uuid;
import java.util.Arrays;
import junit.framework.Test;
import junit.framework.TestCase;
import junit.framework.TestSuite;
import junit.textui.TestRunner;
/**
* Unit tests for [EMAIL PROTECTED] UuidClock}.
*
* @version $Revision: 1.1 $ $Date: 2004/01/11 09:10:19 $
* @author Commons-Uid team
*/
public class UUIDClockTest extends TestCase {
public UUIDClockTest(String name) {
super(name);
}
public static void main(String[] args) {
TestRunner.run(suite());
}
public static Test suite() {
TestSuite suite = new TestSuite(UUIDClockTest.class);
suite.setName("UUID Clock Tests");
return suite;
}
//-------------------------------------------------------------------------
protected void setUp() throws Exception {
super.setUp();
}
/**
* Make sure that time stamps generated by concurrent threads
* are unique.
*/
public void testUnique() throws Exception {
/*
* Number of timestamps to generate on each thread
*/
int iterations = 15000;
/*
* Number of client threads
*/
int threadCount = 4;
// Launch threadCount client threads and set them
// off generating time stamps
long[][] threadTimes = new long[threadCount][iterations];
Thread[] clockClients = new Thread[threadCount];
for (int i = 0; i < threadCount; i++) {
clockClients[i] = new ClockClient(threadTimes[i], iterations);
clockClients[i].start();
}
// Wait until all the threads are done
boolean working = true;
while (working) {
working = false;
for (int i = 0; i < threadCount; i++) {
if (clockClients[i].isAlive()) {
working = true;
}
}
}
// Gather up all of the times and test for uniqueness
long[] times = new long[iterations * threadCount];
int k = 0;
for (int i = 0; i < threadCount; i++) {
for (int j = 0; j < iterations; j++) {
times[k++] = threadTimes[i][j];
}
}
// Ridiculously inefficient, but effective -- sort and walk
Arrays.sort(times);
for (int i = 0; i < times.length - 1; i++) {
if (times[i] == times[i + 1]) {
fail("Duplicate time stamps generated: " + times[i] + " " + i);
}
}
}
/**
* Make sure that generated time stamps are within expected ranges.
* Need to look at this some more -- tolerance is now 10 seconds
*/
public void testRange() throws Exception {
long time = 0;
long baseTime = 0;
for (int i = 0; i < 10; i++) {
Thread.currentThread().sleep(10);
baseTime = System.currentTimeMillis();
for (int j = 0; j < 100; j++) {
time = UUIDClock.getCurrentTime();
assertTrue("Generated timestamp too large",
time < ((baseTime + UUIDClock.GREGORIAN_CHANGE_OFFSET + 10000) *
UUIDClock.TICKS_PER_MILLI));
assertTrue("Generated timestamp too small",
time > ((baseTime + UUIDClock.GREGORIAN_CHANGE_OFFSET - 10000) *
UUIDClock.TICKS_PER_MILLI));
}
}
}
//--------------------------------------------------------------------------
/**
* UuidClock client thread
*/
protected static class ClockClient extends Thread {
/*
* Generated time stamps
*/
protected long[] times;
/*
* Number of time stamps to generate on this thread
*/
protected int iterations;
ClockClient(long[] times, int iterations) {
super();
this.times = times;
this.iterations = iterations;
}
public void run() {
for (int i = 0; i < iterations; i++) {
times[i] = UUIDClock.getCurrentTime();
}
}
}
}
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
