IIOMetadataFormat


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