net.opentsdb.meta

Class UIDMeta

java.lang.Object

net.opentsdb.meta.UIDMeta

public final class UIDMeta
extends Object

UIDMeta objects are associated with the UniqueId of metrics, tag names or tag values. When a new metric, tagk or tagv is generated, a UIDMeta object will also be written to storage with only the uid, type and name filled out.

Users are allowed to edit the following fields:

• display_name
• description
• notes
• custom

The name, uid, type and created fields can only be modified by the system and are usually done so on object creation.

When you call syncToStorage(net.opentsdb.core.TSDB, boolean) on this object, it will verify that the UID object this meta data is linked with still exists. Then it will fetch the existing data and copy changes, overwriting the user fields if specific (e.g. via a PUT command). If overwriting is not called for (e.g. a POST was issued), then only the fields provided by the user will be saved, preserving all of the other fields in storage. Hence the need for the changed hash map and the syncMeta(net.opentsdb.meta.UIDMeta, boolean) method.

Note that the HBase specific storage code will be removed once we have a DAL

Since:

2.0

Constructor Summary

Constructors

Constructor and Description
UIDMeta() Default constructor Initializes the the changed map
UIDMeta(UniqueId.UniqueIdType type, byte[] uid, String name) Constructor used by TSD only to create a new UID with the given data and the current system time for createdd
UIDMeta(UniqueId.UniqueIdType type, String uid) Constructor used for overwriting.

Method Summary

Methods

Modifier and Type	Method and Description
com.stumbleupon.async.Deferred<Object>	delete(TSDB tsdb) Attempts to delete the meta object from storage
long	getCreated()
Map<String,String>	getCustom()
String	getDescription()
String	getDisplayName()
String	getName()
String	getNotes()
UniqueId.UniqueIdType	getType()
String	getUID()
static com.stumbleupon.async.Deferred<UIDMeta>	getUIDMeta(TSDB tsdb, UniqueId.UniqueIdType type, byte[] uid) Verifies the UID object exists, then attempts to fetch the meta from storage and if not found, returns a default object.
static com.stumbleupon.async.Deferred<UIDMeta>	getUIDMeta(TSDB tsdb, UniqueId.UniqueIdType type, String uid) Convenience overload of getUIDMeta(TSDB, UniqueIdType, byte[])
void	setCreated(long created)
void	setCustom(Map<String,String> custom)
void	setDescription(String description)
void	setDisplayName(String display_name)
void	setNotes(String notes)
com.stumbleupon.async.Deferred<Object>	storeNew(TSDB tsdb) Attempts to store a blank, new UID meta object in the proper location.
com.stumbleupon.async.Deferred<Boolean>	syncToStorage(TSDB tsdb, boolean overwrite) Attempts a CompareAndSet storage call, loading the object from storage, synchronizing changes, and attempting a put.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

UIDMeta

public UIDMeta()

Default constructor Initializes the the changed map

UIDMeta

public UIDMeta(UniqueId.UniqueIdType type,
       String uid)

Constructor used for overwriting. Will not reset the name or created values in storage.

Parameters:

type - Type of UID object

uid - UID of the object

UIDMeta

public UIDMeta(UniqueId.UniqueIdType type,
       byte[] uid,
       String name)

Constructor used by TSD only to create a new UID with the given data and the current system time for createdd

Parameters:

type - Type of UID object

uid - UID of the object

name - Name of the UID

Method Detail

toString

public String toString()

Overrides:

toString in class Object

Returns:

a string with details about this object

syncToStorage

public com.stumbleupon.async.Deferred<Boolean> syncToStorage(TSDB tsdb,
                                                    boolean overwrite)

Attempts a CompareAndSet storage call, loading the object from storage, synchronizing changes, and attempting a put. Note: If the local object didn't have any fields set by the caller then the data will not be written.

Parameters:

tsdb - The TSDB to use for storage access

overwrite - When the RPC method is PUT, will overwrite all user accessible fields

