/* * SIP Communicator, the OpenSource Java VoIP and Instant Messaging client. * * Distributable under LGPL license. * See terms of license at gnu.org. */ package net.java.sip.communicator.service.notification; import java.util.*; /** * 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. * * @todo write an example once we have completed the definition of the service. * * @author Emil Ivov * @author Yana Stamcheva */ public interface NotificationService { /** * The log message action type indicates that a message would be logged, * when a notification is fired. */ public static final String ACTION_LOG_MESSAGE = "LogMessageAction"; /** * The popup message action type indicates that a window (or a systray * popup), containing the corresponding notification message would be poped * up, when a notification is fired. */ public static final String ACTION_POPUP_MESSAGE = "PopupMessageAction"; /** * The sound action type indicates that a sound would be played, when a * notification is fired. */ public static final String ACTION_SOUND = "SoundAction"; /** * The command action type indicates that a command would be executed, * when a notification is fired. */ public static final String ACTION_COMMAND = "CommandAction"; /** * Creates a SoundNotificationHandler, by specifying the * path pointing to the sound file and the loop interval if the sound should * be played in loop. If the sound should be played just once the loop * interval should be set to -1. The SoundNotificationHandler is * the one that would take care of playing the sound, when a notification * is fired. * * @param soundFileDescriptor the path pointing to the sound file * @param loopInterval the interval of milliseconds to repeat the sound in * loop * @return the SoundNotificationHandler is the one, that would take * care of playing the given sound, when a notification is fired */ public SoundNotificationHandler createSoundNotificationHandler( String soundFileDescriptor, int loopInterval); /** * Creates a PopupMessageNotificationHandler, by specifying the * default message to show, when no message is provided to the * fireNotification method. The * PopupMessageNotificationHandler is the one that would take care * of showing a popup message (through the systray service for example), * when a notification is fired. * * @param defaultMessage the message to show if not message is provided to * the fireNotification method * @return the PopupMessageNotificationHandler is the one, that * would take care of showing a popup message (through the systray service * for example), when a notification is fired. */ public PopupMessageNotificationHandler createPopupMessageNotificationHandler( String defaultMessage); /** * Creates a LogMessageNotificationHandler, by specifying the * type of the log (error, trace, info, etc.). The * LogMessageNotificationHandler is the one that would take care * of logging a message (through the application log system), when a * notification is fired. * * @param logType the type of the log (error, trace, etc.). One of the types * defined in the LogMessageNotificationHandler interface * @return the LogMessageNotificationHandler is the one, that would * take care of logging a message (through the application log system), when * a notification is fired. */ public LogMessageNotificationHandler createLogMessageNotificationHandler( String logType); /** * Creates a CommandNotificationHandler, by specifying the path to * the command file to execute, when a notification is fired. The * CommandNotificationHandler is the one that would take care * of executing the given program, when a notification is fired. * * @param commandFileDescriptor the path to the file containing the program * to execute * @return the CommandNotificationHandler is the one, that would * take care of executing a program, when a notification is fired. */ public CommandNotificationHandler createCommandNotificationHandler( String commandFileDescriptor); /** * 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 and the corresponding handler that should be used to * handle the action. Unlike the other registerNotificationForEvent * method, this one allows the user to specify its own * NotificationHandler, which would be used to handle notifications * for the specified actionType. * * @param eventType the name of the event (as defined by the plug-in that's * registering it) that we are setting an action for. * @param actionType the type of the action that is to be executed when the * specified event occurs (could be one of the ACTION_XXX fields). * @param handler the NotificationActionHandler, which would be * used to perform the notification action. * @throws IllegalArgumentException if the specified handler do not * correspond to the given actionType. */ public void registerNotificationForEvent( String eventType, String actionType, NotificationActionHandler handler) throws IllegalArgumentException; /** * 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 and the corresponding handler that should be used to * handle the action. Unlike the other * registerDefaultNotificationForEvent * method, this one allows the user to specify its own * NotificationHandler, which would be used to handle notifications * for the specified actionType. * 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. * * @param eventType the name of the event (as defined by the plug-in that's * registering it) that we are setting an action for. * @param actionType the type of the action that is to be executed when the * specified event occurs (could be one of the ACTION_XXX fields). * @param handler the NotificationActionHandler, which would be * used to perform the notification action. * @throws IllegalArgumentException if the specified handler do not * correspond to the given actionType. */ public void registerDefaultNotificationForEvent( String eventType, String actionType, NotificationActionHandler handler) throws IllegalArgumentException; /** * 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 twice the same actionType for the same * eventType 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. * * @param eventType the name of the event (as defined by the plug-in that's * registering it) that we are setting an action for. * @param actionType the type of the action that is to be executed when the * specified event occurs (could be one of the ACTION_XXX fields). * @param 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. * @param defaultMessage the default message to use if no specific message * has been provided when firing the notification. */ public void registerDefaultNotificationForEvent( 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 twice the same actionType for the same * eventType however would cause the first setting to be * overridden. * * @param eventType the name of the event (as defined by the plug-in that's * registering it) that we are setting an action for. * @param actionType the type of the action that is to be executed when the * specified event occurs (could be one of the ACTION_XXX fields). * @param 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. * @param defaultMessage the default message to use if no specific message * has been provided when firing the notification. */ public void registerNotificationForEvent( String eventType, String actionType, String actionDescriptor, String defaultMessage); /** * Deletes all registered events and actions * and registers and saves the default events as current. */ public void restoreDefaults(); /** * 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. * * @param eventType the name of the event (as defined by the plugin that's * registering it) to be removed. */ public void removeEventNotification(String eventType); /** * 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. * * @param eventType the name of the event (as defined by the plugin that's * registering it) for which we'll remove the notification. * @param actionType the type of the action that is to be executed when the * specified event occurs (could be one of the ACTION_XXX fields). */ public void removeEventNotificationAction( String eventType, String actionType); /** * 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). * * @return an iterator over a list of all events registered in this * notifications service */ public Iterator getRegisteredEvents(); /** * Returns a Map containing all action types (as keys) and actionDescriptors * (as values) that have been registered for eventType. *

* This method returns null if the given eventType is not * contained in the list of registered event types. * * @param eventType the name of the event that we'd like to retrieve actions * for. * @return a Map containing the actionTypes (as keys) and * actionHandlers (as values) that should be executed when * an event with the specified name has occurred, or null if no actions * have been defined for eventType. */ public Map getEventNotifications( String eventType); /** * Returns the NotificationActionHandler corresponding to the given * event and action types. *

* This method returns null if the given eventType or * actionType are not contained in the list of registered types. * * @param eventType the type of the event that we'd like to retrieve. * @param actionType the type of the action that we'd like to retrieve a * descriptor for. * @return the NotificationActionHandler corresponding to the given * event and action types */ public NotificationActionHandler getEventNotificationActionHandler( String eventType, String actionType); /** * Registers a listener that would be notified of changes that have occurred * in the registered event notifications. * * @param listener the listener that we'd like to register for changes in * the event notifications stored by this service. */ public void addNotificationChangeListener( 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. * * @param listener the listener to remove. */ public void removeNotificationChangeListener( NotificationChangeListener listener); /** * 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. * * @param eventType the type of the event that we'd like to fire a * notification for. * @param messageTitle the message title to use if and where appropriate * (e.g. with systray) * @param message the message to use if and where appropriate (e.g. with * systray or log notification.) * @param icon the icon to show in the notification if and where * appropriate * @param tag additional info to be used by the notification handler */ public void fireNotification( String eventType, String messageTitle, String message, byte[] icon, Object tag); /** * 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. * * @param eventType the type of the event that we'd like to fire a * notification for. */ public void fireNotification(String eventType); /** * 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. * * @param eventType the name of the event, which actions should be activated * /deactivated. * @param isActive indicates whether to activate or deactivate the actions * related to the specified eventType. */ public void setActive(String eventType, boolean isActive); /** * 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. * * @param eventType the name of the event (as defined by the plugin that's * registered it) that we are checking. * @return 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. */ public boolean isActive(String eventType); }