AnyExtractor

com.apama.util
Event AnyExtractor

Provides a type-safe way to extract the values from a value of the any type.

It is useful for handling payload generated from connectivity plug-in codecs such as JSON. The value held by the any type value must be of one of the following EPL types:

integer
float
boolean
string
sequence<TYPE>
dictionary<any, TYPE>
dictionary<string, TYPE>
event
location

The values held by sequences, dictionaries and events must also be one of the supported types mentioned above.

The values are extracted by specifying the path to the nested value using the "." and "[]" operators. To extract the value held by an existing AnyExtractor event object, use the empty string as the path.

The "." and "[]" operators are interchangeable and can be used to extract nested values from sequences, dictionaries or events. To extract elements from a sequence, an integer must be provided after the "." or within the "[]" operator. To extract values from a dictionary, provide the key after the "." or within the "[]" operator. To extract values from an event, provide the field name after the "." or within the "[]" operator. It is an error if the index, field or key specified by the "." or the "[]" operator either does not exist or is of incorrect type. It does not support extracting entries from a dictionary whose key contains special characters like ., [ or ].

No automatic conversions are performed on the values. It is an error to extract the value as an incorrect type.

Examples

To return the value held by an AnyExtractor event as a specific type:

// For an integer value held by the AnyExtractor event, it can be extracted as follows:
myExtractor.getInteger("");

To extract a value from a dictionary or an event:

// For a dictionary {"temp": 32.0}, the value for "temp" key can be extracted as follows:
AnyExtractor(data).getFloat("temp");

// The type of the data can also be an event with expected fields.
// For example, for a value of type event MyEvent { float temp; }, the field "temp" can be extracted as follows:
AnyExtractor(myEvent).getFloat("temp");

To extract nested values from dictionaries or events:

// For a dictionary with value {"location":{"country":"England", "city":"London"}}, the city can be extracted as follows:
AnyExtractor(data).getString("location.city");

// The "[]" operator can also be used to extract entries from dictionaries:
AnyExtractor(data).getString("location[city]");

// The types of the data and the nested object can also be events with correct fields instead of dictionaries.

To extract nested values from a sequence:

// For a dictionary with value {"users":[{"id":1, "name":"Alice"}, {"id":2, "name":"Bob"}]}, 
// the id of the first user can be extracted as follows:
AnyExtractor(data).getInteger("users[0].id");

// The "." operator can also be used to extract elements for sequences:
AnyExtractor(data).getInteger("users.0.id");

// Or use the "[]" operator for both sequences and dictionaries:
AnyExtractor(data).getInteger("users[0][id]");

// You can also extract values from a top level sequence.
// For example, for a sequence with values [{"id":1, "name":"Alice"}, {"id":2, "name":"Bob"}], the name
// of the second element can be extracted as follows:
AnyExtractor(data).getString("[1].name");

// We can also use index 1 directly:
AnyExtractor(data).getString("1.name");

Since:: 10.2

Field summary
`any`	`data` The value of the `any` type from which to extract the values. Helper actions with names starting with `get` can be used to extract a value and cast it to a specific type.

