1 /* 2 * Copyright (c) 2005, 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.xml.internal.txw2.annotation; 27 28 import com.sun.xml.internal.txw2.TypedXmlWriter; 29 import com.sun.xml.internal.txw2.TXW; 30 import com.sun.xml.internal.txw2.output.XmlSerializer; 31 32 import javax.xml.namespace.QName; 33 import java.lang.annotation.Retention; 34 import java.lang.annotation.Target; 35 36 import static java.lang.annotation.ElementType.TYPE; 37 import static java.lang.annotation.RetentionPolicy.RUNTIME; 38 import static java.lang.annotation.ElementType.METHOD; 39 40 /** 41 * Specifies the name of the XML element. 42 * 43 * <h2>Used on method</h2> 44 * <p> 45 * When used on methods declared on interfaces that derive 46 * from {@link TypedXmlWriter}, it specifies that the invocation 47 * of the method will produce an element of the specified name. 48 * 49 * <p> 50 * The method signature has to match one of the following patterns. 51 * 52 * <dl> 53 * <dt>Child writer: {@code TW foo()}</dt> 54 * <dd>TW must be an interface derived from {@link TypedXmlWriter}. 55 * When this method is called, a new child element is started, 56 * and its content can be written by using the returned {@code TW} 57 * object. This child element will be ended when its _commit method 58 * is called. 59 * <dt>Leaf element: {@code void foo(DT1,DT2,...)}</dt> 60 * <dd>DTi must be datatype objects. 61 * When this method is called, a new child element is started, 62 * followed by the whitespace-separated text data from each of 63 * the datatype objects, followed by the end tag. 64 * </dl> 65 * 66 * <h2>Used on interface</h2> 67 * <p> 68 * When used on interfaces that derive from {@link TypedXmlWriter}, 69 * it associates an element name with that interface. This name is 70 * used in a few places, such as in {@link TXW#create(Class,XmlSerializer)} 71 * and {@link TypedXmlWriter#_element(Class)}. 72 * 73 * 74 * @author Kohsuke Kawaguchi 75 */ 76 @Retention(RUNTIME) 77 @Target({METHOD,TYPE}) 78 public @interface XmlElement { 79 /** 80 * The local name of the element. 81 */ 82 String value() default ""; 83 84 /** 85 * The namespace URI of this element. 86 * 87 * <p> 88 * If the annotation is on an interface and this paramter is left unspecified, 89 * then the namespace URI is taken from {@link XmlNamespace} annotation on 90 * the package that the interface is in. If {@link XmlNamespace} annotation 91 * doesn't exist, the namespace URI will be "". 92 * 93 * <p> 94 * If the annotation is on a method and this parameter is left unspecified, 95 * then the namespace URI is the same as the namespace URI of the writer interface. 96 */ 97 String ns() default "##default"; 98 }