PAL Sidebar UI API

All of the PAL Sidebar interfaces are named ISidebar and all of the SidebarProxy interfaces are named IProxy.


	 1 /**
	 2  * CaloSidebar Interface.
	 3  *
	 4  * 
	 5  * 
	 6  */
	 7
	 8    public interface ISidebarConnections : IService
	 9    {
	10        void SetConnectionObject(string uri);
	11        void SetExistingConnections(object[] items);
	12        void SetSuggestedConnections(object[] items);
	13    }
	14
	15    public interface ISidebarFocus : IService
	16    {
	17        void SetFocusObject(string label, string icon);
	18    }
	19
	20    public interface ISidebarNotification : IService
	21    {
	22      void AddNotification(int type, string id, string message, 
			string summary, string uri, int[] modalities, bool persistent);
	23	void AddNotification(XmlRpcStruct notification);
	24      void RemoveNotification(string id);
	25      void RemoveAllNotifications();
	26	void RemoveNotifications(object[] ids)
	27	string[] CurrentNotifications()
	28	bool IsCurrentNotification(string id)
	29
	30    }
	31
	32    public interface ISidebarPreppak : IService
	33    {
	34        void SetPreppakObject(string label, string icon, string uri);
	35    }
	36
	37    public interface ISidebarSuggestion : IService
	38    {
	39        void AddSuggestionGroup(XmlRpcStruct group);
	40        void AddAllSuggestionGroups(object[] groups);  
	41        void SetSuggestionGroups(object[] groups);
	42        void RemoveSuggestionGroup(string name);
	43        void RemoveAllSuggestionGroups();
	44    }
	45
	46 /**
	47  * SidebarProxy Interface.
	48  *
	49  * @author Jim Carpenter
	50  * @version 0.1 July 08, 2008
	51  */
	52
	53    public interface IConnectionsProxy {
	54        boolean acceptSuggestedConnection(String uri);
	55        boolean rejectSuggestedConnection(String uri);
	56    }
	57
	58    public interface IDispatcherProxy {
	59        boolean acceptText(String callerUri, String text);
	60    }
	61
	62    public interface INotificationProxy {
	63        boolean setResponseForNotification(String id, String response);
	64    }
	65
	66    public interface IPreppakProxy {
	67        Object[] getPrepPakForUri(String uri);
	68        boolean extractorExist(String uri);
	69        Object[] findCandidates(String uri);
	70        boolean addEntryToPrepPak(String uri, String item);
	71        boolean removeEntryFromPrepPak(String uri, String item);
	72    }
	73
	74    public interface ISuggestionProxy {
	75        boolean suggestionGroupChanged(HashMap group); 
	76    }
	77

Coding Example

All of the following examples are written in Java and use the Apache XML-RPC implementation.

Connecting to the Sidebar

The first task is to create an XmlRpcClient object and connect to the PAL Sidebar's remote interface. Note that we are hard-coding localhost and port 11489.


  	1     public static void main(String[] args) {
  	2         XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
  	3         config.setServerURL(new URL("http://localhost:11489/"));
  	4         XmlRpcClient client = new XmlRpcClient();
  	5         client.setConfig(config);
  	6     }

Setting the Focus Object

The SetFocusObject method takes two arguments, a label and icon to display. For a list of available images, see the Icons section at the end of this document.


  	7         Object[] params;
  	8
  	9         // SetFocusObject
 	10         params = new Object[] {"Kickoff Meeting", "CalendarEntry"};
 	11         client.execute("ISidebarFocus.SetFocusObject", params)

Adding Notifications

The AddNotification method takes seven arguments. The first is an integer that represents the type of notification:

public const int NOTIFY_TYPE = 0;
public const int NOTIFY_HTML_TYPE = 1;
public const int NOTIFY_TEXT_TYPE = 2;
public const int NOTIFY_URI_TYPE = 3;

HTML_TYPE is an indication that the message contains html markup. TEXT_TYPE is an indication that the message contains plain text. URI_TYPE is an indication that the uri field contains an object link for dispatch. The second argument is the id of the notification. It is a unique string that can later be used to remove a notification from the sidebar. The message field contains either plain text or html markup. The summary field is a short, single-line description of the notification. The modalities field is a list of ways to display the message. Possible values are:

public const int SIDEBAR_MODALITY = 0;
public const int TOAST_POPUP_MODALITY = 1;
public const int WINDOW_MODALITY = 2;

