optional
An optional is a value that contains either a value (of some EPL type), or is empty and thus has no value. This is useful for mapping to null values in other languages such as Java, or for data which may not be present in some circumstances.
Usage
An optional is either empty or contains a single value. The type of the value is specified between angle brackets in the optional type name and is known as the contained type. You can use the value from an optional in the following ways:
With instance methods. You can use
getOrThrow or
getOr methods to access the value.
Optional types are comparable provided the contained type is comparable. (Thus you can compare them equal, or sort them, provided the contained type supports those operations). When sorting, an empty optional is always less than an optional with a value.
Optionals cannot contain types of context, listener, stream, chunk, optional or action. All of these types may themselves be empty and thus do not need to be wrapped with optional. They can all be used by the ifpresent statement as well.
Example
optional is useful when describing events that have data that may be unavailable. For example, an event describing the position of a smartphone may have several optional fields, depending on which mechanisms have been able to determine the position:
event GPSPosition {
float longitude;
float latitude;
float accuracy;
integer numSatFix;
}
event SmartPhonePosition {
string deviceId;
float timestamp;
optional<GPSPosition> gps;
optional<string> nearestCellId;
optional<sequence<string> > nearestWiFiMacAddresses;
}
This event could distinguish between a GPS fix (in which case all of the members of GPSPosition are available and should be valid) and no GPS fix, and a nearest mobile phone cell or no cells being in range. Also note how it can distinguish between Wi-Fi switched on but no networks in range (non-empty optional containing a zero-length sequence) and Wi-Fi switched off (an empty optional). The deviceId and timestamp are always available in the SmartPhonePosition event.
Syntax
The syntax for optional is:
optional< type > varname
For example:
// An optional that may or may not contain an integer
optional<integer> myOptInt;
The default value of an optional is an empty value. There is a single argument constructor:
optional<integer> myOptInt := optional<integer>(5);
But it is also possible to assign a variable or literal of type T to an optional<T>. For example:
optional<integer> myOptInt := 5;
See the documentation of the different types for detailed information on how to declare the literals.
An
optional variable can potentially contain a cyclic type — a type that directly or indirectly refers to itself. For details about the behavior of such objects, see
Potentially
cyclic types.
Methods
The methods available to the optional data structure are:
canParse(string) —
Returns true if the string argument can be successfully parsed to create an optional object. For more information about the parseable type property, see the table in
Type properties summary.
clone() —
Returns a new optional that is an exact copy of the optional that this method is called on. The contained value (if it exists) is cloned into the new
optional, and if that value is a reference type, its contents are cloned as well.
empty() —
Returns true if the optional is empty. getOr(alternate) —
Returns either the contained value or the alternate if this instance is empty. getOrThrow() —
Returns either the contained value or throws a NullPointerException if this instance contains no value. See also
Exception.
parse(string) —
Returns the optional object represented by the string argument. For more information about the parseable type property, see the table in
Type properties summary. You can call this method on the
optional type or on an instance of an
optional type. The more typical use is to call
parse() directly on the
optional type.
The
parse() method takes a single string as its argument. This string must be the string form of an
optional object. The string must adhere to the format described in
Event file format. For example:
optional<integer> i := new optional<integer>;
s := optional<integer>.parse("optional(42)");
If the correlator is unable to parse the string, the method will throw an exception.
When an optional is a potentially cyclic type , the behavior of the
parse() method is more advanced. See
Potentially
cyclic types.
toString() —
Creates a string representation of the optional, prefixed with the word optional and parentheses enclosing the element. For example:
optional(56)
The string representation of an empty optional is:
optional()
When an optional is a potentially cyclic type, the behavior of the
toString() method is different. See
Potentially
cyclic types.
