1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 // $Id: Schema.java 446598 2006-09-15 12:55:40Z jeremias $
19
20 package javax.xml.validation;
21
22 /**
23 * Immutable in-memory representation of grammar.
24 *
25 * <p>
26 * This object represents a set of constraints that can be checked/
27 * enforced against an XML document.
28 *
29 * <p>
30 * A {@link Schema} object is thread safe and applications are
31 * encouraged to share it across many parsers in many threads.
32 *
33 * <p>
34 * A {@link Schema} object is immutable in the sense that it shouldn't
35 * change the set of constraints once it is created. In other words,
36 * if an application validates the same document twice against the same
37 * {@link Schema}, it must always produce the same result.
38 *
39 * <p>
40 * A {@link Schema} object is usually created from {@link SchemaFactory}.
41 *
42 * <p>
43 * Two kinds of validators can be created from a {@link Schema} object.
44 * One is {@link Validator}, which provides highly-level validation
45 * operations that cover typical use cases. The other is
46 * {@link ValidatorHandler}, which works on top of SAX for better
47 * modularity.
48 *
49 * <p>
50 * This specification does not refine
51 * the {@link java.lang.Object#equals(java.lang.Object)} method.
52 * In other words, if you parse the same schema twice, you may
53 * still get <code>!schemaA.equals(schemaB)</code>.
54 *
55 * @author <a href="mailto:Kohsuke.Kawaguchi@Sun.com">Kohsuke Kawaguchi</a>
56 * @version $Revision: 446598 $, $Date: 2006-09-15 08:55:40 -0400 (Fri, 15 Sep 2006) $
57 * @see <a href="http://www.w3.org/TR/xmlschema-1/">XML Schema Part 1: Structures</a>
58 * @see <a href="http://www.w3.org/TR/xml11/">Extensible Markup Language (XML) 1.1</a>
59 * @see <a href="http://www.w3.org/TR/REC-xml">Extensible Markup Language (XML) 1.0 (Second Edition)</a>
60 * @since 1.5
61 */
62 public abstract class Schema {
63
64 /**
65 * Constructor for the derived class.
66 *
67 * <p>
68 * The constructor does nothing.
69 */
70 protected Schema() {
71 }
72
73 /**
74 * Creates a new {@link Validator} for this {@link Schema}.
75 *
76 * <p>
77 * A validator enforces/checks the set of constraints this object
78 * represents.
79 *
80 * @return
81 * Always return a non-null valid object.
82 */
83 public abstract Validator newValidator();
84
85 /**
86 * Creates a new {@link ValidatorHandler} for this {@link Schema}.
87 *
88 * @return
89 * Always return a non-null valid object.
90 */
91 public abstract ValidatorHandler newValidatorHandler();
92 }