commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pste...@apache.org
Subject cvs commit: jakarta-commons-sandbox/id/src/java/org/apache/commons/id/uuid/state package.html
Date Sat, 06 Mar 2004 17:29:05 GMT
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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message