org.forgerock.openam.services.push

Interface PushNotificationDelegate

All Superinterfaces:

AutoCloseable, Closeable

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 PushNotificationDelegate.send(PushMessage) and provides methods to retrieve its service for replies to respond at via PushNotificationDelegate.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 PushNotificationDelegate.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 PushNotificationDelegate.isRequireNewDelegate(PushNotificationServiceConfig).

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 PushNotificationDelegate.updateDelegate(PushNotificationServiceConfig).

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 PushNotificationDelegate.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 PushNotificationDelegate.getMessageTypeEndpoint(MessageType) method.

See Also:

AbstractPushNotificationDelegate

Method Summary

Modifier and Type	Method and Description
MessageDispatcher	getMessageDispatcher() Returns the MessageDispatcher for this delegate.
Map<MessageType,ClusterMessageHandler>	getMessageHandlers() Returns a set of message handlers required by this delegate for the appropriate DefaultMessageTypes.
Map<MessageType,Set<Predicate>>	getMessagePredicates() Returns a set of message predicates required by this delegate for the appropriate DefaultMessageTypes.
String	getMessageTypeEndpoint(MessageType messageType) Returns the (public, relative) service location of this MessageType - if appropriate.
boolean	isRequireNewDelegate(PushNotificationServiceConfig 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(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(PushNotificationServiceConfig newConfig) Updates the existing delegate's config.

Methods inherited from interface java.io.Closeable

close

Method Detail

startServices

void startServices()

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:

PushNotificationException - if there were any issues starting the service.

send

void send(PushMessage message)

Used to send a message out to the PushNotificationDelegate to be delivered.

Parameters:

message - The message to send.

isRequireNewDelegate

boolean isRequireNewDelegate(PushNotificationServiceConfig 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(PushNotificationServiceConfig 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(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

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<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<MessageType,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.