any

FRAMES NO FRAMES

Overview

Package

Deprecated

Help

API Reference for EPL (ApamaDoc) 10.11.3.3

SUMMARY: IMPORT | CONSTANT | MEMBER | ACTION

DETAIL: IMPORT | CONSTANT | MEMBER | ACTION

<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

Action summary
`boolean`	`static` `canParse(string s)` Check if the string argument can be parsed as an `any`.
`any`	`clone()` Create a deep copy of the value contained within this `any`.
`boolean`	`empty()` Check whether this `any` contains a value or object.
`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`	`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.
`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).
`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:: 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

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:: any#getDeclaredKeyType() - 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:: any#getDeclaredElementType() - 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:: 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, including strings, 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

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:: any#getKeys() - To see what the keys are for each of the possible objects contained in this any.; any#getEntries() - 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:: 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 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:: 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.

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

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

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, including strings, 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.