Package com.bloomberglp.blpapi

Class EventFormatter

java.lang.Object
com.bloomberglp.blpapi.EventFormatter
public final class EventFormatter extends Object
EventFormatter is used to format publisher events or responses to certain ProviderSession requests.

An EventFormatter is created either from an Event obtained from Service.createPublishEvent() or from Service.createResponseEvent(CorrelationID). Once one or more Messages have been appended to the Event using the EventFormatter the Event can be published using ProviderSession.publish(Event) or sent back as a response using ProviderSession.sendResponse(Event).

EventFormatter objects cannot be copied or assigned so as to ensure there is no ambiguity about what happens if two EventFormatters are both formatting the same Event.

An EventFormatter object supports writing once only to each field. It is an error to call setElement() or pushElement() for the same name more than once at a particular level of the schema when creating a message.

  • Constructor Details

    • EventFormatter

      public EventFormatter(Event event)
      Creates an EventFormatter to add messages to the specified event. The behavior is undefined if the specified event already has another EventFormatter attached.
      Parameters:
      event - the event to be formatted

  • Method Details

    • appendMessage

      @Deprecated public void appendMessage(String messageType, Topic topic)
      Deprecated.
      Use {appendMessage(Name, Topic)} instead.
      Appends a (empty) message of the specified 'messageType' that will be published under the specified 'topic' to the event referenced by this EventFormatter. After a message has been appended its elements can be set using the various setElement(java.lang.String,java.lang.String) methods.
      Parameters:
      messageType - the name of the message type that needs to be added
      topic - the corresponding topic

    • appendMessage

      @Deprecated public void appendMessage(String messageType, Topic topic, Integer sequenceNumber)
      Deprecated.
      Use {appendMessage(Name, Topic, Integer)} instead.
      Appends a (empty) message of the specified 'messageType' that will be published under the specified 'topic' with the specified 'sequenceNumber' to the event referenced by this EventFormatter. After a message has been appended its elements can be set using the various setElement(java.lang.String, java.lang.String) methods. The behavior is undefined unless the 'sequenceNumber' is greater (unless the value wrapped) than the last value used in any previous message on this 'topic'.
      Parameters:
      messageType - the name of the message type that needs to be added
      topic - the corresponding topic
      sequenceNumber - the sequence number for this message

    • appendMessage

      public void appendMessage(Name messageType, Topic topic)
      Appends a (empty) message of the specified 'messageType' that will be published under the specified 'topic' to the event referenced by this EventFormatter. After a message has been appended its elements can be set using the various setElement(java.lang.String, java.lang.String) methods.
      Parameters:
      messageType - the name of the message type that needs to be added
      topic - the corresponding topic

    • appendMessage

      public void appendMessage(Name messageType, Topic topic, Integer sequenceNumber)
      Appends a (empty) message of the specified 'messageType' that will be published under the specified 'topic' with the specified 'sequenceNumber' to the event referenced by this EventFormatter. After a message has been appended its elements can be set using the various setElement(java.lang.String, java.lang.String) methods. The behavior is undefined unless the 'sequenceNumber' is greater (unless the value wrapped) than the last value used in any previous message on this 'topic'.
      Parameters:
      messageType - the name of the message type that needs to be added
      topic - the corresponding topic
      sequenceNumber - the sequence number for this message

    • appendRecapMessage

      public void appendRecapMessage(Topic topic, CorrelationID cid)
      Append a (empty) recap message that will be published under the specified 'topic' to the event referenced by this EventFormatter. Specify the optional 'cid' if this recap message is added in response to a TopicRecap message. After a message has been appended its elements can be set using the various setElement(java.lang.String, java.lang.String) methods. It is an error to append a recap message to an admin event.
      Parameters:
      topic - the corresponding topic
      cid - the correlationId of the TopicRecap message if responding to a recap request or null if this is a recap message for all subscribers

    • appendRecapMessage

      public void appendRecapMessage(Topic topic, Integer sequenceNumber, CorrelationID cid)
      Append a (empty) recap message that will be published under the specified 'topic' to the event referenced by this EventFormatter. Specify the optional 'cid' if this recap message is added in response to a TopicRecap message. After a message has been appended its elements can be set using the various setElement(java.lang.String, java.lang.String) methods. It is an error to create append a recap message to an admin event. The behavior is undefined unless the 'sequenceNumber' is greater (unless the value wrapped) than the last value used in any previous message on this 'topic'.
      Parameters:
      topic - the corresponding topic
      sequenceNumber - the sequence number for this message
      cid - the correlationId of the TopicRecap message if responding to a recap request or null if this is a recap message for all subscribers

    • appendResponse

      @Deprecated public void appendResponse(String operationName)
      Deprecated.
      Use {appendResponse(Name) instead.
      Equivalent to appendResponse(Name operationName) with a Name object with the specified operationName value.

      Note that using Name overloads is preferable, as the Name objects have better performance if they are re-used after being created.

      Parameters:
      operationName - name of the operation whose response type is to be used

    • appendResponse

      public void appendResponse(Name operationName)
      Append an (empty) response message of the specified operationName that will be sent in response to the previously received operation request. After a message has been appended its elements can be set using the various setElement(java.lang.String, java.lang.String) methods. Only one response can be appended to an event. The behavior is undefined unless the Event is currently empty.
      Parameters:
      operationName - name of the operation whose response type is to be used

    • appendValue

      public void appendValue(boolean value)
      Append the specified 'value' to the element which represents an array of boolean type.
      Parameters:
      value - the value to be added

    • appendValue

      public void appendValue(char value)
      Append the specified 'value' to the element which represents an array of char type.
      Parameters:
      value - the value to be added

    • appendValue

      public void appendValue(int value)
      Append the specified 'value' to the element which represents an array of int type.
      Parameters:
      value - the value to be added

    • appendValue

      public void appendValue(long value)
      Append the specified 'value' to the element which represents an array of long type.
      Parameters:
      value - the value to be added

    • appendValue

      public void appendValue(float value)
      Append the specified 'value' to the element which represents an array of float type.
      Parameters:
      value - the value to be added

    • appendValue

      public void appendValue(double value)
      Append the specified 'value' to the element which represents an array of double type.
      Parameters:
      value - the value to be added

    • appendValue

      public void appendValue(Datetime value)
      Append the specified 'value' to the element which represents an array of Datetime type.
      Parameters:
      value - the value to be added

    • appendValue

      public void appendValue(String value)
      Append the specified 'value' to the element which represents an array of String type.
      Parameters:
      value - the value to be added

    • appendValue

      public void appendValue(Name value)
      Append the specified 'value' to the element which represents an array of Name type.
      Parameters:
      value - the value to be added

    • appendElement

      public void appendElement()
      Append an empty complex element of the appropriate type to the element which represents an array of Element type.

    • pushElement

      @Deprecated public void pushElement(String name)
      Deprecated.
      Use {pushElement(Name) instead.
      Changes the level at which this EventFormatter is operating to the specified element 'name'. After this returns the context of the EventFormatter is set to the element 'name' in the schema and subsequent calls to setElement(java.lang.String, java.lang.String) or pushElement(java.lang.String) are applied at that level. If 'name' represents an array of scalars then appendValue(boolean) must be used to add values. If 'name' represents an array of complex types then appendElement() creates the first entry and sets the context of the formatter to that element. Calling appendElement() again will create another entry.
      Parameters:
      name - the name of sub-element
      Throws:
      NotFoundException - if the name does not identify a sub-element at the current level of the schema

    • pushElement

      public void pushElement(Name name)
      Changes the level at which this EventFormatter is operating to the specified element 'name'. After this returns the context of the EventFormatter is set to the element 'name' in the schema and subsequent calls to setElement(java.lang.String, java.lang.String) or pushElement(java.lang.String) are applied at that level. If 'name' represents an array of scalars then appendValue(boolean) must be used to add values. If 'name' represents an array of complex types then appendElement() creates the first entry and sets the context of the formatter to that element. Calling appendElement() again will create another entry.
      Parameters:
      name - the name of sub-element
      Throws:
      NotFoundException - if the name does not identify a sub-element at the current level of the schema

    • popElement

      public void popElement()
      Returns this formatter's context back to the location where it was before the most recent call to pushElement(java.lang.String) or {appendElement().

    • setElement

      @Deprecated public void setElement(String name, String value)
      Deprecated.
      Use {setElement(Name, String) instead.
      Sets the element with the specified name within the current element to the specified value. The behavior of this function is undefined if value is null. Note that this function is not intended for publication of null values; use setElementNull(String) instead.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      @Deprecated public void setElement(String name, Name value)
      Deprecated.
      Use {setElement(Name, Name) instead.
      Sets the element with the specified name within the current element to the specified value. The behavior of this function is undefined if value is null. Note that this function is not intended for publication of null values; use setElementNull(String) instead.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      @Deprecated public void setElement(String name, boolean value)
      Deprecated.
      Use {setElement(Name, boolean) instead.
      Sets the element with the specified name within the current element to the specified value.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      @Deprecated public void setElement(String name, char value)
      Deprecated.
      Use {setElement(Name, char) instead.
      Sets the element with the specified name within the current element to the specified value.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      @Deprecated public void setElement(String name, int value)
      Deprecated.
      Use {setElement(Name, int) instead.
      Sets the element with the specified name within the current element to the specified value.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      @Deprecated public void setElement(String name, long value)
      Deprecated.
      Use {setElement(Name, long) instead.
      Sets the element with the specified name within the current element to the specified value.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      @Deprecated public void setElement(String name, float value)
      Deprecated.
      Use {setElement(Name, float) instead.
      Sets the element with the specified name within the current element to the specified value.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      @Deprecated public void setElement(String name, double value)
      Deprecated.
      Use {setElement(Name, double) instead.
      Sets the element with the specified name within the current element to the specified value.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      public void setElement(Name name, String value)
      Sets the element with the specified name within the current element to the specified value. The behavior of this function is undefined if value is null. Note that this function is not intended for publication of null values; use setElementNull(Name) instead.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      public void setElement(Name name, Name value)
      Sets the element with the specified name within the current element to the specified value. The behavior of this function is undefined if value is null. Note that this function is not intended for publication of null values; use setElementNull(Name) instead.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      public void setElement(Name name, boolean value)
      Sets the element with the specified name within the current element to the specified value.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      public void setElement(Name name, char value)
      Sets the element with the specified name within the current element to the specified value.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      public void setElement(Name name, int value)
      Sets the element with the specified name within the current element to the specified value.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      public void setElement(Name name, long value)
      Sets the element with the specified name within the current element to the specified value.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      public void setElement(Name name, float value)
      Sets the element with the specified name within the current element to the specified value.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      public void setElement(Name name, double value)
      Sets the element with the specified name within the current element to the specified value.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      @Deprecated public void setElement(String name, Datetime value)
      Deprecated.
      Use {setElement(Name, Datetime) instead.
      Sets the element with the specified name within the current element to the specified value. The behavior of this function is undefined if value is null. Note that this function is not intended for publication of null values; use setElementNull(String) instead.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      public void setElement(Name name, Datetime value)
      Sets the element with the specified name within the current element to the specified value. The behavior of this function is undefined if value is null. Note that this function is not intended for publication of null values; use setElementNull(Name) instead.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElement

      public void setElement(Name name, byte[] value)
      Sets the element with the specified name within the current element to the specified value. The behavior of this function is undefined if value is null. Note that this function is not intended for publication of null values; use setElementNull(Name) instead.
      Parameters:
      name - the name of subfield
      value - the value to be set
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElementNull

      @Deprecated public void setElementNull(String name)
      Deprecated.
      Use {setElementNull(Name) instead.
      Creates a null element with the specified 'name'. Note that whether or not fields containing null values are published to subscribers is dependent upon details of the service and schema configuration.
      Parameters:
      name - the name of subfield to be nulled
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty

    • setElementNull

      public void setElementNull(Name name)
      Creates a null element with the specified 'name'. Note that whether or not fields containing null values are published to subscribers is dependent upon details of the service and schema configuration.
      Parameters:
      name - the name of subfield to be nulled
      Throws:
      UnsupportedOperationException - if the current element is not a sequence or choice
      NotFoundException - if the schema does not identify a name sub-element of the current sequence or choice element or if the element identified by name has already been set
      InvalidConversionException - if value cannot be converted to the type specified by the schema for the name sub-element
      IllegalStateException - if the operating stack is empty