net.opentsdb.uid

Class UniqueId

java.lang.Object

net.opentsdb.uid.UniqueId

All Implemented Interfaces:

UniqueIdInterface

public final class UniqueId
extends Object
implements UniqueIdInterface

Represents a table of Unique IDs, manages the lookup and creation of IDs.

Don't attempt to use equals() or hashCode() on this class.

See Also:

UniqueIdInterface

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UniqueId.UniqueIdType Enumerator for different types of UIDS @since 2.0

Constructor Summary

Constructors

Constructor and Description
UniqueId(org.hbase.async.HBaseClient client, byte[] table, String kind, int width) Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
int	cacheHits() The number of times we avoided reading from HBase thanks to the cache.
int	cacheMisses() The number of times we had to read from HBase and populate the cache.
int	cacheSize() Returns the number of elements stored in the internal cache.
void	dropCaches() Causes this instance to discard all its in-memory caches.
byte[]	getId(String name) Finds the ID associated with a given name.
com.stumbleupon.async.Deferred<byte[]>	getIdAsync(String name)
String	getName(byte[] id) Finds the name associated with a given ID.
com.stumbleupon.async.Deferred<String>	getNameAsync(byte[] id) Finds the name associated with a given ID.
byte[]	getOrCreateId(String name) Finds the ID associated with a given name or creates it.
com.stumbleupon.async.Deferred<byte[]>	getOrCreateIdAsync(String name) Finds the ID associated with a given name or creates it.
static List<byte[]>	getTagPairsFromTSUID(String tsuid, short metric_width, short tagk_width, short tagv_width) Extracts a list of tagk/tagv pairs from a tsuid
static byte[]	getTSUIDFromKey(byte[] row_key, short metric_width, short timestamp_width) Extracts the TSUID from a storage row key that includes the timestamp.
static com.stumbleupon.async.Deferred<Map<String,Long>>	getUsedUIDs(TSDB tsdb, byte[][] kinds) Returns a map of max UIDs from storage for the given list of UID types
String	kind() Returns what kind of Unique ID is served by this instance.
long	maxPossibleId() The largest possible ID given the number of bytes the IDs are represented on.
void	rename(String oldname, String newname) Reassigns the UID to a different name (non-atomic).
void	setTSDB(TSDB tsdb)
static byte[]	stringToUid(String uid) Converts a hex string to a byte array If the uid is less than uid_length * 2 characters wide, it will be padded with 0s to conform to the spec.
static byte[]	stringToUid(String uid, short uid_length) Converts a hex string to a byte array If the uid is less than uid_length * 2 characters wide, it will be padded with 0s to conform to the spec.
static UniqueId.UniqueIdType	stringToUniqueIdType(String type) Attempts to convert the given string to a type enumerator
List<String>	suggest(String search) Attempts to find suggestions of names given a search term.
List<String>	suggest(String search, int max_results) Attempts to find suggestions of names given a search term.
com.stumbleupon.async.Deferred<List<String>>	suggestAsync(String search, int max_results) Attempts to find suggestions of names given a search term.
String	toString() Returns a human readable string representation of the object.
static String	uidToString(byte[] uid) Converts a byte array to a hex encoded, upper case string with padding
short	width() Returns the number of bytes on which each Unique ID is encoded.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UniqueId

public UniqueId(org.hbase.async.HBaseClient client,
        byte[] table,
        String kind,
        int width)

Constructor.

Parameters:

client - The HBase client to use.

table - The name of the HBase table to use.

kind - The kind of Unique ID this instance will deal with.

width - The number of bytes on which Unique IDs should be encoded.

Throws:

IllegalArgumentException - if width is negative or too small/large or if kind is an empty string.

Method Detail

cacheHits

public int cacheHits()

The number of times we avoided reading from HBase thanks to the cache.

cacheMisses

public int cacheMisses()

The number of times we had to read from HBase and populate the cache.

cacheSize

public int cacheSize()

Returns the number of elements stored in the internal cache.

kind

public String kind()

Description copied from interface: UniqueIdInterface

Returns what kind of Unique ID is served by this instance.

Specified by:

kind in interface UniqueIdInterface

width

public short width()

Description copied from interface: UniqueIdInterface

Returns the number of bytes on which each Unique ID is encoded.

Specified by:

width in interface UniqueIdInterface

setTSDB

public void setTSDB(TSDB tsdb)

Parameters:

tsdb - Whether or not to track new UIDMeta objects

