eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'UUID':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: UUID


Inheritance:

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

Package:
stx:libbasic2
Category:
Net-Communication-Support
Version:
rev: 1.61 date: 2018/04/19 08:19:12
user: stefan
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
o  adjustByteOrder: aByteArray
change the byte order of the uuid

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

o  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
o  initialize
I want to get informed about image restarts

o  nameSpaceToUuidBytes
ASN.1 OID in DER or as Text

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

instance creation
o  basicNew

o  basicNew: size
allow creating with exact size. We need this for XMLStandardDecoder

o  decodeFromLiteralArray: anArray
UUID 'uuid-string'
usage example(s):
     (UUID decodeFromLiteralArray:#(UUID '5b023ce0-41f1-11dd-b99f-001558137da0'))
       literalArrayEncoding   

o  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]. 

o  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.    

o  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]. 

o  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'.
            ]
        ]

o  genRandomUUID
generate a new random UUID
usage example(s):
      self genRandomUUID

o  genTimestampUUID
generate a new timestamp UUID
usage example(s):
      self genTimestampUUID

o  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).
      ].

o  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'.

o  new
self new

o  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
o  clockSeqHiAndReserved

o  clockSeqLow

o  node
answer the node (ethernet) address of this uuid
usage example(s):
       (self allInstances 
            select:[:e| e isTimestampUUID] 
            thenCollect:[:e| e node]) asBag

o  timeHighAndVersion

o  timeLow

o  timeMid

o  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

o  version
the version number of the uuid
usage example(s):
        self genTimestampUUID version
        self genRandomUUID version

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

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

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

o  asString
self genUUID asString

o  asUUID

o  literalArrayEncoding

copying
o  deepCopy
I am never changed, after I have been created.
So there is no need to make a copy

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

o  shallowCopy
I am never changed, after I have been created.
So there is no need to make a copy

o  simpleDeepCopy
I am never changed, after I have been created.
So there is no need to make a copy

generating uuids
o  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).
      ].

o  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'.

o  setRandomUUIDFromBytes: sixteenBytes
answer a randomly generated uuid as defined in RFC4122 section 4.4

hashing
o  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
o  inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package )
returns a string to be shown in the inspector's list

printing & storing
o  displayOn: aGCOrStream
what a kludge - Dolphin and Squeak mean: printOn: a stream;
usage example(s):
        self genUUID displayOn:Transcript

o  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.

o  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

o  storeOn: aStream
Object readFrom:(UUID genUUID storeString)

testing
o  isRandomUUID
self genRandomUUID isRandomUUID

o  isTimestampUUID
self genTimestampUUID isTimestampUUID

o  isUUID



ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Sat, 23 Mar 2019 08:50:46 GMT