SIDEBAR_MODALITY indicates that the notification should be shown directly in the sidebar. TOAST_POPUP_MODALITY indicates that the notification should be displayed in a small popup window that appears above the system tray. WINDOW_MODALITY indicates that the notification should be displayed in a larger popup window in the center of the screen. If no modalities are specified, SIDEBAR_MODALITY is assumed to be the default. The persistent field indicates if the notification should be displayed until manually dismissed by the user. This field is currently not used and all notifications are assumed to be persistent.


 	12         // Add text notification
 	13         int type = NOTIFY_TEXT_TYPE;
 	14         String id = Long.toString(System.currentTimeMillis());
 	15         String message = "This is a test notification";
 	16         String summary = "Test notification";
 	17         String uri = "";
 	18         Vector modalities = new Vector();
 	19         boolean persistent = true;
 	20         params = new Object[] {type, id, message, summary, uri, modalities, persistent};
 	21         client.execute("ISidebarNotification.AddNotification", params);

Removing Notifications

The RemoveNotification method takes an id string that was specified when the notification was added. Notification ids should be unique within the system.


	 22         params = new Object[] {id};
	 23         client.execute("ISidebarNotification.RemoveNotification", params);

Removing all Notifications


	 24         params = new Object[] {};
	 25         client.execute("ISidebarNotification.RemoveAllNotifications", params);

Setting the Preppak Object

A PrepPak is a set of objects related to the focus object. For example, it might contain all documents, emails and contacts related to an upcoming meeting. Calling the SetPreppakObject method will initialize the hyperlink in the sidebar. The label is the text string to be displayed. The uri param is the unique identifier of the object in your application for which we are building a PrepPak. The uri is sent back to you via the IPreppakProxy.getPrepPakForUri callback method.


	 26         String label = "CALO Project";
 	 26         String icon = "Project";
 	 26         String uri = "id://jcarpenter-lt-280.1206145380111";
 	 26         params = new Object[] {label, icon, uri};
 	 27         client.execute("ISidebarPreppak.SetPreppakObject", params);

When the user clicks on the preppak link, a popout window is displayed.



The contents of this window are based on return value of the getPrepPakForUri method implemented by the SidebarProxy. The return value of this method should be an array of xmlrpc structs. Each of these structs is a collection of name-value pairs. The keys of these name-value pairs should be as follows:

public const string LABEL_PARAM = "label";
public const string URI_PARAM = "uri";
public const string MODIFIED_PARAM = "modified";
public const string TYPE_PARAM = "type";
public const string AUTHOR_PARAM = "author";
public const string FOLDER_PARAM = "folder";
public const string LENGTH_PARAM = "length";
public const string SCORE_PARAM = "score";

These keys correspond directly to the column headers of the preppak.

Adding Connections

The SetConnectionObject method is used to specify the source object of all connections. This method must be called before specifying any connection objects. Generally it is called immediately after a focal object change. Once the connection object is specified, the existing/suggested connection objects can be set via the SetExisting/SuggestedConnections methods. Each of these two methods takes a list of connection items as input. Each connection is defined by an XmlStruct. The keys of the struct are as follows:

public const string URI_PARAM = "uri";
public const string LABEL_PARAM = "label";
public const string ICON_PARAM = "icon";

The uri is the unique identifier of the connection object. The label is the text string to display. The icon is not currently used.


	 28         // Set the focal object uri
 	 29         params = new Object[] { "id://jcarpenter-lt-3374.1216076823330" };
	 30         client.execute("ISidebarConnections.SetConnectionObject", params);
	 31         
	 32         // Set existing connections
	 33         HashMap map = new HashMap();
	 34         map.put("uri","id://jcarpenter-lt-280.1206145380111");
	 35         map.put("label","CALO Project");
	 36         map.put("icon","Project");
	 37         Object[] items = new Object[] { map };
	 38         params = new Object[] { items };
	 39         client.execute("ISidebarConnections.SetExistingConnections", params);
	 40         
	 41         // Set the suggested connections
	 42         map = new HashMap();
	 43         map.put("uri","id://jcarpenter-lt-1.1204160169546");
	 44         map.put("label","Jim Carpenter");
	 45         map.put("icon","Person");
	 46         items = new Object[] { map };
	 47         params = new Object[] { items };
	 48         client.execute("ISidebarConnections.SetSuggestedConnections", params);


If the user clicks on an existing connection object, that item will be dispatched by calling the SidebarProxy's acceptText method. If the user selects an object from the combo box, it will be connected to the focal object by calling the proxy's acceptSuggestedConnection method.

Adding Suggestions