Returns:

True if the storage call was successful, false if the object was modified in storage during the CAS call. If false, retry the call. Other failures will result in an exception being thrown.

Throws:

org.hbase.async.HBaseException - if there was an issue fetching

IllegalArgumentException - if parsing failed

NoSuchUniqueId - If the UID does not exist

IllegalStateException - if the data hasn't changed. This is OK!

JSONException - if the object could not be serialized

storeNew

public com.stumbleupon.async.Deferred<Object> storeNew(TSDB tsdb)

Attempts to store a blank, new UID meta object in the proper location. Warning: This should not be called by user accessible methods as it will overwrite any data already in the column. This method does not use a CAS, instead it uses a PUT to overwrite anything in the column.

Parameters:

tsdb - The TSDB to use for calls

Returns:

A deferred without meaning. The response may be null and should only be used to track completion.

Throws:

org.hbase.async.HBaseException - if there was an issue writing to storage

IllegalArgumentException - if data was missing

JSONException - if the object could not be serialized

delete

public com.stumbleupon.async.Deferred<Object> delete(TSDB tsdb)

Attempts to delete the meta object from storage

Parameters:

tsdb - The TSDB to use for access to storage

Returns:

A deferred without meaning. The response may be null and should only be used to track completion.

Throws:

org.hbase.async.HBaseException - if there was an issue

IllegalArgumentException - if data was missing (uid and type)

getUIDMeta

public static com.stumbleupon.async.Deferred<UIDMeta> getUIDMeta(TSDB tsdb,
                                                 UniqueId.UniqueIdType type,
                                                 String uid)

Convenience overload of getUIDMeta(TSDB, UniqueIdType, byte[])

Parameters:

tsdb - The TSDB to use for storage access

type - The type of UID to fetch

uid - The ID of the meta to fetch

Returns:

A UIDMeta from storage or a default

Throws:

org.hbase.async.HBaseException - if there was an issue fetching

NoSuchUniqueId - If the UID does not exist

getUIDMeta

public static com.stumbleupon.async.Deferred<UIDMeta> getUIDMeta(TSDB tsdb,
                                                 UniqueId.UniqueIdType type,
                                                 byte[] uid)

Verifies the UID object exists, then attempts to fetch the meta from storage and if not found, returns a default object.

The reason for returning a default object (with the type, uid and name set) is due to users who may have just enabled meta data or have upgraded; we want to return valid data. If they modify the entry, it will write to storage. You can tell it's a default if the created value is 0. If the meta was generated at UID assignment or updated by the meta sync CLI command, it will have a valid created timestamp.

Parameters:

tsdb - The TSDB to use for storage access

type - The type of UID to fetch

uid - The ID of the meta to fetch

Returns:

A UIDMeta from storage or a default

Throws:

org.hbase.async.HBaseException - if there was an issue fetching

NoSuchUniqueId - If the UID does not exist

getUID

public String getUID()

Returns:

the uid as a hex encoded string

getType

public UniqueId.UniqueIdType getType()

Returns:

the type of UID represented

getName

public String getName()

Returns:

the name of the UID object

getDisplayName

public String getDisplayName()

Returns:

optional display name, use name if empty

getDescription

public String getDescription()

Returns:

optional description

getNotes

public String getNotes()

Returns:

optional notes

getCreated

public long getCreated()

Returns:

when the UID was first assigned, may be 0 if unknown

getCustom

public Map<String,String> getCustom()

Returns:

optional map of custom values from the user

setDisplayName

public void setDisplayName(String display_name)

Parameters:

display_name - an optional descriptive name for the UID

setDescription

public void setDescription(String description)

Parameters:

description - an optional description of the UID

setNotes

public void setNotes(String notes)

Parameters:

notes - optional notes

setCustom

public void setCustom(Map<String,String> custom)

Parameters:

custom - the custom to set

setCreated

public final void setCreated(long created)

Parameters:

created - the created timestamp Unix epoch in seconds