NotificationService


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23   
24  /*
25   * $Header: /cvs/glassfish/admin-core/mbeanapi/src/java/com/sun/appserv/management/base/NotificationService.java,v 1.4 2006/03/09 20:30:20 llc Exp $
26   * $Revision: 1.4 $
27   * $Date: 2006/03/09 20:30:20 $
28   */
29  
30  package com.sun.appserv.management.base;
31  
32  import java.util.Set  ;
33  import java.util.Map  ;
34  
35  import javax.management.ObjectName  ;
36  import javax.management.InstanceNotFoundException  ;
37  import javax.management.Notification  ;
38  import javax.management.NotificationFilter  ;
39  import javax.management.NotificationListener  ;
40  
41  /**
42      Provides enhanced abilities for working with Notifications.  Listens 
43      to other MBeans (as configured) and collects the Notifications
44      which can later be retrieved by calling takeNotifications().  The listening
45      is quite powerful; both "listen to" and "don't listen to" ObjectNames or
46      ObjectName patterns may be specified, and are dynamically maintained.
47      <p>
48      All received Notifications are resent to all listeners on this MBean.  This
49      makes it possible to listen to a single MBean for all "interesting"
50      Notifications across many different MBeans, even if these MBeans
51      are dynamically registered and unregistered.
52      <p>
53      Buffering is also available, via a named buffer facility.  Creation of a
54      buffer together with an optional filter allows a caller to buffer 
55      Notifications of interest which can later be retrieved as a batch.  This
56      facility may be of particular use for clients which disconnect and
57      reconnect.
58      <p>
59      When a buffer overflows, a notification of type BUFFER_OVERFLOW_NOTIFICATION_TYPE
60      is emitted
61   */
62  public interface NotificationService
63      extends AMX, NotificationListener  
64  {
65  /** The j2eeType as returned by {@link com.sun.appserv.management.base.AMX#getJ2EEType}. */
66      public static final String    J2EE_TYPE   = XTypes.NOTIFICATION_SERVICE;
67      
68      /**
69          When the buffer overflows this Notification is issued.  The user
70          data of the Notification contains the Notification that was discarded.
71       */
72      public static final String    BUFFER_OVERFLOW_NOTIFICATION_TYPE   =
73          XTypes.NOTIFICATION_SERVICE + ".BufferOverflow";
74          
75      /**
76          Key for accessing the overwritten Notification with the Notification
77          of type BUFFER_OVERFLOW_NOTIFICATION_TYPE.
78       */
79      public static final String    OVERFLOWED_NOTIFICATION_KEY =
80          XTypes.NOTIFICATION_SERVICE + ".OverflowedNotification";
81      
82      
83      /**
84          The user data supplied when the instance was created.
85       */
86      public Object     getUserData();
87                              
88      /**
89          Listen for Notifications from an  using the specified filter,
90          which may be null, in which case all Notifications are heard.
91          The ObjectName may also be a pattern, in which case all s
92          matching the pattern are listened to.
93          <p>
94          Note that Notifications may also be manually forced into the
95          service by calling handlingNotification().
96          
97          @param pattern  name of  to listen to
98          @param filter
99       */
100     public void listenTo( ObjectName   pattern,
101                         final NotificationFilter   filter )
102                             throws InstanceNotFoundException  ;
103     
104     
105     /**
106         Stop listening for Notifications on the specified . It may
107         also be a pattern, in which case listening is stopped on all
108         s matching the pattern.
109             
110         @param objectName   name of  which should no longer be listened to.
111      */
112     public void dontListenTo( ObjectName   objectName )
113                     throws InstanceNotFoundException  ;
114     
115     
116     /**
117         Get the filter being used for a particular .
118         
119         @param objectName
120         @return NotificationFilter
121      */
122     public NotificationFilter         getFilter( ObjectName   objectName);
123     
124     
125     /**
126         Create a new buffer of the specified size.
127         
128         @param bufferSize   maximum number of Notifications to be buffered
129         @param filter       filter for Notifications to be buffered
130         @return id of the newly-created buffer
131      */
132     public Object     createBuffer( int bufferSize, NotificationFilter   filter );
133     
134     /**
135         Remove the specified buffer.
136      */
137     public void removeBuffer( Object   id );
138     
139     /**
140         Key within the Map returned by getNotifications() that yields the Long
141         for the next sequence number.
142      */
143     public static final String    NEXT_SEQUENCE_NUMBER_KEY    = "NextSequenceNumber";
144     
145     /**
146         Key within the Map returned by getNotifications() that yields the
147         Notifications[].
148      */
149     public static final String    NOTIFICATIONS_KEY           = "Notifications";
150     
151     /**
152         Get all outstanding Notifications which have a sequence number
153         that is equal to or greater than the specified one.
154         A sequence number of 0 means all Notifications.  The sequence
155         number in this case is the overarching one maintained by this buffer,
156         and has nothing to do with the sequence number within any particular
157         Notification.
158         <p>
159         Notifications are never removed from the buffer; be sure to use the
160         returned sequence number as a means of fetching new Notifications.
161         <p>
162         The Map is keyed by the following:
163         <nl>
164         <li>NEXT_SEQUENCE_NUMBER_KEY  returns the Long for the next sequence number
165             for subsequent calls to getNotifications()
166             </li>
167         <li>NOTIFICATIONS_KEY keys the Notification[]</li>
168         </nl>
169         
170         @return result[ 0 ] = next sequence number, result[ 1 ] = Notification[]
171      */
172     public Map  <String  ,Object  >   getBufferNotifications( final Object   bufferID, final long sequenceNumberIn );
173 
174 
175     /**
176         Get the MBeans to which this service listens.
177      */
178     public Set  <ObjectName  >      getListeneeSet();
179 }
180
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags