*    GeoTools - The Open Source Java GIS Toolkit

*    http://geotools.org

*

*    (C) 2002-2008, Open Source Geospatial Foundation (OSGeo)

*

*    This library is free software; you can redistribute it and/or

*    modify it under the terms of the GNU Lesser General Public

*    License as published by the Free Software Foundation;

*    version 2.1 of the License.

*

*    This library is distributed in the hope that it will be useful,

*    but WITHOUT ANY WARRANTY; without even the implied warranty of

*    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

*    Lesser General Public License for more details.

*/

* Utility class for performing various operations.

*

* @author Justin Deoliveira, The Open Planning Project

*

*

*

*

* @source $URL$

*/

    private static final Logger LOGGER = org.geotools.util.logging.Logging.getLogger(Schemas.class.getPackage()

                                                                                                  .getName());

    static {

        //need to register custom factory to load schema resources

        Resource.Factory.Registry.INSTANCE.getExtensionToFactoryMap()

                                          .put("xsd", new XSDResourceFactoryImpl());

    }

    /**

     * Finds all the XSDSchemas used by the {@link Configuration configuration}

     * by looking at the configuration's schema locator and its dependencies.

     *

     * @param configuration the {@link Configuration} for which to find all its

     * related schemas

     *

     * @return a {@link SchemaIndex} holding the schemas related to

     * <code>configuration</code>

     */

    public static final SchemaIndex findSchemas(Configuration configuration) {

        Set configurations = new HashSet(configuration.allDependencies());

        configurations.add(configuration);

        List resolvedSchemas = new ArrayList(configurations.size());

        for (Iterator it = configurations.iterator(); it.hasNext();) {

            Configuration conf = (Configuration) it.next();

            if (LOGGER.isLoggable(Level.FINE)) {

                LOGGER.fine("looking up schema for " + conf.getNamespaceURI());

            }

            XSDSchemaLocator locator = conf.getSchemaLocator();

            if (locator == null) {

                LOGGER.fine("No schema locator for " + conf.getNamespaceURI());

                continue;

            }

            String namespaceURI = conf.getNamespaceURI();

            String schemaLocation = null;

            try {

                URL location = new URL(conf.getSchemaFileURL());

                schemaLocation = location.toExternalForm();

            } catch (MalformedURLException e) {

                throw new RuntimeException(e);

            }

            if (LOGGER.isLoggable(Level.FINE)) {

                LOGGER.fine("schema location: " + schemaLocation);

            }

            XSDSchema schema = locator.locateSchema(null, namespaceURI, schemaLocation, null);

            if (schema != null) {

                resolvedSchemas.add(schema);

            }

        }

        XSDSchema[] schemas = (XSDSchema[]) resolvedSchemas.toArray(new XSDSchema[resolvedSchemas

                .size()]);

        SchemaIndex index = new SchemaIndexImpl(schemas);

        return index;

    }

    /**

     * Finds all {@link XSDSchemaLocationResolver}'s used by the configuration.

     *

     * @param configuration The parser configuration.

     *

     * @return A list of location resolvers, empty if none found.

     */

    public static List findSchemaLocationResolvers(Configuration configuration) {

        List all = configuration.allDependencies();

        List resolvers = new ArrayList();

        for (Iterator c = all.iterator(); c.hasNext();) {

            configuration = (Configuration) c.next();

            XSDSchemaLocationResolver resolver = configuration.getSchemaLocationResolver();

            if (resolver != null) {

                resolvers.add(resolver);

            }

        }

        return resolvers;

    }

    /**

     * Parses a schema at the specified location.

     *

     * @param location A uri pointing to the location of the schema.

     *

     * @return The parsed schema, or null if the schema could not be parsed.

     *

     * @throws IOException In the event of a schema parsing error.

     */

    public static final XSDSchema parse(String location)

        throws IOException {

        return parse(location, Collections.EMPTY_LIST, Collections.EMPTY_LIST);

    }

    /**

     * Parses a schema at the specified location.

     *

     * @param location A uri pointing to the location of the schema.

     * @param locators An array of schema locator objects to be used when

     * parsing imports/includes of the main schema.

     * @param resolvers An array of schema location resolvers used to override

     * schema locations encountered in an instance document or an imported

     * schema.

     *

     * @return The parsed schema, or null if the schema could not be parsed.

     *

     * @throws IOException In the event of a schema parsing error.

     * @deprecated use {@link #parse(String, List, List)}

     */

    public static final XSDSchema parse(String location, XSDSchemaLocator[] locators,

        XSDSchemaLocationResolver[] resolvers) throws IOException {

        return parse(location, (locators != null) ? Arrays.asList(locators) : Collections.EMPTY_LIST,

            (resolvers != null) ? Arrays.asList(resolvers) : Collections.EMPTY_LIST);

    }

    /**

     * Parses a schema at the specified location.

     *

     * @param location A uri pointing to the location of the schema.

     * @param locators A list of schema locator objects to be used when

     * parsing imports/includes of the main schema.

     * @param resolvers A list of schema location resolvers used to override

     * schema locations encountered in an instance document or an imported

     * schema.

     *

     * @return The parsed schema, or null if the schema could not be parsed.

     *

     * @throws IOException In the event of a schema parsing error.

     */

    public static final XSDSchema parse(String location, List locators, List resolvers)

        throws IOException {

        return parse(location, locators, resolvers, null);

    }

    /**

     * Parses a schema at the specified location.

     *

     * @param location A uri pointing to the location of the schema.

     * @param locators A list of schema locator objects to be used when

     * parsing imports/includes of the main schema.

     * @param resolvers A list of schema location resolvers used to override

     * schema locations encountered in an instance document or an imported schema.

     * @param uriHandlers A list of uri handlers to inject into the parsing chain, to handle

     * externally referenced resources, like external schemas, etc...

     *

     * @return The parsed schema, or null if the schema could not be parsed.

     *

     * @throws IOException In the event of a schema parsing error.

     */

    public static final XSDSchema parse(String location, List locators, List resolvers,

        List<URIHandler> uriHandlers) throws IOException {

        ResourceSet resourceSet = new ResourceSetImpl();

       

        //add the specialized schema location resolvers

        if ((resolvers != null) && !resolvers.isEmpty()) {

           AdapterFactory adapterFactory = new SchemaLocationResolverAdapterFactory(resolvers);

           resourceSet.getAdapterFactories().add(adapterFactory);

        }

       

        //add the specialized schema locators as adapters

        if ((locators != null) && !locators.isEmpty()) {

            AdapterFactory adapterFactory = new SchemaLocatorAdapterFactory(locators);

            resourceSet.getAdapterFactories().add(adapterFactory);

        }

        //add the specifialized uri handlers

        if (uriHandlers != null && !uriHandlers.isEmpty()) {

            resourceSet.getURIConverter().getURIHandlers().addAll(0, uriHandlers);

        }

        return parse(location, resourceSet);

    }

   

    public static final XSDSchema parse(String location, ResourceSet resourceSet)

        throws IOException {

        //check for case of file url, make sure it is an absolute reference

        File locationFile = null;

        try {

            locationFile = DataUtilities.urlToFile(new URL(location));

        } catch (MalformedURLException e) {

            // Some tests use relative file URLs, which Schemas.parse cannot

            // support as it does not permit a context URL. Treat them

            // as local file paths. Naughty, naughty.

            locationFile = new File(location);

        }

        if (locationFile != null && locationFile.exists()) {

            location = locationFile.getCanonicalFile().toURI().toString();

        }

        URI uri = URI.createURI(location);

        XSDResourceImpl xsdMainResource = (XSDResourceImpl) resourceSet.createResource(URI.createURI(

                    ".xsd"));

        xsdMainResource.setURI(uri);

        // schema building has effects on referenced schemas, it will alter them -> we need

        // to synchronize this call so that only one of these operations is active at any time

        synchronized(Schemas.class) {

            xsdMainResource.load(resourceSet.getLoadOptions());

            return xsdMainResource.getSchema();

        }

    }

    /**

     * Imports one schema into another.

     *

     * @param schema The schema being imported into.

     * @param importee The schema being imported.

     *

     * @return The import object.

     */

    public static final XSDImport importSchema( XSDSchema schema, final XSDSchema importee ) throws IOException {

        Resource resource = schema.eResource();

        if ( resource == null ) {

            final ResourceSet resourceSet = new ResourceSetImpl();

            resource = (XSDResourceImpl) resourceSet.createResource(URI.createURI(".xsd"));

            resource.getContents().add( schema );

        }

       

        XSDImport imprt = XSDFactory.eINSTANCE.createXSDImport();

        imprt.setNamespace( importee.getTargetNamespace() );

        schema.getContents().add( imprt );

       

        List<XSDSchemaLocator> locators = new ArrayList<XSDSchemaLocator>();

        locators.add( new XSDSchemaLocator() {

            public XSDSchema locateSchema(XSDSchema xsdSchema,

                    String namespaceURI, String rawSchemaLocationURI,

                    String resolvedSchemaLocationURI) {

               

                if ( importee.getTargetNamespace().equals( namespaceURI ) ) {

                    return importee;

                }

               

                return null;

            }

        });

        AdapterFactory adapterFactory = new SchemaLocatorAdapterFactory(locators);

        resource.getResourceSet().getAdapterFactories().add( adapterFactory );

        return imprt;

    }

   

    /**

     * Remove all references to a schema

     * It is important to call this method for every dynamic schema created that is not needed

     * anymore, because references in the static schema's will otherwise keep it alive forever

     *

     * @param schema to be flushed

     */

    public static final void dispose(XSDSchema schema) {

        for (XSDSchemaContent content : schema.getContents()) {

            if (content instanceof XSDSchemaDirective) {

                XSDSchemaDirective directive = (XSDSchemaDirective) content;

                XSDSchema resolvedSchema = directive.getResolvedSchema();

               

                if (resolvedSchema != null) {

                    synchronized (Schemas.class) {

                        resolvedSchema.getReferencingDirectives().remove(directive);

                        for (XSDElementDeclaration dec : resolvedSchema.getElementDeclarations()) {

                            if(dec == null) {

                                continue;

                            }

                            List<XSDElementDeclaration> toRemove = new ArrayList<XSDElementDeclaration>();

                            for (XSDElementDeclaration subs : dec.getSubstitutionGroup()) {

                                if (subs != null && subs.getContainer() != null && subs.getContainer().equals(schema)) {

                                    toRemove.add(subs);

                                }

                            }

                            dec.getSubstitutionGroup().removeAll(toRemove);

                        }

                    }

                }

            }

        }

    }

   

    public static final List validateImportsIncludes(String location) throws IOException {

        return validateImportsIncludes(location,Collections.EMPTY_LIST,Collections.EMPTY_LIST);

    }

   

    public static final List validateImportsIncludes(String location, XSDSchemaLocator[] locators,

            XSDSchemaLocationResolver[] resolvers ) throws IOException {

        return validateImportsIncludes(location, (locators != null) ? Arrays.asList(locators) : Collections.EMPTY_LIST,

                (resolvers != null) ? Arrays.asList(resolvers) : Collections.EMPTY_LIST);

    }

   

    public static final List validateImportsIncludes(String location, List locators, List resolvers) throws IOException {

       

        //create a parser

        SAXParserFactory factory = SAXParserFactory.newInstance();

        factory.setNamespaceAware(true);

        factory.setValidating(false);

       

        SAXParser parser = null;

        try {

            parser = factory.newSAXParser();   

        }

        catch( Exception e ) {

            throw (IOException) new IOException("could not create parser").initCause( e );

        }

       

        SchemaImportIncludeValidator validator = new SchemaImportIncludeValidator( locators, resolvers );

       

        //queue of files to parse

        LinkedList q = new LinkedList();

        q.add( location );

       

        while( !q.isEmpty() ) {

            location = (String) q.removeFirst();

            validator.setBaseLocation( location );

       

            try {

                parser.parse( location, validator );

            }

            catch (SAXException e) {

                throw (IOException) new IOException( "parse error").initCause( e );

            }

           

            //check for errors

            if ( !validator.errors.isEmpty() ) {

                return validator.errors;

            }

           

            if ( !validator.next.isEmpty() ) {

                q.addAll( validator.next );

            }

        }

       

        return Collections.EMPTY_LIST;

    }

   

    static final class SchemaImportIncludeValidator extends DefaultHandler {

  

        /** base location */

        String baseLocation;

        /** locators for resolving to schemas directely */

        List locators;

        /** locators for resolving to absolute schema locations */

        List resolvers;

        /** tracking seen namespaces and schema locations */

        Set seen;

        /** list of errors encountered */

        List errors;

        /** next set of locations to process */

        List next;

       

        SchemaImportIncludeValidator( List locators, List resolvers ) {

            this.locators = locators;

            this.resolvers = resolvers;

            seen = new HashSet();

            errors = new ArrayList();

            next = new ArrayList();

        }

       

        public void setBaseLocation(String baseLocation) {

            this.baseLocation = baseLocation;

        }

       

        public void startDocument() throws SAXException {

            next.clear();

        }

       

        public void startElement(String uri, String localName, String qName, Attributes attributes) throws SAXException {

            //process import

            if ( "import".equals( localName ) ) {

                //get the namespace + location

                String namespace = attributes.getValue( "namespace" );

                String schemaLocation = attributes.getValue( "schemaLocation" );

               

                //do not validate if we have already seen this import

                if ( seen.contains( namespace) ) {

                    return;

                }

                seen.add( namespace );

               

                if ( schemaLocation != null ) {

                    //look for a locator or resolver that can handle it

                    for ( Iterator l = locators.iterator(); l.hasNext(); ) {

                        XSDSchemaLocator locator = (XSDSchemaLocator) l.next();

                       

                        //check for schema locator which canHandle

                        if ( locator instanceof SchemaLocator ) {

                            if ( ((SchemaLocator)locator).canHandle(null, namespace, schemaLocation, null)) {

                                //cool, return here and do not recurse

                                return;

                            }

                        }

                    }

                   

                    //resolve

                    String resolvedSchemaLocation = resolve( namespace, schemaLocation );

                    if ( resolvedSchemaLocation != null ) {

                        recurse( resolvedSchemaLocation );

                    }

                    else {

                        errors.add( "Could not resolve import: " + namespace + "," + schemaLocation);

                    }

                }

                else {

                    errors.add( "No schemaLocation attribute for namespace import: " + namespace );

                }

            }

            else if ( "include".equals( localName ) ) {

                //process include

                String location = attributes.getValue( "location" );

                String resolvedLocation = resolve( null, location );

               

                if ( resolvedLocation != null ) {

                    recurse( resolvedLocation );

                }

                else {

                    errors.add( "Could not resolve include: " + location);

                }

            }

        }

       

        String resolve( String namespace, String location ) {

            //look for a location resolver capable of handling it

            for ( Iterator r = resolvers.iterator(); r.hasNext(); ) {

                XSDSchemaLocationResolver resolver = (XSDSchemaLocationResolver) r.next();

                if ( resolver instanceof SchemaLocationResolver ) {

                    if ( ((SchemaLocationResolver) resolver ).canHandle(null, namespace,location)) {

                        //can handle, actually resolve and recurse

                        String resolvedSchemaLocation =

                            resolver.resolveSchemaLocation(null, namespace, location );

                        if ( resolvedSchemaLocation != null ) {

                            return resolvedSchemaLocation;

                        }

                        else {

                            //should not happen, but just continue

                        }

                    }

                }

            }

           

            //attempt tp resolve manuualy

            File file = new File( location );

            if ( file.exists() ) {

                return file.getAbsolutePath();

            }

            else {

                //try relative to base location

                if ( !file.isAbsolute() ) {

                    File dir = new File( baseLocation ).getParentFile();

                    if ( dir != null ) {

                        file = new File( dir, location );

                        if ( file.exists() ) {

                            return file.getAbsolutePath();

                        }

                    }   

                }

            }

           

            return null;

        }

       

        void recurse( String location ) {

            //do not recurse if we have already processed this one

            if ( seen.contains( location ) ) {

                return;

            }

           

            //mark it as seen

            seen.add( location );

          

            //add to queue for processing of in next round

            next.add( location );

        }

    }

   

    /**

     * Returns a list of all child element declarations of the specified

     * element, no order is guaranteed.

     *

     * @param element The parent element.

     *

     * @return A list of @link XSDElementDeclaration objects, one for each

     * child element.

     *

     * @deprecated use {@link #getChildElementDeclarations(XSDTypeDefinition)}

     */

    public static final List getChildElementDeclarations(XSDElementDeclaration element) {

        return getChildElementDeclarations(element.getType());

    }

    /**

     * Returns a list of all child element declarations of the specified

     * type, no order is guaranteed.

     *

     * @param type The type.

     *

     * @return A list of @link XSDElementDeclaration objects, one for each

     * child element.

     */

    public static final List getChildElementDeclarations(XSDTypeDefinition type) {

        return getChildElementDeclarations(type, true);

    }

    /**

     * Returns a list of all child element declarations of the specified

     * element.

     * <p>

     *         The <code>includeParents</code> flag controls if this method should

     * returns those elements defined on parent types.

     * </p>

     * @param element The parent element.

     * @param includeParents Flag indicating if parent types should be processed.

     * @return A list of @link XSDElementDeclaration objects, one for each

     * child element.

     *

     * @deprecated use {@link #getChildElementDeclarations(XSDTypeDefinition, boolean)}

     */

    public static final List getChildElementDeclarations(XSDElementDeclaration element,

        boolean includeParents) {

        return getChildElementDeclarations(element.getType(), includeParents);

    }

    /**

     * Returns the particle for an element declaration that is part of a type.

     *

     * @param type The type definition.

     * @param name The naem of the child element declaration.

     *

     * @param includeParents Flag to control wether parent types are included.

     *

     * @return The particle representing the element declaration, or <code>null</code> if it could

     * not be found.

     */

    public static final XSDParticle getChildElementParticle(XSDTypeDefinition type, String name,

        boolean includeParents) {

        List particles = getChildElementParticles(type, includeParents);

        for (Iterator p = particles.iterator(); p.hasNext();) {

            XSDParticle particle = (XSDParticle) p.next();

            XSDElementDeclaration element = (XSDElementDeclaration) particle.getContent();

            if (element.isElementDeclarationReference()) {

                element.getResolvedElementDeclaration();

            }

            if (name.equals(element.getName())) {

                return particle;

            }

        }

        return null;

    }

    /**

     * Returns a list of all child element particles that corresponde to element declarations of

     * the specified type, no order is guaranteed.

     * <p>

     * The <code>includeParents</code> flag controls if this method should

     * returns those elements defined on parent types.

     * </p>

     *

     * @param type THe type.

     * @param includeParents flag indicating if parent types should be processed

     *

     * @return A list of {@link XSDParticle}.

     *

     */

    public static final List getChildElementParticles(XSDTypeDefinition type, boolean includeParents) {

        final HashSet contents = new HashSet();

        final ArrayList particles = new ArrayList();

        TypeWalker.Visitor visitor = new TypeWalker.Visitor() {

                public boolean visit(XSDTypeDefinition type) {

                    //simple types dont have children

                    if (type instanceof XSDSimpleTypeDefinition) {

                        return true;

                    }

                    XSDComplexTypeDefinition cType = (XSDComplexTypeDefinition) type;

                    ElementVisitor visitor = new ElementVisitor() {

                            public void visit(XSDParticle particle) {

                                XSDElementDeclaration element = (XSDElementDeclaration) particle

                                    .getContent();

                                if (element.isElementDeclarationReference()) {

                                    element = element.getResolvedElementDeclaration();

                                }

                                //make sure unique

                                if (!contents.contains(element)) {

                                    contents.add(element);

                                    particles.add(particle);

                                }

                            }

                        };

                    visitElements(cType, visitor);

                    return true;

                }

            };

        if (includeParents) {

            //walk up the type hierarchy of the element to generate a list of

            // possible elements

            new TypeWalker().rwalk(type, visitor);

        } else {

            //just visit this type

            visitor.visit(type);

        }

        return new ArrayList(particles);

    }

   

    /**

     * Returns a list of all xs:any element particles that correspond to element declarations of the

     * specified type.

     *

     * @param type

     *            The type.

     *

     * @return A list of {@link XSDParticle}.

     *

     */

    public static final List getAnyElementParticles(XSDTypeDefinition type) {

        final HashSet contents = new HashSet();

        final ArrayList particles = new ArrayList();

        TypeWalker.Visitor visitor = new TypeWalker.Visitor() {

            public boolean visit(XSDTypeDefinition type) {

                // simple types doesn't have children

                if (type instanceof XSDSimpleTypeDefinition) {

                    return true;

                }

                XSDComplexTypeDefinition cType = (XSDComplexTypeDefinition) type;

                ElementVisitor visitor = new ElementVisitor() {

                    public void visit(XSDParticle particle) {

                        XSDWildcard element = (XSDWildcard) particle.getContent();

                        // make sure unique

                        if (!contents.contains(element)) {

                            contents.add(element);

                            particles.add(particle);

                        }

                    }

                };

                visitAnyElements(cType, visitor);

                return true;

            }

        };

        // just visit this type

        visitor.visit(type);

        return new ArrayList(particles);

    }

    /**

     * Method to visit xs:any element. The method differs from visitElements only by the fact that

     * it visits xs:any rather than <element>

     *

     * @param cType

     *            XSDComplexTypeDefinition

     * @param visitor

     *            ElementVisitor

     */

    private static void visitAnyElements(XSDComplexTypeDefinition cType, ElementVisitor visitor) {

        // simple content cant define children

        if ((cType.getContent() == null) || (cType.getContent() instanceof XSDSimpleTypeDefinition)) {

            return;

        }

        // use a queue to simulate the recursion

        LinkedList queue = new LinkedList();

        queue.addLast(cType.getContent());

        while (!queue.isEmpty()) {

            XSDParticle particle = (XSDParticle) queue.removeFirst();

            // analyze type of particle content

            int pType = XSDUtil.nodeType(particle.getElement());

            if (pType == XSDConstants.ANY_ELEMENT) {

                visitor.visit(particle);

            } else {

                // model group

                XSDModelGroup grp = null;

                switch (pType) {

                case XSDConstants.GROUP_ELEMENT:

                    XSDModelGroupDefinition grpDef = (XSDModelGroupDefinition) particle

                            .getContent();

                    if (grpDef.isModelGroupDefinitionReference()) {

                        grpDef = grpDef.getResolvedModelGroupDefinition();

                    }

                    grp = grpDef.getModelGroup();

                    break;

                case XSDConstants.CHOICE_ELEMENT:

                case XSDConstants.ALL_ELEMENT:

                case XSDConstants.SEQUENCE_ELEMENT:

                    grp = (XSDModelGroup) particle.getContent();

                    break;

                }

                if (grp != null) {

                    // enque all particles in the group

                    List parts = grp.getParticles();

                    // TODO: this check isa bit hacky.. .figure out why this is the case

                    if (parts.isEmpty()) {

                        parts = grp.getContents();

                    }

                    // add in reverse order to front of queue to maintain order

                    for (int i = parts.size() - 1; i >= 0; i--) {

                        queue.addFirst(parts.get(i));

                    }

                }

            }

        } // while

    }

   

    /**

     * Returns a list of all child element declarations of the specified

     * type, no order is guaranteed.

     * <p>

     *         The <code>includeParents</code> flag controls if this method should

     * returns those elements defined on parent types.

     * </p>

     * @param type           The type

     * @param includeParents flag indicating if parent types should be processed

     *

     * @return A list of @link XSDElementDeclaration objects, one for each

     * child element.

     */

    public static final List getChildElementDeclarations(XSDTypeDefinition type,

        boolean includeParents) {

        List particles = getChildElementParticles(type, includeParents);

        List elements = new ArrayList();

        for (Iterator p = particles.iterator(); p.hasNext();) {

            XSDParticle particle = (XSDParticle) p.next();

            XSDElementDeclaration decl = (XSDElementDeclaration) particle.getContent();

            if (decl.isElementDeclarationReference()) {

                decl = decl.getResolvedElementDeclaration();

            }

            elements.add(decl);

        }

        return elements;

    }

    /**

     * Returns the base type defintion of <code>type</code> named <code>parentTypeName<code>.

     * <p>

     * This method will handle the case in which the <code>parentTypeName == type.getTypeName()</code>.

     * If no such parent type is found this method will return <code>null</code>.

     * </p>

     * @param type The type.

     * @param parentTypeName The name of the base type to return.

     *

     * @return The base type, or null if it could not be found.

     */

    public static final XSDTypeDefinition getBaseTypeDefinition(XSDTypeDefinition type,

        final QName parentTypeName) {

        final List found = new ArrayList();

        TypeWalker.Visitor visitor = new TypeWalker.Visitor() {

                public boolean visit(XSDTypeDefinition type) {

                    if (nameMatches(type, parentTypeName)) {

                        found.add(type);

                        return false;

                    }

                    return true;

                }

            };

        new TypeWalker().walk(type, visitor);

        return found.isEmpty() ? null : (XSDTypeDefinition) found.get(0);

    }

    /**

     * Determines if the type of an element is a sub-type of another element.

     *

     * @param e1 The element.

     * @param e2 The element to be tested as a base type.

     *

     * @since 2.5

     */

    public static final boolean isBaseType(XSDElementDeclaration e1, XSDElementDeclaration e2 ) {

        XSDTypeDefinition type = e1.getType();

        while( type != null ) {

            if ( type.equals( e2.getType() ) ) {

                return true;

            }

           

            if ( type.equals( type.getBaseType() ) ) {

                break;

            }

           

            type = type.getBaseType();

        }

       

        return false;

    }

    /**

     * Returns the minimum number of occurences of an element within a complex

     * type.

     *

     * @param type The type definition containg the declaration <code>element</code>

     * @param element The declaration of the element.

     *

     * @return The minimum number of occurences.

     *

     * @throws IllegalArgumentException If the element declaration cannot be

     * locaated withing the type definition.

     */

    public static final int getMinOccurs(XSDComplexTypeDefinition type,

        XSDElementDeclaration element) {

        final XSDElementDeclaration fElement = element;

        final ArrayList minOccurs = new ArrayList();

        ElementVisitor visitor = new ElementVisitor() {

                public void visit(XSDParticle particle) {

                    XSDElementDeclaration decl = (XSDElementDeclaration) particle.getContent();

                    if (decl.isElementDeclarationReference()) {

                        decl = decl.getResolvedElementDeclaration();

                    }

                    if (decl == fElement) {

                        if (particle.isSetMinOccurs()) {

                            minOccurs.add(new Integer(particle.getMinOccurs()));

                        } else if (particle.getContainer() instanceof XSDModelGroup

                                && particle.getContainer().getContainer() instanceof XSDParticle) {

                            particle = (XSDParticle) particle.getContainer().getContainer();

                            minOccurs.add(new Integer(particle.getMinOccurs()));

                        } else {

                            minOccurs.add(1);

                        }

                    }

                }

            };

        visitElements(type, visitor, true);

        if (minOccurs.isEmpty()) {

            throw new IllegalArgumentException("Element: " + element + " not found in type: "

                + type);

        }

        return ((Integer) minOccurs.get(0)).intValue();

    }

    /**

     * Returns the minimum number of occurences of an element within a complex

     * type.

     *

     * @param type The type definition containg the declaration <code>element</code>

     * @param element The declaration of the element.

     *

     * @return The minimum number of occurences.

     *

     * @throws IllegalArgumentException If the element declaration cannot be

     * locaated withing the type definition.

     */

    public static final int getMaxOccurs(XSDComplexTypeDefinition type,

        XSDElementDeclaration element) {

        final XSDElementDeclaration fElement = element;

        final ArrayList maxOccurs = new ArrayList();

        ElementVisitor visitor = new ElementVisitor() {

                public void visit(XSDParticle particle) {

                    XSDElementDeclaration decl = (XSDElementDeclaration) particle.getContent();

                    if (decl.isElementDeclarationReference()) {

                        decl = decl.getResolvedElementDeclaration();

                    }

                    if (decl == fElement) {

                        if (particle.isSetMaxOccurs()) {

                            maxOccurs.add(new Integer(particle.getMaxOccurs()));

                        } else if (particle.getContainer() instanceof XSDModelGroup

                                && particle.getContainer().getContainer() instanceof XSDParticle) {

                            particle = (XSDParticle) particle.getContainer().getContainer();

                            maxOccurs.add(new Integer(particle.getMaxOccurs()));

                        } else {

                            maxOccurs.add(1);

                        }

                    }

                }

            };

        visitElements(type, visitor, true);

        if (maxOccurs.isEmpty()) {

            throw new IllegalArgumentException("Element: " + element + " not found in type: "

                + type);

        }

        return ((Integer) maxOccurs.get(0)).intValue();

    }

    private static void visitElements(XSDComplexTypeDefinition cType, ElementVisitor visitor,

        boolean includeParents) {

        if (includeParents) {

            LinkedList baseTypes = new LinkedList();

            XSDTypeDefinition baseType = cType.getBaseType();

            while ((baseType != null) && (baseType != baseType.getBaseType())) {

                if (baseType instanceof XSDComplexTypeDefinition) {

                    baseTypes.addLast(baseType);

                }

                baseType = baseType.getBaseType();

            }

            for (Iterator it = baseTypes.iterator(); it.hasNext();) {

                baseType = (XSDTypeDefinition) it.next();

                visitElements((XSDComplexTypeDefinition) baseType, visitor);

            }

        }

        visitElements(cType, visitor);

    }

    private static void visitElements(XSDComplexTypeDefinition cType, ElementVisitor visitor) {

        //simple content cant define children

        if ((cType.getContent() == null) || (cType.getContent() instanceof XSDSimpleTypeDefinition)) {

            return;

        }

        //use a queue to simulate the recursion

        LinkedList queue = new LinkedList();

        queue.addLast(cType.getContent());

        while (!queue.isEmpty()) {

            XSDParticle particle = (XSDParticle) queue.removeFirst();

            //analyze type of particle content

            int pType = XSDUtil.nodeType(particle.getElement());

            if (pType == XSDConstants.ELEMENT_ELEMENT) {

                visitor.visit(particle);

            } else {

                //model group

                XSDModelGroup grp = null;

                switch (pType) {

                case XSDConstants.GROUP_ELEMENT:

                    XSDModelGroupDefinition grpDef = (XSDModelGroupDefinition) particle.getContent();

                    if (grpDef.isModelGroupDefinitionReference()) {

                        grpDef = grpDef.getResolvedModelGroupDefinition();

                    }

                    grp = grpDef.getModelGroup();

                    break;

                case XSDConstants.CHOICE_ELEMENT:

                case XSDConstants.ALL_ELEMENT:

                case XSDConstants.SEQUENCE_ELEMENT:

                    grp = (XSDModelGroup) particle.getContent();

                    break;

                }

                if (grp != null) {

                    //enque all particles in the group

                    List parts = grp.getParticles();

                   

                    //TODO: this check isa  bit hacky.. .figure out why this is the case

                    if ( parts.isEmpty() ) {

                        parts = grp.getContents();

                    }

                    //add in reverse order to front of queue to maintain order

                    for (int i = parts.size() - 1; i >= 0; i--) {

                        queue.addFirst(parts.get(i));

                    }

                }

            }

        } //while

    }

    /**

     * Returns an element declaration that is contained in the type of another

     * element declaration. The following strategy is used to locate the child

     * element declaration.

     *

     * <ol>

     *         <li>The immediate children of the specified element are examined, if a

     * match is found, it is returned.

     *  </li>If 1. does not match, global elements that derive from the

     *  immediate children are examined.

     * </ol>

     *

     * @param parent the containing element declaration

     * @param qName  the qualified name of the contained element

     *

     * @return The contained element declaration, or false if containment is

     * not satisfied.

     */

    public static final XSDElementDeclaration getChildElementDeclaration(

        XSDElementDeclaration parent, QName qName) {

        //look for a match in a direct child

        List children = getChildElementDeclarations(parent);

        for (Iterator itr = children.iterator(); itr.hasNext();) {

            XSDElementDeclaration element = (XSDElementDeclaration) itr.next();

            if (nameMatches(element, qName)) {

                return element;

            }

        }

        //couldn't find one, look for match in derived elements

        ArrayList derived = new ArrayList();

        for (Iterator itr = children.iterator(); itr.hasNext();) {

            XSDElementDeclaration child = (XSDElementDeclaration) itr.next();

            derived.addAll(getDerivedElementDeclarations(child));

        }

        for (Iterator itr = derived.iterator(); itr.hasNext();) {

            XSDElementDeclaration child = (XSDElementDeclaration) itr.next();

            if (nameMatches(child, qName)) {

                return child;

            }

        }

        return null;

    }

    /**

     * Returns a list of all top level elements that are of a type derived

     * from the type of the specified element.

     *

     * @param element The element.

     *

     * @return All elements which are of a type derived from the type of the

     * specified element.

     */

    public static final List getDerivedElementDeclarations(XSDElementDeclaration element) {

        List elements = element.getSchema().getElementDeclarations();

        List derived = new ArrayList();

        for (Iterator itr = elements.iterator(); itr.hasNext();) {

            XSDElementDeclaration derivee = (XSDElementDeclaration) itr.next();

            if (derivee.equals(element)) {

                continue; //same element

            }

            XSDTypeDefinition type = derivee.getType();

            while (true) {

                if (type.equals(element.getType())) {

                    derived.add(derivee);

                    break;

                }

                if (type.equals(type.getBaseType())) {

                    break;

                }

                type = type.getBaseType();

            }

        }

        return derived;

    }

    /**

     * Returns a list of all attribute declarations declared in the type (or

     * any base type) of the specified element.

     *

     * <p>

     * This method is just a shortcut for {@link #getAttributeDeclarations(XSDTypeDefinition) getAttributeDeclarations(element.getType()}

     * </p>

     *

     * @param element The element.

     *

     * @return A list of @link XSDAttributeDeclaration objects, one for each

     * attribute of the element.

     */

    public static final List getAttributeDeclarations(XSDElementDeclaration element) {

        return getAttributeDeclarations(element.getType());

    }

    /**

     * Returns a list of all attribute declarations declared in the type (or

     * any base type) of the specified element.

     *

     * @param element The element.

     *

     * @return A list of @link XSDAttributeDeclaration objects, one for each

     * attribute of the element.

     */

    public static final List getAttributeDeclarations(XSDTypeDefinition type) {

        return getAttributeDeclarations(type,true);

    }

   

    /**

     * Returns a list of all attribute declarations declared in the type (and optionally

     * any base type) of the specified element.

     *

     * @param element The element.

     * @param includeParents Wether to include parent types.

     *

     * @return A list of @link XSDAttributeDeclaration objects, one for each

     * attribute of the element.

     */

    public static final List getAttributeDeclarations(XSDTypeDefinition type, boolean includeParents) {

        final ArrayList attributes = new ArrayList();

        //walk up the type hierarchy of the element to generate a list of atts

        TypeWalker.Visitor visitor = new TypeWalker.Visitor() {

                public boolean visit(XSDTypeDefinition type) {

                    //simple types dont have attributes

                    if (type instanceof XSDSimpleTypeDefinition) {

                        return true;

                    }

                    XSDComplexTypeDefinition cType = (XSDComplexTypeDefinition) type;

                    //get all the attribute content (groups,or uses) and add to q

                    List attContent = cType.getAttributeContents();

                    for (Iterator itr = attContent.iterator(); itr.hasNext();) {

                        XSDAttributeGroupContent content = (XSDAttributeGroupContent) itr.next();

                        if (content instanceof XSDAttributeUse) {

                            //an attribute, add it to the list

                            XSDAttributeUse use = (XSDAttributeUse) content;

                            attributes.add(use.getAttributeDeclaration());

                        } else if (content instanceof XSDAttributeGroupDefinition) {

                            //attribute group, add all atts in group to list

                            XSDAttributeGroupDefinition attGrp = (XSDAttributeGroupDefinition) content;

                            if (attGrp.isAttributeGroupDefinitionReference()) {

                                attGrp = attGrp.getResolvedAttributeGroupDefinition();

                            }

                            List uses = attGrp.getAttributeUses();

                            for (Iterator aitr = uses.iterator(); aitr.hasNext();) {

                                XSDAttributeUse use = (XSDAttributeUse) aitr.next();

                                attributes.add(use.getAttributeDeclaration());

                            }

                        }

                    }

                    return true;

                }

            };

        if (includeParents) {

            //walk up the type hierarchy of the element to generate a list of

            // possible elements

            new TypeWalker().walk(type, visitor);

        } else {

            //just visit this type

            visitor.visit(type);

        }

       

        return attributes;

    }

    /**

     * Returns an attribute declaration that is contained in the type of another

     * element declaration.

     *

     * @param element The containing element declaration.

     * @param qName The qualified name of the contained attribute

     *

     * @return The contained attribute declaration, or false if containment is

     * not satisfied.

     */

    public static final XSDAttributeDeclaration getAttributeDeclaration(