View Javadoc
1   /*
2    * Copyright (c) 2000, 2013, 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 implementation 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      * primary.
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 description 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 the
438      * named 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 attribute 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      * explicitly 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 description 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      * enumerated 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 }