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