com.apama.iaf.plugin
Class NormalisedEvent

java.lang.Object
  com.apama.iaf.plugin.NormalisedEvent

All Implemented Interfaces:

java.lang.Iterable<java.util.Map.Entry<java.lang.String,java.lang.String>>, java.util.Map<java.lang.String,java.lang.String>

public class NormalisedEvent
extends java.lang.Object
implements java.lang.Iterable<java.util.Map.Entry<java.lang.String,java.lang.String>>, java.util.Map<java.lang.String,java.lang.String>

Represents an Apama event in the normalised form used by the IAF Semantic Mapper. The normalised event is simply a dictionary of name/value String pairs, where all names are unique within the event, but values are not unique and may be null.

The class provides methods for constructing, manipulating and querying the contents of the event, and is designed to be similar to the C interface in 'NormalisedEvent.h', but also implements the standard Java Map and Iterable interfaces.

Java developers may find it simplest to use standard Map methods such as put(String, String) for adding fields to the normalised event, get(Object) for reading field values, and a standard Java for loop to iterate over all the name/value entries in the normalised event.

Note that this class is NOT itself thread-safe.

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Constructor Summary

NormalisedEvent()
Constructs a new NormalisedEvent, initially empty.

NormalisedEvent(java.util.Map<java.lang.String,java.lang.String> m)
Constructs a new NormalisedEvent, with the same name/value pairs as the specified Map.

Method Summary

NormalisedEventIterator	add(java.lang.String key, java.lang.String value) Add a new name-value pair to the event.
void	addQuick(java.lang.String key, java.lang.String value) Add a new name-value pair to the event.
void	clear() Removes all mappings from this map.
boolean	containsKey(java.lang.Object name) Returns true if this map contains a mapping for the specified name.
boolean	containsValue(java.lang.Object value) Returns true if this map maps one or more names to the specified value.
boolean	empty() Check whether the event is empty or not.
java.util.Set<java.util.Map.Entry<java.lang.String,java.lang.String>>	entrySet()
boolean	exists(java.lang.String key) Check whether a given element exists in the normalised event.
NormalisedEventIterator	find(java.lang.String key) Search for a named element in the normalised event.
java.lang.String	findValue(java.lang.String key) Search for a named element in the normalised event and return its value.
java.lang.String	findValueAndRemove(java.lang.String key) Search for a named element in the normalised event and return its value.
java.lang.String	findValueAndRemove2(java.lang.String key) Search for a named element in the normalised event and return its value.
NormalisedEventIterator	first() Return an iterator pointing to the first element of the normalised event.
java.lang.String	get(java.lang.Object key) Returns the value to which the specified name is mapped, or null if the map contains no mapping for this key.
boolean	isEmpty() Returns true if this map contains no key-value mappings.
java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.String>>	iterator() Returns a standard Java Iterator over the contents of the NormalisedEvent using Map.Entry objects.
java.util.Set<java.lang.String>	keySet()
NormalisedEventIterator	last() Return an iterator pointing to the last element of the normalised event.
java.lang.String	put(java.lang.String key, java.lang.String value) Adds or replaces the specified (key,value) pair in the underlying map
void	putAll(java.util.Map<? extends java.lang.String,? extends java.lang.String> m) Copies all of the mappings from the specified map to this map These mappings will replace any mappings that this map had for any of the keys currently in the specified map.
java.lang.String	remove(java.lang.Object key) Removes the mapping for this key from this map if present.
void	remove(java.lang.String key) Remove the named element from the normalised event.
void	removeAll() Remove all elements from the normalised event.
void	replace(java.lang.String key, java.lang.String newValue) Change the value of a named element in the normalised event.
int	size() Get the number of elements (name-value pairs) currently stored by the event.
java.lang.String	toString() Return a printable string representation of the normalised event.
java.util.Collection<java.lang.String>	values() Returns a collection view of the values contained in this map.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

equals, hashCode

Constructor Detail

NormalisedEvent

public NormalisedEvent()

Constructs a new NormalisedEvent, initially empty.

NormalisedEvent

public NormalisedEvent(java.util.Map<java.lang.String,java.lang.String> m)

Constructs a new NormalisedEvent, with the same name/value pairs as the specified Map.

Method Detail

size

public int size()

Get the number of elements (name-value pairs) currently stored by the event.

Specified by:

size in interface java.util.Map<java.lang.String,java.lang.String>

Returns:

The number of elements in the event

empty

public boolean empty()

Check whether the event is empty or not.

Returns:

true if the event has zero elements, false otherwise

add

public NormalisedEventIterator add(java.lang.String key,
                                   java.lang.String value)
                            throws NormalisedEventException

Add a new name-value pair to the event. The given name and value will be copied into the event. If an element with the same name already exists, it will NOT be overwritten.

Parameters:

key - The name of the new element

value - the value of the new element

Returns:

A NormalisedEventIterator pointing to the new element, or null if the element was not added (because the name already existed).

Throws:

NormalisedEventException - Thrown if key=null

addQuick

public void addQuick(java.lang.String key,
                     java.lang.String value)
              throws NormalisedEventException

Add a new name-value pair to the event. The given name and value will be copied into the event. If an element with the same name already exists, it will NOT be overwritten.

This function is faster and more memory-efficient than add(), since it does not bother creating an iterator. However, you have no way of knowing whether the element was actually added or not, other than searching for the name and checking the stored value.

Parameters:

key - The name of the new element

value - The value of the new element

Throws:

NormalisedEventException - Thrown if key=null

remove

public void remove(java.lang.String key)

Remove the named element from the normalised event.

Parameters:

key - The name of the element to be removed

replace

public void replace(java.lang.String key,
                    java.lang.String newValue)
             throws NormalisedEventException

Change the value of a named element in the normalised event. If an element with the given name already exists, its value will be replaced with a copy of the given value. Otherwise, a new element is created just as though addQuick() had been called.

Parameters:

key - The name of the element to be updated

newValue - The new value for the named element

Throws:

NormalisedEventException - Thrown if key=null

removeAll

public void removeAll()

Remove all elements from the normalised event. The empty() function will return true after this function has been called.

exists

public boolean exists(java.lang.String key)

Check whether a given element exists in the normalised event.

Parameters:

key - The element name to search for

Returns:

true if an element with the given name exists in the normalised event, false otherwise.

find

public NormalisedEventIterator find(java.lang.String key)
                             throws NormalisedEventException

Search for a named element in the normalised event.

Parameters:

key - The element name to search for

Returns:

An iterator pointing to the element with the given name, or null if no matching element could be found.

Throws:

NormalisedEventException - Thrown if the key cannot be found

See Also:

iterator()

findValue

public java.lang.String findValue(java.lang.String key)

Search for a named element in the normalised event and return its value.

Parameters:

key - The element name to search for

Returns:

The value associated with the given name, or null if no matching element could be found. Note that this function cannot distinguish between an element with a missing value and an element that does not exist - null will be returned in either case.

findValueAndRemove

public java.lang.String findValueAndRemove(java.lang.String key)

Search for a named element in the normalised event and return its value. If found, the element will also be removed from the event.

Parameters:

key - The element name to search for

Returns:

The value associated with the given name, or null if no matching element could be found. If the element was found, it will be deleted from the event. Note that this function cannot distinguish between an element with a missing value and an element that does not exist - null will be returned in either case.

findValueAndRemove2

public java.lang.String findValueAndRemove2(java.lang.String key)
                                     throws NormalisedEventException

Search for a named element in the normalised event and return its value. If found, the element will also be removed from the event.

Parameters:

key - The element name to search for

Returns:

The value associated with the given name, or null if no matching element could be found. If the element was found, it will be deleted from the event.

Throws:

NormalisedEventException - Thrown if the key did not exist

first

public NormalisedEventIterator first()

Return an iterator pointing to the first element of the normalised event. Successive calls to the next() function of the returned iterator will allow you to visit all the elements of the event. Note that it may be easier to use the iterator() method instead of this one, which returns a standard Java Iterator object for accessing the contents of the Normalised Event.

Returns:

An iterator pointing to the first element of the event, or null if the event has no elements.

See Also:

iterator()

last

public NormalisedEventIterator last()

Return an iterator pointing to the last element of the normalised event. Successive calls to the back() function of the returned iterator will allow you to visit all the elements of the event.

Returns:

An iterator pointing to the last element of the event, or null if the event has no elements.

See Also:

iterator()

toString

public java.lang.String toString()

Return a printable string representation of the normalised event.

Overrides:

toString in class java.lang.Object

Returns:

