/*
 * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package com.sun.xml.internal.txw2.annotation;

import com.sun.xml.internal.txw2.TypedXmlWriter;
import com.sun.xml.internal.txw2.TXW;
import com.sun.xml.internal.txw2.output.XmlSerializer;

import javax.xml.namespace.QName;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import static java.lang.annotation.ElementType.METHOD;

Specifies the name of the XML element.
Used on method
 When used on methods declared on interfaces that derive from TypedXmlWriter, it specifies that the invocation of the method will produce an element of the specified name. 

The method signature has to match one of the following patterns.

 
Child writer: TW foo()
 
TW must be an interface derived from TypedXmlWriter. When this method is called, a new child element is started, and its content can be written by using the returned TW object. This child element will be ended when its _commit method is called. 
Leaf element: void foo(DT1,DT2,...)
 
DTi must be datatype objects.
     When this method is called, a new child element is started,
     followed by the whitespace-separated text data from each of
     the datatype objects, followed by the end tag.

Used on interface
 When used on interfaces that derive from TypedXmlWriter, it associates an element name with that interface. This name is used in a few places, such as in TXW.create(Class<TypedXmlWriter>, XmlSerializer) and TypedXmlWriter._element(Class<TypedXmlWriter>). 
Author:
Kohsuke Kawaguchi/**
 * Specifies the name of the XML element.
 *
 * <h2>Used on method</h2>
 * <p>
 * When used on methods declared on interfaces that derive
 * from {@link TypedXmlWriter}, it specifies that the invocation
 * of the method will produce an element of the specified name.
 *
 * <p>
 * The method signature has to match one of the following patterns.
 *
 * <dl>
 *  <dt>Child writer: {@code TW foo()}</dt>
 *  <dd>TW must be an interface derived from {@link TypedXmlWriter}.
 *      When this method is called, a new child element is started,
 *      and its content can be written by using the returned {@code TW}
 *      object. This child element will be ended when its _commit method
 *      is called.
 *  <dt>Leaf element: {@code void foo(DT1,DT2,...)}</dt>
 *  <dd>DTi must be datatype objects.
 *      When this method is called, a new child element is started,
 *      followed by the whitespace-separated text data from each of
 *      the datatype objects, followed by the end tag.
 * </dl>
 *
 * <h2>Used on interface</h2>
 * <p>
 * When used on interfaces that derive from {@link TypedXmlWriter},
 * it associates an element name with that interface. This name is
 * used in a few places, such as in {@link TXW#create(Class,XmlSerializer)}
 * and {@link TypedXmlWriter#_element(Class)}.
 *
 *
 * @author Kohsuke Kawaguchi
 */
@Retention(RUNTIME)
@Target({METHOD,TYPE})
public @interface XmlElement {
    
The local name of the element.
/**
     * The local name of the element.
     */
    String value() default "";

    
The namespace URI of this element.
 If the annotation is on an interface and this paramter is left unspecified, then the namespace URI is taken from XmlNamespace annotation on the package that the interface is in. If XmlNamespace annotation doesn't exist, the namespace URI will be "". 

If the annotation is on a method and this parameter is left unspecified,
then the namespace URI is the same as the namespace URI of the writer interface.
/**
     * The namespace URI of this element.
     *
     * <p>
     * If the annotation is on an interface and this paramter is left unspecified,
     * then the namespace URI is taken from {@link XmlNamespace} annotation on
     * the package that the interface is in. If {@link XmlNamespace} annotation
     * doesn't exist, the namespace URI will be "".
     *
     * <p>
     * If the annotation is on a method and this parameter is left unspecified,
     * then the namespace URI is the same as the namespace URI of the writer interface.
     */
    String ns() default "##default";
}