001 /*
002 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.bind;
027
028 import javax.xml.namespace.QName;
029 import java.io.Serializable;
030
031 /**
032 * <p>JAXB representation of an Xml Element.</p>
033 *
034 * <p>This class represents information about an Xml Element from both the element
035 * declaration within a schema and the element instance value within an xml document
036 * with the following properties
037 * <ul>
038 * <li>element's xml tag <b><tt>name</tt></b></li>
039 * <li><b><tt>value</tt></b> represents the element instance's atttribute(s) and content model</li>
040 * <li>element declaration's <b><tt>declaredType</tt></b> (<tt>xs:element @type</tt> attribute)</li>
041 * <li><b><tt>scope</tt></b> of element declaration</li>
042 * <li>boolean <b><tt>nil</tt></b> property. (element instance's <tt><b>xsi:nil</b></tt> attribute)</li>
043 * </ul>
044 *
045 * <p>The <tt>declaredType</tt> and <tt>scope</tt> property are the
046 * JAXB class binding for the xml type definition.
047 * </p>
048 *
049 * <p><b><tt>Scope</tt></b> is either {@link GlobalScope} or the Java class representing the
050 * complex type definition containing the schema element declaration.
051 * </p>
052 *
053 * <p>There is a property constraint that if <b><tt>value</tt></b> is <tt>null</tt>,
054 * then <tt>nil</tt> must be <tt>true</tt>. The converse is not true to enable
055 * representing a nil element with attribute(s). If <tt>nil</tt> is true, it is possible
056 * that <tt>value</tt> is non-null so it can hold the value of the attributes
057 * associated with a nil element.
058 * </p>
059 *
060 * @author Kohsuke Kawaguchi, Joe Fialli
061 * @since JAXB 2.0
062 */
063
064 public class JAXBElement<T> implements Serializable {
065
066 /** xml element tag name */
067 final protected QName name;
068
069 /** Java datatype binding for xml element declaration's type. */
070 final protected Class<T> declaredType;
071
072 /** Scope of xml element declaration representing this xml element instance.
073 * Can be one of the following values:
074 * - {@link GlobalScope} for global xml element declaration.
075 * - local element declaration has a scope set to the Java class
076 * representation of complex type defintion containing
077 * xml element declaration.
078 */
079 final protected Class scope;
080
081 /** xml element value.
082 Represents content model and attributes of an xml element instance. */
083 protected T value;
084
085 /** true iff the xml element instance has xsi:nil="true". */
086 protected boolean nil = false;
087
088 /**
089 * Designates global scope for an xml element.
090 */
091 public static final class GlobalScope {
092 }
093
094 /**
095 * <p>Construct an xml element instance.</p>
096 *
097 * @param name Java binding of xml element tag name
098 * @param declaredType Java binding of xml element declaration's type
099 * @param scope
100 * Java binding of scope of xml element declaration.
101 * Passing null is the same as passing <tt>GlobalScope.class</tt>
102 * @param value
103 * Java instance representing xml element's value.
104 * @see #getScope()
105 * @see #isTypeSubstituted()
106 */
107 public JAXBElement(QName name, Class<T> declaredType, Class scope,
108 T value) {
109 if (declaredType == null || name == null)
110 throw new IllegalArgumentException();
111 this .declaredType = declaredType;
112 if (scope == null)
113 scope = GlobalScope.class;
114 this .scope = scope;
115 this .name = name;
116 setValue(value);
117 }
118
119 /**
120 * Construct an xml element instance.
121 *
122 * This is just a convenience method for <tt>new JAXBElement(name,declaredType,GlobalScope.class,value)</tt>
123 */
124 public JAXBElement(QName name, Class<T> declaredType, T value) {
125 this (name, declaredType, GlobalScope.class, value);
126 }
127
128 /**
129 * Returns the Java binding of the xml element declaration's type attribute.
130 */
131 public Class<T> getDeclaredType() {
132 return declaredType;
133 }
134
135 /**
136 * Returns the xml element tag name.
137 */
138 public QName getName() {
139 return name;
140 }
141
142 /**
143 * <p>Set the content model and attributes of this xml element.</p>
144 *
145 * <p>When this property is set to <tt>null</tt>, <tt>isNil()</tt> must by <tt>true</tt>.
146 * Details of constraint are described at {@link #isNil()}.</p>
147 *
148 * @see #isTypeSubstituted()
149 */
150 public void setValue(T t) {
151 this .value = t;
152 }
153
154 /**
155 * <p>Return the content model and attribute values for this element.</p>
156 *
157 * <p>See {@link #isNil()} for a description of a property constraint when
158 * this value is <tt>null</tt></p>
159 */
160 public T getValue() {
161 return value;
162 }
163
164 /**
165 * Returns scope of xml element declaration.
166 *
167 * @see #isGlobalScope()
168 * @return <tt>GlobalScope.class</tt> if this element is of global scope.
169 */
170 public Class getScope() {
171 return scope;
172 }
173
174 /**
175 * <p>Returns <tt>true</tt> iff this element instance content model
176 * is nil.</p>
177 *
178 * <p>This property always returns <tt>true</tt> when {@link #getValue()} is null.
179 * Note that the converse is not true, when this property is <tt>true</tt>,
180 * {@link #getValue()} can contain a non-null value for attribute(s). It is
181 * valid for a nil xml element to have attribute(s).</p>
182 */
183 public boolean isNil() {
184 return (value == null) || nil;
185 }
186
187 /**
188 * <p>Set whether this element has nil content.</p>
189 *
190 * @see #isNil()
191 */
192 public void setNil(boolean value) {
193 this .nil = value;
194 }
195
196 /* Convenience methods
197 * (Not necessary but they do unambiguously conceptualize
198 * the rationale behind this class' fields.)
199 */
200
201 /**
202 * Returns true iff this xml element declaration is global.
203 */
204 public boolean isGlobalScope() {
205 return this .scope == GlobalScope.class;
206 }
207
208 /**
209 * Returns true iff this xml element instance's value has a different
210 * type than xml element declaration's declared type.
211 */
212 public boolean isTypeSubstituted() {
213 if (value == null)
214 return false;
215 return value.getClass() != declaredType;
216 }
217
218 private static final long serialVersionUID = 1L;
219 }
|