History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/javax/imageio/metadata/IIOMetadataFormat.java (1 of 18352 files). Show all

Unified · Split

java/pkg/javax/imageio/metadata/IIOMetadataFormat.java+839−0
@@ -0,0 +1,839 @@
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+}

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t