1 /*
2 * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package com.sun.xml.internal.rngom.ast.builder;
27
28 import com.sun.xml.internal.rngom.ast.om.Location;
29 import com.sun.xml.internal.rngom.ast.om.ParsedElementAnnotation;
30 import com.sun.xml.internal.rngom.ast.om.ParsedNameClass;
31 import com.sun.xml.internal.rngom.ast.om.ParsedPattern;
32 import com.sun.xml.internal.rngom.parse.*;
33 import com.sun.xml.internal.rngom.parse.IllegalSchemaException;
34 import com.sun.xml.internal.rngom.parse.Parseable;
35
36 import java.util.List;
37
38 // TODO: define combine error check should be done by the parser.
39 public interface SchemaBuilder<
40 N extends ParsedNameClass,
41 P extends ParsedPattern,
42 E extends ParsedElementAnnotation,
43 L extends Location,
44 A extends Annotations<E,L,CL>,
45 CL extends CommentList<L>> {
46
47 /**
48 * Returns the {@link NameClassBuilder}, which is used to build name
49 * classes for this {@link SchemaBuilder}. The
50 * {@link com.sun.xml.internal.rngom.nc.NameClass}es that are built will then be
51 * fed into this {@link SchemaBuilder}to further build RELAX NG patterns.
52 *
53 * @return always return a non-null valid object. This method can (and
54 * probably should) always return the same object.
55 */
56 NameClassBuilder<N,E,L,A,CL> getNameClassBuilder() throws BuildException;
57
58 P makeChoice(List<P> patterns, L loc, A anno) throws BuildException;
59
60 P makeInterleave(List<P> patterns, L loc, A anno) throws BuildException;
61
62 P makeGroup(List<P> patterns, L loc, A anno) throws BuildException;
63
64 P makeOneOrMore(P p, L loc, A anno) throws BuildException;
65
66 P makeZeroOrMore(P p, L loc, A anno) throws BuildException;
67
68 P makeOptional(P p, L loc, A anno) throws BuildException;
69
70 P makeList(P p, L loc, A anno) throws BuildException;
71
72 P makeMixed(P p, L loc, A anno) throws BuildException;
73
74 P makeEmpty(L loc, A anno);
75
76 P makeNotAllowed(L loc, A anno);
77
78 P makeText(L loc, A anno);
79
80 P makeAttribute(N nc, P p, L loc, A anno) throws BuildException;
81
82 P makeElement(N nc, P p, L loc, A anno) throws BuildException;
83
84 DataPatternBuilder makeDataPatternBuilder(String datatypeLibrary, String type, L loc) throws BuildException;
85
86 P makeValue(String datatypeLibrary, String type, String value,
87 Context c, String ns, L loc, A anno) throws BuildException;
88
89 /**
90 *
91 * @param parent
92 * The parent scope. null if there's no parent scope.
93 * For example, if the complete document looks like the following:
94 * <pre><xmp>
95 * <grammar>
96 * <start><element name="root"><empty/></element></start>
97 * </grammar>
98 * </xmp></pre>
99 * Then when the outer-most {@link Grammar} is created, it will
100 * receive the <tt>null</tt> parent.
101 */
102 Grammar<P,E,L,A,CL> makeGrammar(Scope<P,E,L,A,CL> parent);
103
104 /**
105 * Called when annotation is found right inside a pattern
106 *
107 * such as,
108 *
109 * <pre><xmp>
110 * <element name="foo"> <!-- this becomes 'P' -->
111 * <foreign:annotation /> <!-- this becomes 'A' -->
112 * ...
113 * </element>
114 * </xmp></pre>
115 */
116 P annotate(P p, A anno) throws BuildException;
117
118 /**
119 * Called when element annotation is found after a pattern.
120 *
121 * such as,
122 *
123 * <pre><xmp>
124 * <element name="foo">
125 * <empty /> <!-- this becomes 'P' -->
126 * <foreign:annotation /> <!-- this becomes 'E' -->
127 * </element>
128 * </xmp></pre>
129 */
130 P annotateAfter(P p, E e) throws BuildException;
131
132 P commentAfter(P p, CL comments) throws BuildException;
133
134 /**
135 *
136 * @param current
137 * Current grammar that we are parsing. This is what contains
138 * externalRef.
139 * @param scope
140 * The parent scope. null if there's no parent scope.
141 * See {@link #makeGrammar(Scope)} for more details about
142 * when this parameter can be null.
143 */
144 P makeExternalRef(Parseable current, String uri, String ns, Scope<P,E,L,A,CL> scope,
145 L loc, A anno) throws BuildException, IllegalSchemaException;
146
147 L makeLocation(String systemId, int lineNumber, int columnNumber);
148
149 /**
150 * Creates {@link Annotations} object to parse annotations on patterns.
151 *
152 * @return
153 * must be non-null.
154 */
155 A makeAnnotations(CL comments, Context context);
156
157 ElementAnnotationBuilder<P,E,L,A,CL> makeElementAnnotationBuilder(String ns,
158 String localName, String prefix, L loc, CL comments,
159 Context context);
160
161 CL makeCommentList();
162
163 P makeErrorPattern();
164
165 /**
166 * If this {@link SchemaBuilder}is interested in actually parsing
167 * comments, this method returns true.
168 * <p>
169 * Returning false allows the schema parser to speed up the processing by
170 * skiping comment-related handlings.
171 */
172 boolean usesComments();
173
174 /**
175 * Called after all the parsing is done.
176 *
177 * <p>
178 * This hook typically allows as {@link SchemaBuilder} to expand
179 * notAllowed (if it's following the simplification as in the spec.)
180 */
181 P expandPattern( P p ) throws BuildException, IllegalSchemaException;
182 }