001 /*
002 * Copyright 2003-2005 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.xml.validation;
027
028 /**
029 * Immutable in-memory representation of grammar.
030 *
031 * <p>
032 * This object represents a set of constraints that can be checked/
033 * enforced against an XML document.
034 *
035 * <p>
036 * A {@link Schema} object is thread safe and applications are
037 * encouraged to share it across many parsers in many threads.
038 *
039 * <p>
040 * A {@link Schema} object is immutable in the sense that it shouldn't
041 * change the set of constraints once it is created. In other words,
042 * if an application validates the same document twice against the same
043 * {@link Schema}, it must always produce the same result.
044 *
045 * <p>
046 * A {@link Schema} object is usually created from {@link SchemaFactory}.
047 *
048 * <p>
049 * Two kinds of validators can be created from a {@link Schema} object.
050 * One is {@link Validator}, which provides highly-level validation
051 * operations that cover typical use cases. The other is
052 * {@link ValidatorHandler}, which works on top of SAX for better
053 * modularity.
054 *
055 * <p>
056 * This specification does not refine
057 * the {@link java.lang.Object#equals(java.lang.Object)} method.
058 * In other words, if you parse the same schema twice, you may
059 * still get <code>!schemaA.equals(schemaB)</code>.
060 *
061 * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
062 * @version $Revision: 1.3 $, $Date: 2005/10/12 17:14:21 $
063 * @see <a href="http://www.w3.org/TR/xmlschema-1/">XML Schema Part 1: Structures</a>
064 * @see <a href="http://www.w3.org/TR/xml11/">Extensible Markup Language (XML) 1.1</a>
065 * @see <a href="http://www.w3.org/TR/REC-xml">Extensible Markup Language (XML) 1.0 (Second Edition)</a>
066 * @since 1.5
067 */
068 public abstract class Schema {
069
070 /**
071 * Constructor for the derived class.
072 *
073 * <p>
074 * The constructor does nothing.
075 */
076 protected Schema() {
077 }
078
079 /**
080 * Creates a new {@link Validator} for this {@link Schema}.
081 *
082 * <p>A validator enforces/checks the set of constraints this object
083 * represents.</p>
084 *
085 * <p>Implementors should assure that the properties set on the
086 * {@link SchemaFactory} that created this {@link Schema} are also
087 * set on the {@link Validator} constructed.</p>
088 *
089 * @return
090 * Always return a non-null valid object.
091 */
092 public abstract Validator newValidator();
093
094 /**
095 * Creates a new {@link ValidatorHandler} for this {@link Schema}.
096 *
097 * <p>Implementors should assure that the properties set on the
098 * {@link SchemaFactory} that created this {@link Schema} are also
099 * set on the {@link ValidatorHandler} constructed.</p>
100 *
101 * @return
102 * Always return a non-null valid object.
103 */
104 public abstract ValidatorHandler newValidatorHandler();
105 }
|