001 /*
002 * Copyright 2000-2004 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.imageio.metadata;
027
028 import java.util.Locale;
029 import javax.imageio.ImageTypeSpecifier;
030
031 /**
032 * An object describing the structure of metadata documents returned
033 * from <code>IIOMetadata.getAsTree</code> and passed to
034 * <code>IIOMetadata.setFromTree</code> and <code>mergeTree</code>.
035 * Document structures are described by a set of constraints on the
036 * type and number of child elements that may belong to a given parent
037 * element type, the names, types, and values of attributes that may
038 * belong to an element, and the type and values of
039 * <code>Object</code> reference that may be stored at a node.
040 *
041 * <p> N.B: classes that implement this interface should contain a
042 * method declared as <code>public static getInstance()</code> which
043 * returns an instance of the class. Commonly, an implentation will
044 * construct only a single instance and cache it for future
045 * invocations of <code>getInstance</code>.
046 *
047 * <p> The structures that may be described by this class are a subset
048 * of those expressible using XML document type definitions (DTDs),
049 * with the addition of some basic information on the datatypes of
050 * attributes and the ability to store an <code>Object</code>
051 * reference within a node. In the future, XML Schemas could be used
052 * to represent these structures, and many others.
053 *
054 * <p> The differences between
055 * <code>IIOMetadataFormat</code>-described structures and DTDs are as
056 * follows:
057 *
058 * <ul>
059 * <li> Elements may not contain text or mix text with embedded
060 * tags.
061 *
062 * <li> The children of an element must conform to one of a few simple
063 * patterns, described in the documentation for the
064 * <code>CHILD_*</code> constants;
065 *
066 * <li> The in-memory representation of an elements may contain a
067 * reference to an <code>Object</code>. There is no provision for
068 * representing such objects textually.
069 * </ul>
070 *
071 * @version 0.5
072 */
073 public interface IIOMetadataFormat {
074
075 // Child policies
076
077 /**
078 * A constant returned by <code>getChildPolicy</code> to indicate
079 * that an element may not have any children. In other words, it
080 * is required to be a leaf node.
081 */
082 int CHILD_POLICY_EMPTY = 0;
083
084 /**
085 * A constant returned by <code>getChildPolicy</code> to indicate
086 * that an element must have a single instance of each of its
087 * legal child elements, in order. In DTD terms, the contents of
088 * the element are defined by a sequence <code>a,b,c,d,...</code>.
089 */
090 int CHILD_POLICY_ALL = 1;
091
092 /**
093 * A constant returned by <code>getChildPolicy</code> to indicate
094 * that an element must have zero or one instance of each of its
095 * legal child elements, in order. In DTD terms, the contents of
096 * the element are defined by a sequence
097 * <code>a?,b?,c?,d?,...</code>.
098 */
099 int CHILD_POLICY_SOME = 2;
100
101 /**
102 * A constant returned by <code>getChildPolicy</code> to indicate
103 * that an element must have zero or one children, selected from
104 * among its legal child elements. In DTD terms, the contents of
105 * the element are defined by a selection
106 * <code>a|b|c|d|...</code>.
107 */
108 int CHILD_POLICY_CHOICE = 3;
109
110 /**
111 * A constant returned by <code>getChildPolicy</code> to indicate
112 * that an element must have a sequence of instances of any of its
113 * legal child elements. In DTD terms, the contents of the
114 * element are defined by a sequence <code>(a|b|c|d|...)*</code>.
115 */
116 int CHILD_POLICY_SEQUENCE = 4;
117
118 /**
119 * A constant returned by <code>getChildPolicy</code> to indicate
120 * that an element must have zero or more instances of its unique
121 * legal child element. In DTD terms, the contents of the element
122 * are defined by a starred expression <code>a*</code>.
123 */
124 int CHILD_POLICY_REPEAT = 5;
125
126 /**
127 * The largest valid <code>CHILD_POLICY_*</code> constant,
128 * to be used for range checks.
129 */
130 int CHILD_POLICY_MAX = CHILD_POLICY_REPEAT;
131
132 /**
133 * A constant returned by <code>getObjectValueType</code> to
134 * indicate the absence of a user object.
135 */
136 int VALUE_NONE = 0;
137
138 /**
139 * A constant returned by <code>getAttributeValueType</code> and
140 * <code>getObjectValueType</code> to indicate that the attribute
141 * or user object may be set a single, arbitrary value.
142 */
143 int VALUE_ARBITRARY = 1;
144
145 /**
146 * A constant returned by <code>getAttributeValueType</code> and
147 * <code>getObjectValueType</code> to indicate that the attribute
148 * or user object may be set a range of values. Both the minimum
149 * and maximum values of the range are exclusive. It is
150 * recommended that ranges of integers be inclusive on both ends,
151 * and that exclusive ranges be used only for floating-point data.
152 *
153 * @see #VALUE_RANGE_MIN_MAX_INCLUSIVE
154 */
155 int VALUE_RANGE = 2;
156
157 /**
158 * A value that may be or'ed with <code>VALUE_RANGE</code> to
159 * obtain <code>VALUE_RANGE_MIN_INCLUSIVE</code>, and with
160 * <code>VALUE_RANGE_MAX_INCLUSIVE</code> to obtain
161 * <code>VALUE_RANGE_MIN_MAX_INCLUSIVE</code>.
162 *
163 * <p> Similarly, the value may be and'ed with the value of
164 * <code>getAttributeValueType</code>or
165 * <code>getObjectValueType</code> to determine if the minimum
166 * value of the range is inclusive.
167 */
168 int VALUE_RANGE_MIN_INCLUSIVE_MASK = 4;
169
170 /**
171 * A value that may be or'ed with <code>VALUE_RANGE</code> to
172 * obtain <code>VALUE_RANGE_MAX_INCLUSIVE</code>, and with
173 * <code>VALUE_RANGE_MIN_INCLUSIVE</code> to obtain
174 * <code>VALUE_RANGE_MIN_MAX_INCLUSIVE</code>.
175 *
176 * <p> Similarly, the value may be and'ed with the value of
177 * <code>getAttributeValueType</code>or
178 * <code>getObjectValueType</code> to determine if the maximum
179 * value of the range is inclusive.
180 */
181 int VALUE_RANGE_MAX_INCLUSIVE_MASK = 8;
182
183 /**
184 * A constant returned by <code>getAttributeValueType</code> and
185 * <code>getObjectValueType</code> to indicate that the attribute
186 * or user object may be set to a range of values. The minimum
187 * (but not the maximum) value of the range is inclusive.
188 */
189 int VALUE_RANGE_MIN_INCLUSIVE = VALUE_RANGE
190 | VALUE_RANGE_MIN_INCLUSIVE_MASK;
191
192 /**
193 * A constant returned by <code>getAttributeValueType</code> and
194 * <code>getObjectValueType</code> to indicate that the attribute
195 * or user object may be set to a range of values. The maximum
196 * (but not the minimum) value of the range is inclusive.
197 */
198 int VALUE_RANGE_MAX_INCLUSIVE = VALUE_RANGE
199 | VALUE_RANGE_MAX_INCLUSIVE_MASK;
200
201 /**
202 * A constant returned by <code>getAttributeValueType</code> and
203 * <code>getObjectValueType</code> to indicate that the attribute
204 * or user object may be set a range of values. Both the minimum
205 * and maximum values of the range are inclusive. It is
206 * recommended that ranges of integers be inclusive on both ends,
207 * and that exclusive ranges be used only for floating-point data.
208 */
209 int VALUE_RANGE_MIN_MAX_INCLUSIVE = VALUE_RANGE
210 | VALUE_RANGE_MIN_INCLUSIVE_MASK
211 | VALUE_RANGE_MAX_INCLUSIVE_MASK;
212
213 /**
214 * A constant returned by <code>getAttributeValueType</code> and
215 * <code>getObjectValueType</code> to indicate that the attribute
216 * or user object may be set one of a number of enumerated values.
217 * In the case of attributes, these values are
218 * <code>String</code>s; for objects, they are
219 * <code>Object</code>s implementing a given class or interface.
220 *
221 * <p> Attribute values of type <code>DATATYPE_BOOLEAN</code>
222 * should be marked as enumerations.
223 */
224 int VALUE_ENUMERATION = 16;
225
226 /**
227 * A constant returned by <code>getAttributeValueType</code> and
228 * <code>getObjectValueType</code> to indicate that the attribute
229 * or user object may be set to a list or array of values. In the
230 * case of attributes, the list will consist of
231 * whitespace-separated values within a <code>String</code>; for
232 * objects, an array will be used.
233 */
234 int VALUE_LIST = 32;
235
236 /**
237 * A constant returned by <code>getAttributeDataType</code>
238 * indicating that the value of an attribute is a general Unicode
239 * string.
240 */
241 int DATATYPE_STRING = 0;
242
243 /**
244 * A constant returned by <code>getAttributeDataType</code>
245 * indicating that the value of an attribute is one of 'true' or
246 * 'false'.
247 */
248 int DATATYPE_BOOLEAN = 1;
249
250 /**
251 * A constant returned by <code>getAttributeDataType</code>
252 * indicating that the value of an attribute is a string
253 * representation of an integer.
254 */
255 int DATATYPE_INTEGER = 2;
256
257 /**
258 * A constant returned by <code>getAttributeDataType</code>
259 * indicating that the value of an attribute is a string
260 * representation of a decimal floating-point number.
261 */
262 int DATATYPE_FLOAT = 3;
263
264 /**
265 * A constant returned by <code>getAttributeDataType</code>
266 * indicating that the value of an attribute is a string
267 * representation of a double-precision decimal floating-point
268 * number.
269 */
270 int DATATYPE_DOUBLE = 4;
271
272 // Root
273
274 /**
275 * Returns the name of the root element of the format.
276 *
277 * @return a <code>String</code>.
278 */
279 String getRootName();
280
281 // Multiplicity
282
283 /**
284 * Returns <code>true</code> if the element (and the subtree below
285 * it) is allowed to appear in a metadata document for an image of
286 * the given type, defined by an <code>ImageTypeSpecifier</code>.
287 * For example, a metadata document format might contain an
288 * element that describes the primary colors of the image, which
289 * would not be allowed when writing a grayscale image.
290 *
291 * @param elementName the name of the element being queried.
292 * @param imageType an <code>ImageTypeSpecifier</code> indicating
293 * the type of the image that will be associated with the
294 * metadata.
295 *
296 * @return <code>true</code> if the node is meaningful for images
297 * of the given type.
298 */
299 boolean canNodeAppear(String elementName,
300 ImageTypeSpecifier imageType);
301
302 /**
303 * Returns the minimum number of children of the named element
304 * with child policy <code>CHILD_POLICY_REPEAT</code>. For
305 * example, an element representing color primary information
306 * might be required to have at least 3 children, one for each
307 * primay.
308 *
309 * @param elementName the name of the element being queried.
310 *
311 * @return an <code>int</code>.
312 *
313 * @exception IllegalArgumentException if <code>elementName</code>
314 * is <code>null</code> or is not a legal element name for this
315 * format.
316 * @exception IllegalArgumentException if the named element does
317 * not have a child policy of <code>CHILD_POLICY_REPEAT</code>.
318 */
319 int getElementMinChildren(String elementName);
320
321 /**
322 * Returns the maximum number of children of the named element
323 * with child policy <code>CHILD_POLICY_REPEAT</code>. For
324 * example, an element representing an entry in an 8-bit color
325 * palette might be allowed to repeat up to 256 times. A value of
326 * <code>Integer.MAX_VALUE</code> may be used to specify that
327 * there is no upper bound.
328 *
329 * @param elementName the name of the element being queried.
330 *
331 * @return an <code>int</code>.
332 *
333 * @exception IllegalArgumentException if <code>elementName</code>
334 * is <code>null</code> or is not a legal element name for this
335 * format.
336 * @exception IllegalArgumentException if the named element does
337 * not have a child policy of <code>CHILD_POLICY_REPEAT</code>.
338 */
339 int getElementMaxChildren(String elementName);
340
341 /**
342 * Returns a <code>String</code> containing a description of the
343 * named element, or <code>null</code>. The desciption will be
344 * localized for the supplied <code>Locale</code> if possible.
345 *
346 * <p> If <code>locale</code> is <code>null</code>, the current
347 * default <code>Locale</code> returned by <code>Locale.getLocale</code>
348 * will be used.
349 *
350 * @param elementName the name of the element.
351 * @param locale the <code>Locale</code> for which localization
352 * will be attempted.
353 *
354 * @return the element description.
355 *
356 * @exception IllegalArgumentException if <code>elementName</code>
357 * is <code>null</code>, or is not a legal element name for this format.
358 */
359 String getElementDescription(String elementName, Locale locale);
360
361 // Children
362
363 /**
364 * Returns one of the constants starting with
365 * <code>CHILD_POLICY_</code>, indicating the legal pattern of
366 * children for the named element.
367 *
368 * @param elementName the name of the element being queried.
369 *
370 * @return one of the <code>CHILD_POLICY_*</code> constants.
371 *
372 * @exception IllegalArgumentException if <code>elementName</code>
373 * is <code>null</code> or is not a legal element name for this
374 * format.
375 */
376 int getChildPolicy(String elementName);
377
378 /**
379 * Returns an array of <code>String</code>s indicating the names
380 * of the element which are allowed to be children of the named
381 * element, in the order in which they should appear. If the
382 * element cannot have children, <code>null</code> is returned.
383 *
384 * @param elementName the name of the element being queried.
385 *
386 * @return an array of <code>String</code>s, or null.
387 *
388 * @exception IllegalArgumentException if <code>elementName</code>
389 * is <code>null</code> or is not a legal element name for this
390 * format.
391 */
392 String[] getChildNames(String elementName);
393
394 // Attributes
395
396 /**
397 * Returns an array of <code>String</code>s listing the names of
398 * the attributes that may be associated with the named element.
399 *
400 * @param elementName the name of the element being queried.
401 *
402 * @return an array of <code>String</code>s.
403 *
404 * @exception IllegalArgumentException if <code>elementName</code>
405 * is <code>null</code> or is not a legal element name for this
406 * format.
407 */
408 String[] getAttributeNames(String elementName);
409
410 /**
411 * Returns one of the constants starting with <code>VALUE_</code>,
412 * indicating whether the values of the given attribute within the
413 * named element are arbitrary, constrained to lie within a
414 * specified range, constrained to be one of a set of enumerated
415 * values, or are a whitespace-separated list of arbitrary values.
416 *
417 * @param elementName the name of the element being queried.
418 * @param attrName the name of the attribute being queried.
419 *
420 * @return one of the <code>VALUE_*</code> constants.
421 *
422 * @exception IllegalArgumentException if <code>elementName</code>
423 * is <code>null</code> or is not a legal element name for this
424 * format.
425 * @exception IllegalArgumentException if <code>attrName</code> is
426 * <code>null</code> or is not a legal attribute name for this
427 * element.
428 */
429 int getAttributeValueType(String elementName, String attrName);
430
431 /**
432 * Returns one of the constants starting with
433 * <code>DATATYPE_</code>, indicating the format and
434 * interpretation of the value of the given attribute within th
435 * enamed element. If <code>getAttributeValueType</code> returns
436 * <code>VALUE_LIST</code>, then the legal value is a
437 * whitespace-spearated list of values of the returned datatype.
438 *
439 * @param elementName the name of the element being queried.
440 * @param attrName the name of the attribute being queried.
441 *
442 * @return one of the <code>DATATYPE_*</code> constants.
443 *
444 * @exception IllegalArgumentException if <code>elementName</code>
445 * is <code>null</code> or is not a legal element name for this
446 * format.
447 * @exception IllegalArgumentException if <code>attrName</code> is
448 * <code>null</code> or is not a legal attribute name for this
449 * element.
450 */
451 int getAttributeDataType(String elementName, String attrName);
452
453 /**
454 * Returns <code>true</code> if the named attribute must be
455 * present within the named element.
456 *
457 * @param elementName the name of the element being queried.
458 * @param attrName the name of the attribute being queried.
459 *
460 * @return <code>true</code> if the attribut must be present.
461 *
462 * @exception IllegalArgumentException if <code>elementName</code>
463 * is <code>null</code> or is not a legal element name for this
464 * format.
465 * @exception IllegalArgumentException if <code>attrName</code> is
466 * <code>null</code> or is not a legal attribute name for this
467 * element.
468 */
469 boolean isAttributeRequired(String elementName, String attrName);
470
471 /**
472 * Returns the default value of the named attribute, if it is not
473 * explictly present within the named element, as a
474 * <code>String</code>, or <code>null</code> if no default value
475 * is available.
476 *
477 * @param elementName the name of the element being queried.
478 * @param attrName the name of the attribute being queried.
479 *
480 * @return a <code>String</code> containing the default value, or
481 * <code>null</code>.
482 *
483 * @exception IllegalArgumentException if <code>elementName</code>
484 * is <code>null</code> or is not a legal element name for this
485 * format.
486 * @exception IllegalArgumentException if <code>attrName</code> is
487 * <code>null</code> or is not a legal attribute name for this
488 * element.
489 */
490 String getAttributeDefaultValue(String elementName, String attrName);
491
492 /**
493 * Returns an array of <code>String</code>s containing the legal
494 * enumerated values for the given attribute within the named
495 * element. This method should only be called if
496 * <code>getAttributeValueType</code> returns
497 * <code>VALUE_ENUMERATION</code>.
498 *
499 * @param elementName the name of the element being queried.
500 * @param attrName the name of the attribute being queried.
501 *
502 * @return an array of <code>String</code>s.
503 *
504 * @exception IllegalArgumentException if <code>elementName</code>
505 * is <code>null</code> or is not a legal element name for this
506 * format.
507 * @exception IllegalArgumentException if <code>attrName</code> is
508 * <code>null</code> or is not a legal attribute name for this
509 * element.
510 * @exception IllegalArgumentException if the given attribute is
511 * not defined as an enumeration.
512 */
513 String[] getAttributeEnumerations(String elementName,
514 String attrName);
515
516 /**
517 * Returns the minimum legal value for the attribute. Whether
518 * this value is inclusive or exclusive may be determined by the
519 * value of <code>getAttributeValueType</code>. The value is
520 * returned as a <code>String</code>; its interpretation is
521 * dependent on the value of <code>getAttributeDataType</code>.
522 * This method should only be called if
523 * <code>getAttributeValueType</code> returns
524 * <code>VALUE_RANGE_*</code>.
525 *
526 * @param elementName the name of the element being queried.
527 * @param attrName the name of the attribute being queried.
528 *
529 * @return a <code>String</code> containing the smallest legal
530 * value for the attribute.
531 *
532 * @exception IllegalArgumentException if <code>elementName</code>
533 * is <code>null</code> or is not a legal element name for this
534 * format.
535 * @exception IllegalArgumentException if <code>attrName</code> is
536 * <code>null</code> or is not a legal attribute name for this
537 * element.
538 * @exception IllegalArgumentException if the given attribute is
539 * not defined as a range.
540 */
541 String getAttributeMinValue(String elementName, String attrName);
542
543 /**
544 * Returns the maximum legal value for the attribute. Whether
545 * this value is inclusive or exclusive may be determined by the
546 * value of <code>getAttributeValueType</code>. The value is
547 * returned as a <code>String</code>; its interpretation is
548 * dependent on the value of <code>getAttributeDataType</code>.
549 * This method should only be called if
550 * <code>getAttributeValueType</code> returns
551 * <code>VALUE_RANGE_*</code>.
552 *
553 * @param elementName the name of the element being queried, as a
554 * <code>String</code>.
555 * @param attrName the name of the attribute being queried.
556 *
557 * @return a <code>String</code> containing the largest legal
558 * value for the attribute.
559 *
560 * @exception IllegalArgumentException if <code>elementName</code>
561 * is <code>null</code> or is not a legal element name for this
562 * format.
563 * @exception IllegalArgumentException if <code>attrName</code> is
564 * <code>null</code> or is not a legal attribute name for this
565 * element.
566 * @exception IllegalArgumentException if the given attribute is
567 * not defined as a range.
568 */
569 String getAttributeMaxValue(String elementName, String attrName);
570
571 /**
572 * Returns the minimum number of list items that may be used to
573 * define this attribute. The attribute itself is defined as a
574 * <code>String</code> containing multiple whitespace-separated
575 * items. This method should only be called if
576 * <code>getAttributeValueType</code> returns
577 * <code>VALUE_LIST</code>.
578 *
579 * @param elementName the name of the element being queried.
580 * @param attrName the name of the attribute being queried.
581 *
582 * @return the smallest legal number of list items for the
583 * attribute.
584 *
585 * @exception IllegalArgumentException if <code>elementName</code>
586 * is <code>null</code> or is not a legal element name for this
587 * format.
588 * @exception IllegalArgumentException if <code>attrName</code> is
589 * <code>null</code> or is not a legal attribute name for this
590 * element.
591 * @exception IllegalArgumentException if the given attribute is
592 * not defined as a list.
593 */
594 int getAttributeListMinLength(String elementName, String attrName);
595
596 /**
597 * Returns the maximum number of list items that may be used to
598 * define this attribute. A value of
599 * <code>Integer.MAX_VALUE</code> may be used to specify that
600 * there is no upper bound. The attribute itself is defined as a
601 * <code>String</code> containing multiple whitespace-separated
602 * items. This method should only be called if
603 * <code>getAttributeValueType</code> returns
604 * <code>VALUE_LIST</code>.
605 *
606 * @param elementName the name of the element being queried.
607 * @param attrName the name of the attribute being queried.
608 *
609 * @return the largest legal number of list items for the
610 * attribute.
611 *
612 * @exception IllegalArgumentException if <code>elementName</code>
613 * is <code>null</code> or is not a legal element name for this
614 * format.
615 * @exception IllegalArgumentException if <code>attrName</code> is
616 * <code>null</code> or is not a legal attribute name for this
617 * element.
618 * @exception IllegalArgumentException if the given attribute is
619 * not defined as a list.
620 */
621 int getAttributeListMaxLength(String elementName, String attrName);
622
623 /**
624 * Returns a <code>String</code> containing a description of the
625 * named attribute, or <code>null</code>. The desciption will be
626 * localized for the supplied <code>Locale</code> if possible.
627 *
628 * <p> If <code>locale</code> is <code>null</code>, the current
629 * default <code>Locale</code> returned by <code>Locale.getLocale</code>
630 * will be used.
631 *
632 * @param elementName the name of the element.
633 * @param attrName the name of the attribute.
634 * @param locale the <code>Locale</code> for which localization
635 * will be attempted.
636 *
637 * @return the attribute description.
638 *
639 * @exception IllegalArgumentException if <code>elementName</code>
640 * is <code>null</code>, or is not a legal element name for this format.
641 * @exception IllegalArgumentException if <code>attrName</code> is
642 * <code>null</code> or is not a legal attribute name for this
643 * element.
644 */
645 String getAttributeDescription(String elementName, String attrName,
646 Locale locale);
647
648 // Object value
649
650 /**
651 * Returns one of the enumerated values starting with
652 * <code>VALUE_</code>, indicating the type of values
653 * (enumeration, range, or array) that are allowed for the
654 * <code>Object</code> reference. If no object value can be
655 * stored within the given element, the result of this method will
656 * be <code>VALUE_NONE</code>.
657 *
658 * <p> <code>Object</code> references whose legal values are
659 * defined as a range must implement the <code>Comparable</code>
660 * interface.
661 *
662 * @param elementName the name of the element being queried.
663 *
664 * @return one of the <code>VALUE_*</code> constants.
665 *
666 * @exception IllegalArgumentException if <code>elementName</code>
667 * is <code>null</code> or is not a legal element name for this
668 * format.
669 *
670 * @see Comparable
671 */
672 int getObjectValueType(String elementName);
673
674 /**
675 * Returns the <code>Class</code> type of the <code>Object</code>
676 * reference stored within the element. If this element may not
677 * contain an <code>Object</code> reference, an
678 * <code>IllegalArgumentException</code> will be thrown. If the
679 * class type is an array, this field indicates the underlying
680 * class type (<i>e.g</i>, for an array of <code>int</code>s, this
681 * method would return <code>int.class</code>).
682 *
683 * <p> <code>Object</code> references whose legal values are
684 * defined as a range must implement the <code>Comparable</code>
685 * interface.
686 *
687 * @param elementName the name of the element being queried.
688 *
689 * @return a <code>Class</code> object.
690 *
691 * @exception IllegalArgumentException if <code>elementName</code>
692 * is <code>null</code> or is not a legal element name for this
693 * format.
694 * @exception IllegalArgumentException if the named element cannot
695 * contain an object value (<i>i.e.</i>, if
696 * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
697 */
698 Class<?> getObjectClass(String elementName);
699
700 /**
701 * Returns an <code>Object</code>s containing the default
702 * value for the <code>Object</code> reference within
703 * the named element.
704 *
705 * @param elementName the name of the element being queried.
706 *
707 * @return an <code>Object</code>.
708 *
709 * @exception IllegalArgumentException if <code>elementName</code>
710 * is <code>null</code> or is not a legal element name for this
711 * format.
712 * @exception IllegalArgumentException if the named element cannot
713 * contain an object value (<i>i.e.</i>, if
714 * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
715 */
716 Object getObjectDefaultValue(String elementName);
717
718 /**
719 * Returns an array of <code>Object</code>s containing the legal
720 * enumerated values for the <code>Object</code> reference within
721 * the named element. This method should only be called if
722 * <code>getObjectValueType</code> returns
723 * <code>VALUE_ENUMERATION</code>.
724 *
725 * <p> The <code>Object</code> associated with a node that accepts
726 * emuerated values must be equal to one of the values returned by
727 * this method, as defined by the <code>==</code> operator (as
728 * opposed to the <code>Object.equals</code> method).
729 *
730 * @param elementName the name of the element being queried.
731 *
732 * @return an array of <code>Object</code>s.
733 *
734 * @exception IllegalArgumentException if <code>elementName</code>
735 * is <code>null</code> or is not a legal element name for this
736 * format.
737 * @exception IllegalArgumentException if the named element cannot
738 * contain an object value (<i>i.e.</i>, if
739 * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
740 * @exception IllegalArgumentException if the <code>Object</code>
741 * is not defined as an enumeration.
742 */
743 Object[] getObjectEnumerations(String elementName);
744
745 /**
746 * Returns the minimum legal value for the <code>Object</code>
747 * reference within the named element. Whether this value is
748 * inclusive or exclusive may be determined by the value of
749 * <code>getObjectValueType</code>. This method should only be
750 * called if <code>getObjectValueType</code> returns one of the
751 * constants starting with <code>VALUE_RANGE</code>.
752 *
753 * @param elementName the name of the element being queried.
754 *
755 * @return the smallest legal value for the attribute.
756 *
757 * @exception IllegalArgumentException if <code>elementName</code>
758 * is <code>null</code> or is not a legal element name for this
759 * format.
760 * @exception IllegalArgumentException if the named element cannot
761 * contain an object value (<i>i.e.</i>, if
762 * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
763 * @exception IllegalArgumentException if the <code>Object</code>
764 * is not defined as a range.
765 */
766 Comparable<?> getObjectMinValue(String elementName);
767
768 /**
769 * Returns the maximum legal value for the <code>Object</code>
770 * reference within the named element. Whether this value is
771 * inclusive or exclusive may be determined by the value of
772 * <code>getObjectValueType</code>. This method should only be
773 * called if <code>getObjectValueType</code> returns one of the
774 * constants starting with <code>VALUE_RANGE</code>.
775 *
776 * @return the smallest legal value for the attribute.
777 *
778 * @param elementName the name of the element being queried.
779 *
780 * @exception IllegalArgumentException if <code>elementName</code>
781 * is <code>null</code> or is not a legal element name for this
782 * format.
783 * @exception IllegalArgumentException if the named element cannot
784 * contain an object value (<i>i.e.</i>, if
785 * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
786 * @exception IllegalArgumentException if the <code>Object</code>
787 * is not defined as a range.
788 */
789 Comparable<?> getObjectMaxValue(String elementName);
790
791 /**
792 * Returns the minimum number of array elements that may be used
793 * to define the <code>Object</code> reference within the named
794 * element. This method should only be called if
795 * <code>getObjectValueType</code> returns
796 * <code>VALUE_LIST</code>.
797 *
798 * @param elementName the name of the element being queried.
799 *
800 * @return the smallest valid array length for the
801 * <code>Object</code> reference.
802 *
803 * @exception IllegalArgumentException if <code>elementName</code>
804 * is <code>null</code> or is not a legal element name for this
805 * format.
806 * @exception IllegalArgumentException if the named element cannot
807 * contain an object value (<i>i.e.</i>, if
808 * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
809 * @exception IllegalArgumentException if the <code>Object</code> is not
810 * an array.
811 */
812 int getObjectArrayMinLength(String elementName);
813
814 /**
815 * Returns the maximum number of array elements that may be used
816 * to define the <code>Object</code> reference within the named
817 * element. A value of <code>Integer.MAX_VALUE</code> may be used
818 * to specify that there is no upper bound. This method should
819 * only be called if <code>getObjectValueType</code> returns
820 * <code>VALUE_LIST</code>.
821 *
822 * @param elementName the name of the element being queried.
823 *
824 * @return the largest valid array length for the
825 * <code>Object</code> reference.
826 *
827 * @exception IllegalArgumentException if <code>elementName</code>
828 * is <code>null</code> or is not a legal element name for this
829 * format.
830 * @exception IllegalArgumentException if the named element cannot
831 * contain an object value (<i>i.e.</i>, if
832 * <code>getObjectValueType(elementName) == VALUE_NONE</code>).
833 * @exception IllegalArgumentException if the <code>Object</code> is not
834 * an array.
835 */
836 int getObjectArrayMaxLength(String elementName);
837 }
|