001    /* MBeanOperationInfo.java -- Information about a bean's operations.
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.lang.reflect.Method;
041    import java.lang.reflect.Type;
042    
043    import java.util.Arrays;
044    
045    /**
046     * Describes the operations of a management bean.
047     * The information in this class is immutable as standard.
048     * Of course, subclasses may change this, but this
049     * behaviour is not recommended.
050     *
051     * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
052     * @since 1.5
053     */
054    public class MBeanOperationInfo
055      extends MBeanFeatureInfo
056      implements Cloneable
057    {
058    
059      /**
060       * Compatible with JDK 1.5
061       */
062      private static final long serialVersionUID = -6178860474881375330L;
063    
064      /**
065       * Used to signify that the operation merely provides information
066       * (akin to an accessor).
067       */
068      public static final int INFO = 0;
069    
070      /**
071       * Used to signify that the operation makes some change to the
072       * state of the bean (akin to a mutator).
073       */
074      public static final int ACTION = 1;
075    
076      /**
077       * Used to signify that the operation makes some state change
078       * to the bean and also returns information.
079       */
080      public static final int ACTION_INFO = 2;
081    
082      /**
083       * Used to signify that the behaviour of the operation is
084       * unknown.
085       */
086      public static final int UNKNOWN = 3;
087    
088      /**
089       * The return type of the method, in the form of its class name.
090       */
091      private String type;
092    
093      /**
094       * The signature of the constructor i.e. the argument types.
095       */
096      private MBeanParameterInfo[] signature;
097    
098      /**
099       * The impact of the method, as one of {@link #INFO}, {@link #ACTION},
100       * {@link #ACTION_INFO} and {@link #UNKNOWN}.
101       */
102      private int impact;
103    
104      /**
105       * Constructs a @link{MBeanOperationInfo} with the specified
106       * description using the given method.  Each parameter is
107       * described merely by its type; the name and description are
108       * <code>null</code>.  The return type and impact of the
109       * method are determined from the {@link Method} instance.
110       *
111       * @param desc a description of the attribute.
112       * @param method the method.
113       */
114      public MBeanOperationInfo(String desc, Method method)
115      {
116        super(method.getName(), desc);
117        Type[] paramTypes = method.getGenericParameterTypes();
118        signature = new MBeanParameterInfo[paramTypes.length];
119        for (int a = 0; a < paramTypes.length; ++a)
120          {
121            Type t = paramTypes[a];
122            if (t instanceof Class)
123              signature[a] = new MBeanParameterInfo(null,
124                                                    ((Class) t).getName(),
125                                                     null);
126            else
127              signature[a] = new MBeanParameterInfo(null, t.toString(), null);
128          }
129        Type retType = method.getGenericReturnType();
130        if (retType instanceof Class)
131          type = ((Class) retType).getName();
132        else
133          type = retType.toString();
134        if (method.getReturnType() == Void.TYPE)
135          {
136            if (paramTypes.length == 0)
137              impact = UNKNOWN;
138            else
139              impact = ACTION;
140          }
141        else
142          {
143            if (paramTypes.length == 0)
144              impact = INFO;
145            else
146              impact = ACTION_INFO;
147          }
148      }
149    
150      /**
151       * Constructs a @link{MBeanOperationInfo} with the specified name,
152       * description, parameter information, return type and impact. A
153       * <code>null</code> value for the parameter information is the same
154       * as passing in an empty array.  A copy of the parameter array is
155       * taken, so later changes have no effect.
156       *
157       * @param name the name of the constructor.
158       * @param desc a description of the attribute.
159       * @param sig the signature of the method, as a series
160       *            of {@link MBeanParameterInfo} objects, one for
161       *            each parameter.
162       * @param type the return type of the method, as the class name.
163       * @param impact the impact of performing the operation.
164       */
165      public MBeanOperationInfo(String name, String desc,
166                                MBeanParameterInfo[] sig, String type,
167                                int impact)
168      {
169        super(name, desc);
170        if (sig == null)
171          signature = new MBeanParameterInfo[0];
172        else
173          {
174            signature = new MBeanParameterInfo[sig.length];
175            System.arraycopy(sig, 0, signature, 0, sig.length);
176          }
177        this.type = type;
178        this.impact = impact;
179      }
180    
181      /**
182       * Returns a clone of this instance.  The clone is created
183       * using just the method provided by {@link java.lang.Object}.
184       * Thus, the clone is just a shallow clone as returned by
185       * that method, and does not contain any deeper cloning based
186       * on the subject of this class.
187       *
188       * @return a clone of this instance.
189       * @see java.lang.Cloneable
190       */
191      public Object clone()
192      {
193        try
194          {
195            return super.clone();
196          }
197        catch (CloneNotSupportedException e)
198          {
199            /* This shouldn't happen; we implement Cloneable */
200            throw new IllegalStateException("clone() called on " +
201                                            "non-cloneable object.");
202          }
203      }
204    
205      /**
206       * Compares this feature with the supplied object.  This returns
207       * true iff the object is an instance of {@link
208       * MBeanConstructorInfo}, {@link Object#equals()} returns true for a
209       * comparison of both the name and description of this notification
210       * with that of the specified object (performed by the superclass),
211       * the return type and impact are equal and the two signature arrays
212       * contain the same elements in the same order (but one may be
213       * longer than the other).
214       *
215       * @param obj the object to compare.
216       * @return true if the object is a {@link MBeanOperationInfo}
217       *         instance, 
218       *         <code>name.equals(object.getName())</code>,
219       *         <code>description.equals(object.getDescription())</code>,
220       *         <code>type.equals(object.getReturnType())</code>,
221       *         <code>impact == object.getImpact()</code>,
222       *         and the corresponding elements of the signature arrays are
223       *         equal.
224       */
225      public boolean equals(Object obj)
226      {
227        if (!(obj instanceof MBeanOperationInfo))
228          return false;
229        if (!(super.equals(obj)))
230          return false;
231        MBeanOperationInfo o = (MBeanOperationInfo) obj;
232        MBeanParameterInfo[] sig = o.getSignature();
233        for (int a = 0; a < signature.length; ++a)
234          {
235            if (a == sig.length)
236              return true;
237            if (!(signature[a].equals(sig[a])))
238              return false;
239          }
240        return (type.equals(o.getReturnType()) &&
241                impact == o.getImpact());
242      }
243      
244      /**
245       * <p>
246       * Returns the impact of performing this operation.
247       * The value is equal to one of the following:
248       * </p>
249       * <ol>
250       * <li>{@link #INFO} &mdash; the method just returns
251       * information (akin to an accessor).</li>
252       * <li>{@link #ACTION} &mdash; the method just alters
253       * the state of the bean, without returning a value
254       * (akin to a mutator).</li>
255       * <li>{@link #ACTION_INFO} &mdash; the method both makes
256       * state changes and returns a value.</li>
257       * <li>{@link #UNKNOWN} &mdash; the behaviour of the operation
258       * is unknown.</li>
259       * </ol>
260       *
261       * @return the impact of performing the operation.
262       */
263      public int getImpact()
264      {
265        return impact;
266      }
267    
268      /**
269       * Returns the return type of the operation, as the class
270       * name.
271       *
272       * @return the return type.
273       */
274      public String getReturnType()
275      {
276        return type;
277      }
278    
279      /**
280       * Returns the operation's signature, in the form of
281       * information on each parameter.  Each parameter is
282       * described by an instance of {@link MBeanParameterInfo}.
283       * The returned array is a shallow copy of the array used
284       * by this instance, so changing which elements are stored
285       * in the array won't affect the array used by this, but
286       * changing the actual elements will affect the ones used
287       * here.
288       *
289       * @return an array of {@link MBeanParameterInfo} objects,
290       *         describing the operation parameters.
291       */
292      public MBeanParameterInfo[] getSignature()
293      {
294        return (MBeanParameterInfo[]) signature.clone();
295      }
296    
297      /**
298       * Returns the hashcode of the operation information as the sum of
299       * the hashcode of the superclass, the parameter array, the return
300       * type and the impact factor.
301       *
302       * @return the hashcode of the operation information.
303       */
304      public int hashCode()
305      {
306        return super.hashCode() + Arrays.hashCode(signature)
307          + type.hashCode() + Integer.valueOf(impact).hashCode();
308      }
309    
310      /**
311       * <p>
312       * Returns a textual representation of this instance.  This
313       * is constructed using the class name
314       * (<code>javax.management.MBeanOperationInfo</code>),
315       * the name, description, return type and impact of the
316       * operation and the contents of the array of parameters.
317       * </p>
318       * <p>
319       * As instances of this class are immutable, the return value
320       * is computed just once for each instance and reused
321       * throughout its life.
322       * </p>
323       *
324       * @return a @link{java.lang.String} instance representing
325       *         the instance in textual form.
326       */
327      public String toString()
328      {
329        if (string == null)
330          {
331            String impactString;
332            switch (impact)
333              {
334              case INFO:
335                impactString = "INFO";
336                break;
337              case ACTION:
338                impactString = "ACTION";
339                break;
340              case ACTION_INFO:
341                impactString = "ACTION_INFO";
342                break;
343              case UNKNOWN:
344                impactString = "UNKNOWN";
345                break;
346              default:
347                impactString = "ERRONEOUS VALUE";
348              }
349            super.toString();
350            string = string.substring(0, string.length() - 1) 
351              + ",returnType=" + type
352              + ",impact=" + impactString 
353              + ",signature=" + Arrays.toString(signature)
354              + "]";
355          }
356        return string;
357      }
358    
359    }