maxPossibleId

public long maxPossibleId()

The largest possible ID given the number of bytes the IDs are represented on.

dropCaches

public void dropCaches()

Causes this instance to discard all its in-memory caches.

Since:

1.1

getName

public String getName(byte[] id)
               throws NoSuchUniqueId,
                      org.hbase.async.HBaseException

Finds the name associated with a given ID.

This method is blocking. Its use within OpenTSDB itself is discouraged, please use getNameAsync(byte[]) instead.

Specified by:

getName in interface UniqueIdInterface

Parameters:

id - The ID associated with that name.

Throws:

NoSuchUniqueId - if the given ID is not assigned.

org.hbase.async.HBaseException - if there is a problem communicating with HBase.

IllegalArgumentException - if the ID given in argument is encoded on the wrong number of bytes.

See Also:

getId(String), getOrCreateId(String)

getNameAsync

public com.stumbleupon.async.Deferred<String> getNameAsync(byte[] id)

Finds the name associated with a given ID.

Parameters:

id - The ID associated with that name.

Throws:

NoSuchUniqueId - if the given ID is not assigned.

org.hbase.async.HBaseException - if there is a problem communicating with HBase.

IllegalArgumentException - if the ID given in argument is encoded on the wrong number of bytes.

Since:

1.1

See Also:

getId(String), getOrCreateIdAsync(String)

getId

public byte[] getId(String name)
             throws NoSuchUniqueName,
                    org.hbase.async.HBaseException

Description copied from interface: UniqueIdInterface

Finds the ID associated with a given name.

The length of the byte array is fixed in advance by the implementation.

Specified by:

getId in interface UniqueIdInterface

Parameters:

name - The name to lookup in the table.

Returns:

A non-null, non-empty byte[] array.

Throws:

NoSuchUniqueName - if the name requested doesn't have an ID assigned.

org.hbase.async.HBaseException - if there is a problem communicating with HBase.

See Also:

UniqueIdInterface.getName(byte[])

getIdAsync

public com.stumbleupon.async.Deferred<byte[]> getIdAsync(String name)

getOrCreateId

public byte[] getOrCreateId(String name)
                     throws org.hbase.async.HBaseException

Finds the ID associated with a given name or creates it.

This method is blocking. Its use within OpenTSDB itself is discouraged, please use getOrCreateIdAsync(java.lang.String) instead.

The length of the byte array is fixed in advance by the implementation.

Specified by:

getOrCreateId in interface UniqueIdInterface

Parameters:

name - The name to lookup in the table or to assign an ID to.

Throws:

org.hbase.async.HBaseException - if there is a problem communicating with HBase.

IllegalStateException - if all possible IDs are already assigned.

IllegalStateException - if the ID found in HBase is encoded on the wrong number of bytes.

getOrCreateIdAsync

public com.stumbleupon.async.Deferred<byte[]> getOrCreateIdAsync(String name)

Finds the ID associated with a given name or creates it.

The length of the byte array is fixed in advance by the implementation.

Parameters:

name - The name to lookup in the table or to assign an ID to.

Throws:

org.hbase.async.HBaseException - if there is a problem communicating with HBase.

IllegalStateException - if all possible IDs are already assigned.

IllegalStateException - if the ID found in HBase is encoded on the wrong number of bytes.

Since:

1.2

suggest

public List<String> suggest(String search)
                     throws org.hbase.async.HBaseException

Attempts to find suggestions of names given a search term.

This method is blocking. Its use within OpenTSDB itself is discouraged, please use suggestAsync(java.lang.String, int) instead.

Parameters:

search - The search term (possibly empty).

Returns:

A list of known valid names that have UIDs that sort of match the search term. If the search term is empty, returns the first few terms.

Throws:

org.hbase.async.HBaseException - if there was a problem getting suggestions from HBase.

suggest

public List<String> suggest(String search,
                   int max_results)
                     throws org.hbase.async.HBaseException

Attempts to find suggestions of names given a search term.

Parameters:

search - The search term (possibly empty).

max_results - The number of results to return. Must be 1 or greater

Returns:

A list of known valid names that have UIDs that sort of match the search term. If the search term is empty, returns the first few terms.

Throws:

org.hbase.async.HBaseException - if there was a problem getting suggestions from HBase.

IllegalArgumentException - if the count was less than 1

Since:

2.0

suggestAsync

public com.stumbleupon.async.Deferred<List<String>> suggestAsync(String search,
                                                        int max_results)

