Suid (suid-server-java 0.9.14 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 iiss |
 |_______________________________________________|_______________________________________________|
 
   0 = 11 reserved bits
   b = 46 block bits
   i = 5 ID bits
   s = 2 shard bits
 
```
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 5 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, 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`

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 int`	`IDSIZE` The number of ID's 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 Suid`	`NULL` Convenient constant for a Suid with a value of `0L`.
`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`	`PREFIX` Prefix used when serializing to/from JSON.
`static int`	`SHARDSIZE` The number of shards available

Constructor Summary

Constructors
Modifier Constructor and Description

protected Suid(String value)
Constructor needed by Jackson.

Constructors
Modifier	Constructor and Description
`protected`	`Suid(String value)` Constructor needed by Jackson.

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 obj)`
`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()`
`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.
`static boolean`	`looksValidJSON(String json)` Indicates whether the given `json` string looks like a valid JSON representation of a suid.
`CharSequence`	`subSequence(int start, int end)`
`String`	`toJSON()` Serializes this suid to JSON.
`Long`	`toLong()` Converts this Suid to a Java Long.
`static List<Long>`	`toLong(List<Suid> ids)`
`String`	`toString()` Returns a base-36 string representation of this suid.
`static List<Suid>`	`valueOf(List<Long> ids)`
`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 string)` Creates a suid based on the given `string`.
`static Suid`	`valueOfJSON(String json)` Deserializes the given JSON string into a suid, if possible.

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
  - NULL
```
public static final Suid NULL
```
    Convenient constant for a Suid with a value of 0L.
  - PREFIX
```
public static final String PREFIX
```
    Prefix used when serializing to/from JSON.
    
    See Also:
    
    Constant Field Values
  - IDSIZE
```
public static final int IDSIZE
```
    The number of ID's available in each block.
    
    See Also:
    
    Constant Field Values
  - SHARDSIZE
```
public static final int SHARDSIZE
```
    The number of shards available
    
    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 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
- Constructor Detail
  - Suid
```
protected Suid(String value)
```
    Constructor needed by Jackson. Protected to signal to the JVM that this is a value class.
    Use the static valueOf methods to instantiate a suid.
    
    Parameters:
    
    value - The value of the new suid as a (possibly JSON) string, or null.
- 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 string)
```
    Creates a suid based on the given string.
    
    Parameters:
    
    string - The base36 string
    
    Returns:
    
    The new suid, or null if string was null.
  - 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()
```
    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
  - 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 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).
  - 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 obj)
```
    Overrides:
    
    equals in class Object
  - compareTo
```
public int compareTo(Suid obj)
```
    Specified by:
    
    compareTo in interface Comparable<Suid>
  - toJSON
```
public String toJSON()
```
    Serializes this suid to JSON.
    This method returns a JSON string of the form "Suid:xxxxx" where xxxxx is the suid's string representation. E.G: "Suid:14shd".
    
    Returns:
    
    The JSON string, never null.
    
    See Also:
    
    PREFIX, valueOfJSON(String), Suid.Serializer, Suid.Deserializer
  - 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 *might* be 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.
    
    See Also:
    
    valueOf(String)
  - looksValidJSON
```
public static boolean looksValidJSON(String json)
```
    Indicates whether the given json string looks like a valid JSON representation of a suid.
    If this method returns true, this only indicates that the JSON *might* be valid as a suid. There are no guarantees.
    
    Parameters:
    
    json - The json string, may be null in which case this method returns false.
    
    Returns:
    
    The suid, or null.
    
    See Also:
    
    looksValid(java.lang.String)
  - valueOfJSON
```
public static Suid valueOfJSON(String json)
```
    Deserializes the given JSON string into a suid, if possible.
    This method checks whether the given json string looks valid. If it does, it's deserialized into a suid and returned. If it does not look valid, null is returned instead.
    
    Returns:
    
    A suid, or null.
    
    See Also:
    
    looksValidJSON(String), toJSON(), PREFIX, Suid.Deserializer
  - toLong
```
public static List<Long> toLong(List<Suid> ids)
```
  - valueOf
```
public static List<Suid> valueOf(List<Long> ids)
```

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

NULL

PREFIX

IDSIZE

SHARDSIZE

MASK_RESERVED

MASK_BLOCK

MASK_ID

MASK_SHARD

COUNT_RESERVED

COUNT_BLOCK

COUNT_ID

COUNT_SHARD

OFFSET_BLOCK

OFFSET_ID

ALPHABET

Constructor Detail

Suid

Method Detail

valueOf

valueOf

valueOf

toString

intValue

longValue

floatValue

doubleValue

toLong

getBlock

getShard

getId

length

charAt

subSequence

hashCode

equals

compareTo

toJSON

looksValid

looksValidJSON

valueOfJSON

toLong

valueOf