Action summary
`com.apama.util.AnyExtractor`	`static` `create(any data)` A static action that constructs an AnyExtractor for use with the functional library.
`any`	`getAny(string path)` Extract the value as an `any`.
`any`	`getAnyOr(string path, any defaultValue)` If an entry for the given path exists, then extract the value as an `any`. If the entry does not exist, then the default value is returned.
`boolean`	`getBoolean(string path)` Extract the value as a `boolean`. This is equivalent to calling `<boolean>getAny(path)`.
`boolean`	`getBooleanOr(string path, boolean defaultValue)` If an entry for the given path exists and it is a `boolean`, then extract this value. Else return the default value.
`dictionary<any, any>`	`getDictionary(string path)` Extract the value as a `dictionary<any,any>`. This is equivalent to calling `<dictionary<any,any> >getAny(path)`.
`dictionary<any, any>`	`getDictionaryOr(string path, dictionary<any, any> defaultValue)` If an entry for the given path exists and it a `dictionary<any,any>`, then extract this value. Else return the default value.
`float`	`getFloat(string path)` Extract the value as a `float`. This is equivalent to calling `<float>getAny(path)`.
`float`	`getFloatOr(string path, float defaultValue)` If an entry for the given path exists and it is a `float` or `integer`, then extract this value as a `float`. Else return the default value.
`integer`	`getInteger(string path)` Extract the value as an `integer`. This is equivalent to calling `<integer>getAny(path)`.
`integer`	`getIntegerOr(string path, integer defaultValue)` If an entry for the given path exists and it is an `integer`, then extract this value. Else return the default value.
`sequence<any>`	`getSequence(string path)` Extract the value as a `sequence<any>`. This is equivalent to calling `<sequence<any> >getAny(path)`.
`sequence<any>`	`getSequenceOr(string path, sequence<any> defaultValue)` If an entry for the given path exists and it is a `sequence` of arbitrary type, then extract this value as a `sequence<any>`. Else return the default value.
`string`	`getString(string path)` Extract the value as a `string`. This is equivalent to calling `<string>getAny(path)`.
`string`	`getStringOr(string path, string defaultValue)` If an entry for the given path exists and it is a `string`, then extract this value. Else return the default value.

Field detail

data

any data

The value of the any type from which to extract the values. Helper actions with names starting with get can be used to extract a value and cast it to a specific type.

Use "" as the path to simply return this value as the specified type.

See Also:: com.apama.util.AnyExtractor.getInteger() - Use getInteger() to extract the value as an integer.; com.apama.util.AnyExtractor.getFloat() - Use getFloat() to extract the value as a float.; com.apama.util.AnyExtractor.getString() - Use getSequence() to extract the value as a string.; com.apama.util.AnyExtractor.getSequence() - Use getSequence() to extract the value as a sequence<any>.; com.apama.util.AnyExtractor.getDictionary() - Use getDictionary() to extract the value as a dictionary<any,any>.; com.apama.util.AnyExtractor.getAny() - Use getAny() to extract the value as an any.

Action detail

create

com.apama.util.AnyExtractor static create(any data)

A static action that constructs an AnyExtractor for use with the functional library.

This is exactly equivalent to creating AnyExtractor the normal way using AnyExtractor(data), but allows the AnyExtractor to be used with the functional library, for example:

Functional(myData)
.map(AnyExtractor.create)
.map(Fn.callAction("getAny", "a.b.c"))
.map(Fn.toType("string"))
.get()

Parameters:: data - The data that the AnyExtractor should hold.

Since:: 10.15.3

See Also:: com.apama.functional.Functional

getAny

any getAny(string path)

Extract the value as an any.

Parameters:: path - The path to the value to extract. Use "" to return the value held. Use "." and "[]" to extract nested values.

Returns:: The extracted value.

Throws:: Throws IllegalArgumentException if the entry does not exist or an unmatched subscripts operator is used.

getAnyOr

any getAnyOr(string path, any defaultValue)

If an entry for the given path exists, then extract the value as an any. If the entry does not exist, then the default value is returned.

Parameters:: path - The path to the value to extract. Use "" to return the value held. Use "." and "[]" to extract nested values.; defaultValue - The value to return if the entry for the specified path does not exist.

Returns:: The extracted value if there is an entry for the specified path. Else the default value.

Throws:: Throws IllegalArgumentException if an unmatched subscripts operator is specified in the path.

Since:: 10.7.1

getBoolean

boolean getBoolean(string path)

Extract the value as a boolean. This is equivalent to calling <boolean>getAny(path).

Parameters:: path - The path to the value to extract. Use "" to return the value held. Use "." and "[]" to extract nested values.

Returns:: The extracted value.

