KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > validation > TypeInfoProvider


1 // $Id: TypeInfoProvider.java,v 1.11 2004/02/06 01:16:10 kk122374 Exp $
2
3 /*
4  * @(#)TypeInfoProvider.java 1.5 04/07/26
5  *
6  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
7  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
8  */
9
10 package javax.xml.validation;
11
12 import org.w3c.dom.TypeInfo JavaDoc;
13
14 /**
15  * This class provides access to the type information determined
16  * by {@link ValidatorHandler}.
17  *
18  * <p>
19  * Some schema languages, such as W3C XML Schema, encourages a validator
20  * to report the "type" it assigns to each attribute/element.
21  * Those applications who wish to access this type information can invoke
22  * methods defined on this "interface" to access such type information.
23  *
24  * <p>
25  * Implementation of this "interface" can be obtained through the
26  * {@link ValidatorHandler#getTypeInfoProvider()} method.
27  *
28  * @author <a HREF="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
29  * @version $Revision: 1.11 $, $Date: 2004/02/06 01:16:10 $
30  * @see org.w3c.dom.TypeInfo
31  * @since 1.5
32  */
33 public abstract class TypeInfoProvider {
34     
35     /**
36      * Constructor for the derived class.
37      *
38      * <p>
39      * The constructor does nothing.
40      */
41     protected TypeInfoProvider() {
42     }
43     
44     /**
45      * <p>Returns the immutable {@link TypeInfo} object for the current element.</p>
46      *
47      * <p>
48      * The method may only be called by the startElement event of
49      * the {@link org.xml.sax.ContentHandler} that the application sets to the
50      * {@link ValidatorHandler}.</p>
51      *
52      * @throws IllegalStateException
53      * If this method is called from other {@link org.xml.sax.ContentHandler}
54      * methods.
55      * @return
56      * An immutable {@link TypeInfo} object that represents the
57      * type of the current element.
58      * Note that the caller can keep references to the obtained
59      * {@link TypeInfo} longer than the callback scope.
60      *
61      * Otherwise, this method returns
62      * null if the validator is unable to
63      * determine the type of the current element for some reason
64      * (for example, if the validator is recovering from
65      * an earlier error.)
66      *
67      */
68     public abstract TypeInfo JavaDoc getElementTypeInfo();
69     
70     /**
71      * Returns the immutable {@link TypeInfo} object for the specified
72      * attribute of the current element.
73      *
74      * <p>
75      * The method may only be called by the startElement event of
76      * the {@link org.xml.sax.ContentHandler} that the application sets to the
77      * {@link ValidatorHandler}.
78      *
79      * @param index
80      * The index of the attribute. The same index for
81      * the {@link org.xml.sax.Attributes} object passed to the
82      * <tt>startElement</tt> callback.
83      *
84      * @throws IndexOutOfBoundsException
85      * If the index is invalid.
86      * @throws IllegalStateException
87      * If this method is called from other {@link org.xml.sax.ContentHandler}
88      * methods.
89      *
90      * @return
91      * An immutable {@link TypeInfo} object that represents the
92      * type of the specified attribute.
93      * Note that the caller can keep references to the obtained
94      * {@link TypeInfo} longer than the callback scope.
95      *
96      * Otherwise, this method returns
97      * null if the validator is unable to
98      * determine the type.
99      */
100     public abstract TypeInfo JavaDoc getAttributeTypeInfo(int index);
101     
102     /**
103      * Returns <tt>true</tt> if the specified attribute is determined
104      * to be ID.
105      *
106      * <p>
107      * Exacly how an attribute is "determined to be ID" is up to the
108      * schema language. In case of W3C XML Schema, this means
109      * that the actual type of the attribute is the built-in ID type
110      * or its derived type.
111      *
112      * <p>
113      * A {@link javax.xml.parsers.DocumentBuilder} uses this information
114      * to properly implement {@link org.w3c.dom.Attr#isId()}.
115      *
116      * <p>
117      * The method may only be called by the startElement event of
118      * the {@link org.xml.sax.ContentHandler} that the application sets to the
119      * {@link ValidatorHandler}.
120      *
121      * @param index
122      * The index of the attribute. The same index for
123      * the {@link org.xml.sax.Attributes} object passed to the
124      * <tt>startElement</tt> callback.
125      *
126      * @throws IndexOutOfBoundsException
127      * If the index is invalid.
128      * @throws IllegalStateException
129      * If this method is called from other {@link org.xml.sax.ContentHandler}
130      * methods.
131      *
132      * @return true
133      * if the type of the specified attribute is ID.
134      */
135     public abstract boolean isIdAttribute(int index);
136     
137     /**
138      * Returns <tt>false</tt> if the attribute was added by the validator.
139      *
140      * <p>
141      * This method provides information necessary for
142      * a {@link javax.xml.parsers.DocumentBuilder} to determine what
143      * the DOM tree should return from the {@link org.w3c.dom.Attr#getSpecified()} method.
144      *
145      * <p>
146      * The method may only be called by the startElement event of
147      * the {@link org.xml.sax.ContentHandler} that the application sets to the
148      * {@link ValidatorHandler}.
149      *
150      * <p>
151      * A general guideline for validators is to return true if
152      * the attribute was originally present in the pipeline, and
153      * false if it was added by the validator.
154      *
155      * @param index
156      * The index of the attribute. The same index for
157      * the {@link org.xml.sax.Attributes} object passed to the
158      * <tt>startElement</tt> callback.
159      *
160      * @throws IndexOutOfBoundsException
161      * If the index is invalid.
162      * @throws IllegalStateException
163      * If this method is called from other {@link org.xml.sax.ContentHandler}
164      * methods.
165      *
166      * @return
167      * <tt>true</tt> if the attribute was present before the validator
168      * processes input. <tt>false</tt> if the attribute was added
169      * by the validator.
170      */
171     public abstract boolean isSpecified(int index);
172 }
173
Popular Tags