1 /*
   2  * Copyright (c) 1997, 2012, 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.bind.v2.model.core;
  27 
  28 import java.util.Map;
  29 
  30 import javax.xml.bind.JAXBException;
  31 import javax.xml.bind.annotation.XmlSchema;
  32 import javax.xml.bind.annotation.XmlNsForm;
  33 import javax.xml.namespace.QName;
  34 import javax.xml.transform.Result;
  35 
  36 import com.sun.xml.internal.bind.v2.model.nav.Navigator;
  37 
  38 /**
  39  * Root of models. Set of {@link TypeInfo}s.
  40  *
  41  * @author Kohsuke Kawaguchi
  42  */
  43 public interface TypeInfoSet<T,C,F,M> {
  44 
  45     /**
  46      * {@link Navigator} for this model.
  47      */
  48     Navigator<T,C,F,M> getNavigator();
  49 
  50 //  turns out we can't have AnnotationReader in XJC, so it's impossible to have this here.
  51 //  perhaps we should revisit this in the future.
  52 //    /**
  53 //     * {@link AnnotationReader} for this model.
  54 //     */
  55 //    AnnotationReader<T,C,F,M> getReader();
  56 
  57     /**
  58      * Returns a {@link TypeInfo} for the given type.
  59      *
  60      * @return
  61      *      null if the specified type cannot be bound by JAXB, or
  62      *      not known to this set.
  63      */
  64     NonElement<T,C> getTypeInfo( T type );
  65 
  66     /**
  67      * Gets the {@link TypeInfo} for the any type.
  68      */
  69     NonElement<T,C> getAnyTypeInfo();
  70 
  71     /**
  72      * Returns a {@link ClassInfo}, {@link ArrayInfo}, or {@link LeafInfo}
  73      * for the given bean.
  74      *
  75      * <p>
  76      * This method is almost like refinement of {@link #getTypeInfo(Object)} except
  77      * our C cannot derive from T.
  78      *
  79      * @return
  80      *      null if the specified type is not bound by JAXB or otherwise
  81      *      unknown to this set.
  82      */
  83     NonElement<T,C> getClassInfo( C type );
  84 
  85     /**
  86      * Returns all the {@link ArrayInfo}s known to this set.
  87      */
  88     Map<? extends T,? extends ArrayInfo<T,C>> arrays();
  89 
  90     /**
  91      * Returns all the {@link ClassInfo}s known to this set.
  92      */
  93     Map<C,? extends ClassInfo<T,C>> beans();
  94 
  95     /**
  96      * Returns all the {@link BuiltinLeafInfo}s known to this set.
  97      */
  98     Map<T,? extends BuiltinLeafInfo<T,C>> builtins();
  99 
 100     /**
 101      * Returns all the {@link EnumLeafInfo}s known to this set.
 102      */
 103     Map<C,? extends EnumLeafInfo<T,C>> enums();
 104 
 105     /**
 106      * Returns a {@link ElementInfo} for the given element.
 107      *
 108      * @param scope
 109      *      if null, return the info about a global element.
 110      *      Otherwise return a local element in the given scope if available,
 111      *      then look for a global element next.
 112      */
 113     ElementInfo<T,C> getElementInfo( C scope, QName name );
 114 
 115     /**
 116      * Returns a type information for the given reference.
 117      */
 118     NonElement<T,C> getTypeInfo(Ref<T,C> ref);
 119 
 120     /**
 121      * Returns all  {@link ElementInfo}s in the given scope.
 122      *
 123      * @param scope
 124      *      if non-null, this method only returns the local element mapping.
 125      */
 126     Map<QName,? extends ElementInfo<T,C>> getElementMappings( C scope );
 127 
 128     /**
 129      * Returns all the {@link ElementInfo} known to this set.
 130      */
 131     Iterable<? extends ElementInfo<T,C>> getAllElements();
 132 
 133 
 134     /**
 135      * Gets all {@link XmlSchema#xmlns()} found in this context for the given namespace URI.
 136      *
 137      * <p>
 138      * This operation is expected to be only used in schema generator, so it can be slow.
 139      *
 140      * @return
 141      *      A map from prefixes to namespace URIs, which should be declared when generating a schema.
 142      *      Could be empty but never null.
 143      */
 144     Map<String,String> getXmlNs(String namespaceUri);
 145 
 146     /**
 147      * Gets {@link XmlSchema#location()} found in this context.
 148      *
 149      * <p>
 150      * This operation is expected to be only used in schema generator, so it can be slow.
 151      *
 152      * @return
 153      *      A map from namespace URI to the value of the location.
 154      *      If the entry is missing, that means a schema should be generated for that namespace.
 155      *      If the value is "", that means the schema location is implied
 156      *      ({@code <xs:schema namespace="..."/>} w/o schemaLocation.)
 157      */
 158     Map<String,String> getSchemaLocations();
 159 
 160     /**
 161      * Gets the reasonable {@link XmlNsForm} for the given namespace URI.
 162      *
 163      * <p>
 164      * The spec doesn't define very precisely what the {@link XmlNsForm} value
 165      * for the given namespace would be, so this method is implemented in rather
 166      * ad-hoc way. It should work as what most people expect for simple cases.
 167      *
 168      * @return never null.
 169      */
 170     XmlNsForm getElementFormDefault(String nsUri);
 171 
 172     /**
 173      * Gets the reasonable {@link XmlNsForm} for the given namespace URI.
 174      *
 175      * <p>
 176      * The spec doesn't define very precisely what the {@link XmlNsForm} value
 177      * for the given namespace would be, so this method is implemented in rather
 178      * ad-hoc way. It should work as what most people expect for simple cases.
 179      *
 180      * @return never null.
 181      */
 182     XmlNsForm getAttributeFormDefault(String nsUri);
 183 
 184     /**
 185      * Dumps this model into XML.
 186      *
 187      * For debug only.
 188      *
 189      * TODO: not sure if this actually works. We don't really know what are T,C.
 190      */
 191     public void dump( Result out ) throws JAXBException;
 192 }