1 /* 2 * Copyright (c) 2000, 2014, 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.ArrayList; 33 import java.util.Collections; 34 import java.util.Iterator; 35 import java.util.List; 36 37 // jmx import 38 // 39 40 41 /** 42 * The <code>TabularType</code> class is the <i> open type</i> class 43 * whose instances describe the types of {@link TabularData TabularData} values. 44 * 45 * @since 1.5 46 */ 47 public class TabularType extends OpenType<TabularData> { 48 49 /* Serial version */ 50 static final long serialVersionUID = 6554071860220659261L; 51 52 53 /** 54 * @serial The composite type of rows 55 */ 56 private CompositeType rowType; 57 58 /** 59 * @serial The items used to index each row element, kept in the order the user gave 60 * This is an unmodifiable {@link ArrayList} 61 */ 62 private List<String> indexNames; 63 64 65 private transient Integer myHashCode = null; // As this instance is immutable, these two values 66 private transient String myToString = null; // need only be calculated once. 67 68 69 /* *** Constructor *** */ 70 71 /** 72 * Constructs a <code>TabularType</code> instance, checking for the validity of the given parameters. 73 * The validity constraints are described below for each parameter. 74 * <p> 75 * The Java class name of tabular data values this tabular type represents 76 * (ie the class name returned by the {@link OpenType#getClassName() getClassName} method) 77 * is set to the string value returned by <code>TabularData.class.getName()</code>. 78 * 79 * @param typeName The name given to the tabular type this instance represents; cannot be a null or empty string. 80 * <br> 81 * @param description The human readable description of the tabular type this instance represents; 82 * cannot be a null or empty string. 83 * <br> 84 * @param rowType The type of the row elements of tabular data values described by this tabular type instance; 85 * cannot be null. 86 * <br> 87 * @param indexNames The names of the items the values of which are used to uniquely index each row element in the 88 * tabular data values described by this tabular type instance; 89 * cannot be null or empty. Each element should be an item name defined in <var>rowType</var> 90 * (no null or empty string allowed). 91 * It is important to note that the <b>order</b> of the item names in <var>indexNames</var> 92 * is used by the methods {@link TabularData#get(java.lang.Object[]) get} and 93 * {@link TabularData#remove(java.lang.Object[]) remove} of class 94 * <code>TabularData</code> to match their array of values parameter to items. 95 * <br> 96 * @throws IllegalArgumentException if <var>rowType</var> is null, 97 * or <var>indexNames</var> is a null or empty array, 98 * or an element in <var>indexNames</var> is a null or empty string, 99 * or <var>typeName</var> or <var>description</var> is a null or empty string. 100 * <br> 101 * @throws OpenDataException if an element's value of <var>indexNames</var> 102 * is not an item name defined in <var>rowType</var>. 103 */ 104 public TabularType(String typeName, 105 String description, 106 CompositeType rowType, 107 String[] indexNames) throws OpenDataException { 108 109 // Check and initialize state defined by parent. 110 // 111 super(TabularData.class.getName(), typeName, description, false); 112 113 // Check rowType is not null 114 // 115 if (rowType == null) { 116 throw new IllegalArgumentException("Argument rowType cannot be null."); 117 } 118 119 // Check indexNames is neither null nor empty and does not contain any null element or empty string 120 // 121 checkForNullElement(indexNames, "indexNames"); 122 checkForEmptyString(indexNames, "indexNames"); 123 124 // Check all indexNames values are valid item names for rowType 125 // 126 for (int i=0; i<indexNames.length; i++) { 127 if ( ! rowType.containsKey(indexNames[i]) ) { 128 throw new OpenDataException("Argument's element value indexNames["+ i +"]=\""+ indexNames[i] + 129 "\" is not a valid item name for rowType."); 130 } 131 } 132 133 // initialize rowType 134 // 135 this.rowType = rowType; 136 137 // initialize indexNames (copy content so that subsequent 138 // modifs to the array referenced by the indexNames parameter 139 // have no impact) 140 // 141 List<String> tmpList = new ArrayList<String>(indexNames.length + 1); 142 for (int i=0; i<indexNames.length; i++) { 143 tmpList.add(indexNames[i]); 144 } 145 this.indexNames = Collections.unmodifiableList(tmpList); 146 } 147 148 /** 149 * Checks that Object[] arg is neither null nor empty (ie length==0) 150 * and that it does not contain any null element. 151 */ 152 private static void checkForNullElement(Object[] arg, String argName) { 153 if ( (arg == null) || (arg.length == 0) ) { 154 throw new IllegalArgumentException("Argument "+ argName +"[] cannot be null or empty."); 155 } 156 for (int i=0; i<arg.length; i++) { 157 if (arg[i] == null) { 158 throw new IllegalArgumentException("Argument's element "+ argName +"["+ i +"] cannot be null."); 159 } 160 } 161 } 162 163 /** 164 * Checks that String[] does not contain any empty (or blank characters only) string. 165 */ 166 private static void checkForEmptyString(String[] arg, String argName) { 167 for (int i=0; i<arg.length; i++) { 168 if (arg[i].trim().isEmpty()) { 169 throw new IllegalArgumentException("Argument's element "+ argName +"["+ i +"] cannot be an empty string."); 170 } 171 } 172 } 173 174 175 /* *** Tabular type specific information methods *** */ 176 177 /** 178 * Returns the type of the row elements of tabular data values 179 * described by this <code>TabularType</code> instance. 180 * 181 * @return the type of each row. 182 */ 183 public CompositeType getRowType() { 184 185 return rowType; 186 } 187 188 /** 189 * <p>Returns, in the same order as was given to this instance's 190 * constructor, an unmodifiable List of the names of the items the 191 * values of which are used to uniquely index each row element of 192 * tabular data values described by this <code>TabularType</code> 193 * instance.</p> 194 * 195 * @return a List of String representing the names of the index 196 * items. 197 * 198 */ 199 public List<String> getIndexNames() { 200 201 return indexNames; 202 } 203 204 /** 205 * Tests whether <var>obj</var> is a value which could be 206 * described by this <code>TabularType</code> instance. 207 * 208 * <p>If <var>obj</var> is null or is not an instance of 209 * <code>javax.management.openmbean.TabularData</code>, 210 * <code>isValue</code> returns <code>false</code>.</p> 211 * 212 * <p>If <var>obj</var> is an instance of 213 * <code>javax.management.openmbean.TabularData</code>, say {@code 214 * td}, the result is true if this {@code TabularType} is 215 * <em>assignable from</em> {@link TabularData#getTabularType() 216 * td.getTabularType()}, as defined in {@link 217 * CompositeType#isValue CompositeType.isValue}.</p> 218 * 219 * @param obj the value whose open type is to be tested for 220 * compatibility with this <code>TabularType</code> instance. 221 * 222 * @return <code>true</code> if <var>obj</var> is a value for this 223 * tabular type, <code>false</code> otherwise. 224 */ 225 public boolean isValue(Object obj) { 226 227 // if obj is null or not a TabularData, return false 228 // 229 if (!(obj instanceof TabularData)) 230 return false; 231 232 // if obj is not a TabularData, return false 233 // 234 TabularData value = (TabularData) obj; 235 TabularType valueType = value.getTabularType(); 236 return isAssignableFrom(valueType); 237 } 238 239 @Override 240 boolean isAssignableFrom(OpenType<?> ot) { 241 if (!(ot instanceof TabularType)) 242 return false; 243 TabularType tt = (TabularType) ot; 244 if (!getTypeName().equals(tt.getTypeName()) || 245 !getIndexNames().equals(tt.getIndexNames())) 246 return false; 247 return getRowType().isAssignableFrom(tt.getRowType()); 248 } 249 250 251 /* *** Methods overriden from class Object *** */ 252 253 /** 254 * Compares the specified <code>obj</code> parameter with this <code>TabularType</code> instance for equality. 255 * <p> 256 * Two <code>TabularType</code> instances are equal if and only if all of the following statements are true: 257 * <ul> 258 * <li>their type names are equal</li> 259 * <li>their row types are equal</li> 260 * <li>they use the same index names, in the same order</li> 261 * </ul> 262 * <br> 263 * @param obj the object to be compared for equality with this <code>TabularType</code> instance; 264 * if <var>obj</var> is <code>null</code>, <code>equals</code> returns <code>false</code>. 265 * 266 * @return <code>true</code> if the specified object is equal to this <code>TabularType</code> instance. 267 */ 268 public boolean equals(Object obj) { 269 270 // if obj is null, return false 271 // 272 if (obj == null) { 273 return false; 274 } 275 276 // if obj is not a TabularType, return false 277 // 278 TabularType other; 279 try { 280 other = (TabularType) obj; 281 } catch (ClassCastException e) { 282 return false; 283 } 284 285 // Now, really test for equality between this TabularType instance and the other: 286 // 287 288 // their names should be equal 289 if ( ! this.getTypeName().equals(other.getTypeName()) ) { 290 return false; 291 } 292 293 // their row types should be equal 294 if ( ! this.rowType.equals(other.rowType) ) { 295 return false; 296 } 297 298 // their index names should be equal and in the same order (ensured by List.equals()) 299 if ( ! this.indexNames.equals(other.indexNames) ) { 300 return false; 301 } 302 303 // All tests for equality were successfull 304 // 305 return true; 306 } 307 308 /** 309 * Returns the hash code value for this <code>TabularType</code> instance. 310 * <p> 311 * The hash code of a <code>TabularType</code> instance is the sum of the hash codes 312 * of all elements of information used in <code>equals</code> comparisons 313 * (ie: name, row type, index names). 314 * This ensures that <code> t1.equals(t2) </code> implies that <code> t1.hashCode()==t2.hashCode() </code> 315 * for any two <code>TabularType</code> instances <code>t1</code> and <code>t2</code>, 316 * as required by the general contract of the method 317 * {@link Object#hashCode() Object.hashCode()}. 318 * <p> 319 * As <code>TabularType</code> instances are immutable, the hash code for this instance is calculated once, 320 * on the first call to <code>hashCode</code>, and then the same value is returned for subsequent calls. 321 * 322 * @return the hash code value for this <code>TabularType</code> instance 323 */ 324 public int hashCode() { 325 326 // Calculate the hash code value if it has not yet been done (ie 1st call to hashCode()) 327 // 328 if (myHashCode == null) { 329 int value = 0; 330 value += this.getTypeName().hashCode(); 331 value += this.rowType.hashCode(); 332 for (String index : indexNames) 333 value += index.hashCode(); 334 myHashCode = Integer.valueOf(value); 335 } 336 337 // return always the same hash code for this instance (immutable) 338 // 339 return myHashCode.intValue(); 340 } 341 342 /** 343 * Returns a string representation of this <code>TabularType</code> instance. 344 * <p> 345 * The string representation consists of the name of this class (ie <code>javax.management.openmbean.TabularType</code>), 346 * the type name for this instance, the row type string representation of this instance, 347 * and the index names of this instance. 348 * <p> 349 * As <code>TabularType</code> instances are immutable, the string representation for this instance is calculated once, 350 * on the first call to <code>toString</code>, and then the same value is returned for subsequent calls. 351 * 352 * @return a string representation of this <code>TabularType</code> instance 353 */ 354 public String toString() { 355 356 // Calculate the string representation if it has not yet been done (ie 1st call to toString()) 357 // 358 if (myToString == null) { 359 final StringBuilder result = new StringBuilder() 360 .append(this.getClass().getName()) 361 .append("(name=") 362 .append(getTypeName()) 363 .append(",rowType=") 364 .append(rowType.toString()) 365 .append(",indexNames=("); 366 String sep = ""; 367 for (String index : indexNames) { 368 result.append(sep).append(index); 369 sep = ","; 370 } 371 result.append("))"); 372 myToString = result.toString(); 373 } 374 375 // return always the same string representation for this instance (immutable) 376 // 377 return myToString; 378 } 379 380 }