Printable string representation of the event. The value returned may differ between implementations, and is not the same as the value returned by the C implementation of this class.

iterator

public java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.String>> iterator()

Returns a standard Java Iterator over the contents of the NormalisedEvent using Map.Entry objects. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation, or through the setValue operation on a map entry returned by the iterator) the results of the iteration are undefined.

Instead of calling this method directly, it may be easier to use the following construction: for (Map.Entry<String,String> element: normalisedEvent) { ... }

Specified by:

iterator in interface java.lang.Iterable<java.util.Map.Entry<java.lang.String,java.lang.String>>

Returns:

An iterator over the contents of the NormalisedEvent.

put

public java.lang.String put(java.lang.String key,
                            java.lang.String value)
                     throws NormalisedEventException

Adds or replaces the specified (key,value) pair in the underlying map

Specified by:

put in interface java.util.Map<java.lang.String,java.lang.String>

Parameters:

key - Any string

value - Any string or null

Returns:

Previous value associated with key (which could be null), or null if the key did not exist

Throws:

NormalisedEventException - If key=null

See Also:

Map.put(Object, Object)

entrySet

public java.util.Set<java.util.Map.Entry<java.lang.String,java.lang.String>> entrySet()

Specified by:

entrySet in interface java.util.Map<java.lang.String,java.lang.String>

Returns:

A set view of the (name,value) pairs making up the NormalisedEvent.

See Also:

Map.entrySet()

keySet

public java.util.Set<java.lang.String> keySet()

Specified by:

keySet in interface java.util.Map<java.lang.String,java.lang.String>

Returns:

A set view of the names of the NormalisedEvent.

See Also:

Map.keySet()

clear

public void clear()

Removes all mappings from this map.

Specified by:

clear in interface java.util.Map<java.lang.String,java.lang.String>

See Also:

Map.clear()

containsKey

public boolean containsKey(java.lang.Object name)

Returns true if this map contains a mapping for the specified name.

Specified by:

containsKey in interface java.util.Map<java.lang.String,java.lang.String>

Parameters:

name - The namewhose presence in this map is to be tested

Returns:

true if this map contains a mapping for the specified key.

See Also:

Map.containsKey(Object)

containsValue

public boolean containsValue(java.lang.Object value)

Returns true if this map maps one or more names to the specified value.

Specified by:

containsValue in interface java.util.Map<java.lang.String,java.lang.String>

Parameters:

value - value whose presence in this map is to be tested.

Returns:

true if this map maps one or more names to the specified value.

See Also:

Map.containsValue(Object)

get

public java.lang.String get(java.lang.Object key)

Returns the value to which the specified name is mapped, or null if the map contains no mapping for this key. A return value of null does not necessarily indicate that the map contains no mapping for the key; it is also possible that the map explicitly maps the key to null. The containsKey method may be used to distinguish these two cases.

Specified by:

get in interface java.util.Map<java.lang.String,java.lang.String>

Parameters:

key - the key whose associated value is to be returned.

Returns:

the value to which this map maps the specified key, or null if the map contains no mapping for this key.

See Also:

Map.put(Object, Object), Map.get(Object)

isEmpty

public boolean isEmpty()

Returns true if this map contains no key-value mappings.

Specified by:

isEmpty in interface java.util.Map<java.lang.String,java.lang.String>

Returns:

true if this map contains no key-value mappings.

See Also:

Map.isEmpty()

putAll

public void putAll(java.util.Map<? extends java.lang.String,? extends java.lang.String> m)

Copies all of the mappings from the specified map to this map These mappings will replace any mappings that this map had for any of the keys currently in the specified map.

Specified by:

putAll in interface java.util.Map<java.lang.String,java.lang.String>

Parameters:

m - mappings to be stored in this map.

Throws:

java.lang.NullPointerException - if the specified map is null.

See Also:

Map.putAll(Map)

remove

public java.lang.String remove(java.lang.Object key)

Removes the mapping for this key from this map if present.

Specified by:

remove in interface java.util.Map<java.lang.String,java.lang.String>

Parameters:

key - key whose mapping is to be removed from the map.

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key.

See Also:

Map.remove(Object)

values

public java.util.Collection<java.lang.String> values()

Returns a collection view of the values contained in this map.

Specified by:

values in interface java.util.Map<java.lang.String,java.lang.String>

Returns:

a collection view of the values contained in this map.

See Also:

Map.values()