001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036:
037: package com.sun.xml.bind.v2.model.core;
038:
039: import java.util.List;
040:
041: import javax.xml.namespace.QName;
042:
043: /**
044: * Property that maps to an element.
045: *
046: * @author Kohsuke Kawaguchi
047: */
048: // TODO: there seems to be too much interactions between switches, and that's no good.
049: public interface ElementPropertyInfo<T, C> extends PropertyInfo<T, C> {
050: /**
051: * Returns the information about the types allowed in this property.
052: *
053: * <p>
054: * In a simple case like the following, an element property only has
055: * one {@link TypeRef} that points to {@link String} and tag name "foo".
056: * <pre>
057: * @XmlElement
058: * String abc;
059: * </pre>
060: *
061: * <p>
062: * However, in a general case an element property can be heterogeneous,
063: * meaning you can put different types in it, each with a different tag name
064: * (and a few other settings.)
065: * <pre>
066: * // list can contain String or Integer.
067: * @XmlElements({
068: * @XmlElement(name="a",type=String.class),
069: * @XmlElement(name="b",type=Integer.class),
070: * })
071: * List<Object> abc;
072: * </pre>
073: * <p>
074: * In this case this method returns a list of two {@link TypeRef}s.
075: *
076: *
077: * @return
078: * Always non-null. Contains at least one entry.
079: * If {@link #isValueList()}==true, there's always exactly one type.
080: */
081: List<? extends TypeRef<T, C>> getTypes();
082:
083: /**
084: * Gets the wrapper element name.
085: *
086: * @return
087: * must be null if {@link #isCollection()}==false or
088: * if {@link #isValueList()}==true.
089: *
090: * Otherwise,
091: * this can be null (in which case there'll be no wrapper),
092: * or it can be non-null (in which case there'll be a wrapper)
093: */
094: QName getXmlName();
095:
096: /**
097: * Checks if the wrapper element is required.
098: *
099: * @return
100: * Always false if {@link #getXmlName()}==null.
101: */
102: boolean isCollectionRequired();
103:
104: /**
105: * Returns true if this property is nillable
106: * (meaning the absence of the value is treated as nil='true')
107: *
108: * <p>
109: * This method is only used when this property is a collection.
110: */
111: boolean isCollectionNillable();
112:
113: /**
114: * Returns true if this property is a collection but its XML
115: * representation is a list of values, not repeated elements.
116: *
117: * <p>
118: * If {@link #isCollection()}==false, this property is always false.
119: *
120: * <p>
121: * When this flag is true, <tt>getTypes().size()==1</tt> always holds.
122: */
123: boolean isValueList();
124:
125: /**
126: * Returns true if this element is mandatory.
127: *
128: * For collections, this property isn't used.
129: * TODO: define the semantics when this is a collection
130: */
131: boolean isRequired();
132:
133: Adapter<T, C> getAdapter();
134: }
|