Suid (suid-server-java 0.10.1 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 bbbb | biii iiis |
 |_______________________________________________|_______________________________________________|
 
   0 = 11 reserved bits
   b = 46 block bits
   i = 6 ID bits
   s = 1 shard bit
 
```
The first 11 bits are reserved and always set to 0. The next 46 bits are used for the block number. These are handed out by a centralized server. Then there are 6 ID bits which are to be filled in by the generator. The last bit is reserved for the shard ID. To prevent a single point of failure, two separate hosts can be handing out ID's for a certain domain, each with their own shard ID (0 or 1).

To make the String representation of Suids both short and easily human-readable and write-able, base-36 encoding is used. Using only lowercase makes suids easy for humans to read, write and pronounce.
Author:

Stijn de Witt [StijnDeWitt@hotmail.com]

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Suid.Deserializer` Deserializes from JSON
`static class`	`Suid.Serializer` Serializes to JSON
`static class`	`Suid.SuidConverter` Converts Suid to/from it's database representation.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ALPHABET` Alphabet used when converting suid to string
`static long`	`BLOCK_SIZE` The number of blocks available.
`static byte`	`COUNT_BLOCK` Number of block bits
`static byte`	`COUNT_ID` Number of ID bits
`static byte`	`COUNT_RESERVED` Number of reserved bits
`static byte`	`COUNT_SHARD` Number of shard bits
`static long`	`IDSIZE` The number of IDs available in each block.
`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 byte`	`OFFSET_BLOCK` Offset of block bits within suid (from LSB)
`static byte`	`OFFSET_ID` Offset of ID bits within suid (from LSB)
`static byte`	`OFFSET_RESERVED` Offset of reserved bits within suid (from LSB)
`static byte`	`OFFSET_SHARD` Offset of shard bit within suid (from LSB)
`static long`	`SHARDSIZE` The number of shards available

Constructor Summary

Constructors
Constructor and Description
`Suid(long value)` Creates a suid based on the given long `value`.
`Suid(long block, byte id, byte shard)` Creates a suid based on the given `block`, `id` and `shard` constituent parts.
`Suid(String value)` Creates a suid based on the given string `value`.

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 base-36 string representation of this suid.
`int`	`compareTo(Suid that)` Compares this suid to `that` for order.
`double`	`doubleValue()` Returns the value of this Suid as a double.
`boolean`	`equals(Object that)` Compares this suid to `that` for equality.
`float`	`floatValue()` Use `longValue()` instead.
`long`	`getBlock()` Gets the block bits.
`byte`	`getId()` Gets the ID bits.
`byte`	`getShard()` Gets the shard bits.
`int`	`hashCode()`
`int`	`intValue()` Use `longValue()` instead.
`int`	`length()` Returns the length of the string representation of this suid.
`long`	`longValue()` Returns this suid's underlying value.
`static boolean`	`looksValid(String value)` Indicates whether the given `value` looks like a valid suid string.
`CharSequence`	`subSequence(int start, int end)`
`Long`	`toLong()` Converts this Suid to a Java Long.
`static List<Long>`	`toLong(List<Suid> ids)` Converts the given list of `ids` to a list of longs.
`String`	`toString()` Returns a base-36 string representation of this suid.
`static List<Suid>`	`valueOf(List<Long> ids)` Converts the given list of `ids` to a list of Suids.

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
  - ALPHABET
```
public static final String ALPHABET
```
    Alphabet used when converting suid to string
    
    See Also:
    
    Constant Field Values
  - 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
  - COUNT_RESERVED
```
public static final byte COUNT_RESERVED
```
    Number of reserved bits
    
    See Also:
    
    Constant Field Values
  - COUNT_BLOCK
```
public static final byte COUNT_BLOCK
```
    Number of block bits
    
    See Also:
    
    Constant Field Values
  - COUNT_ID
```
public static final byte COUNT_ID
```
    Number of ID bits
    
    See Also:
    
    Constant Field Values
  - COUNT_SHARD
```
public static final byte COUNT_SHARD
```
    Number of shard bits
    
    See Also:
    
    Constant Field Values
  - OFFSET_RESERVED
```
public static final byte OFFSET_RESERVED
```
    Offset of reserved bits within suid (from LSB)
    
    See Also:
    
    Constant Field Values
  - OFFSET_BLOCK
```
public static final byte OFFSET_BLOCK
```
    Offset of block bits within suid (from LSB)
    
    See Also:
    
    Constant Field Values
  - OFFSET_ID
```
public static final byte OFFSET_ID
```
    Offset of ID bits within suid (from LSB)
    
    See Also:
    
    Constant Field Values
  - OFFSET_SHARD
```
public static final byte OFFSET_SHARD
```
    Offset of shard bit within suid (from LSB)
    
    See Also:
    
    Constant Field Values
  - BLOCK_SIZE
```
public static final long BLOCK_SIZE
```
    The number of blocks available.
    
    See Also:
    
    Constant Field Values
  - IDSIZE
```
public static final long IDSIZE
```
    The number of IDs available in each block.
    
    See Also:
    
    Constant Field Values
  - SHARDSIZE
```
public static final long SHARDSIZE
```
    The number of shards available
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Suid
```
public Suid(String value)
     throws NumberFormatException
```
    Creates a suid based on the given string value.
    
    Parameters:
    
    value - The value of the new suid as a base-36 string, or null.
    
    Throws:
    
    NumberFormatException - When the supplied value can not be parsed as base-36.
  - Suid
```
public Suid(long value)
```
    Creates a suid based on the given long value.
    
    Parameters:
    
    value - The long value to set this Suid to.
  - Suid
```
public Suid(long block,
            byte id,
            byte shard)
```
    Creates a suid based on the given block, id and shard constituent parts.
    
    Parameters:
    
    block - The block bits for the suid, in a long.
    
    id - The id bits for the suid, in a byte.
    
    shard - The shard bit for the suid, in a byte.
- Method Detail
  - toString
```
public String toString()
```
    Returns a base-36 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.
  - intValue
```
public int intValue()
```
    Use longValue() instead.
    
    Specified by:
    
    intValue in class Number
  - longValue
```
public long longValue()
```
    Returns this suid's underlying value.
    Suid's use a long as underlying value. Avoid using intValue and floatValue as these perform narrowing conversions. These methods are mainly there to satisfy the Number interface.
    
    Specified by:
    
    longValue in class Number
  - floatValue
```
public float floatValue()
```
    Use longValue() instead.
    If you must have a floating point number, use doubleValue which can actually store all possible suids (they are limited to 53 bits for this purpose).
    
    Specified by:
    
    floatValue in class Number
  - doubleValue
```
public double doubleValue()
```
    Returns the value of this Suid as a double.
    Although suids internally use longs to store the bits, since they are limited to 53 bits, they can actually be represented as double as well without loss of precision.
    
    Specified by:
    
    doubleValue in class Number
  - toLong
```
public Long toLong()
```
    Converts this Suid to a Java Long.
    
    Returns:
    
    This suid's value converted to a Long, never null.
  - getBlock
```
public long getBlock()
```
    Gets the block bits.
    
    Returns:
    
    A long with the block bits.
  - getId
```
public byte getId()
```
    Gets the ID bits.
    
    Returns:
    
    An int with the ID bits (always in range 0 .. 63).
  - getShard
```
public byte getShard()
```
    Gets the shard bits.
    
    Returns:
    
    A byte with the shard number (always in range 0 .. 1).
  - length
```
public int length()
```
    Returns the length of the 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 base-36 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 that)
