Support for Google Protocol Buffers topics will be removed in a
future release as
universal topic data
of type BINARY
can
be used to distribute protocol buffer messages.
@Deprecated public interface PBTopicData extends PublishingTopicData
An instance of this type of data can be created using
TopicDataFactory.newPBData
.
The format of the data is described by a single Protocol Buffers message description which is specified when the data is created.
The data may be initialised in one of the following ways:
1) Assume defaults.
If not otherwise initialised then when the Topic Data is attached to a Topic
it will be initialised to all of the default values indicated by the Protocol
Buffer's message description.
2) From a Protocol Buffers Message.
Using initialise(AbstractMessage)
the data may be initialised to the
values from a specified Message of the same type as the data.
3) From a Diffusion Message.
Using
PublishingTopicData.initialise(com.pushtechnology.diffusion.api.message.TopicMessage)
the content of the specified Diffusion message is parsed into a Protocol
Buffers Message which is then used to initialise the data as above.
Updates to this data may occur via the
PublishingTopicData.update(com.pushtechnology.diffusion.api.message.TopicMessage)
method
or the update(AbstractMessage)
method. In the first case the Message
is expected to contain a Google Protocol Buffer message which will be parsed
using the description known to the data. In the latter case the message
passed must be of the same type as the data.
It is also possible to update and publish a delta in a single call of
PublishingTopicData.updateAndPublish(com.pushtechnology.diffusion.api.message.TopicMessage)
which will parse the incoming message using the Protocol Buffers message
description. Alternatively you could use
updateAndPublish(AbstractMessage)
which is the equivalent but
calling update(AbstractMessage)
to perform the updating.
The data that is input on an update is checked against the current data state
and a delta protocol buffer with only those fields that are different will be
generated. If there are no differences then no delta would be required. If
multiple updates are done within the same block then the update effect will
be cumulative in that the newly generated protocol buffers delta is merged
with any existing delta. When repeating fields are used it is important to
note that protocol buffers merges repeating fields by appending them. When
PublishingTopicData.generateDeltaMessage(String...)
is called then the message will be
populated with the cumulative protocol buffers delta.
The way in which messages provided for update are interpreted depends upon
the PBTopicData.UpdateMode
. In partial
mode the
messages are assumed to contain only those optional fields that are being
changed, whereas in full
mode the update messages are
assumed to contain the full Message (Topic) state.
When operating in PBTopicData.UpdateMode.FULL
then deletions of optional fields
are notified to the clients using a deletion value (see
setDeletionValue(String)
).
When operating in PBTopicData.UpdateMode.PARTIAL
then deletions of optional
fields can only be supported using deletion values. The deletion value can be
used in update messages to explicitly specify a deletion and then such
deletions will be notified to clients using the value.
Deletion of optional fields is only supported for fields of type 'string'. For any other types field deletion is not supported.
It should be noted that 'required' fields will always be sent in deltas and therefore to minimise message size their use is discouraged. Also, if an entry of a 'repeated' field or message is changed then all of the occurrences will be retransmitted in the delta.
Because of the limitations this type of Topic Data will work best if the
following recommendations regarding buffer definitions are observed:
1) All fields should be 'optional' as 'required' fields cannot be excluded
from deltas.
2) All optional fields should be of type 'string' as other types will not
support the notification of deletions.
3) 'repeated' fields or messages should not be used as all occurrences must
always be set in deltas.
Modifier and Type | Interface and Description |
---|---|
static class |
PBTopicData.UpdateMode
Deprecated.
The Update mode indicates how messages supplied to update the Topic Data
are interpreted.
|
Modifier and Type | Field and Description |
---|---|
static String |
DEFAULT_DELETION_VALUE
Deprecated.
This is the default deletion value that will be used if none is
explicitly specified.
|
Modifier and Type | Method and Description |
---|---|
String |
getDeletionValue()
Deprecated.
Returns the deletion value.
|
String |
getMessageName()
Deprecated.
The name of the message within the proto class that defines this data.
|
String |
getProtoClassName()
Deprecated.
The full name of the proto class used to create this Topic data.
|
com.google.protobuf.DynamicMessage |
getState()
Deprecated.
Gets the current state of the data as a DynamicMessage.
|
PBTopicData.UpdateMode |
getUpdateMode()
Deprecated.
Returns the update mode.
|
void |
initialise(com.google.protobuf.AbstractMessage initialMessage)
Deprecated.
Initialises the data with values from an input Protocol Buffers Message.
|
void |
setDeletionValue(String value)
Deprecated.
Allows a deletion value to be specified for use with 'string' type
optional fields.
|
void |
setUpdateMode(PBTopicData.UpdateMode mode)
Deprecated.
Set the update mode.
|
boolean |
update(com.google.protobuf.AbstractMessage message)
Deprecated.
Updates the data using a Protocol Buffers Message.
|
boolean |
updateAndPublish(com.google.protobuf.AbstractMessage message)
Deprecated.
As
PublishingTopicData.updateAndPublish(com.pushtechnology.diffusion.api.message.TopicMessage)
but calling update(AbstractMessage) to perform the updating. |
abortUpdate, addListener, asString, endUpdate, generateAckDeltaMessage, generateDeltaMessage, getInitialiser, getLastUpdateTimeMillis, getLoadHeaders, getLoadMessage, hasChanges, hasSlaves, initialise, isDeltaAckRequired, isLoadAckRequired, isSlave, publishExclusiveMessage, publishExclusiveMessage, publishMessage, publishMessage, removeListener, setDeltaAckRequired, setInitialiser, setLoadAckRequired, setLoadHeaders, startUpdate, update, updateAndPublish, updateAndPublish, updateAndPublishFromDelta
getDeltaEncoding, getLoadEncoding, getLoadMessage, getTopic, getType, hasSubscribers, isCommand, isLockedByCurrentThread, isPaged, isPublishing, isRouting, isService, lock, setDeltaEncoding, setLoadEncoding, unlock
getMetadataNode, isMetadataMandatory, setMetadataNode
static final String DEFAULT_DELETION_VALUE
String getProtoClassName()
This is the value that would have been specified to
TopicDataFactory.newPBData
when creating the data.
String getMessageName()
This is the value that would have been specified to
TopicDataFactory.newPBData
when creating the data.
void setUpdateMode(PBTopicData.UpdateMode mode) throws APIException
If the mode is not explicitly set then PBTopicData.UpdateMode.PARTIAL
is
assumed
mode
- the update modeAPIException
- if an attempt is made to set the mode after the data
has been attached to a topicPBTopicData.UpdateMode
PBTopicData.UpdateMode getUpdateMode()
void setDeletionValue(String value) throws APIException
The purpose of this value is to allow a value which will be interpreted as meaning that an optional field has been removed.
When operating in PBTopicData.UpdateMode.FULL
then when input messages do not
have values for optional string fields and the current Topic state does
then it is assumed that the field is being removed and notification of
this removal will be passed to the client by sending the field with this
value.
When operating in PBTopicData.UpdateMode.PARTIAL
then is possible to use the
deletion value to indicate the removal of a field in the update message
and then field removal will be notified to the clients using the same
value.
If no value is explicitly specified then DEFAULT_DELETION_VALUE
is assumed.
value
- the deletion value which may be one or more characters which
the client can interpret as meaning that an optional field has
been removed.APIException
- if an attempt is made to set the deletion value
after the data has been attached to a Topic.String getDeletionValue()
setDeletionValue(String)
void initialise(com.google.protobuf.AbstractMessage initialMessage) throws APIException
initialMessage
- the message representing the initial state of the
data. This must be of the same Message type as that of the data.APIException
- if unable to initialise the data.boolean update(com.google.protobuf.AbstractMessage message) throws APIException
This is similar to the
PublishingTopicData.update(com.pushtechnology.diffusion.api.message.TopicMessage)
method except that it updates from a Protocol Buffers message.
This may only be called from within an update block (see
PublishingTopicData.startUpdate()
).
message
- the message which must be of the same type as that of the
data.APIException
- if unable to perform the update. After such an
exception the update can not continue and when
endUpdate
is called the data state will be
reverted to its state before startUpdate
was called.boolean updateAndPublish(com.google.protobuf.AbstractMessage message) throws TimeoutException, APIException
PublishingTopicData.updateAndPublish(com.pushtechnology.diffusion.api.message.TopicMessage)
but calling update(AbstractMessage)
to perform the updating.message
- the message which must be of the same type as that of the
data.TimeoutException
- if the lock
timeout
period for the Topic has been exceeded whilst waiting to
obtain a lock on the data.APIException
- if unable to perform the update or publish a delta.
If this occurs then the data will still be in the same state as
before the call.com.google.protobuf.DynamicMessage getState() throws TimeoutException, APIException
This will return the current committed state. If called before any initialisation has taken place then the state will first be initialised to the default state as described by the Message descriptor.
If called during an update block this will return the state as it was at the start of the block and not the current updated state.
TimeoutException
- if the lock
timeout
period for the Topic has been exceeded whilst waiting to
obtain a lock on the data.APIException
- if unable to obtain the current state.Copyright © 2016 Push Technology Ltd. All Rights Reserved.