org.thales.punch.libraries.punchlang.api

Interface Tuple

All Superinterfaces:

Comparable<Tuple>

All Known Implementing Classes:

AbstractTupleImpl, ByteBufTuple, DnsTuple, GeoFeatureTuple, LazyInPlaceTuple, LazyTuple, LoggerTuple, PlainTuple, StormTuple, TupleImpl

public interface Tuple
extends Comparable<Tuple>

Tuples provide punchlet with a new basic type that makes working with a json document extra easy.

Tuples can hold primitive values, referred to as a leaf, of type double, long, String or boolean. Tuples can also contains maps, array and set, of primitive values or sub-tuples. A tuple can thus be arbitrary nested.

A tuple allows you to work on json document using a compact and intuitive notation. Here is an example:

 Tuple tuple;
 tuple:[name] = "bob";
 tuple:[age] = 23;
 

Converting this tuple to a String would produce the following output

 {"age":23,"name":"bob"}
 

Tuples can be nested, contain arrays, or primitive types, just as you expect. For example:

 Tuple tuple;
 tuple:[user][name] = "bob";
 tuple:[user][age] = 23;
 tuple:[tags].append("aTag").append("anotherTag");
 

As a string, this tuple is:

    { "tags" : ["aTag", "anotherTag"], "user" : {"age":23 , "name":"bob" } }
 

Check out these examples:

• tuple.punch for basic tuple and control flow usage.
• array.punch for arrays and sets

Method Summary

