001: /*
002: * The Apache Software License, Version 1.1
003: *
004: *
005: * Copyright (c) 1999,2000 The Apache Software Foundation. All rights
006: * reserved.
007: *
008: * Redistribution and use in source and binary forms, with or without
009: * modification, are permitted provided that the following conditions
010: * are met:
011: *
012: * 1. Redistributions of source code must retain the above copyright
013: * notice, this list of conditions and the following disclaimer.
014: *
015: * 2. Redistributions in binary form must reproduce the above copyright
016: * notice, this list of conditions and the following disclaimer in
017: * the documentation and/or other materials provided with the
018: * distribution.
019: *
020: * 3. The end-user documentation included with the redistribution,
021: * if any, must include the following acknowledgment:
022: * "This product includes software developed by the
023: * Apache Software Foundation (http://www.apache.org/)."
024: * Alternately, this acknowledgment may appear in the software itself,
025: * if and wherever such third-party acknowledgments normally appear.
026: *
027: * 4. The names "Xerces" and "Apache Software Foundation" must
028: * not be used to endorse or promote products derived from this
029: * software without prior written permission. For written
030: * permission, please contact apache@apache.org.
031: *
032: * 5. Products derived from this software may not be called "Apache",
033: * nor may "Apache" appear in their name, without prior written
034: * permission of the Apache Software Foundation.
035: *
036: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
037: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
038: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
039: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
040: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
041: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
042: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
043: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
044: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
045: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
046: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
047: * SUCH DAMAGE.
048: * ====================================================================
049: *
050: * This software consists of voluntary contributions made by many
051: * individuals on behalf of the Apache Software Foundation and was
052: * originally based on software copyright (c) 1999, International
053: * Business Machines, Inc., http://www.apache.org. For more
054: * information on the Apache Software Foundation, please see
055: * <http://www.apache.org/>.
056: */
057:
058: package org.apache.xerces.validators.common;
059:
060: import org.apache.xerces.utils.QName;
061: import org.apache.xerces.validators.schema.SubstitutionGroupComparator;
062: import org.apache.xerces.validators.schema.SchemaGrammar;
063:
064: /**
065: * ContentModel is an interface that can be used by your own custom validators
066: * to plug in various types of content models. It is used internally as well
067: * for the same purposes.
068: * <p>
069: * Since there are a number of optimizations that can be used for simple or
070: * special content models, this class provides the interface via which all of
071: * the various content model types are managed. So the validation handler
072: * class has a list of things derived from this class. It finds the one for
073: * the desired element, then asks it to validate the element contents.
074: * <p>
075: * The validation interface from the scanner to the validation handle provides
076: * a child count and an array of element name indices into the string pool.
077: * So it is assumed that those same parameters will be passed to the content
078: * model to be validated. Therefore the validateContent() method accepts
079: * this standard view of the elements to be validated.
080: *
081: * @author Dean Roddey, Eric Ye
082: * @version $Id: XMLContentModel.java,v 1.8 2001/06/20 20:54:40 neilg Exp $
083: */
084: public interface XMLContentModel {
085:
086: /**
087: * Check that the specified content is valid according to this
088: * content model. This method can also be called to do 'what if'
089: * testing of content models just to see if they would be valid.
090: * <p>
091: * A value of -1 in the children array indicates a PCDATA node. All other
092: * indexes will be positive and represent child elements. The count can be
093: * zero, since some elements have the EMPTY content model and that must be
094: * confirmed.
095: *
096: * @param children The children of this element. Each integer is an index within
097: * the <code>StringPool</code> of the child element name. An index
098: * of -1 is used to indicate an occurrence of non-whitespace character
099: * 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)
111: throws Exception;
112:
113: /**
114: * This method is different from "validateContent" in that it will try to use
115: * the SubstitutionGroupComparator to match children against the content model.
116: * <p>
117: * A value of -1 in the children array indicates a PCDATA node. All other
118: * indexes will be positive and represent child elements. The count can be
119: * zero, since some elements have the EMPTY content model and that must be
120: * confirmed.
121: *
122: * @param children The children of this element. Each integer is an index within
123: * the <code>StringPool</code> of the child element name. An index
124: * of -1 is used to indicate an occurrence of non-whitespace character
125: * data.
126: * @param offset Offset into the array where the children starts.
127: * @param length The number of entries in the <code>children</code> array.
128: *
129: * @return The value -1 if fully valid, else the 0 based index of the child
130: * that first failed. If the value returned is equal to the number
131: * of children, then the specified children are valid but additional
132: * content is required to reach a valid ending state.
133: *
134: * @exception Exception Thrown on error.
135: */
136: public int validateContentSpecial(QName children[], int offset,
137: int length) throws Exception;
138:
139: /**
140: * The setter method to pass in the SubstitutionGroupComparator.
141: *
142: * @param comparator a SubstitutionGroupComparator object.
143: * @return
144: * @exception
145: */
146: public void setSubstitutionGroupComparator(
147: SubstitutionGroupComparator comparator);// should really use a Comparator interface
148:
149: /**
150: * Returns information about which elements can be placed at a particular point
151: * in the passed element's content model.
152: * <p>
153: * Note that the incoming content model to test must be valid at least up to
154: * the insertion point. If not, then -1 will be returned and the info object
155: * will not have been filled in.
156: * <p>
157: * If, on return, the info.isValidEOC flag is set, then the 'insert after'
158: * element is a valid end of content. In other words, nothing needs to be
159: * inserted after it to make the parent element's content model valid.
160: *
161: * @param fullyValid Only return elements that can be inserted and still
162: * maintain the validity of subsequent elements past the
163: * insertion point (if any). If the insertion point is at
164: * the end, and this is true, then only elements that can
165: * be legal final states will be returned.
166: * @param info An object that contains the required input data for the method,
167: * and which will contain the output information if successful.
168: *
169: * @return The value -1 if fully valid, else the 0 based index of the child
170: * that first failed before the insertion point. If the value
171: * returned is equal to the number of children, then the specified
172: * children are valid but additional content is required to reach a
173: * valid ending state.
174: *
175: * @see InsertableElementsInfo
176: */
177: public int whatCanGoHere(boolean fullyValid,
178: InsertableElementsInfo info) throws Exception;
179:
180: public ContentLeafNameTypeVector getContentLeafNameTypeVector();
181:
182: // each kind of content model needs to provide a way to validate
183: // Unique Particle Attribution
184: public void checkUniqueParticleAttribution(SchemaGrammar gram)
185: throws Exception;
186: } // interface XMLContentModel
|