<Default Package>
Type any
Special type that can hold a value of any other EPL type.
This is useful for mapping to generic data formats such as JSON, or where the data in an event or being processedby an action may be one of a number of different types.
An any is either empty (similar to the concept of null in other languages) or contains a single value which is of some other type.
All types other than the any type are referred to as concrete types. A concrete type value may be assigned to an any type variable, passed to an action or method that takes an any type, or returned from an action that includes a returns any clause. No casting is required. An empty any value can be specified using new any. For example: any a; // empty, holds no value
a := 1234; // holds an integer value
a := new any; // empty, holds no value
EPL supports casting of the any type to a concrete target type, for example: any a;
integer i := <integer> a;
If the any is empty or an incorrect type, the cast will throw an exception, except for casts to optional which never fail: any a;
optional<integer> i := < optional<integer> > a;
In this case, if the any is empty, or a type other than integer or optional<integer>, the cast will return an empty optional.
The switch statement is the preferred way of handling any values when the type is known or not important. The switch statement looks like this: any a;
switch (a as myvalue)
{
case float: { / * myvalue can be accessed as a float here * / }
case integer: { / * myvalue can be accessed as an integer here * / }
default: { / * other type or empty * / }
}
There is no case fall-through. If you do not provide a default clause, an exception will be thrown if the any does not match any case. an in the switch can be any expression returning any. If it is a simple identifier, then the as clause can be omitted and the identifier will be available cast to the appropriate type within the case block.
any values can be compared, provided that the values' types can be compared. Values of different types are never equal and will sort according to the type's full name, with empty values sorting before any non-empty values.
Note that while primitive types (integer, float, boolean and decimal) can be used freely with the any type, using primitive values in an any object is more expensive than using just primitives. The values are automatically wrapped in an object ("boxed") which has a single field called "value" and unwrapped when converted back to primitive values. This all happens automatically, but there is a higher runtime cost for primitives in an any variable than in normal primitive variables.
-
Since:
- 10.1
canParse
boolean static canParse(string s)
Check if the string argument can be parsed as an any.
-
Parameters:
-
s - The string to test for parseability.
-
Returns:
- True if the string could be parsed as an any, false otherwise.
-
See Also:
-
any#parse() - See the parse method for what is parseable.
clone
any clone()
Create a deep copy of the value contained within this any.
-
Returns:
- A deep copy of this object.
empty
boolean empty()
Check whether this any contains a value or object.
-
Returns:
- True if no value or object contained, False if otherwise
-
Since:
- 10.3
getAction
any getAction(string actionName)
Get the action or method by name.
-
Parameters:
-
actionName - Name of the action.
-
Returns:
- The action corresponding to the actionName.
-
Throws:
- Throws IllegalArgumentException if actionName is not found.
-
Since:
- 10.1.0.4
getActionNames
sequence<string> getActionNames()
Get the names of the actions or methods within this any.
For events, returns the name of all actions, in declaration order.
-
Returns:
- A sequence containing the string name of the actions this any contains.
-
Since:
- 10.1.0.4
getActionParameterNames
sequence<string> getActionParameterNames()
Get the parameter names of the action contained in this any.
-
Returns:
- A sequence containing the string parameter names, in the order of the signature of the action this any contains.
-
Throws:
- Throws IllegalArgumentException if not called on action type.
-
Since:
- 10.1.0.4
getActionParameters
dictionary<string, string> getActionParameters()
Get a dictionary whose keys are the parameter names of the action contained in this any, and whose values are the types of each parameter.
-
Returns:
- A dictionary containing parameter name and its type of the action this any contains.
-
Throws:
- Throws IllegalArgumentException if not called on action type.
-
Since:
- 10.1.0.4
getActionParameterTypeNames
sequence<string> getActionParameterTypeNames()
Get the parameter types of the action contained in this any.
-
Returns:
- A sequence containing the string type names, in the order of the signature of the action this any contains.
-
Throws:
- Throws IllegalArgumentException if not called on action type.
-
Since:
- 10.3.1.0
getActionReturnTypeName
string getActionReturnTypeName()
Get the name of the return type of the action contained in this any.
If an action does not return anything then an empty string is returned.
-
Returns:
- The string form of the return type name of the action this any contains.
-
Throws:
- Throws IllegalArgumentException if not called on action type.
-
Since:
- 10.1.0.4
getConstant
any getConstant(string constantName)
Get the value of a constant by name.
-
Parameters:
-
constantName - Name of the constant.
-
Returns:
- The value of the constant corresponding to the constantName.
-
Throws:
- Throws IllegalArgumentException if constantName is not found.
-
Since:
- 10.1.0.4
getConstantNames
sequence<string> getConstantNames()
Get the names of the constants within this any.
For events, returns the name of all constants, in declaration order.
-
Returns:
- A sequence containing the string name of the constants this any contains.
-
Since:
- 10.1.0.4
getEntries
sequence<any> getEntries()
Get all the entries within the contained object.
For primitives or strings, just returns the same object as a sequence of length 1. For sequences, returns the contents of the sequence. For dictionaries, returns the values in the dictionary, in an arbitrary order. For events, returns the value of all of the event fields, in declaration order.
The order that entries are returned from getKeys, getEntries and getTypes is the same for a given object, but may not be defined across objects.
-
Returns:
- A sequence containing all the entries in the type this any contains.
-
See Also:
-
any#getKeys() - Get the keys for these entries in the same order.
-
any#getTypes() - Get the types for these entries in the same order.
getEntry
any getEntry(any key)
Get the entry corresponding to this key within the contained object.
Primitives have a single entry with the key "value". Sequence keys are integers corresponding to the index in the sequence, starting from 0. Event keys are the names of the fields of the event. Dictionary keys map directly to entry keys.
-
Parameters:
-
key - The key to look up.
-
Returns:
- The value of the entry corresponding to the key.
-
Throws:
- Throws IllegalArgumentException if the key is not found.
getField
any getField(string fieldName)
Get the value of a field by name.
-
Parameters:
-
fieldName
-
Returns:
- Returns the same as getEntry.
-
Throws:
- Throws IllegalArgumentException if fieldName is not found.
-
See Also:
-
any#getEntry() - See getEntry() for details.
getFieldNames
sequence<string> getFieldNames()
Get the names of the fields within this any.
-
Returns:
- Returns the same as getKeys() but with the contents converted to a string.
-
See Also:
-
any#getKeys() - See getKeys() for details.
getFields
sequence<any> getFields()
Get the values of the fields within this any.
-
Returns:
- Returns the same as getEntries().
-
See Also:
-
any#getEntries() - See getEntries() for details.
getFieldString
string getFieldString(string fieldName)
Get the value of a field by name.
-
Parameters:
-
fieldName
-
Returns:
- Returns the same as getEntry but with the value converted to a string.
-
Throws:
- Throws IllegalArgumentException if fieldName is not found.
-
See Also:
-
any#getEntry() - see getEntry() for details.
getFieldTypes
sequence<string> getFieldTypes()
Get the names of the types of the fields within this any.
-
Returns:
- Returns the same as getTypes().
-
See Also:
-
any#getTypes() - See getTypes() for details.
getFieldValues
sequence<string> getFieldValues()
Get the values of the fields within this any.
-
Returns:
- Returns the same as getEntries() but with the contents converted to a string.
-
See Also:
-
any#getEntries() - See getEntries() for details.
getGenericAction
action<sequence<any>> returns any getGenericAction()
Get the generic form of the action.
A generic form allows calling the action via the getGenericAction even if the signature type is not known at compile time. The sequence must be of the same size as the number of arguments to the action. If the action returns a value, then that is wrapped in an any else the action returns an empty any.
-
Returns:
- The signature of the action contained within this any.
-
Throws:
- Throws IllegalArgumentException if not called on action type.
-
Since:
- 10.1.0.4
getKeys
sequence<any> getKeys()
Get the keys for the entries within the contained object.
Primitives have a single key "value". Sequence keys are integers corresponding to the index in the sequence, starting with 0. Dictionary keys map directly to entry keys and are returned in an arbitrary order. Event keys are the names of the fields of the event, in declaration order.
The order in which entries are returned from getKeys, getEntries and getTypes is the same for a given object, but may not be defined across objects.
-
Returns:
- A sequence containing all the keys in the type this any contains.
-
See Also:
-
any#getKeys() - Get the keys for these entries in the same order.
-
any#getTypes() - Get the types for these entries in the same order.
getTypeName
string getTypeName()
Get the name of the type contained in this any.
If this any is empty, "empty" is returned.
-
Returns:
- The string form of the name of the type this any contains.
getTypes
sequence<string> getTypes()
Get the names of the types for the entries within the contained object.
Primitives have a single entry type corresponding to their type. Sequences and dictionaries have value types according to their type parameter. Event entry types correspond to the types of the members of the event, in declaration order.
The order in which entries are returned from getKeys, getEntries and getTypes is the same for a given object, but may not be defined across objects.
-
Returns:
- A sequence containing the string name of the types of the keys of the type this any contains.
-
See Also:
-
any#getKeys() - Get the keys for these entries in the same order.
-
any#getEntries() - Get the values for these entries in the same order.
hasAction
boolean hasAction(string actionName)
Check whether an actionName exists within the contained object.
-
Parameters:
-
actionName
-
Returns:
- True if actionName exists, false otherwise.
-
Since:
- 10.3
hasEntry
boolean hasEntry(any key)
Check whether a key exists within the contained object.
-
Parameters:
-
key
-
Returns:
- True if key exists, false otherwise.
-
Since:
- 10.3
hasField
boolean hasField(string fieldName)
Check whether a fieldName exists within the contained object.
-
Parameters:
-
fieldName
-
Returns:
- True if fieldName exists, false otherwise.
-
Since:
- 10.3
hash
integer hash()
Get an integer hash representation of the underlying object.
This function will return an integer evenly distributed over the whole range suitable for partitioning or indexing of that structure. Multiple different object can resolve to the same hash value.
Trying to call hash on an any which contains a non-hashable type will throw. Empty anys may be hashed.
-
Returns:
- An integer respresentation of the underlying object.
-
Throws:
- Throws IllegalArgumentException if the contained object is not hashable.
newInstance
any static newInstance(string typeName)
Create a new, default-initialized, instance of the given type name.
Note: This cannot instantiate a type which has not yet been seen by the correlator. Container types, such as sequences, will only be created when referenced in EPL. This must have happened for any required types before calling this method.
-
Parameters:
-
typeName - The fully-qualified name of the type to instantiate.
-
Returns:
- A new, default-initialized, instance of typeName.
-
Throws:
- Throws IllegalArgumentException if the type is not found.
parse
any static parse(string s)
Parse a string to an any.
This will parse a string of the form any(TYPE, VALUE).
TYPE is the name of a type. VALUE is a representation of the value that could be parsed by TYPE.parse(), surrounded by quotes if it is a string. For example any(string,"my value"), any(integer, 5).
See the documentation on the individual type parse methods for what is legal.
Note: This cannot parse a type which has not yet been seen by the correlator. Container types, such as sequences, will only be created when referenced in EPL. This must have happened for any required types before calling this method.
-
Parameters:
-
s - The string to parse.
-
Returns:
- The any parsed from the string.
-
Throws:
- Throws ParseException if the string cannot be parsed as an any.
parseType
any static parseType(string typeName, string stringForm)
Parse a string as a given type (by name).
This will parse a string into the type given by typeName. For the details of what is valid in stringForm, see the parse method on the individual type specified.
Note: This cannot parse a type which has not yet been seen by the correlator. Container types, such as sequences, will only be created when referenced in EPL. This must have happened for any required types before calling this method.
-
Parameters:
-
typeName - The type to try and parse the string as.
-
stringForm - A string which can be parsed as typeName.
-
Returns:
- An any containing an instance of typeName parsed from stringForm.
-
Throws:
- Throws IllegalArgumentException if typeName does not exist, or ParseException if stringForm cannot be parsed as a typeName.
setEntry
void setEntry(any key, any value)
Set the entry in the contained type corresponding to a named key.
Primitives have a single entry with the key "value". Sequence keys are integers corresponding to the index in the sequence, starting from 0. Event keys are the names of the fields of the event. Dictionary keys map directly to entry keys.
This method will not attempt to convert the value to the correct type.
If the content is a dictionary, this method can add a new key to the dictionary.
-
Parameters:
-
key - The key of the entry to set.
-
value - The value to set the entry to.
-
Throws:
- Throws IllegalArgumentException if the key does not exist (except dictionaries) or the value is of the wrong type.
setField
void setField(string fieldName, any value)
Set the value of a field by name.
-
Parameters:
-
fieldName
-
value
-
Throws:
- Throws IllegalArgumentException if fieldName is not found.
-
See Also:
-
any#setEntry() - See setEntry() for details.
toString
string toString()
Convert this any to a string.
The string form is the word "any", followed by parentheses. If the any has a value, then the full name of the type of the value follows, then a comma, and then the value surrounded by quotes if the type is string, for example any(string,"my value"), any(integer,5). Any empty any is represented by any().
valueToString
string valueToString()
Convert the contents of this any to a string.
-
Returns:
- The result of calling .toString() on the contained value, or "empty" if this any is empty.