Modifier and Type	Method and Description
Tuple	add(Object element) Add a tuple element into a set.
Tuple	append(Object element) Add a abject element at the end of an array.
List<Tuple>	asArray() Returns an ordered list of elements if the tuple is an array or a set.
boolean	asBoolean() Return the leaf value as a boolean.
byte[]	asBytes() Return the leaf value as a byte array.
Collection<Tuple>	asCollection() Returns a collection of elements.
double	asDouble() Return the leaf value as a double.
double[]	asDoubleArray() Easily get an array of double.
float	asFloat() Return the leaf value as a float.
GeoFeatureTuple	asGeoShape() Convert the Tuple in GeoFeatureTuple if the Tuple have the attributs : type and coordinates in content
int	asInt() Return the leaf value as an integer.
long	asLong() Return the leaf value as a long.
long[]	asLongArray() Easily get an array of long.
Set<Tuple>	asSet() Returns a set of elements.
String	asString() Return the leaf value as a String.
String	asString(String fmt, Object... values) Return the leaf value as a String.
String[]	asStringArray() Easily get an array of long.
void	attach(String key, Object value) Attach some opaque data to this tuple.
String	concat(String str) Concatenates the specified string to the end of this string.
boolean	contains(Object element) This method behaves differently depending on the tuple type.
boolean	containsOneOf(String[] strs) Check if this tuple contains a sub-string.
boolean	containsOneOf(Tuple resource) Check if this tuple contains one of several sub-string.
Tuple	cutPrefix(String s) Remove a matching prefix
Tuple	cutSuffix(String s) Remove a matching prefix
String	decodeBase64() Decode a string Tuple already in base64
String	dump() Return a String representation of this tuple.
Tuple	duplicate() Clone a tuple.
Tuple[]	elements() Returns an array of elements.
void	empty() Make a tuple empty.
String	encodeBase64() Encode a string Tuple into a base64 String
boolean	endsWith(String s) Return true if the String value of this tuple ends with a given suffix.
boolean	equalsOneOf(Tuple resource) Check if this tuple contains a sub-string.
boolean	exists()
Tuple	fromEscapedJson() This method assumes your tuple holds a string leaf value.
Tuple	get(String key) Return a sub-tuple by key.
long	get(String key, long defaultValue) Retrieve a field from a tuple, and if not there return a default.
String	get(String key, String defaultValue) Retrieve a field from a tuple, and if not there return a default.
Tuple	get(Tuple key) Return a sub-tuple by key.
Object	getAttachment(String key) Retrieve an attachment by key.
Tuple	getByKey(String key) Return a sub-tuple by key.
Tuple	getDeep(String key) Return a sub-tuple by key recursively.
Tuple	getDeepEs(String key) Return a sub-tuple by key recursively.
Tuple	getElement() This method returns a new empty array element.
Tuple	getElement(int index) Retrieve the ith item from this tuple.
List<Entry>	getEntries() Returns the list of inner property key/values.
Iterator<Object>	getIterator() This method only works on array tuples.
List<String>	getKeys() Returns the list of inner property keys.
Tuple	getSingleChild() Return the single child of this tuple.
String	getType() return a String representation of the type of the value contained in a tuple.
Collection<Tuple>	getValues() Returns the collection of inner property values.
boolean	hasKey(String key)
int	indexOf(char ch) String operation only.
int	indexOf(char ch, int fromIndex) String operation only.
int	indexOf(String str) String operation only.
int	indexOf(String str, int fromIndex) String operation only.
boolean	isArray() Return true if this tuple contains an array value
boolean	isBooleanLeaf() Check if a tuple contains a long value.
boolean	isBytesLeaf() Check if a tuple contains a Byte array value.
boolean	isDoubleLeaf() Check if a tuple contains a double value.
boolean	isEmpty() Check if a tuple contains some value.
boolean	isEquals(Object o) Check if a tuple contains a leaf value and if it is equal to a given value
boolean	isLeaf()
boolean	isLongLeaf() Check if a tuple contains a long value.
boolean	isRoot() Return true if this tuple is a root one.
boolean	isSet() Check if this tuple holds a set
boolean	isStringLeaf() Check if a tuple contains a String value.
boolean	isTuple() Return true if this tuple contains a tuple value
String	leafAsString() Return any leaf value as a String.
int	length() String API, returns the length of a String leaf Tuple.
boolean	matches(String regex) String API : Tells whether or not this string matches the given regular expression.
Tuple	merge(Tuple b) See mergeWith().
Tuple	mergeWith(Tuple b) Return a merge of two Tuples A and B recursively.
Tuple	putAll(Map<String,Object> map) Put all the provided tuple key values in this tuple.
void	remove() Remove this tuple.
Tuple	remove(String key) Return and removes a sub-tuple by key.
boolean	remove(Tuple element) Set operation: remove an element from a set.
boolean	removeElement(Object value) Remove an element from an array or set.
String	replace(char oldChar, char newChar) Returns a string resulting from replacing all occurrences of oldChar in this string with newChar.
String	replaceAll(String regex, String replacement) Replaces each substring occurence of this string that matches the given regular expression regex with the given replacement.
Tuple	replaceAllKeys(String regex, String replacement) For each inner property Tuple contained in this tuple, replaces each substring occurence of its key that matches the given regular expression with the given replacement.
Tuple	replaceAllKeyValues(String regex, String replacement) Combines replaceAllKeys(java.lang.String, java.lang.String) and replaceAllValues(java.lang.String, java.lang.String) in one call.
Tuple	replaceAllValues(String regex, String replacement) For each inner String value contained in this tuple, replaces each substring occurence that matches the given regular expression with the given replacement.
String	replaceFirst(String regex, String replacement) Replaces the first substring of this string that matches the given regular expression with the given replacement.
Tuple	select(String... keys) Given a tuple, return a selection of one or several of its child.
Tuple	set(Object v) Assign this tuple a new leaf value
Tuple	set(String key, Object v) Add an object as property to this tuple.
int	size() Return the number of fields in this tuple.
void	skip() Skip a tuple value.
String[]	split(String s) Splits this string around matches of the given regular expression.
Tuple[]	splitAsTupleArray(String s) Split this string into a Tuple array of the given regular expression.
boolean	startsWith(String s) Split a string tuple.
String	substring(int beginIndex)
String	substring(int beginIndex, int endIndex)
String	toAsciiJson() Watchout, if you use this variant, any accent will be transformed into an ascii unicode representation.
String	toEscapedJson()
String	toFlat()
String	toJson() This method preserves non ascii characters.
Tuple	toLowerCase()
Map<String,Object>	toMap() Convert a tuple to a Map.
String	toString() Return a String representation of the content of this tuple.
Tuple	toUpperCase()
String	trim() Methods inherited from plain Strings.
Boolean	tryBoolean() Try to parse the given value as Boolean.
boolean	tryBoolean(boolean b) Try to parse as Boolean or return a default value.
byte[]	tryBytes() Try to parse the given value as Byte array.
byte[]	tryBytes(byte[] b) Try to parse as Byte array or return a default value.
Double	tryDouble() Try to parse the given value as Double.
double	tryDouble(double d) Try to parse as Double or return a default value.
String	tryIp() Efficiently check for valid ip address.
String	tryIp(String defaultValue) Efficiently check for a valid ip address.
String	tryIpv4() Efficiently check for an dot decimal ipv4 ip address.
String	tryIpv4(String defaultValue) Efficiently check for an dot decimal ipv4 ip address.
String	tryIpv6() Efficiently check for an dot decimal ipv6 ip address.
String	tryIpv6(String defaultValue) Efficiently check for an dot decimal ipv6 ip address.
Long	tryLong() Try to parse the given value as Long.
long	tryLong(long l) Try to parse as Long or return default.

Methods inherited from interface java.lang.Comparable

compareTo

Method Detail

attach

void attach(String key,
            Object value)

