01: /**********************************************************************************
02: * $URL: https://source.sakaiproject.org/svn/courier/tags/sakai_2-4-1/courier-api/api/src/java/org/sakaiproject/courier/api/CourierService.java $
03: * $Id: CourierService.java 6940 2006-03-23 16:35:31Z ggolden@umich.edu $
04: ***********************************************************************************
05: *
06: * Copyright (c) 2003, 2004, 2005, 2006 The Sakai Foundation.
07: *
08: * Licensed under the Educational Community License, Version 1.0 (the "License");
09: * you may not use this file except in compliance with the License.
10: * You may obtain a copy of the License at
11: *
12: * http://www.opensource.org/licenses/ecl1.php
13: *
14: * Unless required by applicable law or agreed to in writing, software
15: * distributed under the License is distributed on an "AS IS" BASIS,
16: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17: * See the License for the specific language governing permissions and
18: * limitations under the License.
19: *
20: **********************************************************************************/package org.sakaiproject.courier.api;
21:
22: import java.util.List;
23:
24: /**
25: * <p>
26: * CourierService is the Interface for a Sakai service which can be used to push messages from the Sakai server components to the user interface in the browser.<br />
27: * It is used mostly to cause a tool in a particular portal instance to be refreshed to respond to a change noticed at the server.
28: * </p>
29: * <p>
30: * An Address identifies a particular client's window: it merges the Usage session, the window's portal page location, and perhaps the tool id (for floating tool windows).
31: * </p>
32: * <p>
33: * A Delivery object captures the Address, the HTML Element Id involved, and any other details of a particular type of delivery.
34: * </p>
35: */
36: public interface CourierService {
37: /** This string can be used to find the service in the service manager. */
38: static final String SERVICE_NAME = CourierService.class.getName();
39:
40: /**
41: * Queue up a delivery for the client window identified in the Delivery object. The particular form of delivery is determined by the type of Delivery object sent.
42: *
43: * @param delivery
44: * The Delivery (or extension) object to deliver.
45: */
46: void deliver(Delivery delivery);
47:
48: /**
49: * Clear any pending delivery requests to the particular client window for this element.
50: *
51: * @param address
52: * The address of the client window.
53: * @param elementId
54: * The id of the html element.
55: */
56: void clear(String address, String elementId);
57:
58: /**
59: * Clear any pending delivery requests to this session client window.
60: *
61: * @param address
62: * The address of client window.
63: */
64: void clear(String address);
65:
66: /**
67: * Access and de-queue the Deliveries queued up for a particular session client window.
68: *
69: * @param address
70: * The address of client window.
71: * @return a List of Delivery objects addressed to this session client window.
72: */
73: List getDeliveries(String address);
74:
75: /**
76: * Check to see if there are any deliveries queued up for a particular session client window.
77: *
78: * @param address
79: * The address of the client window.
80: * @return true if there are deliveries for this client window, false if not.
81: */
82: boolean hasDeliveries(String address);
83: }
|