Attempts to find suggestions of names given a search term.

Parameters:

search - The search term (possibly empty).

Returns:

A list of known valid names that have UIDs that sort of match the search term. If the search term is empty, returns the first few terms.

Throws:

org.hbase.async.HBaseException - if there was a problem getting suggestions from HBase.

Since:

1.1

rename

public void rename(String oldname,
          String newname)

Reassigns the UID to a different name (non-atomic).

Whatever was the UID of oldname will be given to newname. oldname will no longer be assigned a UID.

Beware that the assignment change is not atommic. If two threads or processes attempt to rename the same UID differently, the result is unspecified and might even be inconsistent. This API is only here for administrative purposes, not for normal programmatic interactions.

Parameters:

oldname - The old name to rename.

newname - The new name.

Throws:

NoSuchUniqueName - if oldname wasn't assigned.

IllegalArgumentException - if newname was already assigned.

org.hbase.async.HBaseException - if there was a problem with HBase while trying to update the mapping.

toString

public String toString()

Returns a human readable string representation of the object.

Overrides:

toString in class Object

uidToString

public static String uidToString(byte[] uid)

Converts a byte array to a hex encoded, upper case string with padding

Parameters:

uid - The ID to convert

Returns:

the UID as a hex string

Throws:

NullPointerException - if the ID was null

Since:

2.0

stringToUid

public static byte[] stringToUid(String uid)

Converts a hex string to a byte array If the uid is less than uid_length * 2 characters wide, it will be padded with 0s to conform to the spec. E.g. if the tagk width is 3 and the given uid string is "1", the string will be padded to "000001" and then converted to a byte array to reach 3 bytes. All uids are padded to 1 byte. If given "1", and uid_length is 0, the uid will be padded to "01" then converted.

Parameters:

uid - The UID to convert

Returns:

The UID as a byte array

Throws:

NullPointerException - if the ID was null

IllegalArgumentException - if the string is not valid hex

Since:

2.0

stringToUniqueIdType

public static UniqueId.UniqueIdType stringToUniqueIdType(String type)

Attempts to convert the given string to a type enumerator

Parameters:

type - The string to convert

Returns:

a valid UniqueIdType if matched

Throws:

IllegalArgumentException - if the string did not match a type

Since:

2.0

stringToUid

public static byte[] stringToUid(String uid,
                 short uid_length)

Converts a hex string to a byte array If the uid is less than uid_length * 2 characters wide, it will be padded with 0s to conform to the spec. E.g. if the tagk width is 3 and the given uid string is "1", the string will be padded to "000001" and then converted to a byte array to reach 3 bytes. All uids are padded to 1 byte. If given "1", and uid_length is 0, the uid will be padded to "01" then converted.

Parameters:

uid - The UID to convert

uid_length - An optional length, in bytes, that the UID must conform to. Set to 0 if not used.

Returns:

The UID as a byte array

Throws:

NullPointerException - if the ID was null

IllegalArgumentException - if the string is not valid hex

Since:

2.0

getTSUIDFromKey

public static byte[] getTSUIDFromKey(byte[] row_key,
                     short metric_width,
                     short timestamp_width)

Extracts the TSUID from a storage row key that includes the timestamp.

Parameters:

row_key - The row key to process

metric_width - The width of the metric

timestamp_width - The width of the timestamp

Returns:

The TSUID

Throws:

ArrayIndexOutOfBoundsException - if the row_key is invalid

getTagPairsFromTSUID

public static List<byte[]> getTagPairsFromTSUID(String tsuid,
                                short metric_width,
                                short tagk_width,
                                short tagv_width)

Extracts a list of tagk/tagv pairs from a tsuid

Parameters:

tsuid - The tsuid to parse

metric_width - The width of the metric tag in bytes

tagk_width - The width of tagks in bytes

tagv_width - The width of tagvs in bytes

Returns:

A list of tagk/tagv pairs alternating with tagk, tagv, tagk, tagv

Throws:

IllegalArgumentException - if the TSUID is malformed

getUsedUIDs

public static com.stumbleupon.async.Deferred<Map<String,Long>> getUsedUIDs(TSDB tsdb,
                                                           byte[][] kinds)

Returns a map of max UIDs from storage for the given list of UID types

Parameters:

tsdb - The TSDB to which we belong

kinds - A list of qualifiers to fetch

Returns:

A map with the "kind" as the key and the maximum assigned UID as the value

Since:

2.0