Attach some opaque data to this tuple. You can then retrieve it using getAttachment(String). Attachments are transient data, they survive as long as the holding tuple survives. Besides, they will not appear in the toString() String representation of this tuple.

Parameters:

key - the key for retrieving the attachment later

value - the attachment value

getAttachment

Object getAttachment(String key)

Retrieve an attachment by key.

Parameters:

key - the attachment key

Returns:

the attachment or null if no attachement is defined for that key.

append

Tuple append(Object element)

Add a abject element at the end of an array. This method erases any non array content stored in the Tuple.

Parameters:

element - the element to append

Returns:

this tuple

add

Tuple add(Object element)

Add a tuple element into a set.

As expected if you add several times the same element, it will be inserted only once.

This method erases any previous value stored inside the tuple if it was not a set.

Parameters:

element - the Tuple you want to add

Returns:

this tuple

asArray

List<Tuple> asArray()

Returns an ordered list of elements if the tuple is an array or a set.

Watch out, if the tuple is a set, the order will be random.

Returns:

the list of array elements

Throws:

PunchRuntimeException - if the contained value is not an array or a set

asBytes

byte[] asBytes()

Return the leaf value as a byte array.

Returns:

the contained value as an array of bytes

Throws:

PunchRuntimeException - if the contained value is not an array of bytes

asCollection

Collection<Tuple> asCollection()

Returns a collection of elements. This assumes the tuple is an array or a set value. It is ordered only if it is an array.

Returns:

the list of array elements

Throws:

PunchRuntimeException - if the contained value is not a collection

asSet

Set<Tuple> asSet()

Returns a set of elements. This assumes the tuple is set value.

Returns:

the list of set elements

Throws:

PunchRuntimeException - if the contained value is not a set

asBoolean

boolean asBoolean()

Return the leaf value as a boolean.

Returns:

the contained value as a boolean

Throws:

PunchRuntimeException - if the contained value is not a boolean

tryBoolean

Boolean tryBoolean()

Try to parse the given value as Boolean. Return the leaf as Boolean if it succeed, return null otherwise.

Returns:

the boolean value or null

tryBoolean

boolean tryBoolean(boolean b)

Try to parse as Boolean or return a default value.

Parameters:

b - the default value

Returns:

the contained boolean or default

asDouble

double asDouble()

Return the leaf value as a double.

Returns:

the contained value as a double

Throws:

PunchRuntimeException - if the contained value is not a double

tryDouble

Double tryDouble()

Try to parse the given value as Double. Return the leaf as Double if it succeed, return null otherwise.

Returns:

the contained value as Double

tryDouble

double tryDouble(double d)

Try to parse as Double or return a default value.

Parameters:

d - a default v alue

Returns:

the contained value as double or default

asFloat

float asFloat()

Return the leaf value as a float. This is DANGEROUS, use double instead. Only use it if for some reason you must deal with floats.

Returns:

the contained value as a float

Throws:

PunchRuntimeException - if the contained value is not a float

asInt

int asInt()

Return the leaf value as an integer. This is DANGEROUS, use long instead. Only use it if for some reason you must deal with floats.

Returns:

the contained value as an integer

Throws:

PunchRuntimeException - if the contained value is not a long

asLong

long asLong()

Return the leaf value as a long.

Returns:

the contained value as a long

Throws:

PunchRuntimeException - if the contained value is not a long

tryLong

Long tryLong()

Try to parse the given value as Long. If it succeed, return the leaf as Long, otherwise return null.

Returns:

the contained value as Long

tryIpv4

String tryIpv4()

Efficiently check for an dot decimal ipv4 ip address.

This method will return a dotted numeric representation of convertible ip addresses.

 // this statement has no effect if there is no ipv4 value in
 // [message][callerIpAddress]
 [logs][log][client][ip] = [message][callerIpAddress].tryIpv4();
 

Returns:

the ip address or null is none match

tryIpv4

String tryIpv4(String defaultValue)

Efficiently check for an dot decimal ipv4 ip address.

This method will return a dotted numeric representation of convertible ip addresses.

 // this statement has no effect if there is no ipv4 value in
 // [message][callerIpAddress]
 [logs][log][client][ip] = [message][callerIpAddress].tryIpv4("0.0.0.0");
 

Parameters:

defaultValue - the default value to return

Returns:

the ip address or the default is none match

tryIpv6

String tryIpv6()

Efficiently check for an dot decimal ipv6 ip address.

This method will return a dotted numeric representation of convertible ip addresses.

 // this statement has no effect if there is no ipv4 value in
 // [message][callerIpAddress]
 [logs][log][client][ipv6] = [message][callerIpAddress].tryIpv6();
 

Returns:

