001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.lib.collab;
043:
044: /**
045: * A Notification service is used to send and receive messages. The
046: * Notification Service is distinct from the conference service, despite
047: * the fact that the same Message definition is used in both.
048: * The differences include
049: * <ul>
050: * <li>In the Notification Service, messages are acknowlegded end-to-end, or
051: * at least can be</li>
052: * <li>in the Notification service, messages can be replied to</li>
053: * <li>in the Notification service, the destination is the actual recipient,
054: * while in the Conference service, the destination is the conference</li>
055: * </ul>
056: *
057: * <u>About Poll</u>
058: * The poll feature is built on top of the notification service.
059: * It uses specific content types defined here.
060: * <a href="../../../application-iim-poll.html">here</a>.
061: *
062: * The service should be intialized by calling intialize() before using any
063: * of the methods.
064: *
065: *
066: * @since version 0.1
067: *
068: */
069: public interface NotificationService {
070: /**
071: * send an alert to a destination. An alert is not sent in the context of
072: * a conference, as it does not allow for a response and does not require
073: * the destination to be online.
074: * @param message alert message
075: * @param listener callback object used by the provider to convey
076: * message disposition notifications.
077: */
078: public void sendMessage(Message message,
079: MessageStatusListener listener)
080: throws CollaborationException;
081:
082: /**
083: * create a message.
084: * @param destination address of the recipient.
085: * more recipient addresses can be added using the Message.addRecipient()
086: * method.
087: */
088: public Message createMessage(String destination)
089: throws CollaborationException;
090:
091: /**
092: * create a message.
093: * recipient addresses can be added using the Message.addRecipient()
094: * method.
095: */
096: public Message createMessage() throws CollaborationException;
097:
098: /**
099: * intialize the service by providing a NotificationServiceListener.
100: * Service should be initialized by calling this method before using
101: * any of the services of NoficationService
102: * @param listener NotificationServiceListener
103: */
104: public void initialize(NotificationServiceListener listener)
105: throws CollaborationException;
106:
107: /**
108: * Add an additional NotificationServiceListener to receive the event notifications.
109: * To receive all the initial events the first NotificationServiceListener should be
110: * added while {@link #initialize(NotificationServiceListener) initializing} NotificationService.
111: * @param listener NotificationServiceListener The NotificationServiceListener to be added.
112: */
113: public void addNotificationServiceListener(
114: NotificationServiceListener listener);
115:
116: /**
117: * Removes an already added ConfereneServiceListener. To prevent loss of any event
118: * notification it is advised to have atleast one NotificationServiceListener
119: * @param listener NotificationServiceListener The NotificationServiceListener to be removed.
120: */
121: public void removeNotificationServiceListener(
122: NotificationServiceListener listener);
123: }
|