```
    Compares this suid to that for equality.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    that - The suid to compare to, may be null, in which case false will be returned.
    
    Returns:
    
    true if this suid is equals to that, false otherwise.
  - compareTo
```
public int compareTo(Suid that)
              throws NullPointerException
```
    Compares this suid to that for order.
    
    Specified by:
    
    compareTo in interface Comparable<Suid>
    
    Parameters:
    
    that - The suid to compare to, never null.
    
    Returns:
    
    -1 if this suid is less than, 0 if it is equals to, and 1 if it is greater than that.
    
    Throws:
    
    NullPointerException - when that is null.
  - looksValid
```
public static boolean looksValid(String value)
```
    Indicates whether the given value looks like a valid suid string.
    If this method returns true, this only indicates that it's *probably* valid. There are no guarantees.
    
    Parameters:
    
    value - The value, may be null, in which case this method returns false.
    
    Returns:
    
    true if it looks valid, false otherwise.
  - toLong
```
public static List<Long> toLong(List<Suid> ids)
```
    Converts the given list of ids to a list of longs.
    
    Parameters:
    
    ids - The ids to convert, may be empty but not null.
    
    Returns:
    
    The list of longs, may be empty but never null.
  - valueOf
```
public static List<Suid> valueOf(List<Long> ids)
```
    Converts the given list of ids to a list of Suids.
    
    Parameters:
    
    ids - The ids to convert, may be empty but not null.
    
    Returns:
    
    The list of Suids, may be empty but never null.

Class Suid

Nested Class Summary

Field Summary

Constructor 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

ALPHABET

MASK_RESERVED

MASK_BLOCK

MASK_ID

MASK_SHARD

COUNT_RESERVED

COUNT_BLOCK

COUNT_ID

COUNT_SHARD

OFFSET_RESERVED

OFFSET_BLOCK

OFFSET_ID

OFFSET_SHARD

BLOCK_SIZE

IDSIZE

SHARDSIZE

Constructor Detail

Suid

Suid

Suid

Method Detail

toString

intValue

longValue

floatValue

doubleValue

toLong

getBlock

getId

getShard

length

charAt

subSequence

hashCode

equals

compareTo

looksValid

toLong

valueOf