the ip address or null is none match

tryIp

String tryIp(String defaultValue)

Efficiently check for a valid ip address.

This method will return a dotted numeric representation of convertible ip addresses.

 // this statement has no effect if there is no ipv4 value in
 // [message][callerIpAddress]
 [logs][log][client][ip] = [message][callerIpAddress].tryIp("0.0.0.0");
 

Parameters:

defaultValue - the default value to return

Returns:

the ip address or the default is none match

tryIp

String tryIp()

Efficiently check for valid ip address.

This method will return a dotted numeric representation of convertible ip addresses.

 // this statement has no effect if there is no ipv4 value in
 // [message][callerIpAddress]
 [logs][log][client][ip] = [message][callerIpAddress].tryIp();
 

Returns:

the ip address or null is none match

tryIpv6

String tryIpv6(String defaultValue)

Efficiently check for an dot decimal ipv6 ip address.

This method will return a dotted numeric representation of convertible ip addresses.

 // this statement has no effect if there is no ipv4 value in
 // [message][callerIpAddress]
 [logs][log][client][ipv6] = [message][callerIpAddress].tryIpv6("::0");
 

Parameters:

defaultValue - the default value to return

Returns:

the ip address or the default is none match

tryLong

long tryLong(long l)

Try to parse as Long or return default.

Parameters:

l - the default value

Returns:

the contained value as Long or default

asString

String asString()

Return the leaf value as a String. Note that this method does not attempt to transform other type into String representation. It only work on String leaf values.

Returns:

the contained value as a String

Throws:

PunchRuntimeException - if the contained value is not a String

asString

String asString(String fmt,
                Object... values)

Return the leaf value as a String. Note that this method does not attempt to transform other type into String representation. It only work on String leaf values.

The additional argument will be used to format an error message in case an exception is raised. This is handy to write log parsers that report clear errors.

Parameters:

fmt -

values -

Returns:

Throws:

PunchRuntimeException - with the provided message if the input is not a string

leafAsString

String leafAsString()

Return any leaf value as a String. This method converts the leaf value to a string. It is different from the toString method in that no quotes are returned.

Returns:

the contained value as a String

Throws:

PunchRuntimeException - if the contained value is not a String

concat

String concat(String str)

Concatenates the specified string to the end of this string.

If the length of the argument string is 0, then this String object is returned. Otherwise, a String object is returned that represents a character sequence that is the concatenation of the character sequence represented by this String object and the character sequence represented by the argument string.

Parameters:

str - the string to concatenate

Returns:

the concatenated string

contains

boolean contains(Object element)

This method behaves differently depending on the tuple type. If your tuple is a string leaf, it just behaves as a String.contains(CharSequence) call.

If your tuple is a set it behaves as a Set.contains(Object) call. Watchout this method is inneficient for large sets.

Parameters:

element - the element

Returns:

true if the element is in the set, or if your substring is in the string leaf.

Throws:

PunchRuntimeException - if the tuple is not a set or a string.

elements

Tuple[] elements()

Returns an array of elements. This works for array or set tuple.

Returns:

an array of elements as Tuple

empty

void empty()

Make a tuple empty. It only keeps its ancestor relationship.

exists

boolean exists()

Returns:

true if this tuple contains something, i.e. at least a leaf value, an array, set or a map.

get

Tuple get(String key)

Return a sub-tuple by key. If the tuple does not contain anything

Watch out, if you get a null value, it means that the Tuple does not contain what you look for OR that it contains no subtuple, i.e. a leaf value, an array or a set.

Parameters:

key - the key of the sub tuple

Returns:

the sub-tuple or null if it does not exists

getDeep

Tuple getDeep(String key)

Return a sub-tuple by key recursively. If the key value is punch-style format, then it executes Tuple.get() functions recursively.

Parameters:

key - the key of the sub-tuple. It can be plain String format "name" or punch-style format "[user][name]"

Returns:

the sub-tuple or null if it does not exists

getDeepEs

Tuple getDeepEs(String key)

Return a sub-tuple by key recursively.
This variant accepts both the punch "[user][name]" format as well as the standard elasticsearch "user.name" format.
For the rest it behaves exactly as getDeep(String)

Parameters:

key - the key of the sub tuple. Accepted forms are "name", "[user][name]" or "user.name"

Returns:

the sub-tuple or null if it does not exists

remove

Tuple remove(String key)

Return and removes a sub-tuple by key. If the tuple does not contain anything or not what you look for, you get an empty tuple.

Parameters:

key - the key of the sub tuple

Returns:

the sub-tuple or null if it does not exists

get

Tuple get(Tuple key)

Return a sub-tuple by key. If it does not exists, create it.

