com.bloomberglp.blpapi
Class EventFormatter

java.lang.Object
  com.bloomberglp.blpapi.EventFormatter

public final class EventFormatter
extends java.lang.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 Summary

EventFormatter(Event event)
Creates an EventFormatter to add messages to the specified event.

Method Summary

void	appendElement() Append an empty complex element of the appropriate type to the element which represents an array of Element type.
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.
void	appendMessage(Name messageType, Topic topic, java.lang.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.
void	appendMessage(java.lang.String 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.
void	appendMessage(java.lang.String messageType, Topic topic, java.lang.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.
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.
void	appendRecapMessage(Topic topic, java.lang.Integer sequenceNumber, CorrelationID cid) Append a (empty) recap message that will be published under the specified 'topic' to the event referenced by this EventFormatter.
void	appendResponse(Name name) Append a (empty) response message of the specified 'name' that will be sent in response to previously received operation request.
void	appendResponse(java.lang.String messageType) Append a (empty) response message of the specified 'messageType' that will be sent in response to previously received operation request.
void	appendValue(boolean value) Append the specified 'value' to the element which represents an array of boolean type.
void	appendValue(char value) Append the specified 'value' to the element which represents an array of char type.
void	appendValue(Datetime value) Append the specified 'value' to the element which represents an array of Datetime type.
void	appendValue(double value) Append the specified 'value' to the element which represents an array of double type.
void	appendValue(float value) Append the specified 'value' to the element which represents an array of float type.
void	appendValue(int value) Append the specified 'value' to the element which represents an array of int type.
void	appendValue(long value) Append the specified 'value' to the element which represents an array of long type.
void	appendValue(Name value) Append the specified 'value' to the element which represents an array of Name type.
void	appendValue(java.lang.String value) Append the specified 'value' to the element which represents an array of String type.
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().
void	pushElement(Name name) Changes the level at which this EventFormatter is operating to the specified element 'name'.
void	pushElement(java.lang.String name) Changes the level at which this EventFormatter is operating to the specified element 'name'.
void	setElement(Name name, boolean value) Sets the element with the specified name within the current element to the specified value.
void	setElement(Name name, char value) Sets the element with the specified name within the current element to the specified value.
void	setElement(Name name, Datetime value) Sets the element with the specified name within the current element to the specified value.
void	setElement(Name name, double value) Sets the element with the specified name within the current element to the specified value.
void	setElement(Name name, float value) Sets the element with the specified name within the current element to the specified value.
void	setElement(Name name, int value) Sets the element with the specified name within the current element to the specified value.
void	setElement(Name name, long value) Sets the element with the specified name within the current element to the specified value.
void	setElement(Name name, Name value) Sets the element with the specified name within the current element to the specified value.
void	setElement(Name name, java.lang.String value) Sets the element with the specified name within the current element to the specified value.
void	setElement(java.lang.String name, boolean value) Sets the element with the specified name within the current element to the specified value.
void	setElement(java.lang.String name, char value) Sets the element with the specified name within the current element to the specified value.
void	setElement(java.lang.String name, Datetime value) Sets the element with the specified name within the current element to the specified value.
void	setElement(java.lang.String name, double value) Sets the element with the specified name within the current element to the specified value.
void	setElement(java.lang.String name, float value) Sets the element with the specified name within the current element to the specified value.
void	setElement(java.lang.String name, int value) Sets the element with the specified name within the current element to the specified value.
void	setElement(java.lang.String name, long value) Sets the element with the specified name within the current element to the specified value.
void	setElement(java.lang.String name, Name value) Sets the element with the specified name within the current element to the specified value.
void	setElement(java.lang.String name, java.lang.String value) Sets the element with the specified name within the current element to the specified value.
void	setElementNull(Name name) Creates a null element with the specified 'name'.
void	setElementNull(java.lang.String name) Creates a null element with the specified 'name'.

Methods inherited from class java.lang.Object

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

Constructor Detail

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 Detail

appendMessage

public void appendMessage(java.lang.String 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() methods.

Parameters:

messageType - the name of the message type that needs to be added

topic - the corresponding topic

appendMessage

public void appendMessage(java.lang.String messageType,
                          Topic topic,
                          java.lang.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

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,
                          java.lang.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,
                               java.lang.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

public void appendResponse(java.lang.String messageType)

Append a (empty) response message of the specified 'messageType' that will be sent in response to 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.

Parameters:

messageType - the name of the response type that needs to be added

appendResponse

public void appendResponse(Name name)

Append a (empty) response message of the specified 'name' that will be sent in response to 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.

Parameters:

name - the name of the response type that needs to be added

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(java.lang.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

public void pushElement(java.lang.String 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

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

public void setElement(java.lang.String name,
                       java.lang.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(String) instead.

Parameters:

name - the name of subfield

value - the value to be set

Throws:

java.lang.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

java.lang.IllegalStateException - if the operating stack is empty

setElement

public void setElement(java.lang.String 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(String) instead.

Parameters:

name - the name of subfield

value - the value to be set

Throws:

java.lang.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

java.lang.IllegalStateException - if the operating stack is empty

setElement

public void setElement(java.lang.String 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:

java.lang.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

java.lang.IllegalStateException - if the operating stack is empty

setElement

public void setElement(java.lang.String 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:

java.lang.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

java.lang.IllegalStateException - if the operating stack is empty

setElement

public void setElement(java.lang.String 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:

java.lang.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

java.lang.IllegalStateException - if the operating stack is empty

setElement

public void setElement(java.lang.String 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:

java.lang.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

java.lang.IllegalStateException - if the operating stack is empty

setElement

public void setElement(java.lang.String 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:

java.lang.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

java.lang.IllegalStateException - if the operating stack is empty

setElement

public void setElement(java.lang.String 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:

java.lang.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

java.lang.IllegalStateException - if the operating stack is empty

setElement

public void setElement(Name name,
                       java.lang.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:

java.lang.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

java.lang.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:

java.lang.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

java.lang.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:

java.lang.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

java.lang.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:

java.lang.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

java.lang.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:

java.lang.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

java.lang.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:

java.lang.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

java.lang.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:

java.lang.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

java.lang.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:

java.lang.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

java.lang.IllegalStateException - if the operating stack is empty

setElement

public void setElement(java.lang.String 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(String) instead.

Parameters:

name - the name of subfield

value - the value to be set

Throws:

java.lang.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

java.lang.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:

java.lang.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

java.lang.IllegalStateException - if the operating stack is empty

setElementNull

public void setElementNull(java.lang.String 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:

java.lang.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

java.lang.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:

java.lang.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

java.lang.IllegalStateException - if the operating stack is empty