com.diffusiondata.gateway.framework

Interface Publisher

All Known Implementing Classes:

CustomPublisher

public interface Publisher

Allows updates to be published to Diffusion by 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.

Author:

DiffusionData Limited

Method Summary

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.

Method Detail

publish

CompletableFuture<?> publish(String path,
                             Object value)
                      throws PayloadConversionException

Publishes a new value to Diffusion.

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.

Parameters:

path - the topic path

value - the unconverted value

Returns:

a CompletableFuture that completes when a response is received from the Diffusion server.

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.

Throws:

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

IllegalArgumentException - if supplied path to publish update to is not valid

publish

CompletableFuture<?> publish(String path,
                             Object value,
                             TopicProperties topicProperties)
                      throws PayloadConversionException

Publishes a new value to Diffusion.

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.

Parameters:

path - the topic path

value - the unconverted value

topicProperties - 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.

Returns:

a CompletableFuture that completes when a response is received from the Diffusion server.

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.

Throws:

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 valid

applyJSONPatch

CompletableFuture<?> applyJSONPatch(String path,
                                    String patch)
                             throws IncompatibleConfigurationException

Apply a JSON patch to a Diffusion topic value.

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.

Parameters:

path - the topic path

patch - the JSON patch to apply

Returns:

a CompletableFuture that completes when a response is received from the Diffusion server.

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;
• 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.

Throws:

IncompatibleConfigurationException - if the topic type in the service properties is not JSON or UpdateMode.STREAMING is defined

IllegalArgumentException - if supplied path to publish update to is not valid

See Also:

to set initial value for a Diffusion JSON topic, to which subsequent patch updates are to be applied

remove

CompletableFuture<?> remove(String topics)

Remove a topic or 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.

Parameters:

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.

Returns:

a CompletableFuture that completes when a response is received from the Diffusion server.

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.

Throws:

IllegalArgumentException - if topics is not a valid topic selector.

setInitialJSONValueForPatchUpdates

void setInitialJSONValueForPatchUpdates(String path,
                                        String jsonValue)

Sets the initial value for a Diffusion JSON topic, to which subsequent patch updates will be applied.

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.

Parameters:

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.

Throws:

IllegalArgumentException - if supplied jsonValue is not valid JSON data

addMissingTopicHandler

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.

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.

Parameters:

topicPath - identifies a branch of the topic tree

missingTopicNotificationHandler - 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)

Returns:

a CompletableFuture that completes when the handler registration is complete.

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.

Throws:

IllegalStateException - if there is an attempt to add a handler for a topicPath, for which another handler is already registered, in same service.

removeMissingTopicHandler

CompletableFuture<?> removeMissingTopicHandler(String topicPath)

Removes 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.

Parameters:

topicPath - topic path for which MissingTopicNotificationHandler should be removed

Returns:

a CompletableFuture that completes when the registered handler is 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:

• DiffusionClientException – if some other exception has been returned from the Diffusion server via the Diffusion Client API. The cause will provide more detail.

getConfiguredTopicProperties

TopicProperties getConfiguredTopicProperties()

Returns a 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.

Returns:

A TopicProperties instance with user-configured or default values.