any

<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 processed by 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

Action summary
`boolean`	`static` `canParse(string s)` Check if the string argument can be parsed as an `any`.
`any`	`static` `newInstance(string typeName)` Create a new, default-initialized, instance of the given type name.
`any`	`static` `parse(string s)` Parse a string to an `any`.
`any`	`static` `parseType(string typeName, string stringForm)` Parse a string as a given type (by name).
`any`	`clone()` Create a deep copy of the value contained within this `any`.
`boolean`	`empty()` Check whether this `any` contains a value or object (this is a legacy alias for the `isEmpty()` method).
`any`	`getAction(string actionName)` Get the action or method by name.
`sequence<string>`	`getActionNames()` Get the names of the actions or methods within this `any`.
`sequence<string>`	`getActionParameterNames()` Get the parameter names of the action contained in this `any`.
`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.
`sequence<string>`	`getActionParameterTypeNames()` Get the parameter types of the action contained in this `any`.
`string`	`getActionReturnTypeName()` Get the name of the return type of the action contained in this `any`.
`any`	`getConstant(string constantName)` Get the value of a constant by name.
`sequence<string>`	`getConstantNames()` Get the names of the constants within this `any`.
`string`	`getDeclaredElementType()` If the object contained in this `any` is a sequence or dictionary type, get the name of the type of values contained within this object.
`string`	`getDeclaredKeyType()` If the object contained in this `any` is a dictionary type, then return the name of the key type of this dictionary.
`sequence<any>`	`getEntries()` Get all the entries within the contained object.
`any`	`getEntry(any key)` Get the entry corresponding to this key within the contained object.
`any`	`getField(string fieldName)` Get the value of a field by name.
`sequence<string>`	`getFieldNames()` Get the names of the fields within this `any`.
`sequence<any>`	`getFields()` Get the values of the fields within this `any`.
`string`	`getFieldString(string fieldName)` Get the value of a field by name.
`sequence<string>`	`getFieldTypes()` Get the names of the types of the fields within this `any`.
`sequence<string>`	`getFieldValues()` Get the values of the fields within this `any`.
`action<sequence<any>> returns any`	`getGenericAction()` Get the `generic` form of the action.
`dictionary<any, any>`	`getGenericDictionary()` Returns the contained object as a `dictionary<any, any>`.
`sequence<any>`	`getKeys()` Get the keys for the entries within the contained object.
`string`	`getTypeName()` Get the name of the type contained in this `any`.
`sequence<string>`	`getTypes()` Get the names of the types for the entries within the contained object.
`boolean`	`hasAction(string actionName)` Check whether an actionName exists within the contained object.
`boolean`	`hasEntry(any key)` Check whether a key exists within the contained object.
`boolean`	`hasField(string fieldName)` Check whether a fieldName exists within the contained object.
`integer`	`hash()` Get an integer hash representation of the underlying object.
`boolean`	`isDictionary()` Checks whether the object contained in this `any` is a dictionary.
`boolean`	`isEmpty()` Check whether this `any` contains a value or object.
`boolean`	`isEvent()` Checks whether the object contained in this `any` is an event.
`boolean`	`isSequence()` Checks whether the object contained in this `any` is a sequence.
`void`	`setEntry(any key, any value)` Set the entry in the contained type corresponding to a named key.
`void`	`setField(string fieldName, any value)` Set the value of a field by name.
`string`	`toString()` Convert this `any` to a string.
`string`	`valueToString()` Convert the contents of this `any` to a string.

Action detail

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:: - See the parse method for what is parseable.

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.

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 (this is a legacy alias for the isEmpty() method).

Returns:: True if no value or object contained directly in this any, False if something is contained (even if the contained object is itself an empty string, sequence, optional etc).

Since:: 10.3

See Also:: com.apama.functional.Fn.isEmpty() - To perform a deep detection for whether an any contains a value that itself is not empty.; - The recommended way to call this.

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

getDeclaredElementType

string getDeclaredElementType()

If the object contained in this any is a sequence or dictionary type, get the name of the type of values contained within this object.

For sequences, this returns the name of the type of the entries contained in the sequence. For example, if this any contains a sequence<integer> then this action will return "integer". If this any contains a sequence<any>, then this action will return "any".

For dictionaries, this returns the type name of the values contained in the dictionary. For example, if this any contains a dictionary<integer, string> then this action will return "string".

Returns:: The name of the type of values contained within this object in string form.

Throws:: Throws IllegalArgumentException if the object is not a sequence or dictionary.

Since:: 10.7.2

See Also:: - to get the name of the key type if the object contained in this any is a dictionary.

getDeclaredKeyType

string getDeclaredKeyType()

If the object contained in this any is a dictionary type, then return the name of the key type of this dictionary.

For example, if the object contained in this any is a dictionary<integer, any> then this action will return "integer". If the object contained in this any is a dictionary<any, string> then this will return "any".

Returns:: The string form of the name of the key type of the dictionary contained in this any.

Throws:: Throws IllegalArgumentException if the object is not a dictionary.

Since:: 10.7.2

See Also:: - to get the name of the type of values contained in this dictionary.

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 values of all of the event fields, in declaration order. For locations and other event-like built-ins, returns the values of all the object's fields. For other built-in types, returns either an empty sequence or a type-specific value.

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:: - Get the keys for these entries in the same order.; - 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, including strings, have a single entry with the key "value". Sequence keys are integers corresponding to the index in the sequence, starting from 0 (negative indexes are not permitted). 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:: - 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:: - 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:: - 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:: - 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:: - 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:: - 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

getGenericDictionary

dictionary<any, any> getGenericDictionary()

Returns the contained object as a dictionary<any, any>.

The keys of the returned dictionary are equivalent to the set of objects returned by getKeys() and the values of the dictionary are equivalent to the set of objects returned by getEntries().

Returns:: The contained object as a dictionary<any, any>.

Since:: 10.7.2

See Also:: - To see what the keys are for each of the possible objects contained in this any.; - To see what the values are for each of the possible objects contained in this any.

getKeys

sequence<any> getKeys()

Get the keys for the entries within the contained object.

Primitives, including strings, 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. For locations and other event-like built-ins, returns the names of the object's fields. For other built-in types, returns either an empty sequence or a type-specific value.

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:: - Get the keys for these entries in the same order.; - 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 or strings 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. For other event-like built-ins, returns the types of the fields of the object. For other built-in types, returns either an empty sequence or a type-specific value.

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:: - Get the keys for these entries in the same order.; - 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.

isDictionary

boolean isDictionary()

Checks whether the object contained in this any is a dictionary.

Returns:: True if the object contained in this any is a dictionary, false otherwise.

Since:: 10.7.2

isEmpty

boolean isEmpty()

Check whether this any contains a value or object.

Returns:: True if no value or object contained directly in this any, False if something is contained (even if the contained object is itself an empty string, sequence, optional etc).

Since:: 10.15.4.0

See Also:: com.apama.functional.Fn.isEmpty() - To perform a deep detection for whether an any contains a value that itself is not empty.

isEvent

boolean isEvent()

Checks whether the object contained in this any is an event.

Returns:: True if the object contained in this any is an event, false otherwise.

Since:: 10.7.2

isSequence

boolean isSequence()

Checks whether the object contained in this any is a sequence.

Returns:: True if the object contained in this any is a sequence, false otherwise.

Since:: 10.7.2

setEntry

void setEntry(any key, any value)

Set the entry in the contained type corresponding to a named key.

Primitives, including strings, have a single entry with the key "value". Sequence keys are integers corresponding to the index in the sequence, starting from 0 (negative indexes are not permitted). 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:: - 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.

<Default Package>Type any