To add a suggestion to the sidebar, you must first construct an instance of a SuggestionGroup and populate all of its fields, text, type, icon, etc. Next, you construct one or more Suggestions and add them to the group. Once the group is fully populated, it can be serialized into an XmlRpc struct using the SuggestionUtil.structFromGroup method. The serialized group is then sent to the sidebar by calling the AddSuggestionGroup method. Note that the suggestion API is contained in suggestion.jar.


	 49         ISuggestionGroup group = new SuggestionGroup("schedule_group");
	 50         group.setText("Schedule Meeting");
	 51         group.setType(ISuggestionGroup.YES_NO_TYPE);
	 52         group.setToolTipText("Schedule a meeting");
	 53         group.setIcon("suggestion");
	 54         
	 55         ISuggestion suggestion = new Suggestion("schedule_suggestion");
	 56         suggestion.setText("Schedule meeting for \"Project Kickoff\"");
	 57         suggestion.setType(ISuggestion.INFO_TYPE);
	 58         suggestion.setIcon("Project");
	 59         suggestion.setHyperlinkLabel("Project Kickoff");
	 60         suggestion.setHyperlinkToolTipText("");
	 61         suggestion.setURI("id://jcarpenter-lt-7119.1216082042350");
	 62         group.addSuggestion(suggestion);
	 63         
	 64         HashMap s = SuggestionUtil.structFromGroup(group);
	 65         params = new Object[] {s};
	 66         client.execute("ISidebarSuggestion.AddSuggestionGroup", params);



When the user submits the suggestion group, a callback is made to the SidebarProxy's suggestionGroupChanged method. The callback parameter is a serialized version of the modified group. The XmlRpc struct can be turned back into an instance of ISuggestionGroup with the SuggestionUtil.groupFromStruct method.

Removing Suggestions


 	67         String name = "schedule_group";
 	68         params = new Object[] {name};
 	69         client.execute("ISidebarSuggestion.RemoveSuggestionGroup", params);

Configuration

The SidebarProxy framework is initialized using a Spring configuration file.


	  1 <?xml version="1.0" encoding="UTF-8"?>
	  2 <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
	  3 <beans default-lazy-init="true">
	  4     <bean class="com.sri.desktop.plugins.sidebarproxy.SidebarProxyImpl" id="sidebarproxy"
	  5           init-method="startup" destroy-method="shutdown" lazy-init="true">
	  6         <description>
	  7             Proxy implementation for the CALO sidebar.
	  8         </description>
	  9         <property name="contextService" ref="com.sri.iris.context.IContextService" />
	 10         <property name="dispatcher" ref="com.sri.iris.dispatcher.IDispatcher" />
	 11         <property name="notificationService" ref="com.sri.iris.notification.INotificationService" />
	 12         <property name="suggestionService" ref="com.sri.iris.suggest.ISuggestionService" />
	 13         <property name="pubSubService" ref="com.sri.iris.pubsub.IPubSubService" />
	 14         <property name="objStore" ref="com.sri.iris.objstore.IObjectStore" />
	 15         <property name="candidatesQuery" ref="preppak-candidates-query.query"/>
	 16         <property name="prepPakMaintenance" ref="preppakmaint.processor"/>
	 17         <property name="featureExtractors" ref="preppak-feature-extraction.somFeatureExtractors"/>
	 18         <property name="handlers">
	 19             <list>
	 20                 <!-- Note that the focus handler must be the first handler in the list -->
	 21                 <bean class="com.sri.desktop.plugins.sidebarproxy.focus.FocusHandler"/>
	 22                 <bean class="com.sri.desktop.plugins.sidebarproxy.dispatcher.DispatcherHandler"/>
	 23                 <bean class="com.sri.desktop.plugins.sidebarproxy.notification.NotificationHandler"/>
	 24                 <bean class="com.sri.desktop.plugins.sidebarproxy.preppak.PreppakHandler"/>
	 25                 <bean class="com.sri.desktop.plugins.sidebarproxy.suggestion.SuggestionHandler"/>
	 26                 <bean class="com.sri.desktop.plugins.sidebarproxy.connections.ConnectionsHandler"/>
	 27             </list>
	 28         </property>
	 29         <property name="sidebarPrefix" value="http://127.0.0.1:11489/"/>
	 30         <property name="proxyPort" value="11490"/>
	 31     </bean>
	 32 </beans> 

Icons

The PAL Sidebar has several built-in icons. When using an icon string in the XML-RPC API above, use exactly one of the names from the following list. Note that many of the names correspond to the SemanticClass local name.