public interface Publisher
source
handlers
or hybrid handlers
.
A instance of this type is provided by the framework when a
SourceHandler
(either a PollingSourceHandler
or
StreamingSourceHandler
) or a HybridHandler
is instantiated.
It provides methods for the handler to pass updates to the framework and on to Diffusion.
The publishing methods on this interface should only be called after the
service has been successfully started
and must
not publish if the service is paused
.
A PollingSourceHandler
should only publish updates when it is
polled
.
A HybridHandler
should only publish updates when its
update
method is called.
If any of the publishing methods complete exceptionally then the service
handler may choose to ignore (and possibly log) the error. However, it could
also pause the service using the StateHandler
. Depending upon the
nature of the exception the handler may get paused anyway.
A {link ServiceStateException} will occur if the handler attempts to publish
when the service is not in an ACTIVE
state.
A publisher instance is for the exclusive use of the service handler for
which it was created and may not be used across services or after the service
has been stopped
.
Modifier and Type | Method and Description |
---|---|
CompletableFuture<?> |
addMissingTopicHandler(String topicPath,
MissingTopicNotificationHandler missingTopicNotificationHandler)
Register a
MissingTopicNotificationHandler which will be notified if a
client subscription request matches no known topics and the selector
prefix of the subscription matches the specified branch of the topic
tree. |
CompletableFuture<?> |
applyJSONPatch(String path,
String patch)
Apply a JSON patch to a Diffusion topic value.
|
TopicProperties |
getConfiguredTopicProperties()
Returns a
TopicProperties with user-configured or default
topic properties for the service. |
CompletableFuture<?> |
publish(String path,
Object value)
Publishes a new value to Diffusion.
|
CompletableFuture<?> |
publish(String path,
Object value,
TopicProperties topicProperties)
Publishes a new value to Diffusion.
|
CompletableFuture<?> |
remove(String topics)
Remove a topic or topics.
|
CompletableFuture<?> |
removeMissingTopicHandler(String topicPath)
Removes
MissingTopicNotificationHandler registered for the
specified topicPath in the service. |
void |
setInitialJSONValueForPatchUpdates(String path,
String jsonValue)
Sets the initial value for a Diffusion JSON topic, to which subsequent patch
updates will be applied.
|
CompletableFuture<?> publish(String path, Object value) throws PayloadConversionException
The payload converter specified for the service will be applied to the supplied value in order to convert it to a Diffusion topic value. The order of updates to this method will be preserved in the topic updates. Therefore, this method should be called in the expected order of updates for a topic path, if order should be maintained.
path
- the topic pathvalue
- the unconverted valueIf the task completes successfully, the CompletableFuture result will be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.
If the task fails, the CompletableFuture will complete
exceptionally with a CompletionException
. Common reasons
for failure, listed by the exception reported as the
cause
, include:
DiffusionSecurityException
– if the application
principal does not have sufficient permissions to perform the
operation;
DiffusionClientException
– if some other
exception has been returned from the Diffusion server via the
Diffusion Client API. The cause will provide more detail.
ServiceStateException
– if the service state is
incompatible with the operation.
PayloadConversionException
- if the supplied value could not be
converted by the payload converter configured for the service, or
the value type is incompatible with the payload converterIllegalArgumentException
- if supplied path to publish update to is
not validCompletableFuture<?> publish(String path, Object value, TopicProperties topicProperties) throws PayloadConversionException
This method operates in a similar manner to
publish(String, Object)
, but it also provides an option to
specify TopicProperties
to be used for the supplied topic.
Use this method in preference over publish(String, Object)
to create Diffusion topics of specific types.
An application user can set topic properties for topics to be
created by a source service in the service configuration or default
values are applied. A TopicProperties
instance that contains
user-configured or default topic properties can be accessed by using the
getConfiguredTopicProperties()
method, which is available after
the service handler is started. Any topic properties in this
configured topic properties instance can be overridden using any of
the helper methods in TopicProperties
and passed in this method.
The helper method in TopicProperties
, such as
TopicProperties.withTopicType(TopicType)
, returns an immutable
instance of `TopicProperties`. Hence, values should be overridden in
the last created `TopicProperties` instance to override multiple values.
An application user can also specify payload converters to be used for the updates to be published. If payload converters are specified in the service configuration, then any user defined configuration will take precedence and the passed topicProperties will be ignored. The configured payload converter will be used to convert the updates passed with this method. In this case, the output type of the converter used will define the type of Diffusion topic to be published.
If any payload converters are not specified by a user or in
SourceServiceProperties.Builder#payloadConverter(String)
}, a
default converter to produce data of the supplied topic type will be
used and topic properties specified in this method will take precedence.
If the topic properties passed with a previously published topic path
changes at runtime, the previously created topic should be removed using
remove(String)
before publishing again.
path
- the topic pathvalue
- the unconverted valuetopicProperties
- The topic properties to use to create the topic.
If many paths require the same
TopicProperties
then the same instance
should be used for efficiency.If the task completes successfully, the CompletableFuture result will be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.
If the task fails, the CompletableFuture will complete
exceptionally with a CompletionException
. Common reasons
for failure, listed by the exception reported as the
cause
, include:
DiffusionSecurityException
– if the application
principal does not have sufficient permissions to perform the
operation;
DiffusionClientException
– if some other
exception has been returned from the Diffusion server via the
Diffusion Client API. The cause will provide more detail.
ServiceStateException
– if the service state is
incompatible with the operation.
PayloadConversionException
- if the supplied value could not be
converted by the payload converter configured for the service, or
the value type is incompatible with the payload converter, or
if the supplied topic type does not match the value created by
the payload converter in the service configuration.IllegalArgumentException
- if the supplied path to publish the
update to is not validCompletableFuture<?> applyJSONPatch(String path, String patch) throws IncompatibleConfigurationException
This method may be used only with JSON
topics to
apply a patch to a Diffusion topic value.
Also this cannot be used if the service properties for the service
specify UpdateMode.STREAMING
.
path
- the topic pathpatch
- the JSON patch to applyIf the task completes successfully, the CompletableFuture result will be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.
If the task fails, the CompletableFuture will complete
exceptionally with a CompletionException
. Common reasons
for failure, listed by the exception reported as the
cause
, include:
DiffusionSecurityException
– if the application
principal does not have sufficient permissions to perform the
operation;
JSONPatchException
– if the patch failed to
apply;
DiffusionClientException
– if some other
exception has been returned from the Diffusion server via the
Diffusion Client API. The cause will provide more detail.
ServiceStateException
– if the service state is
incompatible with the operation.
IncompatibleConfigurationException
- if the topic type in the
service properties is not JSON
or
UpdateMode.STREAMING
is definedIllegalArgumentException
- if supplied path to publish update to is
not validto set
initial value for a Diffusion JSON topic, to which subsequent patch updates are
to be applied
CompletableFuture<?> remove(String topics)
This allows the SourceHandler
or HybridHandler
to remove
a Diffusion topic or topics that it may have previously created
regardless of any persistence policy in use. The topic could have been
created using a topic prefix configured by a user. Hence, this prefix
will be prepended to the passed topic before removing the topic.
Only topics that the application principal has sufficient permission to remove will be removed.
topics
- a single topic may be removed by simply specifying its
path. By specifying a path followed by a single / all topics below
the specified path will be removed. By specifying a path followed
by // all topics below the path and the topic at the path will be
removed.If the task completes successfully, the CompletableFuture result will be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.
If the task fails, the CompletableFuture will complete
exceptionally with a CompletionException
. Common reasons
for failure, listed by the exception reported as the
cause
, include:
DiffusionSecurityException
– if the application
principal does not have sufficient permissions to perform the
operation;
DiffusionClientException
– if some other
exception has been returned from the Diffusion server via the
Diffusion Client API. The cause will provide more detail.
ServiceStateException
– if the service state is
incompatible with the operation.
IllegalArgumentException
- if topics
is not a valid
topic selector.void setInitialJSONValueForPatchUpdates(String path, String jsonValue)
This method will only register the initial value for path in memory,
which will be used when applyJSONPatch(String, String)
method
is called.
If applyJSONPatch(String, String)
fails because topic does
not exist, the topic will be created using the value set in this
method.
This method should be used before applyJSONPatch(String, String)
is called, so that if the topic to
send patch to, does not exist, framework will create a JSON topic with
specified JSON value.
If this method is called multiple times, value set in last method call will be applied.
If this method is not called before applying patch to a JSON topic, and the topic does not exist, the topic will be created with '{}' as initial value.
path
- Diffusion topic path to which initial value is to be set.jsonValue
- JSON string value to be set as initial value when
creating the JSON topic.IllegalArgumentException
- if supplied jsonValue is not valid
JSON dataCompletableFuture<?> addMissingTopicHandler(String topicPath, MissingTopicNotificationHandler missingTopicNotificationHandler)
MissingTopicNotificationHandler
which will be notified if a
client subscription request matches no known topics and the selector
prefix of the subscription matches the specified branch of the topic
tree.
Ideally, this method in Publisher
should be called when starting
the SourceHandler
which contains the publisher.
The provided handler is called when another session subscribes a topic selector which does not match any topics and the selector prefix of the subscription matches the specified branch of the topic tree for which the handler is registered.
topicPath
- identifies a branch of the topic treemissingTopicNotificationHandler
- the handler to use for notifying
topic subscription at or below the topicPath
(unless there is
another handler registered for a more specific topic path)If the task completes successfully, the CompletableFuture result will be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.
If the task fails, the CompletableFuture will complete exceptionally
with a CompletionException
. Common reasons for failure,
listed by the exception reported as the cause
, include:
DiffusionSecurityException
– if the application
principal does not have REGISTER_HANDLER
permission;
DiffusionClientException
– if some other
exception has been returned from the Diffusion server via the
Diffusion Client API. The cause will provide more detail.
IllegalStateException
- if there is an attempt to add a handler for a
topicPath, for which another handler is already registered,
in same service.CompletableFuture<?> removeMissingTopicHandler(String topicPath)
MissingTopicNotificationHandler
registered for the
specified topicPath in the service.
This method can be used to remove handler registration and stop getting missing topic notifications for the topic path.
topicPath
- topic path for which
MissingTopicNotificationHandler
should be removedIf the task completes successfully, the CompletableFuture result will be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.
If the task fails, the CompletableFuture will complete exceptionally
with a CompletionException
. Common reasons for failure,
listed by the exception reported as the cause
, include:
DiffusionClientException
– if some other
exception has been returned from the Diffusion server via the
Diffusion Client API. The cause will provide more detail.
TopicProperties getConfiguredTopicProperties()
TopicProperties
with user-configured or default
topic properties for the service.
If this method is accessed before ServiceHandler.start()
is
called, it will return null.
TopicProperties
instance with user-configured or default values.Copyright © 2024 DiffusionData Limited. All rights reserved.