1 /*
2 * Copyright (c) 2000, 2007, 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
27 package javax.management.openmbean;
28
29
30 // java import
31 //
32 import java.util.Collection;
33
34 // jmx import
35 //
36
37
38 /**
39 * The {@code CompositeData} interface specifies
40 * the behavior of a specific type of complex <i>open data</i> objects
41 * which represent <i>composite data</i> structures.
42 *
43 *
44 * @since 1.5
45 */
46 public interface CompositeData {
47
48
49 /**
50 * Returns the <i>composite type </i> of this <i>composite data</i> instance.
51 *
52 * @return the type of this CompositeData.
53 */
54 public CompositeType getCompositeType();
55
56 /**
57 * Returns the value of the item whose name is {@code key}.
58 *
59 * @param key the name of the item.
60 *
61 * @return the value associated with this key.
62 *
63 * @throws IllegalArgumentException if {@code key} is a null or empty String.
64 *
65 * @throws InvalidKeyException if {@code key} is not an
66 * existing item name for this {@code CompositeData} instance.
67 */
68 public Object get(String key) ;
69
70 /**
71 * Returns an array of the values of the items whose names
72 * are specified by {@code keys}, in the same order as {@code keys}.
73 *
74 * @param keys the names of the items.
75 *
76 * @return the values corresponding to the keys.
77 *
78 * @throws IllegalArgumentException if an element in {@code keys} is a null or empty String.
79 *
80 * @throws InvalidKeyException if an element in {@code keys}
81 * is not an existing item name for this {@code CompositeData} instance.
82 */
83 public Object[] getAll(String[] keys) ;
84
85 /**
86 * Returns {@code true} if and only if this {@code CompositeData} instance contains
87 * an item whose name is {@code key}.
88 * If {@code key} is a null or empty String, this method simply returns false.
89 *
90 * @param key the key to be tested.
91 *
92 * @return true if this {@code CompositeData} contains the key.
93 */
94 public boolean containsKey(String key) ;
95
96 /**
97 * Returns {@code true} if and only if this {@code CompositeData} instance contains an item
98 * whose value is {@code value}.
99 *
100 * @param value the value to be tested.
101 *
102 * @return true if this {@code CompositeData} contains the value.
103 */
104 public boolean containsValue(Object value) ;
105
106 /**
107 * Returns an unmodifiable Collection view of the item values
108 * contained in this {@code CompositeData} instance.
109 * The returned collection's iterator will return the values
110 * in the ascending lexicographic order of the corresponding
111 * item names.
112 *
113 * @return the values.
114 */
115 public Collection<?> values() ;
116
117 /**
118 * Compares the specified <var>obj</var> parameter with this
119 * {@code CompositeData} instance for equality.
120 * <p>
121 * Returns {@code true} if and only if all of the following statements are true:
122 * <ul>
123 * <li><var>obj</var> is non null,</li>
124 * <li><var>obj</var> also implements the {@code CompositeData} interface,</li>
125 * <li>their composite types are equal</li>
126 * <li>their contents, i.e. (name, value) pairs are equal. If a value contained in
127 * the content is an array, the value comparison is done as if by calling
128 * the {@link java.util.Arrays#deepEquals(Object[], Object[]) deepEquals} method
129 * for arrays of object reference types or the appropriate overloading of
130 * {@code Arrays.equals(e1,e2)} for arrays of primitive types</li>
131 * </ul>
132 * <p>
133 * This ensures that this {@code equals} method works properly for
134 * <var>obj</var> parameters which are different implementations of the
135 * {@code CompositeData} interface, with the restrictions mentioned in the
136 * {@link java.util.Collection#equals(Object) equals}
137 * method of the {@code java.util.Collection} interface.
138 *
139 * @param obj the object to be compared for equality with this
140 * {@code CompositeData} instance.
141 * @return {@code true} if the specified object is equal to this
142 * {@code CompositeData} instance.
143 */
144 public boolean equals(Object obj) ;
145
146 /**
147 * Returns the hash code value for this {@code CompositeData} instance.
148 * <p>
149 * The hash code of a {@code CompositeData} instance is the sum of the hash codes
150 * of all elements of information used in {@code equals} comparisons
151 * (ie: its <i>composite type</i> and all the item values).
152 * <p>
153 * This ensures that {@code t1.equals(t2)} implies that {@code t1.hashCode()==t2.hashCode()}
154 * for any two {@code CompositeData} instances {@code t1} and {@code t2},
155 * as required by the general contract of the method
156 * {@link Object#hashCode() Object.hashCode()}.
157 * <p>
158 * Each item value's hash code is added to the returned hash code.
159 * If an item value is an array,
160 * its hash code is obtained as if by calling the
161 * {@link java.util.Arrays#deepHashCode(Object[]) deepHashCode} method
162 * for arrays of object reference types or the appropriate overloading
163 * of {@code Arrays.hashCode(e)} for arrays of primitive types.
164 *
165 * @return the hash code value for this {@code CompositeData} instance
166 */
167 public int hashCode() ;
168
169 /**
170 * Returns a string representation of this {@code CompositeData} instance.
171 * <p>
172 * The string representation consists of the name of the implementing class,
173 * the string representation of the composite type of this instance,
174 * and the string representation of the contents
175 * (ie list the itemName=itemValue mappings).
176 *
177 * @return a string representation of this {@code CompositeData} instance
178 */
179 public String toString() ;
180
181 }