1 /*
   2  * Copyright (c) 1997, 2015, 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.List;
  29 
  30 import javax.xml.namespace.QName;
  31 
  32 /**
  33  * Property that maps to an element.
  34  *
  35  * @author Kohsuke Kawaguchi
  36  */
  37 // TODO: there seems to be too much interactions between switches, and that's no good.
  38 public interface ElementPropertyInfo<T,C> extends PropertyInfo<T,C> {
  39     /**
  40      * Returns the information about the types allowed in this property.
  41      *
  42      * <p>
  43      * In a simple case like the following, an element property only has
  44      * one {@link TypeRef} that points to {@link String} and tag name "foo".
  45      * <pre>
  46      * @XmlElement
  47      * String abc;
  48      * </pre>
  49      *
  50      * <p>
  51      * However, in a general case an element property can be heterogeneous,
  52      * meaning you can put different types in it, each with a different tag name
  53      * (and a few other settings.)
  54      * <pre>{@code
  55      * // list can contain String or Integer.
  56      * @XmlElements({
  57      *   @XmlElement(name="a",type=String.class),
  58      *   @XmlElement(name="b",type=Integer.class),
  59      * })
  60      * List<Object> abc;
  61      * }</pre>
  62      * <p>
  63      * In this case this method returns a list of two {@link TypeRef}s.
  64      *
  65      *
  66      * @return
  67      *      Always non-null. Contains at least one entry.
  68      *      If {@link #isValueList()}==true, there's always exactly one type.
  69      */
  70     List<? extends TypeRef<T,C>> getTypes();
  71 
  72     /**
  73      * Gets the wrapper element name.
  74      *
  75      * @return
  76      *      must be null if {@link #isCollection()}==false or
  77      *      if {@link #isValueList()}==true.
  78      *
  79      *      Otherwise,
  80      *      this can be null (in which case there'll be no wrapper),
  81      *      or it can be non-null (in which case there'll be a wrapper)
  82      */
  83     QName getXmlName();
  84 
  85     /**
  86      * Checks if the wrapper element is required.
  87      *
  88      * @return
  89      *      Always false if {@link #getXmlName()}==null.
  90      */
  91     boolean isCollectionRequired();
  92 
  93     /**
  94      * Returns true if this property is nillable
  95      * (meaning the absence of the value is treated as nil='true')
  96      *
  97      * <p>
  98      * This method is only used when this property is a collection.
  99      */
 100     boolean isCollectionNillable();
 101 
 102     /**
 103      * Returns true if this property is a collection but its XML
 104      * representation is a list of values, not repeated elements.
 105      *
 106      * <p>
 107      * If {@link #isCollection()}==false, this property is always false.
 108      *
 109      * <p>
 110      * When this flag is true, {@code getTypes().size()==1} always holds.
 111      */
 112     boolean isValueList();
 113 
 114     /**
 115      * Returns true if this element is mandatory.
 116      *
 117      * For collections, this property isn't used.
 118      * TODO: define the semantics when this is a collection
 119      */
 120     boolean isRequired();
 121 
 122     Adapter<T,C> getAdapter();
 123 }