See CustomTopicData
.
@Deprecated public interface CustomTopicDataHandler
Custom Topic Data
.
The methods on this interface are called by the Custom Topic Data implementation and should not be called directly.
A handler may initialise the data state in any way that is suitable. The
initialisation of the data may occur when the handler is constructed or as a
result of the PublishingTopicData.initialise(TopicMessage)
method
being called which in turn will invoke initialise(TopicMessage)
.
Note that such a call could only occur before the data is attached to a
topic.
When the data is associated with a Topic the prepare()
method is
called to allow for initialisation to be performed (if not done already).
When an update block is started (either via
PublishingTopicData.startUpdate()
or as a result of
PublishingTopicData.updateAndPublish(TopicMessage)
) the
startUpdate()
method is called to allow the handler to prepare for
updating. This would typically involve taking a copy of the current state to
apply updates to such that it can be commited when endUpdate()
is
called or discarded if abortUpdate()
is called.
The data may be updated via messages in the normal way via
PublishingTopicData.update(TopicMessage)
which in turn would call
update(TopicMessage)
.
Alternatively the data may be updated in some other way, but if this is the case then it is important that it is done within update blocks.
If errors occur within updating then this should be reported to the Topic
Data using CustomTopicData.setUpdateErrors(boolean)
.
One or more updates may be applied before the update block ends (indicated by
endUpdate()
or abortUpdate()
. Updates should be applied to
a local/temporary copy of the state which would only be committed if the
update block ends successfully.
If the update is aborted then abortUpdate()
will be called to allow
the handler to discard updates.
However the data is updated it is important that the actual state of the data
is not updated until endUpdate()
is called.
The populateDelta(TopicMessage)
may be called within an update block
to write the delta to the message. This would only be called if
hasChanges()
returns true.
populateTopicLoad(TopicMessage)
will be called when a Topic Load is
required and should write the current actual state (not any temporary state)
to the message.
An abstract implementation of this interface which has default
implementations of optional methods is provided in
AbstractCustomTopicDataHandler
Modifier and Type | Method and Description |
---|---|
void |
abortUpdate()
Deprecated.
This is called when
PublishingTopicData.abortUpdate() is called. |
String |
asString()
Deprecated.
Renders the current state of the data as a String.
|
boolean |
endUpdate()
Deprecated.
This is called when
PublishingTopicData.endUpdate() is called. |
boolean |
hasChanges()
Deprecated.
This is called to determine whether there have been any changes to the
state of the data during the current update block.
|
void |
initialise(TopicMessage message)
Deprecated.
This is called if
PublishingTopicData.initialise(TopicMessage) is
used. |
void |
populateDelta(TopicMessage delta)
Deprecated.
This is called when
PublishingTopicData.generateDeltaMessage(String...) is called to
populate a new delta message with updates done in the current block. |
void |
populateTopicLoad(TopicMessage topicLoad)
Deprecated.
This will be called to populate an empty Topic Load message with the
current state of the data.
|
void |
prepare()
Deprecated.
This is called when the topic data that specifies the handler is attached
to a topic.
|
void |
setTopicData(CustomTopicData topicData)
Deprecated.
This is called when the data is first created to notify the handler of
the data it is associated with.
|
void |
startUpdate()
Deprecated.
This is called when
PublishingTopicData.startUpdate() is called. |
boolean |
update(TopicMessage message)
Deprecated.
This will be called to update the state of the data from an incoming
delta Message.
|
void setTopicData(CustomTopicData topicData)
topicData
- the topic datavoid initialise(TopicMessage message) throws APIException
PublishingTopicData.initialise(TopicMessage)
is
used.
The handler must parse the message and initialise its state accordingly.
This would only be called before the data is attached to a topic.
message
- the message to initialise fromAPIException
- if unable to initialisevoid prepare() throws APIException
This may be used to perform initialisation processing, possibly setting the initial state if it has not already been
APIException
- to notify a failure. If an exception is thrown the
topic will not be createdvoid populateTopicLoad(TopicMessage topicLoad) throws APIException
This will be called when a load message is needed. For example, the first
time PublishingTopicData.getLoadMessage()
is called after an
update.
This must populate the message with the 'actual' state and not any temporary state being maintained due to an update in progress.
topicLoad
- the empty message to populateAPIException
- used to report a failure to populate the messagevoid startUpdate() throws APIException
PublishingTopicData.startUpdate()
is called.
The data will have been locked before this is called.
Typically the handler would at this point prepare for one or more updates by taking a copy of the current state.
APIException
- to notify a failureboolean update(TopicMessage message) throws APIException
This is called as a result of
PublishingTopicData.update(TopicMessage)
being called.
This will be called one or more times after a call to
startUpdate()
. It should apply the update to the currently held
copy of the topic state.
This method must parse the message and update the state accordingly.
message
- the incoming message that is to be used to update the
state of the dataAPIException
- may be returned to indicate failure to update the
databoolean hasChanges()
If not within an update this should return false.
If there have been one or more updates during the current update block that have resulted in a change to the original state then this should return true.
void populateDelta(TopicMessage delta) throws APIException
PublishingTopicData.generateDeltaMessage(String...)
is called to
populate a new delta message with updates done in the current block.
This will only be called if hasChanges()
has returned true.
This should only be called at the end of the updating block.
delta
- an empty delta message to populateAPIException
- to notify a failure to write to the messagevoid abortUpdate() throws APIException
PublishingTopicData.abortUpdate()
is called.
It allows the handler to discard any updating done within an update block.
APIException
- to notify a failureboolean endUpdate() throws APIException
PublishingTopicData.endUpdate()
is called.
If there have been updates (hasChanges()
returns true) then this
should replace the current state of the data with the updated state.
hasChanges()
==true)APIException
- to notify a failureString asString()
This is purely used for logging or monitoring purposes.
Copyright © 2016 Push Technology Ltd. All Rights Reserved.