Annotation

java.lang.Object
- net.opentsdb.meta.Annotation

All Implemented Interfaces:

Comparable<Annotation>
```
public final class Annotation
extends Object
implements Comparable<Annotation>
```
Annotations are used to record time-based notes about timeseries events. Every note must have an associated start_time as that determines where the note is stored.
Annotations may be associated with a specific timeseries, in which case the tsuid must be configured with a valid TSUID. If no TSUID is provided, the annotation is considered a "global" note that applies to everything stored in OpenTSDB. Global annotations are stored in the rows [ 0, 0, 0, <timestamp>] in the same manner as local annotations and timeseries data.
The description field should store a very brief line of information about the event. GUIs can display the description in their "main" view where multiple annotations may appear. Users of the GUI could then click or hover over the description for more detail including the notes field.
Custom data can be stored in the custom hash map for user specific information. For example, you could add a "reporter" key with the name of the person who recorded the note.

Since:

2.0

Constructor Summary

Constructors
Constructor and Description

Annotation()
Default constructor, initializes the change map

Constructors
Constructor and Description
`Annotation()` Default constructor, initializes the change map

Method Summary

Methods
Modifier and Type	Method and Description
`int`	`compareTo(Annotation note)` Compares the `#start_time` of this annotation to the given note
`com.stumbleupon.async.Deferred<Object>`	`delete(TSDB tsdb)` Attempts to mark an Annotation object for deletion.
`static com.stumbleupon.async.Deferred<Annotation>`	`getAnnotation(TSDB tsdb, byte[] tsuid, long start_time)` Attempts to fetch a global or local annotation from storage
`static com.stumbleupon.async.Deferred<Annotation>`	`getAnnotation(TSDB tsdb, long start_time)` Attempts to fetch a global annotation from storage
`static com.stumbleupon.async.Deferred<Annotation>`	`getAnnotation(TSDB tsdb, String tsuid, long start_time)` Attempts to fetch a global or local annotation from storage
`Map<String,String>`	`getCustom()`
`String`	`getDescription()`
`long`	`getEndTime()`
`static com.stumbleupon.async.Deferred<List<Annotation>>`	`getGlobalAnnotations(TSDB tsdb, long start_time, long end_time)` Scans through the global annotation storage rows and returns a list of parsed annotation objects.
`String`	`getNotes()`
`long`	`getStartTime()`
`String`	`getTSUID()`
`static byte`	`PREFIX()`
`void`	`setCustom(Map<String,String> custom)`
`void`	`setDescription(String description)`
`void`	`setEndTime(long end_time)`
`void`	`setNotes(String notes)`
`void`	`setStartTime(long start_time)`
`void`	`setTSUID(String tsuid)`
`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
  - Annotation
```
public Annotation()
```
    Default constructor, initializes the change map
- Method Detail
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
    
    Returns:
    A string with information about the annotation object
  - compareTo
```
public int compareTo(Annotation note)
```
    Compares the #start_time of this annotation to the given note
    
    Specified by:
    
    compareTo in interface Comparable<Annotation>
    
    Returns:
    1 if the local start time is greater, -1 if it's less or 0 if equal
  - 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 or there weren't any changes, then the data will not be written and an exception will be thrown.
    
    Parameters:
    tsdb - The TSDB to use for storage access
    overwrite - When the RPC method is PUT, will overwrite all user accessible fields 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
    
    IllegalArgumentException - if required data was missing such as the #start_time
    
    IllegalStateException - if the data hasn't changed. This is OK!
    
    JSONException - if the object could not be serialized
  - delete
```
public com.stumbleupon.async.Deferred<Object> delete(TSDB tsdb)
```
    Attempts to mark an Annotation object for deletion. Note that if the annoation does not exist in storage, this delete call will not throw an error.
    
    Parameters:
    tsdb - The TSDB to use for storage access
    
    Returns:
    A meaningless Deferred for the caller to wait on until the call is complete. The value may be null.
  - getAnnotation
```
public static com.stumbleupon.async.Deferred<Annotation> getAnnotation(TSDB tsdb,
                                                       long start_time)
```
    Attempts to fetch a global annotation from storage
    
    Parameters:
    tsdb - The TSDB to use for storage access
    start_time - The start time as a Unix epoch timestamp
    
    Returns:
    A valid annotation object if found, null if not
  - getAnnotation
```
public static com.stumbleupon.async.Deferred<Annotation> getAnnotation(TSDB tsdb,
                                                       String tsuid,
                                                       long start_time)
```
    Attempts to fetch a global or local annotation from storage
    
    Parameters:
    tsdb - The TSDB to use for storage access
    tsuid - The TSUID as a string. May be empty if retrieving a global annotation
    start_time - The start time as a Unix epoch timestamp
    
    Returns:
    A valid annotation object if found, null if not
  - getAnnotation
```
public static com.stumbleupon.async.Deferred<Annotation> getAnnotation(TSDB tsdb,
                                                       byte[] tsuid,
                                                       long start_time)
```
    Attempts to fetch a global or local annotation from storage
    
    Parameters:
    tsdb - The TSDB to use for storage access
    tsuid - The TSUID as a byte array. May be null if retrieving a global annotation
    start_time - The start time as a Unix epoch timestamp
    
    Returns:
    A valid annotation object if found, null if not
  - getGlobalAnnotations
```
public static com.stumbleupon.async.Deferred<List<Annotation>> getGlobalAnnotations(TSDB tsdb,
                                                                    long start_time,
                                                                    long end_time)
```
    Scans through the global annotation storage rows and returns a list of parsed annotation objects. If no annotations were found for the given timespan, the resulting list will be empty.
    
    Parameters:
    tsdb - The TSDB to use for storage access
    start_time - Start time to scan from. May be 0
    end_time - End time to scan to. Must be greater than 0
    
    Returns:
    A list with detected annotations. May be empty.
    
    Throws:
    
    IllegalArgumentException - if the end timestamp has not been set or the end time is less than the start time
  - PREFIX
```
public static byte PREFIX()
```
    Returns:
    The prefix byte for annotation objects
  - getTSUID
```
public final String getTSUID()
```
    Returns:
    the tsuid, may be empty if this is a global annotation
  - getStartTime
```
public final long getStartTime()
```
    Returns:
    the start_time
  - getEndTime
```
public final long getEndTime()
```
    Returns:
    the end_time, may be 0
  - getDescription
```
public final String getDescription()
```
    Returns:
    the description
  - getNotes
```
public final String getNotes()
```
    Returns:
    the notes, may be empty
  - getCustom
```
public final Map<String,String> getCustom()
```
    Returns:
    the custom key/value map, may be null
  - setTSUID
```
public void setTSUID(String tsuid)
```
    Parameters:
    tsuid - the tsuid to store
  - setStartTime
```
public void setStartTime(long start_time)
```
    Parameters:
    start_time - the start_time, required for every annotation
  - setEndTime
```
public void setEndTime(long end_time)
```
    Parameters:
    end_time - the end_time, optional
  - setDescription
```
public void setDescription(String description)
```
    Parameters:
    description - the description, required for every annotation
  - setNotes
```
public void setNotes(String notes)
```
    Parameters:
    notes - the notes to set
  - setCustom
```
public void setCustom(Map<String,String> custom)
```
    Parameters:
    custom - the custom key/value map

Class Annotation

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Annotation

Method Detail

toString

compareTo

syncToStorage

delete

getAnnotation

getAnnotation

getAnnotation

getGlobalAnnotations

PREFIX

getTSUID

getStartTime

getEndTime

getDescription

getNotes

getCustom

setTSUID

setStartTime

setEndTime

setDescription

setNotes

setCustom