01: /*
02: * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
03: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
04: *
05: * This code is free software; you can redistribute it and/or modify it
06: * under the terms of the GNU General Public License version 2 only, as
07: * published by the Free Software Foundation. Sun designates this
08: * particular file as subject to the "Classpath" exception as provided
09: * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22: * CA 95054 USA or visit www.sun.com if you need additional information or
23: * have any questions.
24: */
25: package com.sun.xml.internal.txw2.annotation;
26:
27: import com.sun.xml.internal.txw2.TypedXmlWriter;
28: import com.sun.xml.internal.txw2.TXW;
29: import com.sun.xml.internal.txw2.output.XmlSerializer;
30:
31: import javax.xml.namespace.QName;
32: import java.lang.annotation.Retention;
33: import java.lang.annotation.Target;
34:
35: import static java.lang.annotation.ElementType.TYPE;
36: import static java.lang.annotation.RetentionPolicy.RUNTIME;
37: import static java.lang.annotation.ElementType.METHOD;
38:
39: /**
40: * Specifies the name of the XML element.
41: *
42: * <h2>Used on method</h2>
43: * <p>
44: * When used on methods declared on interfaces that derive
45: * from {@link TypedXmlWriter}, it specifies that the invocation
46: * of the method will produce an element of the specified name.
47: *
48: * <p>
49: * The method signature has to match one of the following patterns.
50: *
51: * <dl>
52: * <dt>Child writer: <tt>TW foo()</tt></dt>
53: * <dd>TW must be an interface derived from {@link TypedXmlWriter}.
54: * When this method is called, a new child element is started,
55: * and its content can be written by using the returned <tt>TW</tt>
56: * object. This child element will be ended when its _commit method
57: * is called.
58: * <dt>Leaf element: <tt>void foo(DT1,DT2,...)</tt></dt>
59: * <dd>DTi must be datatype objects.
60: * When this method is called, a new child element is started,
61: * followed by the whitespace-separated text data from each of
62: * the datatype objects, followed by the end tag.
63: * </dl>
64: *
65: * <h2>Used on interface</h2>
66: * <p>
67: * When used on interfaces that derive from {@link TypedXmlWriter},
68: * it associates an element name with that interface. This name is
69: * used in a few places, such as in {@link TXW#create(Class,XmlSerializer)}
70: * and {@link TypedXmlWriter#_element(Class)}.
71: *
72: *
73: * @author Kohsuke Kawaguchi
74: */
75: @Retention(RUNTIME)
76: @Target({METHOD,TYPE})
77: public @interface XmlElement {
78: /**
79: * The local name of the element.
80: */
81: String value() default "";
82:
83: /**
84: * The namespace URI of this element.
85: *
86: * <p>
87: * If the annotation is on an interface and this paramter is left unspecified,
88: * then the namespace URI is taken from {@link XmlNamespace} annotation on
89: * the package that the interface is in. If {@link XmlNamespace} annotation
90: * doesn't exist, the namespace URI will be "".
91: *
92: * <p>
93: * If the annotation is on a method and this parameter is left unspecified,
94: * then the namespace URI is the same as the namespace URI of the writer interface.
95: */
96: String ns() default "##default";
97: }
|