Introduction

This doc explains how to fire custom events within SageAlert v2.x. SageAlert v2.x takes advantage of the new event model in SageTV v7.0 and allows plugins to easily fire custom events that SageAlert will listen for and act upon by sending configured notifications for all custom events. Custom events are automatically discovered and registered by SageAlert. Minimal effort is required by plugin developers to add custom event support to your plugins.

Install sagealert-common Plugin

The first step to adding SageAlert support to your plugin is to create your custom event classes that you will be firing within your plugin. In order for SageAlert to fire a custom event, the event must implement the com.google.code.sagetvaddons.sagealert.shared.SageAlertCustomEvent interface. You can install this interface by installing the sagealert-common plugin. Ensure your plugin depends on the sagealert-common plugin only. You do not have to depend on the sagealert plugin nor should you depend on it! The sagealert-common plugin is a tiny jar file that contains the common data structures and interfaces used by SageAlert and will only add ~12KB to your plugin installation. Only depending on sagealert-common means that if the user has SageAlert installed then your plugin will support it, if the user does not have SageAlert installed then there's no harm - it just means nothing will be listening for and acting on the events you fire.

WARNING: If you accidentally make your plugin depend on sagealert then installation of your plugin will force an install of sagealert and everything it depends on, including jetty and many other libraries. Do not make your plugin depend on sagealert. You've been warned!

Implement Custom SageAlert Events

Now you have to create the events you want SageAlert to handle. Create classes that implement the com.google.code.sagetvaddons.sagealert.shared.SageAlertCustomEvent interface. Only classes that implement this interface can be handled by SageAlert.

Details on this interface can be read from the javadocs for the SageAlertCustomEvent interface.

I believe the requirements are well documented there. Post a message in the user forums if I'm overlooking something.

Create sagealert.properties File

Once you've created your event classes, you must create a properties file for SageAlert to read and register your custom events.

In your plugin's configured resource path create a file called sagealert.properties, which is a standard Java properties file.

events is a comma separated list of unique event IDs your plugin will be firing. For each event id in this list you must provide the following lines (replace id with the unique id defined in the events property:

id_CLS= The full class name of the event being fired; an invalid class name will result in your plugin being skipped by SageAlert

id_DISPLAY= The friendly display name for your event; this is displayed in the SageAlert GUI

id_DESC= The descriptive text for your event; it is also displayed in the GUI

id_SUBJ= The default subject text for alerts generated by this event; users can customize this value

id_SHORT= The default short text for alerts; again, users can customize this

id_MED= The default medium text for alerts

id_LONG= The default long text for alerts

id_ARGTYPEn (where n is a number, starting at 0)= You must provide a description of each argument you will be providing to the API interpreter; typically this is just the class name of the arguement. The order you provide these in must also be the same order they are provided in the getArgs() method of your SageAlertCustomEvent implementation.

Below is the complete sagealert.properties file provided by the Custom Events plugin. Of note, the references to $n objects ($0, $1) represent the ARGTYPEn listed in the properties file below (i.e. $0 represents the minimum space value configured by the user and $1 represents the free space at the time the event fired).

# This file must be placed in your plugin's defined resource path!
events=CustomEvents_LowRecordingSpace
CustomEvents_LowRecordingSpace_CLS=com.google.code.sagetvaddons.customevents.LowRecordingSpaceEvent
CustomEvents_LowRecordingSpace_DISPLAY=Low Recording Space
CustomEvents_LowRecordingSpace_ARGTYPE0=java.lang.Long (min space)
CustomEvents_LowRecordingSpace_ARGTYPE1=java.lang.Long (free space)
CustomEvents_LowRecordingSpace_DESC=This event is fired when the total recording space available falls below the configured threshold.
CustomEvents_LowRecordingSpace_SUBJ=Recording space is low
CustomEvents_LowRecordingSpace_SHORT=There is less than $0.toString() available on your system's recording drives! [$1.toString() free]
CustomEvents_LowRecordingSpace_MED=There is less than $0.toString() available on your system's recording drives! [$1.toString() free]
CustomEvents_LowRecordingSpace_LONG=There is less than $0.toString() available on your system's recording drives! [$1.toString() free]

Notes about the resource path:

• The resource path cannot be the root installation directory for SageTV. If it is then SageAlert will ignore the plugin and stop looking for the properties file
• The resource path is expected to be relative to the base install directory, as defined by the SageTV API
• If the resource path is not defined or the defined path does not exist then SageAlert will skip processing of the plugin
• Any other kind of read error (lack of permissions, etc.) will force SageAlert to skip the plugin

Fire Your Events in Your Code!

Now you're ready to fire your custom alerts in your code.

   if(this.somethingSpecial()) {
      Map<String, String> args = new HashMap<String, String>();
      args.put("MyArg", "MyValue");
      SageTVPluginRegistry registry = (SageTVPluginRegistry)SageTV.api("GetSageTVPluginRegistry", null);
      registry.postEvent("PluginName_EventName", args);
   }

NOTES:

• The first arg to postEvent() must be one of the keys defined in your sagealert.properties file.
• The map argument to postEvent() doesn't have to be a Map<String, String>, it can be a Map<?, ?>. You just have to know what it is and be able to handle the arguments map as necessary in your event classes.

The typical pattern is to create a separate thread and poll periodically for the conditions of your event. If the conditions are met, fire the event like above. Again, the Custom Events plugin has a complete example. It uses a timer task to periodically check the free space and fire the event if the space is too low.

All Done!

With that, you've added passive SageAlert support to your plugin. Congratulations!