Source Code Cross Referenced for IIOMetadataFormat.java in  » 6.0-JDK-Core » image » javax » imageio » metadata » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Home
Java Source Code / Java Documentation
1.6.0 JDK Core
2.6.0 JDK Modules
3.6.0 JDK Modules com.sun
4.6.0 JDK Modules com.sun.java
5.6.0 JDK Modules sun
6.6.0 JDK Platform
7.Ajax
8.Apache Harmony Java SE
9.Aspect oriented
10.Authentication Authorization
11.Blogger System
12.Build
13.Byte Code
14.Cache
15.Chart
16.Chat
17.Code Analyzer
18.Collaboration
19.Content Management System
20.Database Client
21.Database DBMS
22.Database JDBC Connection Pool
23.Database ORM
24.Development
25.EJB Server
26.ERP CRM Financial
27.ESB
28.Forum
29.Game
30.GIS
31.Graphic 3D
32.Graphic Library
33.Groupware
34.HTML Parser
35.IDE
36.IDE Eclipse
37.IDE Netbeans
38.Installer
39.Internationalization Localization
40.Inversion of Control
41.Issue Tracking
42.J2EE
43.J2ME
44.JBoss
45.JMS
46.JMX
47.Library
48.Mail Clients
49.Music
50.Net
51.Parser
52.PDF
53.Portal
54.Profiler
55.Project Management
56.Report
57.RSS RDF
58.Rule Engine
59.Science
60.Scripting
61.Search Engine
62.Security
63.Sevlet Container
64.Source Control
65.Swing Library
66.Template Engine
67.Test Coverage
68.Testing
69.UML
70.Web Crawler
71.Web Framework
72.Web Mail
73.Web Server
74.Web Services
75.Web Services apache cxf 2.2.6
76.Web Services AXIS2
77.Wiki Engine
78.Workflow Engines
79.XML
80.XML UI
Java Source Code / Java Documentation » 6.0 JDK Core » image » javax.imageio.metadata 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


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