This variant expect the string key to be contained in a tuple. It will convert the leaf value to a string, and fail if it is not a leaf value.

Parameters:

key - the sub-tuple key

Returns:

the sub-tuple

getByKey

Tuple getByKey(String key)

Return a sub-tuple by key. This assumes the tuple is a map tuple. If it is not you will get a null answer.

Parameters:

key - the sub tuple key

Returns:

null if not there, or the requested sub tuple.

getElement

Tuple getElement(int index)

Retrieve the ith item from this tuple. This assumes this tuple contains an array.

Parameters:

index - the index of the element to retrieve

Returns:

the requested element

Throws:

PunchRuntimeException - if it is not an array, if the index is wrong

getEntries

List<Entry> getEntries()

Returns the list of inner property key/values. This assumes the tuple is a map value.

Returns:

a list of entries.

getKeys

List<String> getKeys()

Returns the list of inner property keys. This assumes the tuple is a map tuple.

Returns:

the list of keys

Throws:

PunchRuntimeException - if the tuple is not a map.

getValues

Collection<Tuple> getValues()

Returns the collection of inner property values. This requires a collection tuple.

Returns:

the list of values

Throws:

PunchRuntimeException - if the tuple is not a collection.

getIterator

Iterator<Object> getIterator()

This method only works on array tuples. It returns an iterator.

Returns:

an iterator

hasKey

boolean hasKey(String key)

Parameters:

key - the key to look for

Returns:

true if this tuple has some (direct) subtuple for the given key.

indexOf

int indexOf(char ch)

String operation only. Returns the index within this string of the first occurrence of the specified character.

Parameters:

ch - the character

Returns:

the index

indexOf

int indexOf(char ch,
            int fromIndex)

String operation only. Returns the index within this string of the first occurrence of the specified character, starting the search at the specified index.

Parameters:

ch - the character

fromIndex - the start index

Returns:

the index

indexOf

int indexOf(String str)

String operation only. Returns the index within this string of the first occurrence of the specified substring.

Parameters:

str - the substring to search for.

Returns:

the index

indexOf

int indexOf(String str,
            int fromIndex)

String operation only. Returns the index within this string of the first occurrence of the specified substring, starting at some index.

Parameters:

str - the substring to search for, starting the search at the specified index.

fromIndex - the starting index to start searching from

Returns:

the requested index

isArray

boolean isArray()

Return true if this tuple contains an array value

Returns:

true or false

isBooleanLeaf

boolean isBooleanLeaf()

Check if a tuple contains a long value.

Returns:

true or false

isDoubleLeaf

boolean isDoubleLeaf()

Check if a tuple contains a double value.

Returns:

true or false

isEmpty

boolean isEmpty()

Check if a tuple contains some value.

Returns:

true if the tuple contains a leaf, map, set or array.

isEquals

boolean isEquals(Object o)

Check if a tuple contains a leaf value and if it is equal to a given value

Parameters:

o - a java object value

Returns:

true or false

isLeaf

boolean isLeaf()

Returns:

Return true if this tuple contains a primitive value.

isLongLeaf

boolean isLongLeaf()

Check if a tuple contains a long value.

Returns:

true or false

isRoot

boolean isRoot()

Return true if this tuple is a root one. A candidate tuple is non root.

Returns:

true or false

isSet

boolean isSet()

Check if this tuple holds a set

Returns:

true or false

isStringLeaf

boolean isStringLeaf()

Check if a tuple contains a String value.

Returns:

true or false

isBytesLeaf

boolean isBytesLeaf()

Check if a tuple contains a Byte array value.

Returns:

true or false

isTuple

boolean isTuple()

Return true if this tuple contains a tuple value

Returns:

true or false

length

int length()

String API, returns the length of a String leaf Tuple. This is a shortcut for asString().length. Watch Out : this only works for String leaf tuple.

Returns:

the string leaf length.

Throws:

PunchRuntimeException - if the tuple contains something else than a String leaf.

matches

boolean matches(String regex)

String API : Tells whether or not this string matches the given regular expression.

Parameters:

regex - the regular expression to which this string is to be matched

Returns:

true if it matches

Throws:

PunchRuntimeException - if not a String leaf tuple

mergeWith

Tuple mergeWith(Tuple b)

Return a merge of two Tuples A and B recursively. It follows the following truth table:

TypesA/B	B Leaf	B Array or Set	B Map
A Leaf	B	B	B
A Array or Set	A	Fusion A&B	Exception
A Map	A	Exception	Recursive Merge on Keys

Parameters:

b - The Tuple to be merged.

Returns:

the Tuple merging both values.

Throws:

PunchRuntimeException - if a merge is not possible (Array or Set with Map).

merge

Tuple merge(Tuple b)

