ohair@286: /* ohair@286: * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved. ohair@286: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. ohair@286: * ohair@286: * This code is free software; you can redistribute it and/or modify it ohair@286: * under the terms of the GNU General Public License version 2 only, as ohair@286: * published by the Free Software Foundation. Oracle designates this ohair@286: * particular file as subject to the "Classpath" exception as provided ohair@286: * by Oracle in the LICENSE file that accompanied this code. ohair@286: * ohair@286: * This code is distributed in the hope that it will be useful, but WITHOUT ohair@286: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or ohair@286: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License ohair@286: * version 2 for more details (a copy is included in the LICENSE file that ohair@286: * accompanied this code). ohair@286: * ohair@286: * You should have received a copy of the GNU General Public License version ohair@286: * 2 along with this work; if not, write to the Free Software Foundation, ohair@286: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. ohair@286: * ohair@286: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@286: * or visit www.oracle.com if you need additional information or have any ohair@286: * questions. ohair@286: */ ohair@286: ohair@286: package javax.xml.bind.annotation; ohair@286: ohair@286: import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter; ohair@286: import static java.lang.annotation.RetentionPolicy.RUNTIME; ohair@286: import static java.lang.annotation.ElementType.FIELD; ohair@286: import static java.lang.annotation.ElementType.METHOD; ohair@286: import java.lang.annotation.Retention; ohair@286: import java.lang.annotation.Target; ohair@286: ohair@286: /** ohair@286: * Generates a wrapper element around XML representation. ohair@286: * ohair@286: * This is primarily intended to be used to produce a wrapper ohair@286: * XML element around collections. The annotation therefore supports ohair@286: * two forms of serialization shown below. ohair@286: * ohair@286: *
ohair@286: * //Example: code fragment ohair@286: * int[] names; ohair@286: * ohair@286: * // XML Serialization Form 1 (Unwrapped collection) ohair@286: * <names> ... </names> ohair@286: * <names> ... </names> ohair@286: * ohair@286: * // XML Serialization Form 2 ( Wrapped collection ) ohair@286: * <wrapperElement> ohair@286: * <names> value-of-item </names> ohair@286: * <names> value-of-item </names> ohair@286: * .... ohair@286: * </wrapperElement> ohair@286: *ohair@286: * ohair@286: *
The two serialized XML forms allow a null collection to be ohair@286: * represented either by absence or presence of an element with a ohair@286: * nillable attribute. ohair@286: * ohair@286: *
Usage
ohair@286: *ohair@286: * The @XmlElementWrapper annotation can be used with the ohair@286: * following program elements: ohair@286: *
The usage is subject to the following constraints: ohair@286: *
See "Package Specification" in javax.xml.bind.package javadoc for ohair@286: * additional common information.
ohair@286: * ohair@286: * @authorohair@286: * If the value is "##default", then the namespace is determined ohair@286: * as follows: ohair@286: *
ohair@286: * If required() is true, then the corresponding generated ohair@286: * XML schema element declaration will have minOccurs="1", ohair@286: * to indicate that the wrapper element is always expected. ohair@286: * ohair@286: *
ohair@286: * Note that this only affects the schema generation, and ohair@286: * not the unmarshalling or marshalling capability. This is ohair@286: * simply a mechanism to let users express their application constraints ohair@286: * better. ohair@286: * ohair@286: * @since JAXB 2.1 ohair@286: */ ohair@286: boolean required() default false; ohair@286: }