KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > enhydra > apache > xerces > validators > common > XMLContentModel


1 /*
2  * The Apache Software License, Version 1.1
3  *
4  *
5  * Copyright (c) 1999,2000 The Apache Software Foundation. All rights
6  * reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * 1. Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  *
15  * 2. Redistributions in binary form must reproduce the above copyright
16  * notice, this list of conditions and the following disclaimer in
17  * the documentation and/or other materials provided with the
18  * distribution.
19  *
20  * 3. The end-user documentation included with the redistribution,
21  * if any, must include the following acknowledgment:
22  * "This product includes software developed by the
23  * Apache Software Foundation (http://www.apache.org/)."
24  * Alternately, this acknowledgment may appear in the software itself,
25  * if and wherever such third-party acknowledgments normally appear.
26  *
27  * 4. The names "Xerces" and "Apache Software Foundation" must
28  * not be used to endorse or promote products derived from this
29  * software without prior written permission. For written
30  * permission, please contact apache@apache.org.
31  *
32  * 5. Products derived from this software may not be called "Apache",
33  * nor may "Apache" appear in their name, without prior written
34  * permission of the Apache Software Foundation.
35  *
36  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47  * SUCH DAMAGE.
48  * ====================================================================
49  *
50  * This software consists of voluntary contributions made by many
51  * individuals on behalf of the Apache Software Foundation and was
52  * originally based on software copyright (c) 1999, International
53  * Business Machines, Inc., http://www.apache.org. For more
54  * information on the Apache Software Foundation, please see
55  * <http://www.apache.org/>.
56  */
57
58 package org.enhydra.apache.xerces.validators.common;
59
60 import org.enhydra.apache.xerces.utils.QName;
61 import org.enhydra.apache.xerces.validators.schema.SchemaGrammar;
62 import org.enhydra.apache.xerces.validators.schema.SubstitutionGroupComparator;
63
64 /**
65  * ContentModel is an interface that can be used by your own custom validators
66  * to plug in various types of content models. It is used internally as well
67  * for the same purposes.
68  * <p>
69  * Since there are a number of optimizations that can be used for simple or
70  * special content models, this class provides the interface via which all of
71  * the various content model types are managed. So the validation handler
72  * class has a list of things derived from this class. It finds the one for
73  * the desired element, then asks it to validate the element contents.
74  * <p>
75  * The validation interface from the scanner to the validation handle provides
76  * a child count and an array of element name indices into the string pool.
77  * So it is assumed that those same parameters will be passed to the content
78  * model to be validated. Therefore the validateContent() method accepts
79  * this standard view of the elements to be validated.
80  *
81  * @author Dean Roddey, Eric Ye
82  * @version $Id: XMLContentModel.java,v 1.2 2005/01/26 08:28:44 jkjome Exp $
83  */
84 public interface XMLContentModel {
85
86     /**
87      * Check that the specified content is valid according to this
88      * content model. This method can also be called to do 'what if'
89      * testing of content models just to see if they would be valid.
90      * <p>
91      * A value of -1 in the children array indicates a PCDATA node. All other
92      * indexes will be positive and represent child elements. The count can be
93      * zero, since some elements have the EMPTY content model and that must be
94      * confirmed.
95      *
96      * @param children The children of this element. Each integer is an index within
97      * the <code>StringPool</code> of the child element name. An index
98      * of -1 is used to indicate an occurrence of non-whitespace character
99      * data.
100      * @param offset Offset into the array where the children starts.
101      * @param length The number of entries in the <code>children</code> array.
102      *
103      * @return The value -1 if fully valid, else the 0 based index of the child
104      * that first failed. If the value returned is equal to the number
105      * of children, then the specified children are valid but additional
106      * content is required to reach a valid ending state.
107      *
108      * @exception Exception Thrown on error.
109      */
110     public int validateContent(QName children[], int offset, int length) throws Exception JavaDoc;
111
112     /**
113      * This method is different from "validateContent" in that it will try to use
114      * the SubstitutionGroupComparator to match children against the content model.
115      * <p>
116      * A value of -1 in the children array indicates a PCDATA node. All other
117      * indexes will be positive and represent child elements. The count can be
118      * zero, since some elements have the EMPTY content model and that must be
119      * confirmed.
120      *
121      * @param children The children of this element. Each integer is an index within
122      * the <code>StringPool</code> of the child element name. An index
123      * of -1 is used to indicate an occurrence of non-whitespace character
124      * data.
125      * @param offset Offset into the array where the children starts.
126      * @param length The number of entries in the <code>children</code> array.
127      *
128      * @return The value -1 if fully valid, else the 0 based index of the child
129      * that first failed. If the value returned is equal to the number
130      * of children, then the specified children are valid but additional
131      * content is required to reach a valid ending state.
132      *
133      * @exception Exception Thrown on error.
134      */
135     public int validateContentSpecial(QName children[], int offset, int length) throws Exception JavaDoc;
136
137     /**
138      * The setter method to pass in the SubstitutionGroupComparator.
139      *
140      * @param comparator a SubstitutionGroupComparator object.
141      * @return
142      * @exception
143      */
144     public void setSubstitutionGroupComparator(SubstitutionGroupComparator comparator);// should really use a Comparator interface
145
146     /**
147      * Returns information about which elements can be placed at a particular point
148      * in the passed element's content model.
149      * <p>
150      * Note that the incoming content model to test must be valid at least up to
151      * the insertion point. If not, then -1 will be returned and the info object
152      * will not have been filled in.
153      * <p>
154      * If, on return, the info.isValidEOC flag is set, then the 'insert after'
155      * element is a valid end of content. In other words, nothing needs to be
156      * inserted after it to make the parent element's content model valid.
157      *
158      * @param fullyValid Only return elements that can be inserted and still
159      * maintain the validity of subsequent elements past the
160      * insertion point (if any). If the insertion point is at
161      * the end, and this is true, then only elements that can
162      * be legal final states will be returned.
163      * @param info An object that contains the required input data for the method,
164      * and which will contain the output information if successful.
165      *
166      * @return The value -1 if fully valid, else the 0 based index of the child
167      * that first failed before the insertion point. If the value
168      * returned is equal to the number of children, then the specified
169      * children are valid but additional content is required to reach a
170      * valid ending state.
171      *
172      * @see InsertableElementsInfo
173      */
174     public int whatCanGoHere(boolean fullyValid,
175                              InsertableElementsInfo info) throws Exception JavaDoc;
176
177     public ContentLeafNameTypeVector getContentLeafNameTypeVector() ;
178
179     // each kind of content model needs to provide a way to validate
180 // Unique Particle Attribution
181 public void checkUniqueParticleAttribution(SchemaGrammar gram) throws Exception JavaDoc;
182 } // interface XMLContentModel
183
Popular Tags