View Javadoc
1   /*
2    * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.management;
27  
28  import java.util.ArrayList;
29  import java.util.Collection;
30  import java.util.LinkedHashMap;
31  import java.util.List;
32  import java.util.Map;
33  
34  /**
35   * <p>Represents a list of values for attributes of an MBean.  See the
36   * {@link MBeanServerConnection#getAttributes getAttributes} and
37   * {@link MBeanServerConnection#setAttributes setAttributes} methods of
38   * {@link MBeanServer} and {@link MBeanServerConnection}.</p>
39   *
40   * <p id="type-safe">For compatibility reasons, it is possible, though
41   * highly discouraged, to add objects to an {@code AttributeList} that are
42   * not instances of {@code Attribute}.  However, an {@code AttributeList}
43   * can be made <em>type-safe</em>, which means that an attempt to add
44   * an object that is not an {@code Attribute} will produce an {@code
45   * IllegalArgumentException}.  An {@code AttributeList} becomes type-safe
46   * when the method {@link #asList()} is called on it.</p>
47   *
48   * @since 1.5
49   */
50  /* We cannot extend ArrayList<Attribute> because our legacy
51     add(Attribute) method would then override add(E) in ArrayList<E>,
52     and our return value is void whereas ArrayList.add(E)'s is boolean.
53     Likewise for set(int,Attribute).  Grrr.  We cannot use covariance
54     to override the most important methods and have them return
55     Attribute, either, because that would break subclasses that
56     override those methods in turn (using the original return type
57     of Object).  Finally, we cannot implement Iterable<Attribute>
58     so you could write
59         for (Attribute a : attributeList)
60     because ArrayList<> implements Iterable<> and the same class cannot
61     implement two versions of a generic interface.  Instead we provide
62     the asList() method so you can write
63         for (Attribute a : attributeList.asList())
64  */
65  public class AttributeList extends ArrayList<Object> {
66  
67      private transient volatile boolean typeSafe;
68      private transient volatile boolean tainted;
69  
70      /* Serial version */
71      private static final long serialVersionUID = -4077085769279709076L;
72  
73      /**
74       * Constructs an empty <CODE>AttributeList</CODE>.
75       */
76      public AttributeList() {
77          super();
78      }
79  
80      /**
81       * Constructs an empty <CODE>AttributeList</CODE> with
82       * the initial capacity specified.
83       *
84       * @param initialCapacity the initial capacity of the
85       * <code>AttributeList</code>, as specified by {@link
86       * ArrayList#ArrayList(int)}.
87       */
88      public AttributeList(int initialCapacity) {
89          super(initialCapacity);
90      }
91  
92      /**
93       * Constructs an <CODE>AttributeList</CODE> containing the
94       * elements of the <CODE>AttributeList</CODE> specified, in the
95       * order in which they are returned by the
96       * <CODE>AttributeList</CODE>'s iterator.  The
97       * <CODE>AttributeList</CODE> instance has an initial capacity of
98       * 110% of the size of the <CODE>AttributeList</CODE> specified.
99       *
100      * @param list the <code>AttributeList</code> that defines the initial
101      * contents of the new <code>AttributeList</code>.
102      *
103      * @see ArrayList#ArrayList(java.util.Collection)
104      */
105     public AttributeList(AttributeList list) {
106         super(list);
107     }
108 
109     /**
110      * Constructs an {@code AttributeList} containing the elements of the
111      * {@code List} specified, in the order in which they are returned by
112      * the {@code List}'s iterator.
113      *
114      * @param list the {@code List} that defines the initial contents of
115      * the new {@code AttributeList}.
116      *
117      * @exception IllegalArgumentException if the {@code list} parameter
118      * is {@code null} or if the {@code list} parameter contains any
119      * non-Attribute objects.
120      *
121      * @see ArrayList#ArrayList(java.util.Collection)
122      *
123      * @since 1.6
124      */
125     public AttributeList(List<Attribute> list) {
126         // Check for null parameter
127         //
128         if (list == null)
129             throw new IllegalArgumentException("Null parameter");
130 
131         // Check for non-Attribute objects
132         //
133         adding(list);
134 
135         // Build the List<Attribute>
136         //
137         super.addAll(list);
138     }
139 
140     /**
141      * Return a view of this list as a {@code List<Attribute>}.
142      * Changes to the returned value are reflected by changes
143      * to the original {@code AttributeList} and vice versa.
144      *
145      * @return a {@code List<Attribute>} whose contents
146      * reflect the contents of this {@code AttributeList}.
147      *
148      * <p>If this method has ever been called on a given
149      * {@code AttributeList} instance, a subsequent attempt to add
150      * an object to that instance which is not an {@code Attribute}
151      * will fail with a {@code IllegalArgumentException}. For compatibility
152      * reasons, an {@code AttributeList} on which this method has never
153      * been called does allow objects other than {@code Attribute}s to
154      * be added.</p>
155      *
156      * @throws IllegalArgumentException if this {@code AttributeList} contains
157      * an element that is not an {@code Attribute}.
158      *
159      * @since 1.6
160      */
161     @SuppressWarnings("unchecked")
162     public List<Attribute> asList() {
163         typeSafe = true;
164         if (tainted)
165             adding((Collection<?>) this);  // will throw IllegalArgumentException
166         return (List<Attribute>) (List<?>) this;
167     }
168 
169     /**
170      * Adds the {@code Attribute} specified as the last element of the list.
171      *
172      * @param object  The attribute to be added.
173      */
174     public void add(Attribute object)  {
175         super.add(object);
176     }
177 
178     /**
179      * Inserts the attribute specified as an element at the position specified.
180      * Elements with an index greater than or equal to the current position are
181      * shifted up. If the index is out of range {@literal (index < 0 || index >
182      * size())} a RuntimeOperationsException should be raised, wrapping the
183      * java.lang.IndexOutOfBoundsException thrown.
184      *
185      * @param object  The <CODE>Attribute</CODE> object to be inserted.
186      * @param index The position in the list where the new {@code Attribute}
187      * object is to be inserted.
188      */
189     public void add(int index, Attribute object)  {
190         try {
191             super.add(index, object);
192         }
193         catch (IndexOutOfBoundsException e) {
194             throw new RuntimeOperationsException(e,
195                 "The specified index is out of range");
196         }
197     }
198 
199     /**
200      * Sets the element at the position specified to be the attribute specified.
201      * The previous element at that position is discarded. If the index is
202      * out of range {@literal (index < 0 || index > size())} a RuntimeOperationsException
203      * should be raised, wrapping the java.lang.IndexOutOfBoundsException thrown.
204      *
205      * @param object  The value to which the attribute element should be set.
206      * @param index  The position specified.
207      */
208     public void set(int index, Attribute object)  {
209         try {
210             super.set(index, object);
211         }
212         catch (IndexOutOfBoundsException e) {
213             throw new RuntimeOperationsException(e,
214                 "The specified index is out of range");
215         }
216     }
217 
218     /**
219      * Appends all the elements in the <CODE>AttributeList</CODE> specified to
220      * the end of the list, in the order in which they are returned by the
221      * Iterator of the <CODE>AttributeList</CODE> specified.
222      *
223      * @param list  Elements to be inserted into the list.
224      *
225      * @return true if this list changed as a result of the call.
226      *
227      * @see ArrayList#addAll(java.util.Collection)
228      */
229     public boolean addAll(AttributeList list)  {
230         return (super.addAll(list));
231     }
232 
233     /**
234      * Inserts all of the elements in the <CODE>AttributeList</CODE> specified
235      * into this list, starting at the specified position, in the order in which
236      * they are returned by the Iterator of the {@code AttributeList} specified.
237      * If the index is out of range {@literal (index < 0 || index > size())} a
238      * RuntimeOperationsException should be raised, wrapping the
239      * java.lang.IndexOutOfBoundsException thrown.
240      *
241      * @param list  Elements to be inserted into the list.
242      * @param index  Position at which to insert the first element from the
243      * <CODE>AttributeList</CODE> specified.
244      *
245      * @return true if this list changed as a result of the call.
246      *
247      * @see ArrayList#addAll(int, java.util.Collection)
248      */
249     public boolean addAll(int index, AttributeList list)  {
250         try {
251             return super.addAll(index, list);
252         } catch (IndexOutOfBoundsException e) {
253             throw new RuntimeOperationsException(e,
254                 "The specified index is out of range");
255         }
256     }
257 
258     /*
259      * Override all of the methods from ArrayList<Object> that might add
260      * a non-Attribute to the List, and disallow that if asList has ever
261      * been called on this instance.
262      */
263 
264     /**
265      * {@inheritDoc}
266      * @throws IllegalArgumentException if this {@code AttributeList} is
267      * <a href="#type-safe">type-safe</a> and {@code element} is not an
268      * {@code Attribute}.
269      */
270     @Override
271     public boolean add(Object element) {
272         adding(element);
273         return super.add(element);
274     }
275 
276     /**
277      * {@inheritDoc}
278      * @throws IllegalArgumentException if this {@code AttributeList} is
279      * <a href="#type-safe">type-safe</a> and {@code element} is not an
280      * {@code Attribute}.
281      */
282     @Override
283     public void add(int index, Object element) {
284         adding(element);
285         super.add(index, element);
286     }
287 
288     /**
289      * {@inheritDoc}
290      * @throws IllegalArgumentException if this {@code AttributeList} is
291      * <a href="#type-safe">type-safe</a> and {@code c} contains an
292      * element that is not an {@code Attribute}.
293      */
294     @Override
295     public boolean addAll(Collection<?> c) {
296         adding(c);
297         return super.addAll(c);
298     }
299 
300     /**
301      * {@inheritDoc}
302      * @throws IllegalArgumentException if this {@code AttributeList} is
303      * <a href="#type-safe">type-safe</a> and {@code c} contains an
304      * element that is not an {@code Attribute}.
305      */
306     @Override
307     public boolean addAll(int index, Collection<?> c) {
308         adding(c);
309         return super.addAll(index, c);
310     }
311 
312     /**
313      * {@inheritDoc}
314      * @throws IllegalArgumentException if this {@code AttributeList} is
315      * <a href="#type-safe">type-safe</a> and {@code element} is not an
316      * {@code Attribute}.
317      */
318     @Override
319     public Object set(int index, Object element) {
320         adding(element);
321         return super.set(index, element);
322     }
323 
324     private void adding(Object x) {
325         if (x == null || x instanceof Attribute)
326             return;
327         if (typeSafe)
328             throw new IllegalArgumentException("Not an Attribute: " + x);
329         else
330             tainted = true;
331     }
332 
333     private void adding(Collection<?> c) {
334         for (Object x : c)
335             adding(x);
336     }
337 }