001 /*
002 * Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.management.openmbean;
027
028 // java import
029 //
030 import java.util.Collection;
031
032 // jmx import
033 //
034
035 /**
036 * The <tt>CompositeData</tt> interface specifies the behavior of a specific type of complex <i>open data</i> objects
037 * which represent <i>composite data</i> structures.
038 *
039 *
040 * @since 1.5
041 */
042 public interface CompositeData {
043
044 /**
045 * Returns the <i>composite type </i> of this <i>composite data</i> instance.
046 *
047 * @return the type of this CompositeData.
048 */
049 public CompositeType getCompositeType();
050
051 /**
052 * Returns the value of the item whose name is <tt>key</tt>.
053 *
054 * @param key the name of the item.
055 *
056 * @return the value associated with this key.
057 *
058 * @throws IllegalArgumentException if <tt>key</tt> is a null or empty String.
059 *
060 * @throws InvalidKeyException if <tt>key</tt> is not an existing item name for this <tt>CompositeData</tt> instance.
061 */
062 public Object get(String key);
063
064 /**
065 * Returns an array of the values of the items whose names are specified by <tt>keys</tt>, in the same order as <tt>keys</tt>.
066 *
067 * @param keys the names of the items.
068 *
069 * @return the values corresponding to the keys.
070 *
071 * @throws IllegalArgumentException if an element in <tt>keys</tt> is a null or empty String.
072 *
073 * @throws InvalidKeyException if an element in <tt>keys</tt> is not an existing item name for this <tt>CompositeData</tt> instance.
074 */
075 public Object[] getAll(String[] keys);
076
077 /**
078 * Returns <tt>true</tt> if and only if this <tt>CompositeData</tt> instance contains
079 * an item whose name is <tt>key</tt>.
080 * If <tt>key</tt> is a null or empty String, this method simply returns false.
081 *
082 * @param key the key to be tested.
083 *
084 * @return true if this <tt>CompositeData</tt> contains the key.
085 */
086 public boolean containsKey(String key);
087
088 /**
089 * Returns <tt>true</tt> if and only if this <tt>CompositeData</tt> instance contains an item
090 * whose value is <tt>value</tt>.
091 *
092 * @param value the value to be tested.
093 *
094 * @return true if this <tt>CompositeData</tt> contains the value.
095 */
096 public boolean containsValue(Object value);
097
098 /**
099 * Returns an unmodifiable Collection view of the item values contained in this <tt>CompositeData</tt> instance.
100 * The returned collection's iterator will return the values in the ascending lexicographic order of the corresponding
101 * item names.
102 *
103 * @return the values.
104 */
105 public Collection<?> values();
106
107 /**
108 * Compares the specified <var>obj</var> parameter with this
109 * <code>CompositeData</code> instance for equality.
110 * <p>
111 * Returns <tt>true</tt> if and only if all of the following statements are true:
112 * <ul>
113 * <li><var>obj</var> is non null,</li>
114 * <li><var>obj</var> also implements the <code>CompositeData</code> interface,</li>
115 * <li>their composite types are equal</li>
116 * <li>their contents, i.e. (name, value) pairs are equal. If a value contained in
117 * the content is an array, the value comparison is done as if by calling
118 * the {@link java.util.Arrays#deepEquals(Object[], Object[]) deepEquals} method
119 * for arrays of object reference types or the appropriate overloading of
120 * {@code Arrays.equals(e1,e2)} for arrays of primitive types</li>
121 * </ul>
122 * <p>
123 * This ensures that this <tt>equals</tt> method works properly for
124 * <var>obj</var> parameters which are different implementations of the
125 * <code>CompositeData</code> interface, with the restrictions mentioned in the
126 * {@link java.util.Collection#equals(Object) equals}
127 * method of the <tt>java.util.Collection</tt> interface.
128 *
129 * @param obj the object to be compared for equality with this
130 * <code>CompositeData</code> instance.
131 * @return <code>true</code> if the specified object is equal to this
132 * <code>CompositeData</code> instance.
133 */
134 public boolean equals(Object obj);
135
136 /**
137 * Returns the hash code value for this <code>CompositeData</code> instance.
138 * <p>
139 * The hash code of a <code>CompositeData</code> instance is the sum of the hash codes
140 * of all elements of information used in <code>equals</code> comparisons
141 * (ie: its <i>composite type</i> and all the item values).
142 * <p>
143 * This ensures that <code> t1.equals(t2) </code> implies that <code> t1.hashCode()==t2.hashCode() </code>
144 * for any two <code>CompositeData</code> instances <code>t1</code> and <code>t2</code>,
145 * as required by the general contract of the method
146 * {@link Object#hashCode() Object.hashCode()}.
147 * <p>
148 * Each item value's hash code is added to the returned hash code.
149 * If an item value is an array,
150 * its hash code is obtained as if by calling the
151 * {@link java.util.Arrays#deepHashCode(Object[]) deepHashCode} method
152 * for arrays of object reference types or the appropriate overloading
153 * of {@code Arrays.hashCode(e)} for arrays of primitive types.
154 *
155 * @return the hash code value for this <code>CompositeData</code> instance
156 */
157 public int hashCode();
158
159 /**
160 * Returns a string representation of this <code>CompositeData</code> instance.
161 * <p>
162 * The string representation consists of the name of the implementing class,
163 * the string representation of the composite type of this instance, and the string representation of the contents
164 * (ie list the itemName=itemValue mappings).
165 *
166 * @return a string representation of this <code>CompositeData</code> instance
167 */
168 public String toString();
169
170 }
|