psteitz 2004/03/06 09:29:05
Modified: id/src/java/org/apache/commons/id/uuid package.html
id/src/java/org/apache/commons/id/uuid/clock package.html
id/src/java/org/apache/commons/id/uuid/state package.html
Log:
Added package html for uuid and subpackages.
Contributed by: Tim Reilly
PR # 27488
Revision Changes Path
1.4 +15 -3
jakarta-commons-sandbox/id/src/java/org/apache/commons/id/uuid/package.html
Index: package.html
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/id/src/java/org/apache/commons/id/uuid/package.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- package.html 4 Mar 2004 03:17:44 -0000 1.3
+++ package.html 6 Mar 2004 17:29:04 -0000 1.4
@@ -15,8 +15,20 @@
-->
<body>
<p>
- This package contains contains implementations of the
- <a href="http://www.ietf.org/internet-drafts/draft-mealling-uuid-urn-02.txt";>
- IETF Draft UUID specification</a>.
+ <p>
+ This package contains UUID (Universally Unique Identifier)
+ generator implementations and supporting classes. A UUID is 128-bits
+ long and can provide an extremely high likelihood of uniqueness. For more
+ information see the Internet Engineering Task Force
+ <a href="http://www.ietf.org/internet-drafts/draft-mealling-uuid-urn-02.txt";>
+ IETF Draft UUID specification</a>.
</p>
+ <p>
+ The version 1 uuid generator collaborates with various interfaces that
+ allow for custom implementations in solving some challenges relating to:
+ where and how to retrieve the node identifier (usually the MAC-address), how
+ to persist generator data, and how to resolve uuid timestamps. Default
+ implementations are provided in this package and sub-packages.
+ </p>
+ </p>
</body>
1.2 +25 -3
jakarta-commons-sandbox/id/src/java/org/apache/commons/id/uuid/clock/package.html
Index: package.html
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/id/src/java/org/apache/commons/id/uuid/clock/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 4 Mar 2004 03:17:45 -0000 1.1
+++ package.html 6 Mar 2004 17:29:05 -0000 1.2
@@ -16,8 +16,30 @@
<body>
<p>
- This package contains contains clock implementations for generating uuid
timestamps per
- <a href="http://www.ietf.org/internet-drafts/draft-mealling-uuid-urn-02.txt";>
- IETF Draft UUID specification</a>.
+ This package contains the Clock interface and implementations for
+ generating UUID timestamps. UUID timestamps are measured in 100-nano
+ second intervals since the Gregorian changeover epoch (00:00:00.00,
+ 15 October 1582.) Due to several factors relating to time precision and
+ time resolution on Windows <sup>tm</sup> and in Java <sup>tm</sup> in
+ general; the Clock interface is introduced to allow different or custom
+ strategies in timestamp generation. The IETF (Internet Engineering Task Force)
+ specification details some of these approaches. For more information see
+ <a href="http://www.ietf.org/internet-drafts/draft-mealling-uuid-urn-02.txt";>
+ IETF Draft UUID specification</a>.
</p>
+ <p>
+ Two provided implementation are:
+ <ul>
+ <li><code>SystemClockImpl</code> - uses System.currentTimeMillis() and an
+ artificial counter to allow up to 10,000 ticks per millisecond interval.
+ </li>
+ <li><code>ThreadClockImpl</code> - time resolution on certain operating
+ systems may not be 1-millisecond intervals. Windows <sup>tm</sup> according
+ to some reports to have time resolution in the 1-ms to 54-ms range. Using a
+ thread to provide a clock that increments it's counter at 10-ms intervals is
+ one means of compensating for this. <em>(Due to bug parade issue:
+ 4500388 10-ms and not 1-ms intervals are used in this implementation.)</em>
+ </li>
+ </ul>
+ </p>
</body>
1.2 +25 -4
jakarta-commons-sandbox/id/src/java/org/apache/commons/id/uuid/state/package.html
Index: package.html
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/id/src/java/org/apache/commons/id/uuid/state/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 4 Mar 2004 03:17:45 -0000 1.1
+++ package.html 6 Mar 2004 17:29:05 -0000 1.2
@@ -16,9 +16,30 @@
<body>
<p>
- This package contains contains state implementations for persisting stateful
data
- related to the generation of UUID's based on the:
- <a href="http://www.ietf.org/internet-drafts/draft-mealling-uuid-urn-02.txt";>
- IETF Draft UUID specification</a>.
+ This package contains persistent and non-persistent state
+ implementations for data related to the generation of version 1 UUIDs. Not
+ all containers allow I/O; however when generating version 1 UUIDs it is best
+ to persist the node identifier (MAC address), clock sequence, and last
+ timestamp generated combination to stable storage. This allows the generator
+ to determine if the time has been set backwards so that a different clock
+ sequence is used to reduce the likelihood of duplicate identifiers.
+ </p>
+ <p>
+ Three provided implementation are:
+ <ul>
+ <li><code>ReadOnlyResourceStateImpl</code> - loads one of the data points
+ (node id) using the Classloader's getSystemResource method. Useful for
+ containers that allow reading resources but that don't allow writing to file.
+ The clock sequence is always initialized to a random short.
+ </li>
+ <li><code>ReadWriteFileStateImpl</code> - when possible a version one
+ generator should persist to stable storage. This implementation extends
+ ReadOnlyResourceStateImpl but also writes to the state configuration file.
+ </li>
+ <li><code>InMemoryStateImpl</code> - all data points are strictly managed
+ in memory with no long-term storage. The node identifier is created from a
+ MD5 hash of System properties.
+ </li>
+ </ul>
</p>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
