Package com.apama.iaf.plugin

Class 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 extends java.lang.Object,​V extends java.lang.Object>

    • Constructor Summary

      Constructors 
      Constructor Description
      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

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      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.
      java.lang.String replace​(java.lang.String key, java.lang.String newValue)
      Deprecated.
      This method has been deprecated to avoid confusion, please update code to use the standard put(String, String) method instead.
      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.lang.Iterable

        forEach, spliterator

      • Methods inherited from interface java.util.Map

        compute, computeIfAbsent, computeIfPresent, equals, forEach, getOrDefault, hashCode, merge, putIfAbsent, remove, replace, replaceAll

    • 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

        @Deprecated
public java.lang.String replace​(java.lang.String key,
                                java.lang.String newValue)
                         throws NormalisedEventException
        Deprecated.
        This method has been deprecated to avoid confusion, please update code to use the standard put(String, String) method instead.
        Identical to put(String, String).

        This method does not have the same semantics as the new Map.replace method introduced in Java 1.8, and has therefore been deprecated to avoid confusion.

        Specified by:
        replace in interface java.util.Map<java.lang.String,​java.lang.String>
        Throws:
        NormalisedEventException

      • 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()