See mergeWith().

Parameters:

b - The Tuple to be merged.

Returns:

the Tuple merging both values.

Throws:

PunchRuntimeException - if a merge is not possible (Array or Set with Map).

remove

boolean remove(Tuple element)

Set operation: remove an element from a set.

Parameters:

element - the contained tuple to remove

Returns:

true if the element was removed. false if it was not there.

Throws:

PunchRuntimeException - if there's something else than a set

remove

void remove()

Remove this tuple. This has two effect : make this tuple empty, and remove the ancestor tree should a tree path becomes empty. Once removed you cannot use your tuple anymore

replace

String replace(char oldChar,
               char newChar)

Returns a string resulting from replacing all occurrences of oldChar in this string with newChar.

If the character oldChar does not occur in the character sequence represented by this String object, then a reference to this String object is returned. Otherwise, a String object is returned that represents a character sequence identical to the character sequence represented by this String object, except that every occurrence of oldChar is replaced by an occurrence of newChar. Examples:

        "mesquite in your cellar".replace('e', 'o')
        returns "mosquito in your collar"
  "the war of baronets".replace('r', 'y')
        returns "the way of bayonets"
  "sparring with a purple porpoise".replace('p', 't')
        returns "starring with a turtle tortoise"
  "JonL".replace('q', 'x') returns "JonL" (no change)
 

Parameters:

oldChar - the old char

newChar - the new char

Returns:

the update String

replaceAll

String replaceAll(String regex,
                  String replacement)

Replaces each substring occurence of this string that matches the given regular expression regex with the given replacement. This methods only acts on the Tuple String value. It has no effect if the Tuple contains somethng else than a String.

Check the replaceAllValues(java.lang.String, java.lang.String), replaceAllKeys(java.lang.String, java.lang.String) or replaceAllKeyValues(java.lang.String, java.lang.String) for recursive versions that do the job on all keys and?or values contained in a nested Tuple.

Parameters:

regex - the regular expression

replacement - the replacement String

Returns:

the updated String

replaceAllValues

Tuple replaceAllValues(String regex,
                       String replacement)

For each inner String value contained in this tuple, replaces each substring occurence that matches the given regular expression with the given replacement.

Parameters:

regex - the regular expression

replacement - the replacement String

Returns:

the updated String

replaceAllKeys

Tuple replaceAllKeys(String regex,
                     String replacement)

For each inner property Tuple contained in this tuple, replaces each substring occurence of its key that matches the given regular expression with the given replacement.

Parameters:

regex - the regular expression

replacement - the replacement String

Returns:

the updated String

replaceAllKeyValues

Tuple replaceAllKeyValues(String regex,
                          String replacement)

Combines replaceAllKeys(java.lang.String, java.lang.String) and replaceAllValues(java.lang.String, java.lang.String) in one call.

Parameters:

regex - the regular expression

replacement - the replacement String

Returns:

the updated String

replaceFirst

String replaceFirst(String regex,
                    String replacement)

Replaces the first substring of this string that matches the given regular expression with the given replacement.

Parameters:

regex - the regular expression

replacement - the replacement String

Returns:

the updated String

set

Tuple set(Object v)

Assign this tuple a new leaf value

Parameters:

v - the value

Returns:

a new leaf Tuple

set

Tuple set(String key,
          Object v)

Add an object as property to this tuple.

Parameters:

key - the key of your new field

v - the new field value

Returns:

the filled tuple

size

int size()

Return the number of fields in this tuple. This returns the number of element in a map, array or set tuple, 1 for a leaf tuple, and 0 if the tuple is empty.

Returns:

the size of the tuple.

substring

String substring(int beginIndex)

Parameters:

beginIndex - the substring start index

Returns:

the requested substring

Throws:

PunchRuntimeException - if not a string

substring

String substring(int beginIndex,
                 int endIndex)

Parameters:

beginIndex - the substring start index

endIndex - the substring end index

Returns:

the requested substring

Throws:

PunchRuntimeException - if not a string

toLowerCase

Tuple toLowerCase()

Returns:

the upper case String

Throws:

PunchRuntimeException - if not a string

cutPrefix

Tuple cutPrefix(String s)

Remove a matching prefix

Parameters:

s - the string value

Returns:

a new leaf Tuple

cutSuffix

Tuple cutSuffix(String s)

Remove a matching prefix

Parameters:

s - the string value

Returns:

a new leaf Tuple

startsWith

boolean startsWith(String s)

Split a string tuple.

Parameters:

s - the string value

Returns:

a new leaf Tuple

split

String[] split(String s)

Splits this string around matches of the given regular expression.

Parameters:

s - - the delimiting regular expression

Returns:

a new leaf Tuple

Throws:

