com.diffusiondata.gateway.framework

Interface Publisher

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.
CompletableFuture<?>	publish(String path, Object value) Publish 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 JSON topic, to which subsequent patch updates will be applied.

Method Detail

publish

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

Publish a new value to Diffusion.

The payload convertor specified for the service will be applied to the supplied value in order to convert it to a Diffusion topic value.

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 convertor configured for the service, or the value type is incompatible with the payload convertor

IllegalArgumentException - if supplied path to publish 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 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.

setInitialJSONValueForPatchUpdates

void setInitialJSONValueForPatchUpdates(String path,
                                        String jsonValue)

Sets the initial value for a 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.