001/* MBeanNotificationInfo.java -- Information about a bean's notification.
002   Copyright (C) 2006 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;
039
040import java.util.Arrays;
041
042/**
043 * <p>
044 * Describes the notifications emitted by a management bean.
045 * An instance of this class is specific to notifications
046 * involving a particular type of object.  A new instance
047 * should be created for each Java class used for notifications,
048 * and the Java class name forms the name of the instance.
049 * Each instance lists a number of notification types; these
050 * are not types in the sense of different Java classes, but
051 * instead form the names of notifications following the same
052 * syntax as Java property and package names.
053 * </p>
054 * <p>
055 * For instance, a management bean may emit two notifications
056 * containing {@link java.lang.String} objects.  Both would be described
057 * using one instance of this class, with a member of the array
058 * returned by {@link #getNotifTypes()} for each one.  If another
059 * notification containing a {@link java.util.Date} object were to
060 * be added, this would require a new instance of this class.
061 * </p>
062 * <p>
063 * The information in this class is immutable as standard.
064 * Of course, subclasses may change this, but this
065 * behaviour is not recommended.
066 * </p>
067 *
068 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
069 * @since 1.5
070 */
071public class MBeanNotificationInfo
072  extends MBeanFeatureInfo
073  implements Cloneable
074{
075
076  /**
077   * Compatible with JDK 1.5
078   */
079  private static final long serialVersionUID = -3888371564530107064L;
080
081  /**
082   * The types of notification described by this instance.
083   *
084   * @serial the types of notification.
085   */
086  private String[] types;
087
088  /**
089   * Constructs a new {@link MBeanNotificationInfo} with the
090   * specified name, description and notification types. The
091   * notification types array may be <code>null</code> or of
092   * zero length, in order to indicate the absence of any types.
093   *
094   * @param types an array of {@link java.lang.String} objects,
095   *              containing the names of the notifications emitted
096   *              of this Java type.  The names use the dot notation
097   *              familiar from Java property and package names.
098   * @param name the name of the Java class the notifications described
099   *             by this object are instances of.
100   * @param description a description of the data.
101   * @throws IllegalArgumentException for some reason...
102   */
103  public MBeanNotificationInfo(String[] types, String name,
104                               String description)
105  {
106    super(name, description);
107    this.types = types;
108  }
109
110  /**
111   * Returns a clone of this instance.  The clone is created
112   * using just the method provided by {@link java.lang.Object}.
113   * Thus, the clone is just a shallow clone as returned by
114   * that method, and does not contain any deeper cloning based
115   * on the subject of this class.
116   *
117   * @return a clone of this instance.
118   * @see java.lang.Cloneable
119   */
120  public Object clone()
121  {
122    try
123      {
124        return super.clone();
125      }
126    catch (CloneNotSupportedException e)
127      {
128        /* This shouldn't happen; we implement Cloneable */
129        throw new IllegalStateException("clone() called on " +
130                                        "non-cloneable object.");
131      }
132  }
133
134  /**
135   * Compares this feature with the supplied object.  This returns
136   * true iff the object is an instance of {@link
137   * MBeanNotificationInfo}, {@link Object#equals()} returns true for
138   * a comparison of both the name and description of this
139   * notification with that of the specified object, and the two
140   * notification type arrays contain the same elements in the same
141   * order (but one may be longer than the other).
142   *
143   * @param obj the object to compare.
144   * @return true if the object is a {@link MBeanNotificationInfo}
145   *         instance, 
146   *         <code>name.equals(object.getName())</code>,
147   *         <code>description.equals(object.getDescription())</code>
148   *         and the corresponding elements of the type arrays are
149   *         equal.
150   */
151  public boolean equals(Object obj)
152  {
153    if (obj instanceof MBeanNotificationInfo)
154      {
155        if (!(super.equals(obj)))
156          return false;
157        MBeanNotificationInfo o = (MBeanNotificationInfo) obj;
158        String[] oTypes = o.getNotifTypes();
159        for (int a = 0; a < types.length; ++a)
160          {
161            if (a == oTypes.length)
162              return true;
163            if (!(types[a].equals(oTypes[a])))
164              return false;
165          }
166        return true;
167      }
168    else
169      return false;
170  }
171
172  /**
173   * Returns the notification types that the management bean may emit.
174   * The notification types are strings using the dot notation
175   * familiar from Java property and package names.  Changing the
176   * returned array does not affect the values retained by this
177   * instance.
178   *
179   * @return the notification types.
180   */
181  public String[] getNotifTypes()
182  {
183    return types;
184  }
185
186  /**
187   * Returns the hashcode of the notification information as the sum
188   * of the hashcode of the superclass and the hashcode of the types
189   * array.
190   *
191   * @return the hashcode of the notification information.
192   */
193  public int hashCode()
194  {
195    return super.hashCode() + Arrays.hashCode(types);
196  }
197
198  /**
199   * <p>
200   * Returns a textual representation of this instance.  This
201   * is constructed using the class name
202   * (<code>javax.management.MBeanNotificationInfo</code>),
203   * the name and description of the notification and the 
204   * contents of the array of types.
205   * </p>
206   * <p>
207   * As instances of this class are immutable, the return value
208   * is computed just once for each instance and reused
209   * throughout its life.
210   * </p>
211   *
212   * @return a @link{java.lang.String} instance representing
213   *         the instance in textual form.
214   */
215  public String toString()
216  {
217    if (string == null)
218      {
219        super.toString();
220        string = string.substring(0, string.length() - 1) 
221          + ",types=" + Arrays.toString(types)
222          + "]";
223      }
224    return string;
225  }
226
227}