net.opentsdb.tree

Class TreeRule

java.lang.Object

net.opentsdb.tree.TreeRule

public final class TreeRule
extends Object

Represents single rule in a set of rules for a given tree. Each rule is uniquely identified by:

• tree_id - The ID of the tree to which the rule belongs
• level - Outer processing order where the rule resides. Lower values are processed first. Starts at 0.
• order - Inner processing order within a given level. Lower values are processed first. Starts at 0.

Each rule is stored as an individual column so that they can be modified individually. RPC calls can also bulk replace rule sets.

Since:

2.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TreeRule.TreeRuleType Types of tree rules

Constructor Summary

Constructors

Constructor and Description
TreeRule() Default constructor necessary for de/serialization
TreeRule(int tree_id) Constructor initializes the tree ID
TreeRule(TreeRule original) Copy constructor that creates a completely independent copy of the original object

Method Summary

Methods

Modifier and Type	Method and Description
boolean	copyChanges(TreeRule rule, boolean overwrite) Copies changed fields from the incoming rule to the local rule
static com.stumbleupon.async.Deferred<Object>	deleteAllRules(TSDB tsdb, int tree_id) Attempts to delete all rules belonging to the given tree.
static com.stumbleupon.async.Deferred<Object>	deleteRule(TSDB tsdb, int tree_id, int level, int order) Attempts to delete the specified rule from storage
static com.stumbleupon.async.Deferred<TreeRule>	fetchRule(TSDB tsdb, int tree_id, int level, int order) Attempts to retrieve the specified tree rule from storage.
Pattern	getCompiledRegex()
String	getCustomField()
String	getDescription()
String	getDisplayFormat()
String	getField()
int	getLevel()
String	getNotes()
int	getOrder()
static byte[]	getQualifier(int level, int order) Completes the column qualifier given a level and order using the configured prefix
String	getRegex()
int	getRegexGroupIdx()
String	getSeparator()
int	getTreeId()
TreeRule.TreeRuleType	getType()
static TreeRule	parseFromStorage(org.hbase.async.KeyValue column) Parses a rule from the given column.
static byte[]	RULE_PREFIX()
void	setCustomField(String custom_field)
void	setDescription(String description)
void	setDisplayFormat(String display_format)
void	setField(String field)
void	setLevel(int level)
void	setNotes(String notes)
void	setOrder(int order)
void	setRegex(String regex)
void	setRegexGroupIdx(int regex_group_idx)
void	setSeparator(String separator)
void	setTreeId(int tree_id)
void	setType(TreeRule.TreeRuleType type)
static TreeRule.TreeRuleType	stringToType(String type) Parses a string into a rule type enumerator
com.stumbleupon.async.Deferred<Boolean>	syncToStorage(TSDB tsdb, boolean overwrite) Attempts to write the rule to storage via CompareAndSet, merging changes with an existing rule.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

TreeRule

public TreeRule()

Default constructor necessary for de/serialization

TreeRule

public TreeRule(int tree_id)

Constructor initializes the tree ID

Parameters:

tree_id - The tree this rule belongs to

TreeRule

public TreeRule(TreeRule original)

Copy constructor that creates a completely independent copy of the original object

Parameters:

original - The original object to copy from

Throws:

PatternSyntaxException - if the regex is invalid

Method Detail

copyChanges

public boolean copyChanges(TreeRule rule,
                  boolean overwrite)

Copies changed fields from the incoming rule to the local rule

Parameters:

rule - The rule to copy from

overwrite - Whether or not to replace all fields in the local object

Returns:

True if there were changes, false if everything was identical

toString

public String toString()

Overrides:

toString in class Object

Returns:

the rule ID as [tree_id:level:order]

syncToStorage

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

Attempts to write the rule to storage via CompareAndSet, merging changes with an existing rule. 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. Note: This method also validates the rule, making sure that proper combinations of data exist before writing to storage.

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 CAS call succeeded, false if the stored data was modified in flight. This should be retried if that happens.

Throws:

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

IllegalArgumentException - if parsing failed or the tree ID was invalid or validation failed

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

JSONException - if the object could not be serialized

parseFromStorage

public static TreeRule parseFromStorage(org.hbase.async.KeyValue column)

Parses a rule from the given column. Used by the Tree class when scanning a row for rules.

Parameters:

column - The column to parse

Returns:

A valid TreeRule object if parsed successfully

Throws:

IllegalArgumentException - if the column was empty

