net.java.sip.communicator.service.notification
Interface NotificationService

All Known Implementing Classes:

NotificationServiceImpl

public interface NotificationService

This service is previewed for use by bundles that implement some kind of user notification (e.g. playing sounds, poping systray tooltips, or triggering commands.) In the case when such bundles would like to leave the user the possibility to enable/disable or configure these notifications they could register an event type in this Registry service.

Author:

Emil Ivov, Yana Stamcheva

To do:

write an example once we have completed the definition of the service.

Method Summary

void	addActionHandler(NotificationHandler handler) Adds an object that executes the actual action of a notification action.
void	addNotificationChangeListener(NotificationChangeListener listener) Registers a listener that would be notified of changes that have occurred in the registered event notifications.
NotificationData	fireNotification(String eventType) Fires all notifications registered for the specified eventType using the default message specified upon registration as a notification message wherever appropriate.
NotificationData	fireNotification(String eventType, String messageTitle, String message, byte[] icon, Object tag) Fires all notifications registered for the specified eventType using message as a notification message wherever appropriate (e.g.
NotificationData	fireNotification(String eventType, String messageTitle, String message, Map<String,String> extra, byte[] icon, Object tag) Fires all notifications registered for the specified eventType using message as a notification message wherever appropriate (e.g.
Iterable<NotificationHandler>	getActionHandlers(String actionType) Gets at list of handler for the specified action type.
NotificationAction	getEventNotificationAction(String eventType, String actionType) Returns the NotificationAction corresponding to the given event and action type.
Iterable<String>	getRegisteredEvents() Returns an iterator over a list of all events registered in this notification service.
boolean	isActive(String eventType) Indicates whether or not actions for the specified eventType are activated.
void	registerDefaultNotificationForEvent(String eventType, NotificationAction handler) Registers a default notification for the given eventType by specifying the action to be performed when a notification is fired for this event.
void	registerDefaultNotificationForEvent(String eventType, String actionType, String actionDescriptor, String defaultMessage) Registers a default notification for the given eventType by specifying the type of the action to be performed when a notification is fired for this event, the actionDescriptor for sound and command actions and the defaultMessage for popup and log actions.
void	registerNotificationForEvent(String eventType, NotificationAction action) Registers a notification for the given eventType by specifying the action to be performed when a notification is fired for this event.
void	registerNotificationForEvent(String eventType, String actionType, String actionDescriptor, String defaultMessage) Registers a notification for the given eventType by specifying the type of the action to be performed when a notification is fired for this event, the actionDescriptor for sound and command actions and the defaultMessage for popup and log actions.
void	removeActionHandler(String actionType) Removes an object that executes the actual action of notification action.
void	removeEventNotification(String eventType) Removes the given eventType from the list of event notifications.
void	removeEventNotificationAction(String eventType, String actionType) Removes the event notification corresponding to the specified actionType and eventType.
void	removeNotificationChangeListener(NotificationChangeListener listener) Remove the specified listener so that it won't receive further notifications of changes that occur with actions registered for events stored by this service.
void	restoreDefaults() Deletes all registered events and actions and registers and saves the default events as current.
void	setActive(String eventType, boolean isActive) Activates or deactivates all notification actions related to the specified eventType.

Method Detail

registerNotificationForEvent

void registerNotificationForEvent(String eventType,
                                  NotificationAction action)

Registers a notification for the given eventType by specifying the action to be performed when a notification is fired for this event. Unlike the other registerNotificationForEvent method, this one allows the user to specify its own NotificationAction, which would be used to handle notifications for the specified actionType.

Parameters:

eventType - the name of the event (as defined by the plug-in that's registering it) that we are setting an action for.

action - the NotificationAction, which would be used to perform the notification action.

registerDefaultNotificationForEvent

void registerDefaultNotificationForEvent(String eventType,
                                         NotificationAction handler)

Registers a default notification for the given eventType by specifying the action to be performed when a notification is fired for this event. Unlike the other registerDefaultNotificationForEvent method, this one allows the user to specify its own NotificationAction, which would be used to handle notifications. Default events are stored or executed at first run or when they are missing in the configuration. Also the registered default events are used when restoreDefaults is called.

Parameters:

eventType - the name of the event (as defined by the plug-in that's registering it) that we are setting an action for.

handler - the NotificationActionHandler, which would be used to perform the notification action.

registerDefaultNotificationForEvent

void registerDefaultNotificationForEvent(String eventType,
                                         String actionType,
                                         String actionDescriptor,
                                         String defaultMessage)

Registers a default notification for the given eventType by specifying the type of the action to be performed when a notification is fired for this event, the actionDescriptor for sound and command actions and the defaultMessage for popup and log actions. Actions registered by this method would be handled by some default NotificationHandlers, declared by the implementation.

The method allows registering more than one actionType for a specific event. Setting the same actionType for the same eventType twice however would cause the first setting to be overridden. Default events are stored or executed at first run or when they are missing in the configuration. Also the registered default events are used when restoreDefaults is called.

Parameters:

eventType - the name of the event (as defined by the plug-in that's registering it) that we are setting an action for.

actionType - the type of the action that is to be executed when the specified event occurs (could be one of the ACTION_XXX fields).

actionDescriptor - a String containing a description of the action (a URI to the sound file for audio notifications or a command line for exec action types) that should be executed when the action occurs.

defaultMessage - the default message to use if no specific message has been provided when firing the notification.

registerNotificationForEvent

void registerNotificationForEvent(String eventType,
                                  String actionType,
                                  String actionDescriptor,
                                  String defaultMessage)

Registers a notification for the given eventType by specifying the type of the action to be performed when a notification is fired for this event, the actionDescriptor for sound and command actions and the defaultMessage for popup and log actions. Actions registered by this method would be handled by some default NotificationHandlers, declared by the implementation.

The method allows registering more than one actionType for a specific event. Setting the same actionType for the same eventType twice however would cause the first setting to be overridden.

Parameters:

eventType - the name of the event (as defined by the plug-in that's registering it) that we are setting an action for.

actionType - the type of the action that is to be executed when the specified event occurs (could be one of the ACTION_XXX fields).

actionDescriptor - a String containing a description of the action (a URI to the sound file for audio notifications or a command line for exec action types) that should be executed when the action occurs.

defaultMessage - the default message to use if no specific message has been provided when firing the notification.

restoreDefaults

void restoreDefaults()

Deletes all registered events and actions and registers and saves the default events as current.

removeEventNotification

void removeEventNotification(String eventType)

Removes the given eventType from the list of event notifications. This means that we delete here all registered notifications for the given eventType.

This method does nothing if the given eventType is not contained in the list of registered event types.

Parameters:

eventType - the name of the event (as defined by the plugin that's registering it) to be removed.

removeEventNotificationAction

void removeEventNotificationAction(String eventType,
                                   String actionType)

Removes the event notification corresponding to the specified actionType and eventType.

This method does nothing if the given eventType or actionType are not contained in the list of registered types.

Parameters:

eventType - the name of the event (as defined by the plugin that's registering it) for which we'll remove the notification.

actionType - the type of the action that is to be executed when the specified event occurs (could be one of the ACTION_XXX fields).

getRegisteredEvents

Iterable<String> getRegisteredEvents()

Returns an iterator over a list of all events registered in this notification service. Each line in the returned list consists of a String, representing the name of the event (as defined by the plugin that registered it).

Returns:

an iterator over a list of all events registered in this notifications service

getEventNotificationAction

NotificationAction getEventNotificationAction(String eventType,
                                              String actionType)

Returns the NotificationAction corresponding to the given event and action type.

This method returns null if the given eventType or actionType are not contained in the list of registered types.

Parameters:

eventType - the type of the event that we'd like to retrieve.

actionType - the type of the action that we'd like to retrieve a descriptor for.

Returns:

the NotificationAction corresponding to the given event and action type

addNotificationChangeListener

void addNotificationChangeListener(NotificationChangeListener listener)

Registers a listener that would be notified of changes that have occurred in the registered event notifications.

Parameters:

listener - the listener that we'd like to register for changes in the event notifications stored by this service.

removeNotificationChangeListener

void removeNotificationChangeListener(NotificationChangeListener listener)

Remove the specified listener so that it won't receive further notifications of changes that occur with actions registered for events stored by this service.

Parameters:

listener - the listener to remove.

addActionHandler

void addActionHandler(NotificationHandler handler)

Adds an object that executes the actual action of a notification action.

Parameters:

handler - The handler that executes the action.

removeActionHandler

void removeActionHandler(String actionType)

Removes an object that executes the actual action of notification action.

Parameters:

actionType - The handler type to remove.

getActionHandlers

Iterable<NotificationHandler> getActionHandlers(String actionType)

Gets at list of handler for the specified action type.

Parameters:

actionType - the type for which the list of handlers should be retrieved or null if all handlers shall be returned.

Returns:

Iterable of NotificationHandler objects

fireNotification

NotificationData fireNotification(String eventType,
                                  String messageTitle,
                                  String message,
                                  byte[] icon,
                                  Object tag)

Fires all notifications registered for the specified eventType using message as a notification message wherever appropriate (e.g. systray notifications, logs, etc.)

This method does nothing if the given eventType is not contained in the list of registered event types.

Parameters:

eventType - the type of the event that we'd like to fire a notification for.

messageTitle - the message title to use if and where appropriate (e.g. with systray)

message - the message to use if and where appropriate (e.g. with systray or log notification.)

icon - the icon to show in the notification if and where appropriate

tag - additional info to be used by the notification handler

Returns:

An object referencing the notification. It may be used to stop a still running notification. Can be null if the eventType is unknown or the notification is not active.

fireNotification

NotificationData fireNotification(String eventType,
                                  String messageTitle,
                                  String message,
                                  Map<String,String> extra,
                                  byte[] icon,
                                  Object tag)

Fires all notifications registered for the specified eventType using message as a notification message wherever appropriate (e.g. systray notifications, logs, etc.)

This method does nothing if the given eventType is not contained in the list of registered event types.

Parameters:

eventType - the type of the event that we'd like to fire a notification for.

messageTitle - the message title to use if and where appropriate (e.g. with systray)

message - the message to use if and where appropriate (e.g. with systray or log notification.)

extra - the extra data to pass (especially for Command execution)

icon - the icon to show in the notification if and where appropriate

tag - additional info to be used by the notification handler

Returns:

An object referencing the notification. It may be used to stop a still running notification. Can be null if the eventType is unknown or the notification is not active.

fireNotification

NotificationData fireNotification(String eventType)

Fires all notifications registered for the specified eventType using the default message specified upon registration as a notification message wherever appropriate. (e.g. systray notifications, logs, etc.)

This method does nothing if the given eventType is not contained in the list of registered event types.

Parameters:

eventType - the type of the event that we'd like to fire a notification for.

Returns:

An object referencing the notification. It may be used to stop a still running notification. Can be null if the eventType is unknown or the notification is not active.

setActive

void setActive(String eventType,
               boolean isActive)

Activates or deactivates all notification actions related to the specified eventType. This method does nothing if the given eventType is not contained in the list of registered event types.

Parameters:

eventType - the name of the event, which actions should be activated /deactivated.

isActive - indicates whether to activate or deactivate the actions related to the specified eventType.

isActive

boolean isActive(String eventType)

Indicates whether or not actions for the specified eventType are activated. This method returns false if the given eventType is not contained in the list of registered event types.

Parameters:

eventType - the name of the event (as defined by the plugin that's registered it) that we are checking.

Returns:

true if actions for the specified eventType are activated, false - otherwise. If the given eventType is not contained in the list of registered event types - returns false.