1 /* Copyright 2004 The Apache Software Foundation
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16 package org.apache.xmlbeans;
17
18 import java.io.File;
19
20 /**
21 * A finite set of XML Schema component definitions.
22 * <p>
23 * Every {@link SchemaComponent} such as a {@link SchemaType},
24 * {@link SchemaGlobalElement}, {@link SchemaGlobalAttribute},
25 * {@link SchemaModelGroup}, {@link SchemaAttributeGroup}, or
26 * {@link SchemaIdentityConstraint}, is defined in exactly one
27 * SchemaTypeSystem. (See {@link SchemaComponent#getTypeSystem()}.)
28 * A single SchemaTypeSystem can include definitions
29 * from any number of namespaces; one SchemaTypeSystem consists simply
30 * of a set of component definitions that were compiled together.
31 * <p>
32 * Since every component is defined in a single SchemaTypeSystem, no
33 * SchemaTypeSystem other than {@link XmlBeans#getBuiltinTypeSystem()}
34 * includes any of the the built-in types. That means
35 * you cannot ordinarily load instances using a single
36 * SchemaTypeSystem by itself. Instead, you will want to combine a path of
37 * SchemaTypeSystems together using {@link XmlBeans#typeLoaderUnion}
38 * to form a SchemaTypeLoader that can be used for loading instances.
39 * <p>
40 * For example, the following code compiles the schema in myXSDFile
41 * in the presence of only the minimal builtin type system.
42 * The resulting SchemaTypeSystem <code>sts</code> contains only the definitions
43 * from myXSD file. In order to load and validate an instance within
44 * the context of those types, we must next construct a
45 * {@link SchemaTypeLoader} <code>stl</code> that contains both
46 * the builtin type system and the types defined within the myXSD file.
47 * <pre>
48 * SchemaTypeSystem sts = XmlBeans.compileXsd(new XmlObject[]
49 * { XmlObject.Factory.parse(myXSDFile) },
50 * XmlBeans.getBuiltinTypeSystem(),
51 * null);
52 * SchemaTypeLoader stl = XmlBeans.typeLoaderUnion(new SchemaTypeLoader[]
53 * { sts, XmlBeans.getBuiltinTypeSystem() });
54 * XmlObject mydoc = stl.parse(instanceFile, null, null);
55 * System.out.println("Document valid: " + mydoc.validate());
56 * </pre>
57 * <p>
58 * As you can see, for working with instances, you typically want to
59 * work with a SchemaTypeLoader constructed from a path rather than
60 * a solitary SchemaTypeSystem. See {@link XmlBeans#loadXsd} for
61 * a convenient alternative to {@link XmlBeans#compileXsd}.
62 * <p>
63 * A SchemaTypeSystem is useful when you need to enumerate the exact set
64 * of component definitions derived from a set of XSD files, for example,
65 * when you are analyzing the contents of the XSD files themselves.
66 * Here is how to use a SchemaTypeSystem to inspect a set of schema
67 * definitions:
68 * <ol>
69 * <li>First, use {@link XmlBeans#compileXsd} to compile any number
70 * of schema files. If the schema files are valid, result will
71 * be a SchemaTypeSystem that contains all the component definitions
72 * from those files. It will contain no other component definitions.
73 * <li>Alternatively, call {@link SchemaComponent#getTypeSystem} on
74 * a precompiled schema component to discover the SchemaTypeSystem
75 * within which that component was originally compiled.
76 * <li>Once you have a SchemaTypeSystem, call:
77 * <ul>
78 * <li> {@link #globalTypes()} for all the global type definitions.
79 * <li> {@link #globalElements()} for all the global element definitions.
80 * <li> {@link #globalAttributes()} for all the global attribute definitions.
81 * <li> {@link #modelGroups()} for all the named model group definitions.
82 * <li> {@link #attributeGroups()} for all the attribute group definitions.
83 * </ul>
84 * <li>In addition, there are special types generated for XML Beans thare
85 * are not formally part of the Schema specification:
86 * <ul>
87 * <li> {@link #documentTypes()} returns all the document types.
88 * <li> {@link #attributeTypes()} returns all the attribute types.
89 * </ul>
90 * </ol>
91 *
92 * <p>
93 * A document type is a type that contains a single global element; there
94 * is one document type for each global element definition in a
95 * SchemaTypeSystem. In an instance document, only the root XmlObject
96 * can have a document type as its type.
97 * <p>
98 * Similarly, an attribute type is a type that contains a single global
99 * attribute, and there is one attribute type for each global attribute
100 * definition in a SchemaTypeSystem. It is possible to have a root
101 * XmlObject representing a fragment whose type is an attribute type,
102 * but attribute types are present mainly for symmetry and to simplify
103 * code such as the type-tree-walking code below.
104 * <p>
105 * The global component methods above only provide a view of the top-level
106 * components of a SchemaTypeSystem and do not include any nested
107 * definitions. To view all the nested definitions, you will want to
108 * traverse the entire tree of {@link SchemaType} defintions within a
109 * SchemaTypeSystem by examining the {@link SchemaType#getAnonymousTypes()}
110 * within each {@link SchemaType} recursively.
111 * <p>The following code is a standard treewalk that visits every
112 * {@link SchemaType} in the SchemaTypeSystem once, including nested
113 * definitions.
114 * <pre>
115 * List allSeenTypes = new ArrayList();
116 * allSeenTypes.addAll(Arrays.asList(typeSystem.documentTypes()));
117 * allSeenTypes.addAll(Arrays.asList(typeSystem.attributeTypes()));
118 * allSeenTypes.addAll(Arrays.asList(typeSystem.globalTypes()));
119 * for (int i = 0; i < allSeenTypes.size(); i++)
120 * {
121 * SchemaType sType = (SchemaType)allSeenTypes.get(i);
122 * System.out.prinlnt("Visiting " + sType.toString());
123 * allSeenTypes.addAll(Arrays.asList(sType.getAnonymousTypes()));
124 * }
125 * </pre>
126 *
127 * @see SchemaType
128 * @see SchemaTypeLoader
129 * @see XmlBeans#compileXsd
130 * @see XmlBeans#typeLoaderUnion
131 * @see XmlBeans#getBuiltinTypeSystem
132 */
133 public interface SchemaTypeSystem extends SchemaTypeLoader
134 {
135 /**
136 * Returns the name of this loader.
137 */
138 public String getName();
139
140 /**
141 * Returns the global types defined in this loader.
142 */
143 public org.apache.xmlbeans.SchemaType[] globalTypes();
144
145 /**
146 * Returns the document types defined in this loader.
147 */
148 public org.apache.xmlbeans.SchemaType[] documentTypes();
149
150 /**
151 * Returns the attribute types defined in this loader.
152 */
153 public org.apache.xmlbeans.SchemaType[] attributeTypes();
154
155 /**
156 * Returns the global elements defined in this loader.
157 */
158 public SchemaGlobalElement[] globalElements();
159
160 /**
161 * Returns the global attributes defined in this loader.
162 */
163 public SchemaGlobalAttribute[] globalAttributes();
164
165 /**
166 * Returns the model groups defined in this loader.
167 */
168 public SchemaModelGroup[] modelGroups();
169
170 /**
171 * Returns the attribute groups defined in this loader.
172 */
173 public SchemaAttributeGroup[] attributeGroups();
174
175 /**
176 * Returns the top-level annotations */
177 public SchemaAnnotation[] annotations();
178
179 /**
180 * Initializes a type system (resolves all handles within the type system).
181 */
182 public void resolve();
183
184 /**
185 * Locates a type, element, or attribute using the handle.
186 */
187 public SchemaComponent resolveHandle(String handle);
188
189 /**
190 * Locates a type, element, or attribute using the handle.
191 */
192 public SchemaType typeForHandle(String handle);
193
194 /**
195 * Returns the classloader used by this loader for resolving types.
196 */
197 public ClassLoader getClassLoader();
198
199 /**
200 * Saves this type system to a directory.
201 */
202 public void saveToDirectory(File classDir);
203
204 /**
205 * Saves this type system using a Filer
206 */
207 public void save(Filer filer);
208 }