Smalltalk/X Webserver

Documentation of class 'UUID':

Class: UUID

Inheritance
Description
Class protocol
Instance protocol

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--UninterpretedBytes
               |
               +--ByteArray
                  |
                  +--UUID

Package:: stx:libbasic2

Category:: Net-Communication-Support

Version:: rev: 1.80 date: 2024/03/21 17:50:16; user: cg; file: UUID.st directory: libbasic2; module: stx stc-classLibrary: libbasic2

Description:

128-bit Universal Unique Ids (UUIDs) as defined by OpenGroup/DCE
    http://www.opengroup.org/onlinepubs/9629399/apdxa.htm.

See also RFC4122.

A UUID is unique in time and space (at least until about Year 3400).

Several fields if the UUID are interpreted as integers, so host/network byte
order is relevant. UUIDs are stored in a ByteArray in network byte order (MSB-first),
so they may be exported/imported between different machines.

You can import UUIDs in host byte order using #fromNativeBytes:


[instance variables:]

[class variables:]

copyrightCOPYRIGHT (c) 2002 by eXept Software AG
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

change & update

update: something with: aParameter from: changedObject: flush cached MAC address (may have been restarted on another host)

helpers

adjustByteOrder: aByteArray

change the byte order of the uuid

getDtssUtcTime

return the DTSS based time in 100 nsec intervals
DTSS UTC base time is October 15, 1582 (the start of the Gregorian Calendar).

getValidMACAddress

return the first valid MAC address (i.e. having at least 6 bytes with the first six bytes ~~ 0).
As a side effect, initialize anything needed for timestamp UUIDs.

Usage example(s):

       CachedMACAddress := nil.
       self getValidMACAddress

initialization

initialize: I want to get informed about image restarts
nameSpaceToUuidBytes: ASN.1 OID in DER or as Text

instance creation

basicNew

(comment from inherited method)
return an instance of myself without indexed variables.
If the receiver-class has indexed instvars, the new object will have
a basicSize of zero -
i.e. 'aClass basicNew' is equivalent to 'aClass basicNew:0'.

** Do not redefine this method in any class **

basicNew: size

allow creating with exact size. We need this for XMLStandardDecoder

decodeFromLiteralArray: anArray

UUID 'uuid-string'

Usage example(s):

     (UUID decodeFromLiteralArray:#(UUID '5b023ce0-41f1-11dd-b99f-001558137da0'))
       literalArrayEncoding

fromBytes: aByteArray

set uuid from aByteArray.
aByteArray must be 16 bytes in network byte order (MSB-first)

Usage example(s):

 UUID fromBytes:#[16r01 16r02 16r03 16r04
                  16r05 16r06 16r07 16r08
                  16r09 16r10 16r11 16r12
                  16r13 16r14 16r15 16r16].

fromBytes: aByteArray MSB: msb

Set the UUID from aByteArray. UUIDS are stored internally as MSB-first.
So, alway set
msb = true if reading from network or persistent storage

Usage example(s):

     UUID fromBytes:#[16r01 16r02 16r03 16r04
                      16r05 16r06 16r07 16r08
                      16r09 16r10 16r11 16r12
                      16r13 16r14 16r15 16r16] msb:false.

Usage example(s):

     UUID fromBytes:#[16r01 16r02 16r03 16r04
                      16r05 16r06 16r07 16r08
                      16r09 16r10 16r11 16r12
                      16r13 16r14 16r15 16r16] msb:true.

fromNativeBytes: aByteArray

convert bytes to uuid.
aByteArray represents a UUID in host byte order
- e.g. an UUID fetched from the Windows OS

Usage example(s):

 UUID fromNativeBytes:#[16r01 16r02 16r03 16r04
                          16r05 16r06 16r07 16r08
                          16r09 16r10 16r11 16r12
                          16r13 16r14 16r15 16r16].

fromString: aStringOrSymbol

convert aStringOrSymbol to a UUID.
If aStringOrSymbol is a symbol, cache this UUID for faster conversion.

The real conversion is done in #readFrom:onError.

Usage example(s):

        UUID fromString:'be1ef7a0-ae1d-11e0-9cb5-02ff7d4f61ea'
        UUID fromString:#'be1ef7a0-ae1d-11e0-9cb5-02ff7d4f61ea'

        Time millisecondsToRun:[
            100000 timesRepeat:[
                UUID fromString:'be1ef7a0-ae1d-11e0-9cb5-02ff7d4f61ea'.
            ]
        ]

        Time millisecondsToRun:[
            100000 timesRepeat:[
                UUID fromString:#'be1ef7a0-ae1d-11e0-9cb5-02ff7d4f61ea'.
            ]
        ]