JSONException - if the object could not be serialized

fetchRule

public static com.stumbleupon.async.Deferred<TreeRule> fetchRule(TSDB tsdb,
                                                 int tree_id,
                                                 int level,
                                                 int order)

Attempts to retrieve the specified tree rule from storage.

Parameters:

tsdb - The TSDB to use for storage access

tree_id - ID of the tree the rule belongs to

level - Level where the rule resides

order - Order where the rule resides

Returns:

A TreeRule object if found, null if it does not exist

Throws:

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

IllegalArgumentException - if the one of the required parameters was missing

JSONException - if the object could not be serialized

deleteRule

public static com.stumbleupon.async.Deferred<Object> deleteRule(TSDB tsdb,
                                                int tree_id,
                                                int level,
                                                int order)

Attempts to delete the specified rule from storage

Parameters:

tsdb - The TSDB to use for storage access

tree_id - ID of the tree the rule belongs to

level - Level where the rule resides

order - Order where the rule resides

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 the one of the required parameters was missing

deleteAllRules

public static com.stumbleupon.async.Deferred<Object> deleteAllRules(TSDB tsdb,
                                                    int tree_id)

Attempts to delete all rules belonging to the given tree.

Parameters:

tsdb - The TSDB to use for storage access

tree_id - ID of the tree the rules belongs to

Returns:

A deferred to wait on for completion. The value has no meaning and may be null.

Throws:

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

IllegalArgumentException - if the one of the required parameters was missing

stringToType

public static TreeRule.TreeRuleType stringToType(String type)

Parses a string into a rule type enumerator

Parameters:

type - The string to parse

Returns:

The type enumerator

Throws:

IllegalArgumentException - if the type was empty or invalid

RULE_PREFIX

public static byte[] RULE_PREFIX()

Returns:

The configured rule column prefix

getQualifier

public static byte[] getQualifier(int level,
                  int order)

Completes the column qualifier given a level and order using the configured prefix

Parameters:

level - The level of the rule

order - The order of the rule

Returns:

A byte array with the column qualifier

getType

public TreeRule.TreeRuleType getType()

Returns:

the type of rule

getField

public String getField()

Returns:

the name of the field to match on

getCustomField

public String getCustomField()

Returns:

the custom_field if matching

getRegex

public String getRegex()

Returns:

the user supplied, uncompiled regex

getSeparator

public String getSeparator()

Returns:

an optional separator

getDescription

public String getDescription()

Returns:

the description of the rule

getNotes

public String getNotes()

Returns:

the notes

getRegexGroupIdx

public int getRegexGroupIdx()

Returns:

the regex_group_idx if using regex group extraction

getDisplayFormat

public String getDisplayFormat()

Returns:

the display_format

getLevel

public int getLevel()

Returns:

the level where the rule resides

getOrder

public int getOrder()

Returns:

the order of rule processing within a level

getTreeId

public int getTreeId()

Returns:

the tree_id

getCompiledRegex

public Pattern getCompiledRegex()

Returns:

the compiled_regex

setType

public void setType(TreeRule.TreeRuleType type)

Parameters:

type - The type of rule

setField

public void setField(String field)

Parameters:

field - The field name for matching

setCustomField

public void setCustomField(String custom_field)

Parameters:

custom_field - The custom field name to set if matching

setRegex

public void setRegex(String regex)

Parameters:

regex - Stores AND compiles the regex string for use in processing

Throws:

PatternSyntaxException - if the regex is invalid

setSeparator

public void setSeparator(String separator)

Parameters:

separator - A character or string to separate on

setDescription

public void setDescription(String description)

Parameters:

description - A brief description of the rule

setNotes

public void setNotes(String notes)

Parameters:

notes - Optional detailed notes about the rule

setRegexGroupIdx

public void setRegexGroupIdx(int regex_group_idx)

Parameters:

regex_group_idx - An optional index (start at 0) to use for regex group extraction. Must be a positive value.

setDisplayFormat

public void setDisplayFormat(String display_format)

Parameters:

display_format - Optional format string to alter the display name

setLevel

public void setLevel(int level)

Parameters:

level - The top level processing order. Must be 0 or greater

Throws:

IllegalArgumentException - if the level was negative

setOrder

public void setOrder(int order)

Parameters:

order - The order of processing within a level. Must be 0 or greater

Throws:

IllegalArgumentException - if the order was negative

setTreeId

public void setTreeId(int tree_id)

Parameters:

tree_id - The tree_id to set