001    /* MBeanNotificationInfo.java -- Information about a bean's notification.
002       Copyright (C) 2006 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package javax.management;
039    
040    import 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     */
071    public 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    }