public final class Suid extends Number implements CharSequence, Comparable<Suid>
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.
| 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
|
| 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. |
byteValue, shortValueclone, finalize, getClass, notify, notifyAll, wait, wait, waitchars, codePointspublic static final long MASK_RESERVED
public static final long MASK_BLOCK
public static final long MASK_ID
public static final long MASK_SHARD
public static final long MASK_TOKEN
public static final int COUNT_RESERVED
public static final int COUNT_BLOCK
public static final int COUNT_ID
public static final int COUNT_SHARD
public static final int OFFSET_BLOCK
public static final int OFFSET_ID
public static final String ALPHABET
public static final String[][] REPLACEMENT_SYMBOLS
public static Suid valueOf(long value)
value.value - The long valuenull.public static Suid valueOf(long block, int id, byte shard)
block number, generator id and shard id.block - The block numberid - The generator ID bitsshard - The shard IDnull.public static Suid valueOf(String compressed)
compressed string.compressed - The compressed base32 stringnull if compressed was null.decompress(java.lang.String),
valueOfBase32(java.lang.String)public static Suid valueOfBase32(String base32)
base32 string.base32 - The base32 stringnull if compressed was null.decompress(java.lang.String)public String toString()
toString in interface CharSequencetoString in class Objectcompress(java.lang.String)public String toBase32()
This method uses a 32 character ALPHABET to create the
base-32 representation of this suid.
null.ALPHABETpublic static String compress(String base32)
base32 string.base32 - The string to compress, never null.decompress(java.lang.String)public static String decompress(String compressed)
compressed string.compressed - The string to decompress, never null.null if compressed was null.compress(java.lang.String)public long longValue()
public float floatValue()
floatValue in class Numberpublic double doubleValue()
doubleValue in class Numberpublic long getBlock()
public byte getShard()
0 .. 3).public int getId()
0 .. 255).public boolean isBlock()
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.
true if this suid is a block suid, false otherwise.public int length()
Equivalent to toString().length().
length in interface CharSequencepublic char charAt(int index)
index in the compressed string representation of this suid.
Equivalent to toString().charAt(index).
charAt in interface CharSequencepublic CharSequence subSequence(int start, int end)
subSequence in interface CharSequencepublic int compareTo(Suid obj)
compareTo in interface Comparable<Suid>Copyright © 2015. All rights reserved.