Suid (suid-server-java 0.9.2 API)

java.lang.Object
- java.lang.Number
- - ws.suid.Suid

All Implemented Interfaces:

Serializable, CharSequence, Comparable<Suid>
```
public final class Suid
extends Number
implements CharSequence, Comparable<Suid>
```
Stores a 53-bit service-unique ID in a 64-bit long.
The bits are distributed over the 64-bit long as depicted below:
```
                     HIGH INT                                         LOW INT
 ________________________________________________________________________________________________
 |                                               |                                               |
 | 0000 0000 | 000b bbbb | bbbb bbbb | bbbb bbbb | bbbb bbbb | bbbb bbbb | bbbb bbii | iiii iiss |
 |_______________________________________________|_______________________________________________|
 
   0 = 11 reserved bits
   b = 43 block bits
   i = 8 ID bits
   s = 2 shard bits
 
```
The first 11 bits are reserved and always set to 0. The next 43 bits are used for the block number. These are handed out by a centralized server. Then there are 8 ID bits which are to be filled in by the generator. The last 2 bits are reserved for the shard ID. To prevent a single point of failure, at most 4 individual hosts can be handing out ID's for a certain domain, each with their own shard ID.

To make the String representation of Suids both short and easily human-readable and write-able, an encoding scheme is used based on the alphanumerals [a-z,0-9] as follows:
```
   0123456789a cdefghijk mn p rstuvwxyz  = 32 character alphabet
              ^         ^  ^ ^ 
              b         l  o q
 
   bloq = 4 Replacement symbols:
     b = 00
     l = 01
     o = 02
     q = 03
 
```
Using only lowercase (to make it easily writable by humans), the alphanumerals give us 36 individual tokens in our alphabet. To make things simpler, we take out 4 characters and use them as replacement symbols instead: 'b', 'l', 'o' and 'q'. Now we end up with a 32 token alphabet, neatly encoding 5 bits per token.

We can use the replacement symbols to perform some 'compression'. Using the fact that all blocks will end with the characters '00', '01', '02' or '03' (for shards 0 .. 3) we can save one character off any block suid by replacing the character sequence by it's corresponding replacement symbol. This at the same time uniquely marks a suid as a block suid.
Author:

