CustomPublisher (gateway-framework-api 2.2.0

java.lang.Object
- com.diffusiondata.gateway.framework.CustomPublisher

All Implemented Interfaces:

Publisher
```
public abstract class CustomPublisher
extends Object
implements Publisher
```
An extension of a Publisher that enables overriding default publication by a Gateway application.
Normally, within a source or hybrid ServiceHandler in a Gateway application Publisher.publish(String, Object) method is called to publish an update to a Diffusion topic. This default behavior in the application can be overridden by configuring a service to use a CustomPublisher. An implementation of CustomPublisher can be plugged into the application to handle the pre-processing of an update and perform any operations provided by the Publisher. For example, dividing a single update into multiple updates, enriching those updates and publishing them to multiple Diffusion topics or removing a Diffusion topic based on the update.
Using a CustomPublisher is an advanced option and is sensible when the update pre-processing implementation needs to be reused in multiple Gateway applications or the default publication mechanism in an already existing application needs to be overridden. Hence, this feature is supported in the Gateway applications supplied by DiffusionData Limited to enable overriding default publication. An externally written developer application that needs to pre-process an update can do so by simply using a Publisher.
Similar to the PayloadConverter, the implementation of this CustomPublisher can be provided in a standalone JAR. This can then be used with a Gateway application by supplying it in the classpath when starting the application. Thus, such JAR can be reused with multiple applications if both the application and the CustomPublisher are compatible with each other. This means if the application supports using the CustomPublisher and the CustomPublisher can handle updates supplied by the application.
If the implementation of this CustomPublisher is available in the classpath and an application user has configured a service to use a custom publisher, then the framework will supply an instance of this custom publisher to `add` methods of the GatewayApplication for source and hybrid service types. This should be cast into a CustomPublisher and used to process the update that the source or hybrid service receives.

Author:

DiffusionData Limited

See Also:

Publisher

Constructor Summary

Constructors
Constructor and Description

CustomPublisher(Publisher publisher)
Constructor to create an instance of CustomPublisher.

Constructors
Constructor and Description
`CustomPublisher(Publisher publisher)` Constructor to create an instance of `CustomPublisher`.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
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.
`String`	`getApplicationType()` Returns the type of the Gateway application that uses the Custom publisher.
`TopicProperties`	`getConfiguredTopicProperties()` Returns a `TopicProperties` with user-configured or default topic properties for the service.
`abstract CompletableFuture<?>`	`process(Map<String,Object> context, Object update)` Processes the supplied update to publish to Diffusion topics.
`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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - CustomPublisher
```
public CustomPublisher(Publisher publisher)
```
    Constructor to create an instance of CustomPublisher.
    The Framework uses reflection to instantiate the subclass by injecting a Publisher instance into the constructor of the subclass. The subclass should supply this instance of the publisher to its super constructor. The instance of the subclass thus created will then be supplied to the `add` methods of the GatewayApplication for source and hybrid service types, which will then be used to process the updates.
    If the subclass requires a Map context for its construction, the signature of the constructor can also include a Map, after Publisher, containing keys of String type and values of Object type. The framework then extracts the configured context for the CustomPublisher in the service configuration and supplies it to the constructor.
    
    Parameters:
    
    publisher - the publisher instance that is used to delegate all operations supported by the Publisher.
- Method Detail
  - process
```
public abstract CompletableFuture<?> process(Map<String,Object> context,
                                             Object update)
                                      throws PayloadConversionException
```
    Processes the supplied update to publish to Diffusion topics.
    The implementation of this method can call all the Publisher methods via the abstract superclass.
    The payload converter specified for the service will be applied to the final value that is supplied to the Publisher.publish(String, Object, TopicProperties) or Publisher.publish(String, Object) method to convert it to a Diffusion topic value. Hence, the implementation of this interface should clarify what happens in this method and what type of updates will be supplied to the Publisher.publish(String, Object, TopicProperties) or Publisher.publish(String, Object) methods.
    
    Parameters:
    
    context - the Gateway application-specific and update-specific context that can be used to process the update. The context provided by different applications can be different. Hence, the custom publisher should handle them accordingly, and if any required context is absent, an IllegalArgumentException should be thrown. The application manual can be consulted to understand if it supports using a custom publisher and context it supplies.
    
    update - the update to process.
    
    Returns:
    
    a CompletableFuture that completes when processing the update completes.
    To indicate success, the completable future should complete successfully with a null value. If a call to a Publisher method completes exceptionally then that future can be returned. If any other processing error occurs, the method should return an exceptionally completed future with a suitable exception.
    
    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.
  - getApplicationType
```
public final String getApplicationType()
```
    Returns the type of the Gateway application that uses the Custom publisher.
    
    Returns:
    
    the Gateway application type
  - publish
```
public final CompletableFuture<?> publish(String path,
                                          Object value)
                                   throws PayloadConversionException
```
    Description copied from interface: Publisher
    
    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.
    Specified by:
    
    publish in interface Publisher
    
    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
  - publish
```
public final CompletableFuture<?> publish(String path,
                                          Object value,
                                          TopicProperties topicProperties)
                                   throws PayloadConversionException
```
    Description copied from interface: Publisher
    
    Publishes a new value to Diffusion.
    This method operates in a similar manner to Publisher.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 Publisher.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 Publisher.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 Publisher.remove(String) before publishing again.
    Specified by:
    
    publish in interface Publisher
    
    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.
  - applyJSONPatch
```
public final CompletableFuture<?> applyJSONPatch(String path,
                                                 String patch)
                                          throws IncompatibleConfigurationException
```
    Description copied from interface: Publisher
    
    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.
    Specified by:
    
    applyJSONPatch in interface Publisher
    
    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
    
    See Also:
    
    to set initial value for a Diffusion JSON topic, to which subsequent patch updates are to be applied
  - remove
```
public final CompletableFuture<?> remove(String topics)
```
    Description copied from interface: Publisher
    
    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.
    Specified by:
    
    remove in interface Publisher
    
    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
```
public final void setInitialJSONValueForPatchUpdates(String path,
                                                     String jsonValue)
```
    Description copied from interface: Publisher
    
    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 Publisher.applyJSONPatch(String, String) method is called. If Publisher.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 Publisher.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.
    
    Specified by:
    
    setInitialJSONValueForPatchUpdates in interface Publisher
    
    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.
  - addMissingTopicHandler
```
public final CompletableFuture<?> addMissingTopicHandler(String topicPath,
                                                         MissingTopicNotificationHandler missingTopicNotificationHandler)
```
    Description copied from interface: Publisher
    
    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.
    Specified by:
    
    addMissingTopicHandler in interface Publisher
    
    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.
  - removeMissingTopicHandler
```
public final CompletableFuture<?> removeMissingTopicHandler(String topicPath)
```
    Description copied from interface: Publisher
    
    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.
    Specified by:
    
    removeMissingTopicHandler in interface Publisher
    
    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
```
public final TopicProperties getConfiguredTopicProperties()
```
    Description copied from interface: Publisher
    
    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.
    
    Specified by:
    
    getConfiguredTopicProperties in interface Publisher
    
    Returns:
    
    A TopicProperties instance with user-configured or default values.

Class CustomPublisher

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CustomPublisher

Method Detail

process

getApplicationType

publish

publish

applyJSONPatch

remove

setInitialJSONValueForPatchUpdates

addMissingTopicHandler

removeMissingTopicHandler

getConfiguredTopicProperties