Smalltalk/X Webserver

Documentation of class 'UUID':

Class: UUID

Inheritance
Description
Related information
Class protocol
Instance protocol

Inheritance:

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

Package:: stx:libbasic2

Category:: Net-Communication-Support

Version:: rev: 1.63 date: 2019/08/11 22:12:49; user: cg; file: UUID.st directory: libbasic2; module: stx stc-classLibrary: libbasic2

Author:

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:]

Related information:

Class protocol:

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
update: something with: aParameter from: changedObject: flush cached MAC address (may have been restarted on another host)

instance creation

basicNew

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

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

skip $-

usage example(s):

     UUID readFrom:'5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77' 
     UUID readFrom:'{5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77}' 
     UUID readFrom:'{5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77' 
     UUID fromString:'5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77 bllll' 
     UUID fromString:'5ab2e9b4-3d48-11d2-9ea4-80c5140aaa77' 
     UUID fromString:'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'

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)
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: self genUUID asString
asUUID
literalArrayEncoding

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.

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

Object readFrom:(UUID genUUID storeString)

testing

isRandomUUID: self genRandomUUID isRandomUUID
isTimestampUUID: self genTimestampUUID isTimestampUUID
isUUID

ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Mon, 29 May 2023 13:06:50 GMT