001/* NotificationResult.java -- Wrapper for a series of buffered notifications.
002   Copyright (C) 2008 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038package javax.management.remote;
039
040import java.io.Serializable;
041
042/**
043 * <p>
044 * Wraps the result of a query for buffered notifications.  In a remote
045 * scenario, it may be more practical for the server to buffer individual
046 * notifications from its beans and then return them in bulk on request.
047 * This class contains the notifications returned by such a request.
048 * </p>
049 * <p>
050 * It consists of a series of {@link Notification} and identifier pairs,
051 * wrapped in a {@link TargetedNotification} object.  The identifiers
052 * serve to pair up the notification with the listener that requested
053 * it.  Two positive numbers are also included: the first sequence number
054 * used by the returned notifications, and the sequence number of the
055 * notification which will be returned by the next query.  The first
056 * sequence number may be greater than the next sequence number if some
057 * notifications have been lost.
058 * </p>
059 *
060 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
061 * @since 1.5
062 */
063public class NotificationResult
064  implements Serializable
065{
066
067  /**
068   * Compatible with JDK 1.6
069   */
070  private static final long serialVersionUID = 1191800228721395279L;
071
072  /**
073   * The sequence number of the first notification.
074   */
075  private long earliestSequenceNumber;
076
077  /**
078   * The sequence number of the next notification to be
079   * returned by a future query.
080   */
081  private long nextSequenceNumber;
082
083  /**
084   * The pairs of notifications and identifiers returned
085   * by the query.
086   */
087  private TargetedNotification[] targetedNotifications;
088
089  /**
090   * Constructs a new {@link NotificationResult} using the specified
091   * sequence numbers and the supplied array of notification pairs.
092   *
093   * @param startSeqNumber the sequence number of the first notification
094   *                       being returned.
095   * @param nextSeqNumber the sequence numbr of the next notification
096   *                      that will be returned from a future query.
097   * @param notifications the notification and identifier pairs.  This
098   *                      may be empty.
099   * @throws IllegalArgumentException if a sequence number is negative
100   *                                  or <code>notifications</code> is
101   *                                  <code>null</code>.
102   */
103  public NotificationResult(long startSeqNumber, long nextSeqNumber,
104                            TargetedNotification[] notifications)
105  {
106    if (startSeqNumber < 0)
107      throw new IllegalArgumentException("Starting sequence number is " +
108                                         "less than 0.");
109    if (nextSeqNumber < 0)
110      throw new IllegalArgumentException("Next sequence number is " +
111                                         "less than 0.");
112    if (notifications == null)
113      throw new IllegalArgumentException("The array of notifications is null.");
114    earliestSequenceNumber = startSeqNumber;
115    nextSequenceNumber = nextSeqNumber;
116    targetedNotifications = notifications;
117  }
118
119  /**
120   * Returns the sequence number of the earliest notification
121   * in the buffer.
122   *
123   * @return the sequence number of the earliest notification.
124   */
125  public long getEarliestSequenceNumber()
126  {
127    return earliestSequenceNumber;
128  }
129
130  /**
131   * Returns the sequence number of the next notification to
132   * be returned by a future query.
133   *
134   * @return the sequence number of the next notification.
135   */
136  public long getNextSequenceNumber()
137  {
138    return nextSequenceNumber;
139  }
140
141  /**
142   * Returns the notification and identifier pairs returned
143   * by the query.
144   *
145   * @return the notification and identifier pairs.
146   */
147  public TargetedNotification[] getTargetedNotifications()
148  {
149    return targetedNotifications;
150  }
151
152  /**
153   * Returns a textual representation of the object.
154   *
155   * @return a textual representation.
156   */
157  public String toString()
158  {
159    return getClass().getName() +
160      "[earliestSequenceNumber=" + earliestSequenceNumber +
161      ",nextSequenceNumber=" + nextSequenceNumber +
162      ",targetedNotifications=" + targetedNotifications +
163      "]";
164  }
165
166}