Stijn de Witt [StijnDeWitt@hotmail.com]

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ALPHABET` Alphabet used when converting suid to string
`static int`	`COUNT_BLOCK` Number of block bits
`static int`	`COUNT_ID` Number of ID bits
`static int`	`COUNT_RESERVED` Number of reserved bits
`static int`	`COUNT_SHARD` Number of shard bits
`static long`	`MASK_BLOCK` Mask that singles out the block bits
`static long`	`MASK_ID` Mask that singles out the ID bits
`static long`	`MASK_RESERVED` Mask that singles out the reserved bits
`static long`	`MASK_SHARD` Mask that singles out the shard bits
`static long`	`MASK_TOKEN` Mask that singles out a token
`static int`	`OFFSET_BLOCK` Offset of block bits within suid (from LSB)
`static int`	`OFFSET_ID` Offset of ID bits within suid (from LSB)
`static String[][]`	`REPLACEMENT_SYMBOLS` Replacement symbols used when converting suid to string

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`char`	`charAt(int index)` Returns the char present at the given `index` in the compressed string representation of this suid.
`int`	`compareTo(Suid obj)`
`static String`	`compress(String base32)` Compresses the given `base32` string.
`static String`	`decompress(String compressed)` Decompresses the given `compressed` string.
`double`	`doubleValue()`
`boolean`	`equals(Object obj)`
`float`	`floatValue()`
`long`	`getBlock()` Gets the block number.
`int`	`getId()` Gets the generated ID.
`byte`	`getShard()` Gets the shard ID.
`int`	`hashCode()`
`int`	`intValue()`
`boolean`	`isBlock()` Indicates whether this Suid is a block suid.
`int`	`length()` Returns the length of the compressed string representation of this suid.
`long`	`longValue()` Returns this suid's underlying value.
`CharSequence`	`subSequence(int start, int end)`
`String`	`toBase32()` Returns a base-32 String representation of this suid that is not compressed.
`String`	`toString()` Returns a compressed base-32 string representation of this suid.
`static Suid`	`valueOf(long value)` Creates a suid based on the given long `value`.
`static Suid`	`valueOf(long block, int id, byte shard)` Creates a suid based on the given `block` number, generator `id` and `shard` id.
`static Suid`	`valueOf(String compressed)` Creates a suid based on the given `compressed` string.
`static Suid`	`valueOfBase32(String base32)` Creates a suid based on the given `base32` string.

Methods inherited from class java.lang.Number
byteValue, shortValue

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.CharSequence
chars, codePoints

- Field Detail
  - MASK_RESERVED
```
public static final long MASK_RESERVED
```
    Mask that singles out the reserved bits
    
    See Also:
    
    Constant Field Values
  - MASK_BLOCK
```
public static final long MASK_BLOCK
```
    Mask that singles out the block bits
    
    See Also:
    
    Constant Field Values
  - MASK_ID
```
public static final long MASK_ID
```
    Mask that singles out the ID bits
    
    See Also:
    
    Constant Field Values
  - MASK_SHARD
```
public static final long MASK_SHARD
```
    Mask that singles out the shard bits
    
    See Also:
    
    Constant Field Values
  - MASK_TOKEN
```
public static final long MASK_TOKEN
```
    Mask that singles out a token
    
    See Also:
    
    Constant Field Values
  - COUNT_RESERVED
```
public static final int COUNT_RESERVED
```
    Number of reserved bits
    
    See Also:
    
    Constant Field Values
  - COUNT_BLOCK
```
public static final int COUNT_BLOCK
```
    Number of block bits
    
    See Also:
    
    Constant Field Values
  - COUNT_ID
```
public static final int COUNT_ID
```
    Number of ID bits
    
    See Also:
    
    Constant Field Values
  - COUNT_SHARD
```
public static final int COUNT_SHARD
```
    Number of shard bits
    
    See Also:
    
    Constant Field Values
  - OFFSET_BLOCK
```
public static final int OFFSET_BLOCK
```
    Offset of block bits within suid (from LSB)
    
    See Also:
    
    Constant Field Values
  - OFFSET_ID
```
public static final int OFFSET_ID
```
    Offset of ID bits within suid (from LSB)
    
    See Also:
    
    Constant Field Values
  - ALPHABET
```
public static final String ALPHABET
```
    Alphabet used when converting suid to string
    
    See Also:
    
    Constant Field Values
  - REPLACEMENT_SYMBOLS
```
public static final String[][] REPLACEMENT_SYMBOLS
```
    Replacement symbols used when converting suid to string
- Method Detail
  - valueOf
```
public static Suid valueOf(long value)
```
    Creates a suid based on the given long value.
    
    Parameters:
    
    value - The long value
    
    Returns:
    
    A new suid, never null.
  - valueOf
```
public static Suid valueOf(long block,
                           int id,
                           byte shard)
```
    Creates a suid based on the given block number, generator id and shard id.
    
    Parameters:
    
    block - The block number
    
    id - The generator ID bits
    
    shard - The shard ID
    
    Returns:
    
    A new suid, never null.
  - valueOf
```
public static Suid valueOf(String compressed)
```
    Creates a suid based on the given compressed string.
    
    Parameters:
    
    compressed - The compressed base32 string
    
    Returns:
    
    The new suid, or null if compressed was null.
    
    See Also:
    
    decompress(java.lang.String), valueOfBase32(java.lang.String)
  - valueOfBase32
```
public static Suid valueOfBase32(String base32)
```
    Creates a suid based on the given base32 string.
    
    Parameters:
    
    base32 - The base32 string
    
    Returns:
    
    The new suid, or null if compressed was null.
    
    See Also:
    
    decompress(java.lang.String)
  - toString
```
public String toString()
```
    Returns a compressed base-32 string representation of this suid.
    
    Specified by:
    
    toString in interface CharSequence
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    A String of at least 1 character and at most 11 characters.
    
    See Also:
    
    compress(java.lang.String)
  - toBase32
```
public String toBase32()
```
    Returns a base-32 String representation of this suid that is not compressed.
    This method uses a 32 character ALPHABET to create the base-32 representation of this suid.
    
    Returns:
    
    A String of at least 1 character and at most 11 characters, never null.
    
    See Also:
    
    ALPHABET
  - compress
```
public static String compress(String base32)
```
    Compresses the given base32 string.
    
    Parameters:
    
    base32 - The string to compress, never null.
    
    Returns:
    
    The compressed string, which may be shorter or of equal length but never longer than the given String.
    
    See Also:
    
    decompress(java.lang.String)
  - decompress
```
public static String decompress(String compressed)
```
    Decompresses the given compressed string.
    
    Parameters:
    
    compressed - The string to decompress, never null.
    
    Returns:
    
    The decompressed string, which may be longer or of equal length but never shorter than the given String, or null if compressed was null.
    
    See Also:
    
    compress(java.lang.String)
  - intValue
```
public int intValue()
```
    Specified by:
    
    intValue in class Number
  - longValue
```
public long longValue()
```
    Returns this suid's underlying value.
    
    Specified by:
    
    longValue in class Number
  - floatValue
```
public float floatValue()
```
    Specified by:
    
    floatValue in class Number
  - doubleValue
```
public double doubleValue()
```
    Specified by:
    
    doubleValue in class Number
  - getBlock
```
public long getBlock()
```
    Gets the block number.
    
    Returns:
    
    A long with just the block number.
  - getShard
```
public byte getShard()
```
    Gets the shard ID.
    
    Returns:
    
    A byte with the shard number (always in range 0 .. 3).
  - getId
```
public int getId()
```
    Gets the generated ID.
    
    Returns:
    
    An int with the generated ID (always in range 0 .. 255).
  - isBlock
```
public boolean isBlock()
```
    Indicates whether this Suid is a block suid.
    Block suids are the only suids a server will ever distribute. They have all zeroes in the ID bits. The ID generator on the client will fill in these bits to generate ID's. Block suids are themselves also valid IDs. The string representation of a block suid is always 'compressed', because block suids' normalized base-32 string representations always end with one of the character sequences "01", "02", "03" or "04", which are replaced by the replacement symbols 'b', 'l', 'o' and 'q' respectively.
    
    Returns:
    
    true if this suid is a block suid, false otherwise.
  - length
```
public int length()
```
    Returns the length of the compressed string representation of this suid.
    Equivalent to toString().length().
    
    Specified by:
    
    length in interface CharSequence
  - charAt
```
public char charAt(int index)
```
    Returns the char present at the given index in the compressed string representation of this suid.
    Equivalent to toString().charAt(index).
    
    Specified by:
    
    charAt in interface CharSequence
  - subSequence
```
public CharSequence subSequence(int start,
                                int end)
```
    Specified by:
    
    subSequence in interface CharSequence
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
  - compareTo
```
public int compareTo(Suid obj)
```
    Specified by:
    
    compareTo in interface Comparable<Suid>

Class Suid

Field Summary

Method Summary

Methods inherited from class java.lang.Number

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.CharSequence

Field Detail

MASK_RESERVED

MASK_BLOCK

MASK_ID

MASK_SHARD

MASK_TOKEN

COUNT_RESERVED

COUNT_BLOCK

COUNT_ID

COUNT_SHARD

OFFSET_BLOCK

OFFSET_ID

ALPHABET

REPLACEMENT_SYMBOLS

Method Detail

valueOf

valueOf

valueOf

valueOfBase32

toString

toBase32

compress

decompress

intValue

longValue

floatValue

doubleValue

getBlock

getShard

getId

isBlock

length

charAt

subSequence

hashCode

equals

compareTo