Package org.forgerock.openam.services.push

Interface PushNotificationDelegate

  • All Superinterfaces:
    AutoCloseable, Closeable
    @SupportedAll
public interface PushNotificationDelegate
extends Closeable

    A PushNotificationDelegate is an implementation of OpenAM's Push Notification Service PushNotificationService specific to a realm as generated by a PushNotificationDelegateFactory.

    It is used for sending messages out via a Push service provider (such as Amazon's SNS) via send(PushMessage) and provides methods to retrieve its service for replies to respond at via getMessageTypeEndpoint(MessageType). Response messages should be handled by an endpoint or service and may use PushMessageResource to assist in ensuring messages return to the appropriate sender (either via local memory of via the CTS). A delegate should make its Predicates available via an appropriate mapping in getMessagePredicates() and ensure they are evaluated prior to response messages being returned to the appropriate place.

    The PushNotificationService is responsible for monitoring configuration changes and detecting when it should create new instances of any given PushNotificationDelegate. If a configuration change takes place, the service will ascertain whether a new instance is required by calling isRequireNewDelegate(PushNotificationServiceConfig.Realm).

    If a new instance is required, the previous instance will be shutdown by calling the Closeable.close() method before creating a new instance. If a new instance is not required then the existing instance will be updated by calling updateDelegate(PushNotificationServiceConfig.Realm).

    As of OpenAM 13.5, a default Amazon SNS-based endpoint SnsMessageResource is supplied with the system and enabled; which is provided via the SnsMessageResourceRouteProvider. The addition of routes during OpenAM operation is not yet supported, so CREST endpoint implementations should service-load their providers in.

    It is highly recommended that implementations of this interface who intend to utilise the ForgeRock Authenticator mobile app and associated ForgeRock Authenticator (Push) login module extend the abstract class AbstractPushNotificationDelegate.

    Implementations which operate without exposing a specific CREST endpoint may do so via the appropriate startServices() method. This service should be closed off via the Closeable.close() mechanism. A CREST resource-based implementation such as the provided Amazon SNS implementation does not require the explicit addition or removal of the endpoint via these methods.

    If a new exposed service or CREST endpoint is added, the location of this should be advertised via an appropriate mapping in the getMessageTypeEndpoint(MessageType) method.

    See Also:
    AbstractPushNotificationDelegate

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      org.forgerock.openam.services.push.dispatch.MessageDispatcher getMessageDispatcher()
      Returns the MessageDispatcher for this delegate.
      Map<org.forgerock.openam.services.push.MessageType,​org.forgerock.openam.services.push.dispatch.handlers.ClusterMessageHandler> getMessageHandlers()
      Returns a set of message handlers required by this delegate for the appropriate DefaultMessageTypes.
      Map<org.forgerock.openam.services.push.MessageType,​Set<Predicate>> getMessagePredicates()
      Returns a set of message predicates required by this delegate for the appropriate DefaultMessageTypes.
      String getMessageTypeEndpoint​(org.forgerock.openam.services.push.MessageType messageType)
      Returns the (public, relative) service location of this MessageType - if appropriate.
      boolean isRequireNewDelegate​(org.forgerock.openam.services.push.PushNotificationServiceConfig.Realm newConfig)
      Returns whether or not the new config is so different from the old that the existing delegate should be removed from the pool.
      void send​(org.forgerock.openam.services.push.PushMessage message)
      Used to send a message out to the PushNotificationDelegate to be delivered.
      void startServices()
      Starts any required services for this delegate.
      void updateDelegate​(org.forgerock.openam.services.push.PushNotificationServiceConfig.Realm newConfig)
      Updates the existing delegate's config.

    • Method Detail

      • startServices

        void startServices()
            throws org.forgerock.openam.services.push.PushNotificationException
        Starts any required services for this delegate. This may include e.g. listeners to specific ports. This method is called once after a new delegate is generated, but before it is made available for general use by the PushNotificationService.
        Throws:
        org.forgerock.openam.services.push.PushNotificationException - if there were any issues starting the service.

      • send

        void send​(org.forgerock.openam.services.push.PushMessage message)
        Used to send a message out to the PushNotificationDelegate to be delivered.
        Parameters:
        message - The message to send.

      • isRequireNewDelegate

        boolean isRequireNewDelegate​(org.forgerock.openam.services.push.PushNotificationServiceConfig.Realm newConfig)
        Returns whether or not the new config is so different from the old that the existing delegate should be removed from the pool.
        Parameters:
        newConfig - The new configuration to check against the old.
        Returns:
        True if the configuration change requires the PushNotificationService to instantiate a new instance of this delegate.

      • updateDelegate

        void updateDelegate​(org.forgerock.openam.services.push.PushNotificationServiceConfig.Realm newConfig)
        Updates the existing delegate's config. Implementors must not alter the connection parameters of the delegate, but may alter extraneous information such as values added to static fields in the delegate's communicated messages.
        Parameters:
        newConfig - The new config from which to update the existing delegate.

      • getMessageTypeEndpoint

        String getMessageTypeEndpoint​(org.forgerock.openam.services.push.MessageType messageType)
        Returns the (public, relative) service location of this MessageType - if appropriate. Otherwise returns null.
        Parameters:
        messageType - The message type for the endpoint to return.
        Returns:
        The (public, relative) service location of this delegate as exposed to the world.

      • getMessageDispatcher

        org.forgerock.openam.services.push.dispatch.MessageDispatcher getMessageDispatcher()
        Returns the MessageDispatcher for this delegate. Used to get messages back to the originator when returned through a different medium.
        Returns:
        The MessageDispatcher for this delegate.

      • getMessagePredicates

        Map<org.forgerock.openam.services.push.MessageType,​Set<Predicate>> getMessagePredicates()
        Returns a set of message predicates required by this delegate for the appropriate DefaultMessageTypes.
        Returns:
        A map of message types to sets of predicate delegates.

      • getMessageHandlers

        Map<org.forgerock.openam.services.push.MessageType,​org.forgerock.openam.services.push.dispatch.handlers.ClusterMessageHandler> getMessageHandlers()
        Returns a set of message handlers required by this delegate for the appropriate DefaultMessageTypes.
        Returns:
        A map of message types to message handlers.