aoqi@0: /*
aoqi@0:  * Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved.
aoqi@0:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
aoqi@0:  *
aoqi@0:  * This code is free software; you can redistribute it and/or modify it
aoqi@0:  * under the terms of the GNU General Public License version 2 only, as
aoqi@0:  * published by the Free Software Foundation.  Oracle designates this
aoqi@0:  * particular file as subject to the "Classpath" exception as provided
aoqi@0:  * by Oracle in the LICENSE file that accompanied this code.
aoqi@0:  *
aoqi@0:  * This code is distributed in the hope that it will be useful, but WITHOUT
aoqi@0:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
aoqi@0:  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
aoqi@0:  * version 2 for more details (a copy is included in the LICENSE file that
aoqi@0:  * accompanied this code).
aoqi@0:  *
aoqi@0:  * You should have received a copy of the GNU General Public License version
aoqi@0:  * 2 along with this work; if not, write to the Free Software Foundation,
aoqi@0:  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
aoqi@0:  *
aoqi@0:  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
aoqi@0:  * or visit www.oracle.com if you need additional information or have any
aoqi@0:  * questions.
aoqi@0:  */
aoqi@0: 
aoqi@0: package com.sun.xml.internal.xsom;
aoqi@0: 
aoqi@0: import com.sun.xml.internal.xsom.parser.SchemaDocument;
aoqi@0: import com.sun.xml.internal.xsom.visitor.XSFunction;
aoqi@0: import com.sun.xml.internal.xsom.visitor.XSVisitor;
aoqi@0: import org.xml.sax.Locator;
aoqi@0: 
aoqi@0: import javax.xml.namespace.NamespaceContext;
aoqi@0: import java.util.List;
aoqi@0: import java.util.Collection;
aoqi@0: 
aoqi@0: /**
aoqi@0:  * Base interface for all the schema components.
aoqi@0:  *
aoqi@0:  * @author
aoqi@0:  *  Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
aoqi@0:  */
aoqi@0: public interface XSComponent
aoqi@0: {
aoqi@0:     /** Gets the annotation associated to this component, if any. */
aoqi@0:     XSAnnotation getAnnotation();
aoqi@0: 
aoqi@0:     /**
aoqi@0:      * Works like {@link #getAnnotation()}, but allow a new empty {@link XSAnnotation} to be created
aoqi@0:      * if not exist.
aoqi@0:      *
aoqi@0:      * @param createIfNotExist
aoqi@0:      *      true to create a new {@link XSAnnotation} if it doesn't exist already.
aoqi@0:      *      false to make this method behavel like {@link #getAnnotation()}.
aoqi@0:      *
aoqi@0:      * @return
aoqi@0:      *      null if <tt>createIfNotExist==false</tt> and annotation didn't exist.
aoqi@0:      *      Otherwise non-null.
aoqi@0:      */
aoqi@0:     XSAnnotation getAnnotation(boolean createIfNotExist);
aoqi@0: 
aoqi@0:     /**
aoqi@0:      * Gets the foreign attributes on this schema component.
aoqi@0:      *
aoqi@0:      * <p>
aoqi@0:      * In general, a schema component may match multiple elements
aoqi@0:      * in a schema document, and those elements can individually
aoqi@0:      * carry foreign attributes.
aoqi@0:      *
aoqi@0:      * <p>
aoqi@0:      * This method returns a list of {@link ForeignAttributes}, where
aoqi@0:      * each {@link ForeignAttributes} object represent foreign attributes
aoqi@0:      * on one element.
aoqi@0:      *
aoqi@0:      * @return
aoqi@0:      *      can be an empty list but never be null.
aoqi@0:      */
aoqi@0:     List<? extends ForeignAttributes> getForeignAttributes();
aoqi@0: 
aoqi@0:     /**
aoqi@0:      * Gets the foreign attribute of the given name, or null if not found.
aoqi@0:      *
aoqi@0:      * <p>
aoqi@0:      * If multiple occurences of the same attribute is found,
aoqi@0:      * this method returns the first one.
aoqi@0:      *
aoqi@0:      * @see #getForeignAttributes()
aoqi@0:      */
aoqi@0:     String getForeignAttribute(String nsUri, String localName);
aoqi@0: 
aoqi@0:     /**
aoqi@0:      * Gets the locator that indicates the source location where
aoqi@0:      * this component is created from, or null if no information is
aoqi@0:      * available.
aoqi@0:      */
aoqi@0:     Locator getLocator();
aoqi@0: 
aoqi@0:     /**
aoqi@0:      * Gets a reference to the {@link XSSchema} object to which this component
aoqi@0:      * belongs.
aoqi@0:      * <p>
aoqi@0:      * In case of <code>XSEmpty</code> component, this method
aoqi@0:      * returns null since there is no owner component.
aoqi@0:      */
aoqi@0:     XSSchema getOwnerSchema();
aoqi@0: 
aoqi@0:     /**
aoqi@0:      * Gets the root schema set that includes this component.
aoqi@0:      *
aoqi@0:      * <p>
aoqi@0:      * In case of <code>XSEmpty</code> component, this method
aoqi@0:      * returns null since there is no owner component.
aoqi@0:      */
aoqi@0:     XSSchemaSet getRoot();
aoqi@0: 
aoqi@0:     /**
aoqi@0:      * Gets the {@link SchemaDocument} that indicates which document this component
aoqi@0:      * was defined in.
aoqi@0:      *
aoqi@0:      * @return
aoqi@0:      *      null for components that are built-in to XML Schema, such
aoqi@0:      *      as anyType, or "empty" {@link XSContentType}. This method also
aoqi@0:      *      returns null for {@link XSSchema}.
aoqi@0:      *      For all other user-defined
aoqi@0:      *      components this method returns non-null, even if they are local.
aoqi@0:      */
aoqi@0:     SchemaDocument getSourceDocument();
aoqi@0: 
aoqi@0:     /**
aoqi@0:      * Evaluates a schema component designator against this schema component
aoqi@0:      * and returns the resulting schema components.
aoqi@0:      *
aoqi@0:      * @throws IllegalArgumentException
aoqi@0:      *      if SCD is syntactically incorrect.
aoqi@0:      *
aoqi@0:      * @param scd
aoqi@0:      *      Schema component designator. See {@link SCD} for more details.
aoqi@0:      * @param nsContext
aoqi@0:      *      The namespace context in which SCD is evaluated. Cannot be null.
aoqi@0:      * @return
aoqi@0:      *      Can be empty but never null.
aoqi@0:      */
aoqi@0:     Collection<XSComponent> select(String scd, NamespaceContext nsContext);
aoqi@0: 
aoqi@0:     /**
aoqi@0:      * Evaluates a schema component designator against this schema component
aoqi@0:      * and returns the first resulting schema component.
aoqi@0:      *
aoqi@0:      * @throws IllegalArgumentException
aoqi@0:      *      if SCD is syntactically incorrect.
aoqi@0:      *
aoqi@0:      * @param scd
aoqi@0:      *      Schema component designator. See {@link SCD} for more details.
aoqi@0:      * @param nsContext
aoqi@0:      *      The namespace context in which SCD is evaluated. Cannot be null.
aoqi@0:      * @return
aoqi@0:      *      null if the SCD didn't match anything. If the SCD matched more than one node,
aoqi@0:      *      the first one will be returned.
aoqi@0:      */
aoqi@0:     XSComponent selectSingle(String scd, NamespaceContext nsContext);
aoqi@0: 
aoqi@0:     /**
aoqi@0:      * Accepts a visitor.
aoqi@0:      */
aoqi@0:     void visit( XSVisitor visitor );
aoqi@0:     /**
aoqi@0:      * Accepts a functor.
aoqi@0:      */
aoqi@0:     <T> T apply( XSFunction<T> function );
aoqi@0: }