/*

 * Copyright 2005-2006 Sun Microsystems, Inc.  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.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

//Copyright Sun Microsystems Inc. 2004 - 2005.

package javax.annotation;

import java.lang.annotation.*;

import static java.lang.annotation.ElementType.*;

import static java.lang.annotation.RetentionPolicy.*;

/**

 * The Resource annotation marks a resource that is needed

 * by the application.  This annotation may be applied to an

 * application component class, or to fields or methods of the

 * component class.  When the annotation is applied to a

 * field or method, the container will inject an instance

 * of the requested resource into the application component

 * when the component is initialized.  If the annotation is

 * applied to the component class, the annotation declares a

 * resource that the application will look up at runtime. <p>

 *

 * Even though this annotation is not marked Inherited, deployment

 * tools are required to examine all superclasses of any component

 * class to discover all uses of this annotation in all superclasses.

 * All such annotation instances specify resources that are needed

 * by the application component.  Note that this annotation may

 * appear on private fields and methods of superclasses; the container

 * is required to perform injection in these cases as well.

 *

 * @since Common Annotations 1.0

 */

@Target({TYPE, FIELD, METHOD})

@Retention(RUNTIME)

public @interface Resource {

    /**

     * The JNDI name of the resource.  For field annotations,

     * the default is the field name.  For method annotations,

     * the default is the JavaBeans property name corresponding

     * to the method.  For class annotations, there is no default

     * and this must be specified.

     */

    String name() default "";

    /**

     * The Java type of the resource.  For field annotations,

     * the default is the type of the field.  For method annotations,

     * the default is the type of the JavaBeans property.

     * For class annotations, there is no default and this must be

     * specified.

     */

    Class type() default java.lang.Object.class;

    /**

     * The two possible authentication types for a resource.

     */

    enum AuthenticationType {

            CONTAINER,

            APPLICATION

    }

    /**

     * The authentication type to use for this resource.

     * This may be specified for resources representing a

     * connection factory of any supported type, and must

     * not be specified for resources of other types.

     */

    AuthenticationType authenticationType() default AuthenticationType.CONTAINER;

    /**

     * Indicates whether this resource can be shared between

     * this component and other components.

     * This may be specified for resources representing a

     * connection factory of any supported type, and must

     * not be specified for resources of other types.

     */

    boolean shareable() default true;

    /**

     * A product specific name that this resource should be mapped to.

     * The name of this resource, as defined by the <code>name</code>

     * element or defaulted, is a name that is local to the application

     * component using the resource.  (It's a name in the JNDI

     * <code>java:comp/env</code> namespace.)  Many application servers

     * provide a way to map these local names to names of resources

     * known to the application server.  This mapped name is often a

     * <i>global</i> JNDI name, but may be a name of any form. <p>

     *

     * Application servers are not required to support any particular

     * form or type of mapped name, nor the ability to use mapped names.

     * The mapped name is product-dependent and often installation-dependent.

     * No use of a mapped name is portable.

     */

    String mappedName() default "";

    /**

     * Description of this resource.  The description is expected

     * to be in the default language of the system on which the

     * application is deployed.  The description can be presented

     * to the Deployer to help in choosing the correct resource.

     */

    String description() default "";

}