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