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.tools.internal.xjc.api;
  27 
  28 import java.util.List;
  29 
  30 import javax.xml.namespace.QName;
  31 
  32 /**
  33  * JAXB-induced mapping between a Java class
  34  * and an XML element declaration. A part of the compiler artifacts.
  35  *
  36  * <p>
  37  * To be precise, this is a mapping between two Java classes and an
  38  * XML element declaration. There's one Java class/interface that
  39  * represents the element, and there's another Java class/interface that
  40  * represents the type of the element.
  41  *
  42  * The former is called "element representation" and the latter is called
  43  * "type representation".
  44  *
  45  * <p>
  46  * The {@link Mapping} interface provides operation that lets the caller
  47  * convert an instance of the element representation to that of the
  48  * type representation or vice versa.
  49  *
  50  * @author
  51  *     Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
  52  */
  53 public interface Mapping {
  54     /**
  55      * Name of the XML element.
  56      *
  57      * @return
  58      *      never be null.
  59      */
  60     QName getElement();
  61 
  62     /**
  63      * Returns the fully-qualified name of the java class for the type of this element.
  64      *
  65      * TODO: does this method returns the name of the wrapper bean when it's qualified
  66      * for the wrapper style? Seems no (consider &lt;xs:element name='foo' type='xs:long' />),
  67      * but then how does JAX-RPC captures that bean?
  68      *
  69      * @return
  70      *      never be null.
  71      */
  72     TypeAndAnnotation getType();
  73 
  74     /**
  75      * If this element is a so-called "wrapper-style" element,
  76      * obtains its member information.
  77      *
  78      * <p>
  79      * The notion of the wrapper style should be defined by the JAXB spec,
  80      * and ideally it should differ from that of the JAX-RPC only at
  81      * the point where the JAX-RPC imposes additional restriction
  82      * on the element name.
  83      *
  84      * <p>
  85      * As of this writing the JAXB spec doesn't define "the wrapper style"
  86      * and as such the exact definition of what XJC thinks
  87      * "the wrapper style" isn't spec-ed.
  88      *
  89      * <p>
  90      * Ths returned list includes {@link Property} defined not just
  91      * in this class but in all its base classes.
  92      *
  93      * @return
  94      *      null if this isn't a wrapper-style element.
  95      *      Otherwise list of {@link Property}s. The order signifies
  96      *      the order they appeared inside a schema.
  97      */
  98     List<? extends Property> getWrapperStyleDrilldown();
  99 }
--- EOF ---