PunchRuntimeException - if not a string

splitAsTupleArray

Tuple[] splitAsTupleArray(String s)

Split this string into a Tuple array of the given regular expression.

Parameters:

s - - the delimiting regular expression

Returns:

the array of leaf Tuple

Throws:

PunchRuntimeException - if not a string

endsWith

boolean endsWith(String s)

Return true if the String value of this tuple ends with a given suffix.

Parameters:

s - the String to match a suffix

Returns:

true or false

toString

String toString()

Return a String representation of the content of this tuple. If your tuple contains a leaf value (String, a long double or boolean value) you will get that value simply converted as a String. For composite object, map or array, you get a toString representation. These are not JSON representations.

Watchout : this method was originally documented as returning a JSON representation. If you need that use instead the or toAsciiJson() variants. If you are outside a punchlet, prefer the TupleFactory.getJsonFromTuple(Tuple) method and the likes.

This method is completely different than asString(). Use it to produce a Json.

Overrides:

toString in class Object

Returns:

the json-ified tuple

toJson

String toJson()

This method preserves non ascii characters.

Returns:

a valid Json representation of a tuple.

toAsciiJson

String toAsciiJson()

Watchout, if you use this variant, any accent will be transformed into an ascii unicode representation.

Returns:

valid full ascii Json representation of a tuple.

dump

String dump()

Return a String representation of this tuple.

This method is completely different than toString() in that it will not escape inner Strings. Use it to debug the tuple you work with.

Returns:

the content of the tuple

toUpperCase

Tuple toUpperCase()

Returns:

the upper case String

Throws:

PunchRuntimeException - if not a string

toMap

Map<String,Object> toMap()

Convert a tuple to a Map. This only works it the tuple contains a map, i.e. if tuple.isTuple() is true.

Returns:

the corresponding Map, or null if the tuple does not contain inner tuples.

trim

String trim()

Methods inherited from plain Strings. This only works if the tuple is a String leaf tuple.

See String.trim().

Returns:

the trimed String

Throws:

PunchRuntimeException - if not a string

get

String get(String key,
           String defaultValue)

Retrieve a field from a tuple, and if not there return a default.

Parameters:

key - the key to look for

defaultValue - a default value to return if no value is associated to the key

Returns:

the requested value

get

long get(String key,
         long defaultValue)

Retrieve a field from a tuple, and if not there return a default.

Parameters:

key - the key to look for

defaultValue - a default value to return if no value is associated to the key

Returns:

the requested value

getType

String getType()

return a String representation of the type of the value contained in a tuple. This methods returns one of "String", "bool", "array", "set", "long", "double", "bytes", "tuple" or "empty".

Returns:

a type description.

containsOneOf

boolean containsOneOf(String[] strs)

Check if this tuple contains a sub-string. You can pass one or several substring as argument. This method simply iterates to check if one of the substring you need is in there. If you have a large list, prefer the variant using a resource tuple which internally relies on a PatriciaTree.

Here is a typical usage :

 
        if (tuple.containsOneOf("CNN", "FOX", "TF1")) {
                ...
    }
 
 

Should you need to ignore the case :

 
        if (tuple.toLowerCase().containsOneOf("cnn", "fox", "tf1")) {
                ...
    }
 
 

Parameters:

strs - the list of String to check for

Returns:

true if one of the string is in there

containsOneOf

boolean containsOneOf(Tuple resource)

Check if this tuple contains one of several sub-string. This variant takes in a resource tuple, and creates an aho-corasick index. It is created only the first time you call this method, subsequent calls will benefit from the ready to be used index.

Please note that this tuple must be a Leaf tuple, more precisely of type String for this to work. Otherwise, you will get false.

Use this variant only if your set of substrings does never change. It is the most efficient in particular if you have many sub-strings to check for.

An example will best illustrate how it works. Say you have a domain name in a tuple field, [host][name] that contains for example "www.mydomain-prod.com". Suppose you want to know if that domain name contains one of the following substring

 
        [ "prod", "admin" ]
 
 

Put your substring in a resource file (say) my-patterns.json. You can then simply write :

 
  Tuple tuple = [host][name]
    ...
        if (tuple.containsOneOf(getResourceTuple("my-patterns"))) {
                ...
    }
 
 

Parameters:

resource - your resource tuple, containing your string atoms

Returns:

true if your String leaf value contains one of the substring defined in the resource tuple.

equalsOneOf

boolean equalsOneOf(Tuple resource)

Check if this tuple contains a sub-string. This variant takes in a resource tuple, and creates an PatriciaTrie index. It is created only the first time you call this method, subsequent calls will benefit from the ready to be used index. Use this variant in production if the set of substrings you need is always the same. It is the most efficient in particular if you have many sub-strings to check for.

