01: /*
02: * The contents of this file are subject to the terms
03: * of the Common Development and Distribution License
04: * (the "License"). You may not use this file except
05: * in compliance with the License.
06: *
07: * You can obtain a copy of the license at
08: * https://jwsdp.dev.java.net/CDDLv1.0.html
09: * See the License for the specific language governing
10: * permissions and limitations under the License.
11: *
12: * When distributing Covered Code, include this CDDL
13: * HEADER in each file and include the License file at
14: * https://jwsdp.dev.java.net/CDDLv1.0.html If applicable,
15: * add the following below this CDDL HEADER, with the
16: * fields enclosed by brackets "[]" replaced with your
17: * own identifying information: Portions Copyright [yyyy]
18: * [name of copyright owner]
19: */
20:
21: package com.sun.xml.txw2.annotation;
22:
23: import com.sun.xml.txw2.TypedXmlWriter;
24: import com.sun.xml.txw2.TXW;
25: import com.sun.xml.txw2.output.XmlSerializer;
26:
27: import javax.xml.namespace.QName;
28: import java.lang.annotation.Retention;
29: import java.lang.annotation.Target;
30:
31: import static java.lang.annotation.ElementType.TYPE;
32: import static java.lang.annotation.RetentionPolicy.RUNTIME;
33: import static java.lang.annotation.ElementType.METHOD;
34:
35: /**
36: * Specifies the name of the XML element.
37: *
38: * <h2>Used on method</h2>
39: * <p>
40: * When used on methods declared on interfaces that derive
41: * from {@link TypedXmlWriter}, it specifies that the invocation
42: * of the method will produce an element of the specified name.
43: *
44: * <p>
45: * The method signature has to match one of the following patterns.
46: *
47: * <dl>
48: * <dt>Child writer: <tt>TW foo()</tt></dt>
49: * <dd>TW must be an interface derived from {@link TypedXmlWriter}.
50: * When this method is called, a new child element is started,
51: * and its content can be written by using the returned <tt>TW</tt>
52: * object. This child element will be ended when its _commit method
53: * is called.
54: * <dt>Leaf element: <tt>void foo(DT1,DT2,...)</tt></dt>
55: * <dd>DTi must be datatype objects.
56: * When this method is called, a new child element is started,
57: * followed by the whitespace-separated text data from each of
58: * the datatype objects, followed by the end tag.
59: * </dl>
60: *
61: * <h2>Used on interface</h2>
62: * <p>
63: * When used on interfaces that derive from {@link TypedXmlWriter},
64: * it associates an element name with that interface. This name is
65: * used in a few places, such as in {@link TXW#create(Class,XmlSerializer)}
66: * and {@link TypedXmlWriter#_element(Class)}.
67: *
68: *
69: * @author Kohsuke Kawaguchi
70: */
71: @Retention(RUNTIME)
72: @Target({METHOD,TYPE})
73: public @interface XmlElement {
74: /**
75: * The local name of the element.
76: */
77: String value() default "";
78:
79: /**
80: * The namespace URI of this element.
81: *
82: * <p>
83: * If the annotation is on an interface and this paramter is left unspecified,
84: * then the namespace URI is taken from {@link XmlNamespace} annotation on
85: * the package that the interface is in. If {@link XmlNamespace} annotation
86: * doesn't exist, the namespace URI will be "".
87: *
88: * <p>
89: * If the annotation is on a method and this parameter is left unspecified,
90: * then the namespace URI is the same as the namespace URI of the writer interface.
91: */
92: String ns() default "##default";
93: }
|