Original spec added (#69)
diff --git a/pom.xml b/pom.xml index 311602d..e2520fd 100644 --- a/pom.xml +++ b/pom.xml
@@ -23,7 +23,7 @@ <parent> <groupId>org.eclipse.ee4j</groupId> <artifactId>project</artifactId> - <version>1.0.5</version> + <version>1.0.6</version> </parent> <groupId>jakarta.annotation</groupId>
diff --git a/spec/src/main/asciidoc/annotations-spec.adoc b/spec/src/main/asciidoc/annotations-spec.adoc index 2c417eb..fea5dd1 100644 --- a/spec/src/main/asciidoc/annotations-spec.adoc +++ b/spec/src/main/asciidoc/annotations-spec.adoc
@@ -26,3 +26,7 @@ // == Scope :sectnums: include::scope.adoc[] + +// == Spec +:sectnums: +include::spec.adoc[]
diff --git a/spec/src/main/asciidoc/images/annotations-10.png b/spec/src/main/asciidoc/images/annotations-10.png new file mode 100644 index 0000000..191893b --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-10.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/annotations-3.png b/spec/src/main/asciidoc/images/annotations-3.png new file mode 100644 index 0000000..ae10fab --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-3.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/annotations-4.png b/spec/src/main/asciidoc/images/annotations-4.png new file mode 100644 index 0000000..191893b --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-4.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/annotations-5.png b/spec/src/main/asciidoc/images/annotations-5.png new file mode 100644 index 0000000..ef59b76 --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-5.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/annotations-6.png b/spec/src/main/asciidoc/images/annotations-6.png new file mode 100644 index 0000000..ae10fab --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-6.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/annotations-7.png b/spec/src/main/asciidoc/images/annotations-7.png new file mode 100644 index 0000000..191893b --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-7.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/annotations-8.png b/spec/src/main/asciidoc/images/annotations-8.png new file mode 100644 index 0000000..ef59b76 --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-8.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/annotations-9.png b/spec/src/main/asciidoc/images/annotations-9.png new file mode 100644 index 0000000..ae10fab --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-9.png Binary files differ
diff --git a/spec/src/main/asciidoc/spec.adoc b/spec/src/main/asciidoc/spec.adoc new file mode 100644 index 0000000..1fe3753 --- /dev/null +++ b/spec/src/main/asciidoc/spec.adoc
@@ -0,0 +1,1921 @@ +== Jakarta Annotations Specification, Version 1.3 + +Copyright (c) 2016, 2019 Oracle and/or its affiliates. All rights reserved. + +Oracle and Java are registered trademarks of Oracle and/or its +affiliates. Other names may be trademarks of their respective owners. + +=== + +image:annotations-3.png[image] + +Introduction + +image:annotations-4.png[image] + +With the addition of JSR 175 (A Metadata +Facility for the JavaTM Programming Language) in the Java platform we +envision that various technologies will use annotations to enable a +declarative style of programming. It would be unfortunate if these +technologies each independently defined their own annotations for common +concepts. It would be valuable to have consistency within the Java EE +and Java SE component technologies, but it will also be valuable to +allow consistency between Java EE and Java SE. + +It is the intention of this specification to +define a small set of common annotations that will be available for use +within other specifications. It is hoped that this will help to avoid +unnecessary redundancy or duplication between annotations defined in +different Java Specification Requests (JSR). This would allow us to have +the common annotations all in one place and let the technologies refer +to this specification rather than have them specified in multiple +specifications. This way all technologies can use the same version of +the annotations and there will be consistency in the annotations used +across the platforms. + +=== + +image:annotations-5.png[image] + +Goals + +Define annotations for use in Java EE: This +JSR will define annotations for use within component technologies in +Java EE as well as the platform as a whole. + +Define annotations for use in future revisions +of Java SE: This JSR will define annotations for use in JSRs targeted +for Java SE as well as future revisions of Java SE. + + + +=== + +image:annotations-5.png[image] + +Non-Goals + +Support for Java versions prior to J2SE 5.0 + +Annotations were introduced in J2SE 5.0. It +is not possible to do annotation processing in versions prior to J2SE +5.0. It is not a goal of this specification to define a way of doing +annotation processing of any kind for versions prior to J2SE 5.0. + +=== + +image:annotations-5.png[image] + +Compatibility + +The annotations defined in this specification +may be included individually as needed in products that make use of +them. Other Java specifications will require support for subsets of +these annotations. Products that support these Java specifications must +include the required annotations. + +=== + +image:annotations-5.png[image] + +Conventions + +The keywords ‘MUST’, ‘MUST NOT’, ‘REQUIRED’, +‘SHALL’, ‘SHALL NOT’, ‘SHOULD’, ‘SHOULD NOT’, ‘RECOMMENDED’, ‘MAY’ AND +‘OPTIONAL’ in this document are to be interpreted as described in RFC +2119. + + + +Java code is formatted as shown below in +figure 1.1: + +Figure 1.1 Example Java code + +package com.wombat.hello; + +public class Hello \{ + + public static void main(String[] args) \{ + + System.out.println("Hello world"); + + } + +} + +=== + +image:annotations-5.png[image] + +Expert Group Members + +The following expert group members +participated in JSR 250: + +Cedric Beust (individual) + +Bill Burke (JBoss) + +Wayne Carr (Intel) + +Robert Clevenger (Oracle) + +Evan Ireland (Sybase) + +Woo Jin Kim (Tmax Soft) + +Gavin King (JBoss) + +Rajiv Mordani (Oracle Corporation, +Specification lead) + +Ted Neward (individual) + +Anurag Parashar (Pramati technologies) + +Michael Santos (individual) + +Hani Suleiman (Ironflare AB) + +Seth White (BEA) + +=== + +image:annotations-5.png[image] + +Acknowledgements + +In addition to the expert group listed above, +Linda DeMichiel, Ron Monzillo, Lance Andersen and Bill Shannon all of +whom work at Oracle Corporation have provided input to this +specification. + + + +=== + +=== + +image:annotations-6.png[image] + +Annotations + +image:annotations-7.png[image] + +This chapter describes the standard +annotations, some guidelines for annotation inheritance and the usage of +these annotations where possible. + +=== + +image:annotations-8.png[image] + +General Guidelines for Inheritance of Annotations + +The interplay of annotations and inheritance +in the Java language is potentially a source of complexity for +developers. Developers will rely on some implicit assumptions when +figuring out how annotations compose with other language features. At +the same time, annotation semantics are defined by individual +specifications, hence the potential for inconsistencies to arise. For +instance, consider the following example: + + + +public class Base \{ + + @TransactionAttribute(REQUIRES_NEW) + + public void foo \{...} + +} + +@Stateless + +public class Derived extends Base \{ + + @TransactionAttribute(NEVER) + + public void foo \{...} + +} + + + +In keeping with the concept of method +overriding, most developers will assume that in the _Derived_ class, the +effective _TransactionAttribute_ annotation for method _foo_ is +_TransactionAttribute(NEVER)_ . On the other hand, it might have been +possible for the specification governing the semantics of the +_TransactionAttribute_ annotations type to require that the effective +_TransactionAttribute_ to be the most restrictive one in the whole +inheritance tree, that is, in the example above +_TransactionAttribute(REQUIRES_NEW)_ . A motivation for these semantics +might have been that the _foo_ method in the _Derived_ class may call +_super.foo()_ , resulting in the execution of some code that needs a +transaction to be in place. Such a choice on the part of the +specification for _TransactionAttribute_ would have contradicted a +developer’s intuition on how method overriding works. + +In order to keep the resulting complexity in +control, below are some guidelines recommended for how annotations +defined in the different specifications should interact with +inheritance: + + Class-level annotations only affect the +class they annotate and its members, that is, its methods and fields. +They never affect a member declared by a superclass, even if it is not +hidden or overridden by the class in question. + +In addition to affecting the annotated class, +class-level annotations may act as a shorthand for member-level +annotations. If a member carries a specific member-level annotation, any +annotations of the same type implied by a class-level annotation are +ignored. In other words, explicit member-level annotations have priority +over member-level annotations implied by a class-level annotation. For +example, a _TransactionAttribute(REQUIRED)_ annotation on a class +implies that all the public methods in the class that it is applied on +are annotated with _TransactionAttribute(REQUIRED)_ . However if there +is a _TransactionAttribute(NEVER)_ annotation on a particular method, +then the _TransactionAttribute(NEVER)_ applies for that particular +method and not _TransactionAttribute(REQUIRED)_ . + +The interfaces implemented by a class never +contribute annotations to the class itself or any of its members. + +Members inherited from a superclass and which +are not hidden or overridden maintain the annotations they had in the +class that declared them, including member-level annotations implied by +class-level ones. + +Member-level annotations on a hidden or +overridden member are always ignored. + +This set of guidelines guarantees that the +effects of an annotation are local to the class on, or inside, which it +appears. In order to find the effective annotation for a class member, a +developer has to track down its last non-hidden and non-overridden +declaration and examine it. If the sought-for annotation is not found +there, then (s)he will have to examine the enclosing class declaration. +If even this step fails to provide an annotation, no other source file +will be consulted. + +Below are some examples that explain how the +guidelines defined above will be applied to the _TransactionAttribute_ +annotation. + + + +@TransactionAttribute(REQUIRED) + +class Base \{ + + @TransactionAttribute(NEVER) + + public void foo() \{...} + + public void bar() \{...} + +} + + + +@Stateless + +class ABean extends Base \{ + + public void foo() \{...} + +} + + + +@Stateless + +public class BBean extends Base \{ + + @TransactionAttribute(REQUIRES_NEW) + + public void foo() \{...} + +} + + + +@Stateless + +@TransactionAttribute(REQUIRES_NEW) + +public class CBean extends Base \{ + + public void foo() \{...} + + public void bar() \{...} + +} + + + +@Stateless + +@TransactionAttribute(REQUIRES_NEW) + +public class DBean extends Base \{ + + public void bar() \{...} + +} + + + +@Stateless + +@TransactionAttribute(REQUIRES_NEW) + +public class EBean extends Base \{ + +} + + + +The table below shows the effective +_TransactionAttribute_ annotation in each of the cases above by applying +the guidelines specified for annotations and inheritance: + + + + + +=== + +Methods in derived classes + +Effective TransactionAttribute value + + _foo() in ABean_ + + _TransactionAttribute(REQUIRED). (Default +TransactionAttribute as defined by the EJB specification)._ + + _bar() in ABean_ + + _TransactionAttribute(REQUIRED)_ + + _foo() in BBean_ + + _TransactionAttribute(REQUIRES_NEW)_ + + _bar() in BBean_ + + _TransactionAttribute(REQUIRED)_ + + _foo() in CBean_ + + _TransactionAttribute(REQUIRES_NEW)_ + + _bar() in CBean_ + + _TransactionAttribute(REQUIRES_NEW)_ + + _foo() in DBean_ + + _TransactionAttribute(NEVER) (from the Base +class)_ + + _bar() in DBean_ + + _TransactionAttribute(REQUIRES_NEW)_ + + _foo() in EBean_ + + _TransactionAttribute(NEVER) (From Base +class)_ + + __ + + _bar() in EBean_ + + _TransactionAttribute(REQUIRED)(from Base +class)_ + +For more details about the +_TransactionAttribute_ annotation, see the _EJB 3 Core Contracts_ +specification. + +All annotations defined in this specification +follow the guidelines defined above unless explicitly stated otherwise. + +=== + +image:annotations-8.png[image] + +javax.annotation.Generated + +The _Generated_ annotation is used to mark +source code that has been generated. It can be specified on a class, +method, or field. It can also be used to differentiate user-written code +from generated code in a single file. + +The _value_ element MUST have the name of the +code generator. The recommended convention is to use the fully qualified +name of the code generator. For example: _com.company.package.classname_ +. + +The _date_ element is used to indicate the +date the source was generated. The _date_ element MUST follow the ISO +8601 standard. For example the _date_ element could have the following +value: + + _2001-07-04T12:08:56.235-0700_ + +which represents 2001-07-04 12:08:56 local +time in the U.S. Pacific time zone. + +The _comments_ element is a place holder for +any comments that the code generator may want to include in the +generated code. + + + +package javax.annotation; + +import static +java.lang.annotation.ElementType.*; + +import static +java.lang.annotation.RetentionPolicy.*; + +@Target(\{ANNOTATION_TYPE, CONSTRUCTOR, +FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE}) + +@Retention(SOURCE) + +public @interface Generated \{ + + String[] value(); + + String date() default ""; + + String comments() default ""; + +} + + + +=== + +Element + +Description + +Default + + _value_ + +Name of the code generator + + + + _date_ + +Date source was generated. MUST follow ISO +8601 standard + +"" + + _comments_ + +placeholder for comments that the generator +may want to include in the generated code + +"" + + + +The following example shows the usage of the +annotation defined above: + + + +@Generated("com.sun.xml.rpc.AProcessor") + +public interface StockQuoteService extends +java.rmi.Remote \{ + + this.context = context; + +} + + + +=== + +image:annotations-8.png[image] + +javax.annotation.Resource + +The _Resource_ annotation is used to declare +a reference to a resource. It can be specified on a class, method, or +field. When the annotation is applied on a field or method, the +container will inject an instance of the requested resource into the +application when the application is initialized. If the annotation is +applied to a class, the annotation declares a resource that the +application will look up at runtime. Even though this annotation is not +marked _Inherited_ , all superclasses MUST be examined to discover all +uses of this annotation. All such annotation instances specify resources +that are needed by the application. Note that this annotation may appear +on private fields and methods of superclasses. Injection of the declared +resources needs to happen in these cases as well, even if a method with +such an annotation is overridden by a subclass. + +The _name_ element is the JNDI name of the +resource. When the _Resource_ annotation is applied on a field, the +default value of the _name_ element is the field name qualified by the +class name. When applied on a method, the default is the JavaBeans +property name corresponding to the method qualified by the class name. +When applied on a class, there is no default and the name MUST be +specified. + +The _type_ element defines the Java type of +the resource. When the _Resource_ annotation is applied on a field, the +default value of the _type_ element is the type of the field. When +applied on a method, the default is the type of the JavaBeans property. +When applied on a class, there is no default and the type MUST be +specified. When used, the type MUST be assignment compatible. + +The _authenticationType_ element is used to +indicate the authentication type to use for the resource. It can take +one of two values defined as an _Enum_ : _CONTAINER_ or _APPLICATION_ . +This element may be specified for resources representing a connection +factory of any supported type and MUST NOT be specified for resources of +other types. + +The _shareable_ element is used to indicate +whether a resource can be shared between this component and other +components. This element may be specified for resources representing a +connection factory of any supported type or ORB object instances and +MUST NOT be specified for resources of other types. + +The _mappedName_ element is a +product-specific name that this resource should be mapped to. The +_mappedName_ element provides for mapping the resource reference +specified by the _Resource_ annotation to the name of a resource known +to the application server. The mapped name could be of any form. +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 +mapped name is portable. + +The _description_ element is the description +of the 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 help in choosing the correct resource. + +The _lookup_ element specifies the JNDI name +of a resource that the resource being defined will be bound to. The type +of the referenced resource must be compatible with that of the resource +being defined. + + + +package javax.annotation; + +import static +java.lang.annotation.ElementType.*; + +import static +java.lang.annotation.RetentionPolicy.*; + +@Target(\{TYPE, METHOD, FIELD}) + +@Retention(RUNTIME) + +@Repeatable(Resources.class) + +public @interface Resource \{ + + public enum AuthenticationType \{ + + CONTAINER, + + APPLICATION + + } + + String name() default ""; + + Class<?> type() default Object.class; + + AuthenticationType authenticationType() +default AuthenticationType.CONTAINER; + + boolean shareable() default true; + + String mappedName() default ""; + + String description() default ""; + + String lookup() default ""; + +} + + + +=== + +Element + +Description + +Default + + _name_ + +The JNDI name of the resource + + _""_ + + _type_ + +The Java type of the resource + + _Object.class_ + + _authenticationType_ + +The authentication type to use for the +resource + + _CONTAINER_ + + _shareable_ + +Indicates whether the resource can be shared. + + _true_ + + _mappedName_ + +A product-specific name that the resource +should map to. + + _""_ + + _description_ + +Description of the resource. + + _""_ + + _lookup_ + +the JNDI name of a resource that the resource +being defined will be bound to + + _""_ + +=== Field based injection: + +To access a resource a developer declares a +field and annotates it as being a resource reference. If the name and +type elements are missing from the annotation they will be inferred by +looking at the field declaration itself. It is an error if the type +specified by the _Resource_ annotation and the type of the field are +incompatible. + +For example: + + + +@Resource + +private DataSource myDB; + +In the example above the effective name is +_com.example.class/myDB_ and the effective type is +_javax.sql.DataSource.class_ . + + + +@Resource(name="customerDB") + +private DataSource myDB; + +In the example above the name is _customerDB_ +and the effective type is _javax.sql.DataSource.class_ . + +=== Setter based injection: + +To access a resource a developer declares a +setter method and annotates it as being a resource reference. The name +and type of resource may be inferred by inspecting the method +declaration if necessary. The name of the resource, if not declared, is +the name of the JavaBeans property as determined from the name of the +setter method. The setter method MUST follow the standard JavaBeans +convention—the name starts with “ _set_ ”; the return type is _void_ ; +and there is only one parameter. Additionally, the type of the parameter +MUST be compatible with the _type_ element of the _Resource_ annotation, +if specified. + +For example: + + + +@Resource + +private void setMyDB(DataSource ds) \{ + + myDB = ds; + +} + +private DataSource myDB; + +In the example above the effective name is +_com.example.class/myDB_ and the type is _javax.sql.DataSource.class_ . + + + +@Resource(name="customerDB") + +private void setMyDB(DataSource ds) \{ + + myDB = ds; + +} + +private DataSource myDB; + + + +In the example above the name is _customerDB_ +and the type is _javax.sql.DataSource.class_ . + +The table below shows the mapping from Java +type to the equivalent resource type in the Java EE 5 (and later) +deployment descriptors: + + + +=== + +[width="100%",cols="50%,50%",options="header",] +|=== +|Java Type +|Equivalent Resource type +|java.lang.String +|env-entry + +|java.lang.Character +|env-entry + +|java.lang.Integer +|env-entry + +|java.lang.Boolean +|env-entry + +|java.lang.Double +|env-entry + +|java.lang.Byte +|env-entry + +|java.lang.Short +|env-entry + +|java.lang.Long +|env-entry + +|java.lang.Float +|env-entry + +|javax.xml.rpc.Service +|service-ref + +|javax.xml.ws.Service +|service-ref + +|javax.jws.WebService +|service-ref + +|javax.sql.DataSource +|resource-ref + +|javax.jms.ConnectionFactory +|resource-ref + +|javax.jms.QueueConnectionFactory +|resource-ref + +|javax.jms.TopicConnectionFactory +|resource-ref + +|javax.mail.Session +|resource-ref + +|java.net.URL +|resource-ref + +|javax.resource.cci.ConnectionFactory +|resource-ref + +|org.omg.CORBA_2_3.ORB +|resource-ref + +|any other connection factory defined by a +resource adapter |resource-ref + +|javax.jms.Queue +|message-destination-ref + +|javax.jms.Topic +|message-destination-ref + +|javax.resource.cci.InteractionSpec +|resource-env-ref + +|javax.transaction.UserTransaction +|resource-env-ref + +|Everything else +|resource-env-ref +|=== + + + +=== + +image:annotations-8.png[image] + +javax.annotation.Resources + +The _Resource_ annotation is used to declare +a reference to a resource. The _Resources_ annotation acts as a +container for multiple resource declarations. + + + +package javax.annotation; + +import static +java.lang.annotation.ElementType.*; + +import static +java.lang.annotation.RetentionPolicy.*; + +@Target(\{TYPE}) + +@Retention(RUNTIME) + +public @interface Resources \{ + + Resource[] value; + +} + +=== + +Element + +Description + +Default + + _value_ + +Container for defining multiple resources. + + + + + +The following example shows the usage of the +annotation defined above: + +@Resources (\{ + + @Resource(name="myDB" +type=javax.sql.DataSource), + + @Resource(name="myMQ" +type=javax.jms.ConnectionFactory) + +}) + +public class CalculatorBean \{ + + //... + +} + +=== + +image:annotations-8.png[image] + +javax.annotation.PostConstruct + +The _PostConstruct_ annotation is used on a +method that needs to be executed after dependency injection is done to +perform any initialization. This method MUST be invoked before the class +is put into service. This annotation MUST be supported on all classes +that support dependency injection. The method annotated with +_PostConstruct_ MUST be invoked even if the class does not request any +resources to be injected. Only one method in a given class can be +annotated with this annotation. The method on which the _PostConstruct_ +annotation is applied MUST fulfill all of the following requirements, +except in cases where these requirements have been relaxed by another +specification. See in particular the _Interceptors_ specification. + +- The method MUST NOT have any para meters. + +- The return type of the method MUST be +_void_ . + +- The method MUST NOT throw a checked +exception. + +- The method on which _PostConstruct_ is +applied MAY be _public_ , _protected_ , package private or _private_ . + +- The method MUST NOT be static except for +the application client. + +- In general, the method MUST NOT be final. +However, other specifications are permitted to relax this requirement on +a per-component basis. + +- If the method throws an unchecked exception +the class MUST NOT be put into service. + + + +package javax.annotation; + +import static +java.lang.annotation.ElementType.*; + +import static +java.lang.annotation.RetentionPolicy.*; + +@Target(METHOD) + +@Retention(RUNTIME) + +public @interface PostConstruct \{ + +} + + + +The following example shows the usage of the +annotation defined above: + +@Resource + +private void setMyDB(DataSource ds) \{ + + myDB = ds; + +} + + + +@PostConstruct + +private void initialize() \{ + + //Initialize the connection object from the +DataSource + + connection = myDB.getConnection(); + +} + + + +private DataSource myDB; + +private Connection connection; + + + +=== + +image:annotations-8.png[image] + +javax.annotation.PreDestroy + +The _PreDestroy_ annotation is used on a +method as a callback notification to signal that the instance is in the +process of being removed by the container. The method annotated with +_PreDestroy_ is typically used to release resources that the instance +has been holding. This annotation MUST be supported by all container +managed objects that support _PostConstruct_ except the application +client. The method on which the _PreDestroy_ annotation is applied MUST +fulfill all of the following requirements, except in cases where these +requirements have been relaxed by another specification. See in +particular the _Interceptors_ specification. + + + +- The method MUST NOT have any para meters. + +- The return type of the method MUST be +_void_ . + +- The method MUST NOT throw a checked +exception. + +- The method on which _PreDestroy_ is applied +MAY be _public_ , _protected_ , package private or _private_ . + +- The method MUST NOT be static. + +- In general, the method MUST NOT be final. +However, other specifications are permitted to relax this requirement on +a per-component basis. + +- If the method throws an unchecked exception +it is ignored. + + + +package javax.annotation; + +import static +java.lang.annotation.ElementType.*; + +import static +java.lang.annotation.RetentionPolicy.*; + +@Target(METHOD) + +@Retention(RUNTIME) + +public @interface PreDestroy \{ + +} + + + +The following example shows the usage of the +annotation defined above: + + + +@Resource + +private void setMyDB(DataSource ds) \{ + + myDB = ds; + +} + + + +@PostConstruct + +private void initialize() \{ + + //Initialize the connection object from the +DataSource + + connection = myDB.getConnection(); + +} + +@PreDestroy + +private void cleanup() \{ + + //Close the connection to the DataSource. + + connection.close(); + +} + + + +private DataSource myDB; + +private Connection connection; + +=== + +image:annotations-8.png[image] + +javax.annotation.Priority + +The _Priority_ annotation can be applied to +classes or parameters to indicate in what order they should be used. The +effect of using the _Priority_ annotation in any particular instance is +defined by other specifications that define the use of a specific class. + +For example, the _Interceptors_ specification +defines the use of priorities on interceptors to control the order in +which interceptors are called. + +Priority values should generally be +non-negative, with negative values reserved for special meanings such as +“undefined” or “not specified”. A specification that defines use of the +_Priority_ annotation may define the range of allowed priorities and any +priority values with special meaning. + + + +package javax.annotation; + +import java.lang.annotation.*; + +import static +java.lang.annotation.ElementType.*; + +import static +java.lang.annotation.RetentionPolicy.*; + + + +@Target(\{TYPE, PARAMETER}) + +@Retention(RUNTIME) + +@Documented + +public @interface Priority \{ + + /** + + * The priority value. + + */ + + int value(); + +} + + + +=== + +image:annotations-8.png[image] + +javax.annotation.security.RunAs + +The _RunAs_ annotation defines the security +role of the application during execution in a Java EE container. It can +be specified on a class. This allows developers to execute an +application under a particular role. The role MUST map to the user / +group information in the container’s security realm. The _value_ element +in the annotation is the name of a security role. + + + +package javax.annotation.security; + +import static +java.lang.annotation.ElementType.*; + +import static +java.lang.annotation.RetentionPolicy.*; + +@Target(TYPE) + +@Retention(RUNTIME) + +public @interface RunAs \{ + + String value(); + +} + + + +=== + +Element + +Description + +Default + + _value_ + +Security role of the application during +execution in a Java EE container + + + + + +The following example shows the usage of the +annotation defined above: + +@RunAs("Admin") + +public class Calculator \{ + + //.... + +} + +=== + +image:annotations-8.png[image] + +javax.annotation.security.RolesAllowed + +The _RolesAllowed_ annotation specifies the +security roles permitted to access method(s) in an application. The +value element of the _RolesAllowed_ annotation is a list of security +role names. + +The _RolesAllowed_ annotation can be +specified on a class or on method(s). Specifying it at a class level +means that it applies to all the methods in the class. Specifying it on +a method means that it is applicable to that method only. If applied at +both the class and method level, the method value overrides the class +value. + + + +package javax.annotation.security; + +import static +java.lang.annotation.ElementType.*; + +import static +java.lang.annotation.RetentionPolicy.*; + +@Target(\{TYPE,METHOD}) + +@Retention(RUNTIME) + +public @interface RolesAllowed \{ + + String[] value(); + +} + + + +=== + +Element + +Description + +Default + + _value_ + +List of roles permitted to access methods in +the application + + + + + +The following example shows the usage of the +annotation defined above: + +@RolesAllowed("Users") + +public class Calculator \{ + + @RolesAllowed("Administrator") + + public void setNewRate(int rate) \{ + + //... + +} + +=== + +image:annotations-8.png[image] + +javax.annotation.security.PermitAll + +The _PermitAll_ annotation specifies that all +security roles are allowed to invoke the specified method(s), that is, +that the specified method(s) are “unchecked”. It can be specified on a +class or on methods. Specifying it on the class means that it applies to +all methods of the class. If specified at the method level, it only +affects that method. + + + +package javax.annotation.security; + +import static +java.lang.annotation.ElementType.*; + +import static +java.lang.annotation.RetentionPolicy.*; + +@Target(\{TYPE,METHOD}) + +@Retention(RUNTIME) + +public @interface PermitAll \{ + +} + +The following example shows the usage of the +annotation defined above: + +import javax.annotation.security.*; + +@RolesAllowed("Users") + +public class Calculator \{ + + @RolesAllowed("Administrator") + + public void setNewRate(int rate) \{ + + //... + + } + + @PermitAll + + public long convertCurrency(long amount) \{ + + //... + + } + +} + + + +=== + +image:annotations-8.png[image] + +javax.annotation.security.DenyAll + +The _DenyAll_ annotation specifies that no +security roles are allowed to invoke the specified method(s), that is, +that the method(s) are to be excluded from execution in the Java EE +container. + + + +package javax.annotation.security; + +import static +java.lang.annotation.ElementType.*; + +import static +java.lang.annotation.RetentionPolicy.*; + +@Target(\{TYPE, METHOD}) + +@Retention(RUNTIME) + +public @interface DenyAll \{ + +} + +The following example shows the usage of the +annotation defined above: + +import javax.annotation.security.*; + +@RolesAllowed("Users") + +public class Calculator \{ + + @RolesAllowed("Administrator") + + public void setNewRate(int rate) \{ + + //... + + } + + @DenyAll + + public long convertCurrency(long amount) \{ + + //... + + } + +} + +=== + +image:annotations-8.png[image] + +PermitAll, DenyAll and RolesAllowed interactions + +The _PermitAll_ , _DenyAll_ and +_RolesAllowed_ annotations all define which security roles are allowed +to access the methods on which they are applied. This section describes +how these annotations interact and which usages of these annotations are +valid. + +If the _PermitAll_ , _DenyAll_ and +_RolesAllowed_ annotations are applied on methods of a class, then the +method level annotations take precedence (at the corresponding methods) +over any class level annotations of type _PermitAll_ , _DenyAll_ and +_RolesAllowed_ . + +=== + +image:annotations-8.png[image] + +javax.annotation.security.DeclareRoles + +The _DeclareRoles_ annotation is used to +specify security roles used by the application. It can be specified on a +class. It typically would be used to define roles that could be tested +(i.e., by calling _isUserInRole_ ) from within the methods of the +annotated class. It could also be used to declare roles that are not +implicitly declared as the result of their use in a _RolesAllowed_ +annotation on the class or a method of the class. + + + +package javax.annotation.security; + +import static +java.lang.annotation.ElementType.*; + +import static +java.lang.annotation.RetentionPolicy.*; + +@Target(TYPE) + +@Retention(RUNTIME) + +public @interface DeclareRoles\{ + + String[] value(); + +} + + + +=== + +Element + +Description + +Default + + _value_ + +List of security roles specified by the +application + + + + + +The following example shows the usage of the +annotation defined above: + +@DeclareRoles("BusinessAdmin") + +public class Calculator \{ + + public void convertCurrency() \{ + + if(x.isUserInRole("BusinessAdmin")) \{ + + //.... + + } + + } + + //... + +} + + + +=== + +image:annotations-8.png[image] + +javax.annotation.sql.DataSourceDefinition + +The _DataSourceDefinition_ annotation is used +to define a container _DataSource_ to be registered with JNDI. The +_DataSource_ may be configured by setting the annotation elements for +commonly-used _DataSource_ properties. Additional standard and +vendor-specific properties may be specified using the _properties_ +element. The data source will be registered under the name specified in +the _name_ element. It may be defined to be in any valid Java EE +namespace, which will determine the accessibility of the data source +from other components. A JDBC driver implementation class of the +appropriate type, either _DataSource_ , _ConnectionPoolDataSource_ , or +_XADataSource_ , must be indicated by the _className_ element. The +driver class is not required to be available at deployment but must be +available at runtime prior to any attempt to access the _DataSource_ . + + _DataSource_ properties should not be +specified more than once. If the _url_ annotation element contains a +_DataSource_ property that was also specified using the corresponding +annotation element or was specified in the _properties_ annotation +element, the precedence order is undefined and implementation specific. + +Vendors are not required to support +_properties_ that do not normally apply to a specific data source type. +For example, specifying the _transactional_ property to be _true_ but +supplying a value for _className_ that implements a data source class +other than _XADataSource_ may not be supported. + +Vendor-specific properties may be combined +with or used to override standard data source properties defined using +this annotation. + + _DataSource_ properties that are specified +and are not supported in a given configuration or cannot be mapped to a +vendor-specific configuration property may be ignored. + +Although the annotation allows you to specify +a password, it is recommended not to embed passwords in production code. +The _password_ element in the annotation is provided as a convenience +for ease of development. + + + +package javax.annotation.sql; + +import java.lang.annotation.Target; + +import java.lang.annotation.Retention; + +import java.lang.annotation.ElementType; + +import java.lang.annotation.RetentionPolicy; + +@Target(\{ElementType.TYPE}) + +@Retention(RetentionPolicy.RUNTIME) + +@Repeatable(DataSourceDefinitions.class) + +public @interface DataSourceDefinition \{ + + String name(); + + String className(); + + String description() default ""; + + String url() default ""; + + String user() default ""; + + String password() default ""; + + String databaseName() default ""; + + int portNumber() default -1; + + String serverName() default "localhost"; + + int isolationLevel() default -1; + + boolean transactional() default true; + + int initialPoolSize() default -1; + + int maxPoolSize() default -1; + + int minPoolSize() default -1; + + int maxIdleTime() default -1; + + int maxStatements() default -1; + + String[] properties() default \{}; + + int loginTimeout() default 0; + +} + + + +=== + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Element +|Description +|Default +| _name_ |JNDI +name by which the data source will be registered +| + +| _className_ +|DataSource implementation class name +| + +| _description_ +|Description of the data source +|"" + +| _url_ |A JDBC +URL. If the url annotation element contains a DataSource property that +was also specified using the corresponding annotation element, the +precedence order is undefined and implementation specific. +|"" + +| _user_ |User +name for connection authentications |"" + +| _password_ +|Password for connection authentications +|"" + +| _databaseName_ +|Name of a database on a server +|"" + +| _portNumber_ +|Port number where a server is listening for +requests |"" + +| _serverName_ +|Database server name +|"localhost" + +| _isolationLevel_ +|Isolation level for connections. +|-1 (vendor specific) + +| _transactional_ +|Indicates whether a connection is +transactional or not |true + +| _initialPoolSize_ +|Number of connections that should be created +when a connection pool is initialized |-1 +(vendor specific) + +| _maxPoolSize_ +|Maximum number of connections that should be +concurrently allocated for a connection pool +|-1 (vendor specific) + +| _minPoolSize_ +|Minimum number of connections that should be +allocated for a connection pool |-1 (vendor +specific) + +| _maxIdleTime_ +|The number of seconds that a physical +connection should remain unused in the pool before the connection is +closed for a connection pool |-1 (vendor +specific) + +| _maxStatements_ +|The total number of statements that a +connection pool should keep open. A value of 0 indicates that the +caching of statements is disabled for a connection pool +|-1 (vendor specific) + +| _properties_ +|Used to specify vendor-specific properties +and less commonly used _DataSource_ properties. If a _DataSource_ +property is specified in the properties element and the annotation +element for the property is also specified, the annotation element value +takes precedence. |\{} + +| _loginTimeout_ +|The maximum time in seconds that this data +source will wait while attempting to connect to a database. A value of 0 +specifies that the timeout is the default system timeout if there is +one, otherwise it specifies that there is no timeout +|0 +|=== + + + +Examples: + + + +@DataSourceDefinition(name="java:global/MyApp/MyDataSource", + + className="com.foobar.MyDataSource", + + portNumber=6689, + + serverName="myserver.com", + + user="lance", + + password="secret") + + + +Using a URL: + + + +@DataSourceDefinition(name="java:global/MyApp/MyDataSource", + + +className="org.apache.derby.jdbc.ClientDataSource", + + url="jdbc:derby://localhost:1527/myDB", + + user="lance", + + password="secret") + + + +=== + +image:annotations-8.png[image] + +javax.annotation.sql.DataSourceDefinitions + +The _DataSourceDefinition_ annotation is used +to declare a container _DataSource_ . The _DataSourceDefinitions_ +annotation acts as a container for multiple data source declarations. + + + +package javax.annotation.sql; + +import java.lang.annotation.Target; + +import java.lang.annotation.Retention; + +import java.lang.annotation.ElementType; + +import java.lang.annotation.RetentionPolicy; + +@Target(\{ElementType.TYPE}) + +@Retention(RetentionPolicy.RUNTIME) + +public @interface DataSourceDefinitions \{ + + DataSourceDefinition[] value (); + +} + + + +=== + +Element + +Description + +Default + + _value_ + +Container for defining multiple data sources. + + + + + +The following example shows the usage of the +annotation defined above: + +@DataSourceDefinitions (\{ + +@DataSourceDefinition(name="java:global/MyApp/MyDataSource", + + className="com.foobar.MyDataSource", + + portNumber=6689, + + serverName="myserver.com", + + user="lance", + + password="secret") + +@DataSourceDefinition(name="java:global/MyApp/MyDataSource", + + +className="org.apache.derby.jdbc.ClientDataSource", + + url="jdbc:derby://localhost:1527/myDB", + + user="lance", + + password="secret") + +}) + +public class CalculatorBean \{ + + //... + +} + +=== + +image:annotations-8.png[image] + +javax.annotation.ManagedBean + +The _ManagedBean_ annotation is used to +declare a Managed Bean as specified in the _Managed Beans_ +specification. Managed Beans are container-managed objects that support +a small set of basic services such as resource injection, lifecycle +callbacks and interceptors. A Managed Bean may optionally have a name, a +_String_ specified via the _value_ element. + + + +package javax.annotation; + +import static +java.lang.annotation.ElementType.*; + +import static +java.lang.annotation.RetentionPolicy.*; + +@Target(TYPE) + +@Retention(RUNTIME) + +public @interface ManagedBean \{ + + boolean value() default ""; + +} + +} + +=== + +Element + +Description + +Default + + _value_ + +Name of the Managed Bean + +"" + + + + + +Examples: + +@ManagedBean("cart") + +public class ShoppingCart \{ + +... + + + +} + +=== + +=== + +image:annotations-9.png[image] + +References + +image:annotations-10.png[image] + +JSR 175: A Metadata Facility for the Java +Programming Language. http://jcp.org/en/jsr/detail?id=175 + +Java Platform, Enterprise Edition, v7 (Java +EE). http://jcp.org/en/jsr/detail?id=342 + +Java 2 Platform, Standard Edition, v5.0 +(J2SE). http://java.sun.com/j2se + +Enterprise JavaBeans, v3.2 (EJB). +http://jcp.org/en/jsr/detail?id=345 + +Interceptors, 1.2. +http://jcp.org/en/jsr/detail?id=318 + +Managed Beans. +http://jcp.org/en/jsr/detail?id=316 + +RFC 2119. +http://www.faqs.org/rfcs/rfc2119.html