genRandomUUID

generate a new random UUID

Usage example(s):

      self genRandomUUID

Usage example(s):

      |uuids sample|
      sample := 100000.
      uuids := Set new:sample.  
      sample timesRepeat:[
          uuids add:UUID genRandomUUID.
      ].
      self assert:(uuids size = sample).  
      uuids

      1 to: 100 do:[ : el |
          Transcript show:el.
          Transcript show:': '.
          Transcript showCR:(UUID genRandomUUID).
      ].

genTimestampUUID

generate a new timestamp UUID

Usage example(s):

      self genTimestampUUID

genUUID

generate a uuid.
If a physical mac address can be retrieved from the OS,
a mac-address/timestamp uuid is generated,
otherwise a random uuid will be generated.

Usage example(s):

      self genUUID

Usage example(s):

      1 to: 100 do:[ : el |
          Transcript show:el.
          Transcript show:': '.
          Transcript showCR:(UUID genUUID).
      ].

genUUID: nameStringOrBytes inNameSpace: namespaceStringOrUUID

generate a namespace UUID (Version 5, hashed by SHA-1).
See RFC4122.

Usage example(s):

        self genUUID:'www.example.org' inNameSpace:'DNS'.
        self genUUID:'http://www.exept.de' inNameSpace:'URL'.
        self genUUID:'1.2.3.4.5' inNameSpace:'OID'.
        self genUUID:(OSI::DERCoder encode:(OSI::ASN1_OID newID:#(1 2 3 4 5))) 
             inNameSpace:'OID'.
        self genUUID:'c=de, o=eXept Software AG, cn=Development' 
             inNameSpace:'X500'.
        self genUUID:(OSI::DERCoder encode:(OSI::DistinguishedName fromString:'c=de, o=eXept Software AG, cn=Development') asAsn1Value) 
             inNameSpace:'X500'.

new

self new

readFrom: aStringOrStream onError: errorBlock

tunes because we read lots of them in expecco and expeccoALM

Usage example(s):

     |idString|
     idString := UUID genUUID storeString. 
     Transcript showCR:idString.
     UUID readFromString:idString 

     UUID readFrom:'5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77'               => 5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77
     UUID readFrom:'{5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77 }'            => 5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77
     UUID readFrom:'{5ab2e9b4+3d48-11d2-9ea4-80c5140aaa77 }'            => error
     UUID readFrom:'{5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77'              => error
     UUID fromString:'5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77 bllll'       => 5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77
     UUID fromString:'5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77'             => 5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77
     UUID fromString:'00000001-0000-0000-C000-000000000046'             => 00000001-0000-0000-c000-000000000046
     UUID fromString:'00000001-0000-0000-C000-000000004600'
     UUID fromString:'00000001-0000-0000-C000-000000460000'
     UUID fromString:'00000001-0000-0000-C000-000046000000'
     UUID fromString:'00000001-0000-0000-C000-004600000000'
     UUID fromString:'00000001-0000-0000-C000-460000000000'
     UUID fromString:'00000001-0000-0000-C046-000000000000'
     UUID fromString:'00000001-0000-0046-C000-000000000000'
     UUID fromString:'00000001-0000-4600-C000-000000000000'
     UUID fromString:'00000001-0046-0000-C000-000000000000'
     UUID fromString:'00000001-4600-0000-C000-000000000000'
     UUID fromString:'00000100-4600-0000-C000-000000000000'
     UUID fromString:'00010000-4600-0000-C000-000000000000'
     UUID fromString:'10000000-4600-0000-C000-000000000000'  => 10000000-4600-0000-c000-000000000000
     UUID fromString:'01020304-0506-0708-090A-0B0C0D0E0F10'  => 01020304-0506-0708-090a-0b0c0d0e0f10
     UUID fromString:'11223344-5566-7788-99AA-BBCCDDEEFF00'  => 11223344-5566-7788-99aa-bbccddeeff00
     UUID fromString:'ConvertToDNArray'

     TimeDuration toRun:[
        100000 timesRepeat:[
            UUID readFrom:'10000000-4600-0000-C000-000000000000' onError:nil.
        ].
     ] 34.299ms  26.097ms 
     
     TimeDuration toRun:[
        100000 timesRepeat:[
            UUID readFrom:' 10000000-4600-0000-C000-000000000000' startingAt:2 onError:nil.
        ].
     ] 16.314ms 17.546ms 19.330ms 26.097ms 

     TimeDuration toRun:[
        100000 timesRepeat:[
            UUID readFrom:'  10000000-4600-0000-C000-000000000000' onError:nil.
        ].
     ] 1.420s 1.443s 1.415s

readFrom: aStringOrStream startingAt: startIndex onError: errorBlock

tunes because we read lots of them in expecco and expeccoALM

Usage example(s):

     |idString|
     idString := UUID genUUID storeString. 
     Transcript showCR:idString.
     UUID readFromString:idString 

     UUID readFrom:'5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77'               => 5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77
     UUID readFrom:'{5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77 }'            => 5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77
     UUID readFrom:'{5ab2e9b4+3d48-11d2-9ea4-80c5140aaa77 }'            => error
     UUID readFrom:'{5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77'              => error
     UUID fromString:'5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77 bllll'       => 5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77
     UUID fromString:'5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77'             => 5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77
     UUID fromString:'00000001-0000-0000-C000-000000000046'             => 00000001-0000-0000-c000-000000000046
     UUID fromString:'00000001-0000-0000-C000-000000004600'
     UUID fromString:'00000001-0000-0000-C000-000000460000'
     UUID fromString:'00000001-0000-0000-C000-000046000000'
     UUID fromString:'00000001-0000-0000-C000-004600000000'
     UUID fromString:'00000001-0000-0000-C000-460000000000'
     UUID fromString:'00000001-0000-0000-C046-000000000000'
     UUID fromString:'00000001-0000-0046-C000-000000000000'
     UUID fromString:'00000001-0000-4600-C000-000000000000'
     UUID fromString:'00000001-0046-0000-C000-000000000000'
     UUID fromString:'00000001-4600-0000-C000-000000000000'
     UUID fromString:'00000100-4600-0000-C000-000000000000'
     UUID fromString:'00010000-4600-0000-C000-000000000000'
     UUID fromString:'10000000-4600-0000-C000-000000000000'  => 10000000-4600-0000-c000-000000000000
     UUID fromString:'01020304-0506-0708-090A-0B0C0D0E0F10'  => 01020304-0506-0708-090a-0b0c0d0e0f10
     UUID fromString:'11223344-5566-7788-99AA-BBCCDDEEFF00'  => 11223344-5566-7788-99aa-bbccddeeff00
     UUID fromString:'ConvertToDNArray'

     TimeDuration toRun:[
        100000 timesRepeat:[
            UUID readFrom:'10000000-4600-0000-C000-000000000000' onError:nil.
        ].
     ] 1.413s  1.537s 
     TimeDuration toRun:[
        100000 timesRepeat:[
            UUID readFrom:' 10000000-4600-0000-C000-000000000000' onError:nil.
        ].
     ]

Instance protocol:

accessing

clockSeqHiAndReserved

clockSeqLow

node

answer the node (ethernet) address of this uuid

Usage example(s):

       (self allInstances 
            select:[:e| e isTimestampUUID] 
            thenCollect:[:e| e node]) asBag

timeHighAndVersion

timeLow

timeMid

timestamp

Get the UTC timestamp, when the UUID has been created.
This is only valid for timestampUUIDs

Usage example(s):

        self genTimestampUUID timestamp
        self genRandomUUID timestamp

        (self allInstances asSet asArray select:[:e| e isTimestampUUID] 
                                            thenCollect:[:e| e timestamp]) sort

version

the version number of the uuid

Usage example(s):

        self genTimestampUUID version
        self genRandomUUID version

converting

asBytes

convert this UUID to a ByteArray in network byte order (MSB-first)

Usage example(s):

     |bytes|
        
     bytes := #[16r01 16r02 16r03 16r04
                      16r05 16r06 16r07 16r08
                      16r09 16r10 16r11 16r12
                      16r13 16r14 16r15 16r16].
     (UUID fromBytes:bytes) asBytes ~= bytes ifTrue:[self halt]

asBytesMSB: msb

convert this UUID to a ByteArray.
If msb == false, it is converted into LSB-first byte ordering

asNativeBytes

convert this uuid to a ByteArray in host byte order.
Use this only to pass the UUID to the OS (Windows)

asString

undo the redefinition in ByteArray and Collection

Usage example(s):

        self genUUID asString

asUUID

literalArrayEncoding

(comment from inherited method)
encode myself as an array literal, from which a copy of the receiver
can be reconstructed with #decodeAsLiteralArray.

copying

deepCopy: I am never changed, after I have been created.
So there is no need to make a copy
deepCopyUsing: aDictionary postCopySelector: postCopySelector: I am never changed, after I have been created.
So there is no need to make a copy
shallowCopy: I am never changed, after I have been created.
So there is no need to make a copy
simpleDeepCopy: I am never changed, after I have been created.
So there is no need to make a copy

generating uuids

genTimestampUUID

generate a timestamp (and mac-address) based uuid

Usage example(s):

      self genTimestampUUID
      self genTimestampUUID genTimestampUUID

Usage example(s):

      1 to: 100 do:[ : el |
          Transcript show:el.
          Transcript show:': '.
          Transcript showCR:(UUID genTimestampUUID).
      ].

genUUID: nameStringOrBytes inNameSpace: namespaceStringOrUUID

generate a namespace UUID (Version 5, hashed by SHA-1).
See RFC4122.

Usage example(s):

        self genUUID:'www.example.org' inNameSpace:'DNS'.
        self genUUID:'http://www.exept.de' inNameSpace:'URL'.
        self genUUID:'some text' inNameSpace:(UUID fromString:'885f7d80-7d60-11e5-a133-101f74535bd0').
        self genUUID:'1.2.3.4.5' inNameSpace:'OID'.
        self genUUID:(OSI::DERCoder encode:(OSI::ASN1_OID newID:#(1 2 3 4 5))) 
             inNameSpace:'OID'.
        self genUUID:'c=de, o=eXept Software AG, cn=Development' 
             inNameSpace:'X500'.
        self genUUID:(OSI::DERCoder encode:(OSI::DistinguishedName fromString:'c=de, o=eXept Software AG, cn=Development') asAsn1Value) 
             inNameSpace:'X500'.

setRandomUUIDFromBytes: sixteenBytes

answer a randomly generated uuid as defined in RFC4122 section 4.4

hashing

hash

Generate a 30 bit hash value.
For Timestamp-UUIDs:
Bytes 1,2,3,4 are the least significant bits of the timestamp,
Bytes 13,14,15,16 are the least significant bytes of the mac address -
but considering these bytes does not generate a better hash to
justify the additional computations.

For random UUIDs, every byte is random anyway.

Usage example(s):

     |allHashes nonConflictsRatio|

     allHashes := UUID allInstances collect:[:each| each hash].
     Transcript showCR:'collisions: %1 (in %2 UUIDs)' with:(allHashes size - allHashes asSet size) with:allHashes size.  
     nonConflictsRatio := (allHashes asSet size / allHashes size) asFloat asFixedPoint:2.
     Transcript showCR:'%1%% collision rate' with:(1 asFixedPoint - nonConflictsRatio)*100

inspecting

inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package ): returns a string to be shown in the inspector's list

printing & storing

displayOn: aGCOrStream

what a kludge - Dolphin and Squeak mean: printOn: a stream;

Usage example(s):

        self genUUID displayOn:Transcript

printOn: aStream

UUID genUUID printString
UUID genUUID asString

Usage example(s):

d printOn:tmpStream base:16 size:8 fill:$0.

Usage example(s):

d printOn:tmpStream base:16 size:4 fill:$0.

Usage example(s):

d printOn:tmpStream base:16 size:4 fill:$0.

Usage example(s):

d printOn:tmpStream base:16 size:2 fill:$0.

Usage example(s):

d printOn:tmpStream base:16 size:2 fill:$0.

Usage example(s):

d printOn:tmpStream base:16 size:2 fill:$0.

printString

return a printed representation of the receiver for printing.
Uses the basic print mechanism of the underlying technology.

Usage example(s):

        UUID genUUID printString

storeOn: aStream

UUID readFrom:(UUID genUUID storeString)

testing

isRandomUUID: self genRandomUUID isRandomUUID
isTimestampUUID: self genTimestampUUID isTimestampUUID
isUUID: (comment from inherited method)
Return true if the receiver is a uuid.
Note: Do not override in any class except UUID.

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Wed, 08 May 2024 03:32:16 GMT