An example will best illustrate how it works. Say you have a domain name in a tuple field, [host][name] that contains for example "www.mydomain-prod.com". Suppose you want to know if that domain name contains one of the following substring

 
    { "prod", "admin" }
 
 

Put your substring in a resource file (say) my-patterns.json. You can then simply write :

 
        if (tuple.equalsOneOf(getResourceTuple("my-patterns"))) {
                ...
    }
 
 

Parameters:

resource - your resource tuple, containing your string atoms

Returns:

true if your String leaf value matches one of the String defined in the resource tuple.

getElement

Tuple getElement()

This method returns a new empty array element.

Returns:

an empty array element

removeElement

boolean removeElement(Object value)

Remove an element from an array or set.

Parameters:

value - the value to remove

Returns:

true only if the element was in the array or set.

getSingleChild

Tuple getSingleChild()

Return the single child of this tuple. This method only succeeds if this tuple contain a single sub-tuple.

It is handy to deal with a very common punchplatform use case : receiving logs as single stream/field value. If you know that by configuration you can only receive a root tuple from a Storm PunchBolt as a single valued [streamId][fieldId] tuple, then you can simply write :

 
        tuple = root.getSingleChild().getSingleChild();
 
 

Returns:

the single child tuple.

Throws:

PunchRuntimeException - if the tuple does not contain a single sub tuple value or one named "default"

duplicate

Tuple duplicate()

Clone a tuple. This will return to you a deep copy of your tuple. Remember by default tuple operations are performed by reference.

Returns:

a new tuple

encodeBase64

String encodeBase64()

Encode a string Tuple into a base64 String

Usage examples: String encoded = [a].encodeBase64(); [b] = [a].encodeBase64();

Returns:

base64 string

decodeBase64

String decodeBase64()

Decode a string Tuple already in base64

Usage example: String decoded = [a].decodeBase64(); [b] = [a].decodeBase64();

Returns:

decoded string

select

Tuple select(String... keys)

Given a tuple, return a selection of one or several of its child. For example :

 
 // say input is a metricbeat  document with tons of fields including a "metricset" part
 // Executing this
 Tuple t = input.select("metricset");

 // produces a tuple t containing only "metricset", i.e. :
 //   "metricset" : {
 //     "module": "system",
 //     "name": "load",
 //     "rtt": 29
 //   }
 }
 
 

Parameters:

keys - the key(s) you want to select

Returns:

the selected tuple(s)

toFlat

String toFlat()

Returns:

a key value flatten representation of your tuple

toEscapedJson

String toEscapedJson()

Returns:

an RFC 4627 compliant escaped representation of this tuple

fromEscapedJson

Tuple fromEscapedJson()

This method assumes your tuple holds a string leaf value.

Returns:

a tuple from a RFC 4627 compliant escaped json string.

Throws:

PunchRuntimeException - if the contained value is not a string

skip

void skip()

Skip a tuple value. This makes an inner field be removed and its content rattached to its father.

 
    // root : { "a" : { "b" : { "c" : 3 } } }
    root:[a].skip();
    // you have root == { "b" : { "c" : 3 } }
 
 

asDoubleArray

double[] asDoubleArray()

Easily get an array of double. It works as long as the inner value(s) can be transformed into double.

Longs are converted to doubles, String also as long as they represent a valid double number.

If your tuple contains a single value an array of size 1 will be returned.

Returns:

an array of double

asLongArray

long[] asLongArray()

Easily get an array of long. It works as long as the inner value(s) can be transformed into double.

Longs are converted to doubles, String also as long as they represent a valid double number.

If your tuple contains a single value an array of size 1 will be returned.

Returns:

an array of double

asStringArray

String[] asStringArray()

Easily get an array of long. It works as long as the inner value(s) can be transformed into double.

Longs are converted to doubles, String also as long as they represent a valid double number.

If your tuple contains a single value an array of size 1 will be returned.

Returns:

an array of double

asGeoShape

GeoFeatureTuple asGeoShape()

Convert the Tuple in GeoFeatureTuple if the Tuple have the attributs : type and coordinates in content

Returns:

GeoFeatureTuple

tryBytes

byte[] tryBytes()

Try to parse the given value as Byte array. Return the leaf as Byte array if it succeed, return null otherwise.

Returns:

the Byte[] value or null

tryBytes

byte[] tryBytes(byte[] b)

Try to parse as Byte array or return a default value.

Parameters:

b - the default value

Returns:

the contained Byte[] or default

putAll

Tuple putAll(Map<String,Object> map)

Put all the provided tuple key values in this tuple. This will transform your tuple into a map if not already one.

Parameters:

map -

Returns:

this tuple