Throws:: Throws CastException if the extracted value is not a boolean.

See Also:: com.apama.util.AnyExtractor.getAny() - Use getAny() to extract the value as an any.

getBooleanOr

boolean getBooleanOr(string path, boolean defaultValue)

If an entry for the given path exists and it is a boolean, then extract this value. Else return the default value.

If you would like to throw if it exists but is the wrong type (rather than returning the default), instead write <boolean>getAnyOr(path, defaultValue).

Parameters:: path - The path to the value to extract. Use "" to return the value held. Use "." and "[]" to extract nested values.; defaultValue - The value to return if the entry for the given path does not exist or the entry is not a boolean.

Returns:: The extracted value if the entry exists and the entry is a boolean, or the default value otherwise.

Throws:: Throws IllegalArgumentException if an unmatched subscripts operator is specified in the path.

Since:: 10.7.1

See Also:: com.apama.util.AnyExtractor.getAnyOr() - Use getAnyOr() to extract the value as an any.

getDictionary

dictionary<any, any> getDictionary(string path)

Extract the value as a dictionary<any,any>. This is equivalent to calling <dictionary<any,any> >getAny(path).

The CastException is thrown if the extracted value is either not a dictionary or is a dictionary of type other than dictionary<any,any>. Use getAny action to extract dictionaries of type other than dictionary<any,any>.

Parameters:: path - The path to the value to extract. Use "" to return the value held. Use "." and "[]" to extract nested values.

Returns:: The extracted value.

Throws:: Throws CastException if the extracted value is not a dictionary<any,any>.

See Also:: com.apama.util.AnyExtractor.getAny() - Use getAny() to extract the value as an any.

getDictionaryOr

dictionary<any, any> getDictionaryOr(string path, dictionary<any, any> defaultValue)

If an entry for the given path exists and it a dictionary<any,any>, then extract this value. Else return the default value.

If you would like to throw if it exists but is the wrong type (rather than returning the default), instead write <dictionary<any,any>> getAnyOr(path, defaultValue).

Parameters:: path - The path to the value to extract. Use "" to return the value held. Use "." and "[]" to extract nested values.; defaultValue - The value to return if the entry for the given path does not exist or the entry is not a dictionary<any,any>.

Returns:: The extracted value if the entry exists and the entry is a dictionary<any,any>, or the default value otherwise.

Throws:: Throws IllegalArgumentException if an unmatched subscripts operator is specified in the path.

Since:: 10.7.1

See Also:: com.apama.util.AnyExtractor.getAnyOr() - Use getAnyOr() to extract the value as an any.

getFloat

float getFloat(string path)

Extract the value as a float. This is equivalent to calling <float>getAny(path).

Parameters:: path - The path to the value to extract. Use "" to return the value held. Use "." and "[]" to extract nested values.

Returns:: The extracted value.

Throws:: Throws CastException if the extracted value is not a float or integer or decimal.

See Also:: com.apama.util.AnyExtractor.getAny() - Use getAny() to extract the value as an any.

getFloatOr

float getFloatOr(string path, float defaultValue)

If an entry for the given path exists and it is a float or integer, then extract this value as a float. Else return the default value.

If you would like to throw if it exists but is the wrong type (rather than returning the default), instead write <float>getAnyOr(path, defaultValue).

Parameters:: path - The path to the value to extract. Use "" to return the value held. Use "." and "[]" to extract nested values.; defaultValue - The value to return if the entry for the given path does not exist or the entry is not a float or integer or decimal.

Returns:: The extracted value if the entry exists and the entry is a float or integer or decimal, or the default value otherwise.

Throws:: Throws IllegalArgumentException if an unmatched subscripts operator is specified in the path.

Since:: 10.7.1

See Also:: com.apama.util.AnyExtractor.getAnyOr() - Use getAnyOr() to extract the value as an any.

getInteger

integer getInteger(string path)

