Home » xmlbeans-2.5.0-src » org.apache » xmlbeans » [javadoc | source]

    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   }

Home » xmlbeans-2.5.0-src » org.apache » xmlbeans » [javadoc | source]