Extract the value as an integer. This is equivalent to calling <integer>getAny(path).

Parameters:: path - The path to the value to extract. Use "" to return the value held. Use "." and "[]" to extract nested values.

Returns:: The extracted value.

Throws:: Throws CastException if the extracted value is not an integer.

See Also:: com.apama.util.AnyExtractor.getAny() - Use getAny() to extract the value as an any.

getIntegerOr

integer getIntegerOr(string path, integer defaultValue)

If an entry for the given path exists and it is an integer, then extract this value. Else return the default value.

If you would like to throw if it exists but is the wrong type (rather than returning the default), instead write <integer>getAnyOr(path, defaultValue).

Parameters:: path - The path to the value to extract. Use "" to return the value held. Use "." and "[]" to extract nested values.; defaultValue - The value to return if the entry for the given path does not exist or the entry is not an integer.

Returns:: The extracted value if the entry exists and the entry is an integer, or the default value otherwise.

Throws:: Throws IllegalArgumentException if an unmatched subscripts operator is specified in the path.

Since:: 10.7.1

See Also:: com.apama.util.AnyExtractor.getAnyOr() - Use getAnyOr() to extract the value as an any.

getSequence

sequence<any> getSequence(string path)

Extract the value as a sequence<any>. This is equivalent to calling <sequence<any> >getAny(path).

The CastException is thrown if the extracted value is either not a sequence or is a sequence of type other than sequence<any>. Use getAny action to extract sequences of type other than sequence<any>.

Parameters:: path - The path to the value to extract. Use "" to return the value held. Use "." and "[]" to extract nested values.

Returns:: The extracted value.

Throws:: Throws CastException if the extracted value is not a sequence<any>.

See Also:: com.apama.util.AnyExtractor.getAny() - Use getAny() to extract the value as an any.

getSequenceOr

sequence<any> getSequenceOr(string path, sequence<any> defaultValue)

If an entry for the given path exists and it is a sequence of arbitrary type, then extract this value as a sequence<any>. Else return the default value.

If you would like to throw if it exists but is the wrong type (rather than returning the default), instead write <sequence<any>>getAnyOr(path,defaultValue).

Parameters:: path - The path to the value to extract. Use "" to return the value held. Use "." and "[]" to extract nested values.; defaultValue - The value to return if the entry for the given path does not exist or the entry is not a sequence.

Returns:: A copy of the extracted value if the entry exists and the entry is a sequence of arbitrary type, or the default value otherwise.

Throws:: Throws IllegalArgumentException if an unmatched subscripts operator is specified in the path.

Since:: 10.7.1

See Also:: com.apama.util.AnyExtractor.getAnyOr() - Use getAnyOr() to extract the value as an any.

getString

string getString(string path)

Extract the value as a string. This is equivalent to calling <string>getAny(path).

Parameters:: path - The path to the value to extract. Use "" to return the value held. Use "." and "[]" to extract nested values.

Returns:: The extracted value.

Throws:: Throws CastException if the extracted value is not a string.

See Also:: com.apama.util.AnyExtractor.getAny() - Use getAny() to extract the value as an any.

getStringOr

string getStringOr(string path, string defaultValue)

If an entry for the given path exists and it is a string, then extract this value. Else return the default value.

If you would like to throw if it exists but is the wrong type (rather than returning the default), instead write <string>getAnyOr(path, defaultValue).

Parameters:: path - The path to the value to extract. Use "" to return the value held. Use "." and "[]" to extract nested values.; defaultValue - The value to return if the entry for the given path does not exist or the entry is not a string.

Returns:: The extracted value if the entry exists and the entry is a string, or the default value otherwise.

Throws:: Throws IllegalArgumentException if an unmatched subscripts operator is specified in the path.

Since:: 10.7.1

See Also:: com.apama.util.AnyExtractor.getAnyOr() - Use getAnyOr() to extract the value as an any.

com.apama.utilEvent AnyExtractor