Jakartified spec (#71)
Signed-off-by: Dmitry Kornilov <dmitry.kornilov@oracle.com>
diff --git a/spec/src/main/asciidoc/license-efsl.adoc b/spec/src/main/asciidoc/license-efsl.adoc
index ebc7070..2aa72e0 100644
--- a/spec/src/main/asciidoc/license-efsl.adoc
+++ b/spec/src/main/asciidoc/license-efsl.adoc
@@ -13,7 +13,7 @@
Release: {revdate}
....
-Copyright (c) 2019 Eclipse Foundation.
+Copyright (c) 2020 Eclipse Foundation.
=== Eclipse Foundation Specification License
diff --git a/spec/src/main/asciidoc/spec.adoc b/spec/src/main/asciidoc/spec.adoc
index 1fe3753..fca9e38 100644
--- a/spec/src/main/asciidoc/spec.adoc
+++ b/spec/src/main/asciidoc/spec.adoc
@@ -1,59 +1,32 @@
-== 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]
+== Introduction
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
+concepts. It would be valuable to have consistency within the Jakarta EE
and Java SE component technologies, but it will also be valuable to
-allow consistency between Java EE and Java SE.
+allow consistency between Jakarta 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
+different Jakarta EE specifications. 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.
-===
+=== Goals
-image:annotations-5.png[image]
+Define annotations for use in Jakarta EE: This
+spec will define annotations for use within component technologies in
+Jakarta EE as well as the platform as a whole.
-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
+=== Non-Goals
Support for Java versions prior to J2SE 5.0
@@ -62,11 +35,7 @@
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
+=== Compatibility
The annotations defined in this specification
may be included individually as needed in products that make use of
@@ -74,104 +43,59 @@
these annotations. Products that support these Java specifications must
include the required annotations.
-===
-
-image:annotations-5.png[image]
-
-Conventions
+=== 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:
-
-Java code is formatted as shown below in
-figure 1.1:
-
-Figure 1.1 Example Java code
-
+[source,java]
+----
package com.wombat.hello;
-public class Hello \{
-
- public static void main(String[] args) \{
-
- System.out.println("Hello world");
-
- }
-
+public class Hello {
+ public static void main(String[] args) {
+ System.out.println("Hello world");
+ }
}
+----
-===
-
-image:annotations-5.png[image]
-
-Expert Group Members
+=== Expert Group Members
The following expert group members
participated in JSR 250:
-Cedric Beust (individual)
+- 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)
-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
+=== 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]
+== Annotations
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
+=== General Guidelines for Inheritance of Annotations
The interplay of annotations and inheritance
in the Java language is potentially a source of complexity for
@@ -181,27 +105,19 @@
specifications, hence the potential for inconsistencies to arise. For
instance, consider the following example:
-
-
-public class Base \{
-
- @TransactionAttribute(REQUIRES_NEW)
-
- public void foo \{...}
-
+[source,java]
+----
+public class Base {
+ @TransactionAttribute(REQUIRES_NEW)
+ public void foo {...}
}
@Stateless
-
-public class Derived extends Base \{
-
- @TransactionAttribute(NEVER)
-
- public void foo \{...}
-
+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
@@ -223,12 +139,12 @@
defined in the different specifications should interact with
inheritance:
- Class-level annotations only affect the
+. 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,
+. 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
@@ -241,16 +157,15 @@
then the _TransactionAttribute(NEVER)_ applies for that particular
method and not _TransactionAttribute(REQUIRED)_ .
-The interfaces implemented by a class never
+. 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
+. 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.
+. 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
@@ -265,152 +180,82 @@
guidelines defined above will be applied to the _TransactionAttribute_
annotation.
-
-
+[source,java]
+----
@TransactionAttribute(REQUIRED)
+class Base {
+ @TransactionAttribute(NEVER)
+ public void foo() {...}
-class Base \{
-
- @TransactionAttribute(NEVER)
-
- public void foo() \{...}
-
- public void bar() \{...}
-
+ public void bar() {...}
}
-
-
@Stateless
-
-class ABean extends Base \{
-
- public void foo() \{...}
-
+class ABean extends Base {
+ public void foo() {...}
}
-
-
@Stateless
-
-public class BBean extends Base \{
-
- @TransactionAttribute(REQUIRES_NEW)
-
- public void foo() \{...}
-
+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() \{...}
-
+public class CBean extends Base {
+ public void foo() {...}
+ public void bar() {...}
}
-
-
@Stateless
-
@TransactionAttribute(REQUIRES_NEW)
-
-public class DBean extends Base \{
-
- public void bar() \{...}
-
+public class DBean extends Base {
+ public void bar() {...}
}
-
-
@Stateless
-
@TransactionAttribute(REQUIRES_NEW)
-
-public class EBean extends Base \{
-
+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 Base class)
+|bar() in DBean
+|TransactionAttribute(REQUIRES_NEW)
+|foo() in EBean
+|TransactionAttribute(NEVER) (from Base class)
+|bar() in EBean
+|TransactionAttribute(REQUIRED) (from Base class)
+|===
-
-
-
-===
-
-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_
+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
+=== jakarta.annotation.Generated
The _Generated_ annotation is used to mark
source code that has been generated. It can be specified on a class,
@@ -427,7 +272,7 @@
8601 standard. For example the _date_ element could have the following
value:
- _2001-07-04T12:08:56.235-0700_
+ 2001-07-04T12:08:56.235-0700
which represents 2001-07-04 12:08:56 local
time in the U.S. Pacific time zone.
@@ -436,84 +281,40 @@
any comments that the code generator may want to include in the
generated code.
+[source,java]
+----
+package jakarta.annotation;
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
-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})
-
+@Target({ANNOTATION_TYPE, CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
@Retention(SOURCE)
-
-public @interface Generated \{
-
- String[] value();
-
- String date() default "";
-
- String comments() default "";
-
+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:
-===
-
-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:
-
-
-
+[source,java]
+----
@Generated("com.sun.xml.rpc.AProcessor")
-
-public interface StockQuoteService extends
-java.rmi.Remote \{
-
- this.context = context;
-
+public interface StockQuoteService extends java.rmi.Remote {
+ this.context = context;
}
+----
-
-
-===
-
-image:annotations-8.png[image]
-
-javax.annotation.Resource
+=== jakarta.annotation.Resource
The _Resource_ annotation is used to declare
a reference to a resource. It can be specified on a class, method, or
@@ -577,105 +378,51 @@
of the referenced resource must be compatible with that of the resource
being defined.
+[source,java]
+----
+package jakarta.annotation;
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
-package javax.annotation;
-
-import static
-java.lang.annotation.ElementType.*;
-
-import static
-java.lang.annotation.RetentionPolicy.*;
-
-@Target(\{TYPE, METHOD, FIELD})
-
+@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
-
@Repeatable(Resources.class)
+public @interface Resource {
+ public enum AuthenticationType {
+ CONTAINER,
+ APPLICATION
+ }
-public @interface Resource \{
+ String name() default "";
- public enum AuthenticationType \{
+ Class<?> type() default Object.class;
- CONTAINER,
+ AuthenticationType authenticationType() default AuthenticationType.CONTAINER;
- APPLICATION
+ boolean shareable() default true;
- }
+ String mappedName() default "";
- String name() default "";
+ String description() default "";
- Class<?> type() default Object.class;
-
- AuthenticationType authenticationType()
-default AuthenticationType.CONTAINER;
-
- boolean shareable() default true;
-
- String mappedName() default "";
-
- String description() default "";
-
- String lookup() 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 |""
+|===
-===
-
-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:
+==== Field based injection
To access a resource a developer declares a
field and annotates it as being a resource reference. If the name and
@@ -686,26 +433,26 @@
For example:
-
-
+[source,java]
+----
@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_ .
-
-
+[source,java]
+----
@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:
+==== Setter based injection
To access a resource a developer declares a
setter method and annotates it as being a resource reference. The name
@@ -720,34 +467,28 @@
For example:
-
-
+[source,java]
+----
@Resource
-
-private void setMyDB(DataSource ds) \{
-
- myDB = ds;
-
+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_ .
-
-
+[source,java]
+----
@Resource(name="customerDB")
-
-private void setMyDB(DataSource ds) \{
-
- myDB = ds;
-
+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_ .
@@ -756,165 +497,77 @@
type to the equivalent resource type in the Java EE 5 (and later)
deployment descriptors:
-
-
-===
-
-[width="100%",cols="50%,50%",options="header",]
+[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
+|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
+|jakarta.xml.rpc.Service |service-ref
+|jakarta.xml.ws.Service |service-ref
+|jakarta.jws.WebService |service-ref
+|javax.sql.DataSource |resource-ref
+|jakarta.jms.ConnectionFactory |resource-ref
+|jakarta.jms.QueueConnectionFactory |resource-ref
+|jakarta.jms.TopicConnectionFactory |resource-ref
+|jakarta.mail.Session |resource-ref
+|java.net.URL |resource-ref
+|jakarta.resource.cci.ConnectionFactory |resource-ref
+|org.omg.CORBA_2_3.ORB |resource-ref
+|any other connection factory defined by a resource adapter |resource-ref
+|jakarta.jms.Queue |message-destination-ref
+|jakarta.jms.Topic |message-destination-ref
+|jakarta.resource.cci.InteractionSpec |resource-env-ref
+|jakarta.transaction.UserTransaction |resource-env-ref
+|Everything else |resource-env-ref
|===
-
-
-===
-
-image:annotations-8.png[image]
-
-javax.annotation.Resources
+=== jakarta.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.
+[source,java]
+----
+package jakarta.annotation;
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
-package javax.annotation;
-
-import static
-java.lang.annotation.ElementType.*;
-
-import static
-java.lang.annotation.RetentionPolicy.*;
-
-@Target(\{TYPE})
-
+@Target({TYPE})
@Retention(RUNTIME)
-
-public @interface Resources \{
-
- Resource[] value;
-
+public @interface Resources {
+ Resource[] value;
}
+----
-===
+|===
+|Element |Description |Default
+|value |Container for defining multiple resources. |
+|===
-Element
+The following example shows the usage of the annotation defined above:
-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)
-
+[source,java]
+----
+@Resources ({
+ @Resource(name="myDB", type=javax.sql.DataSource),
+ @Resource(name="myMQ", type=jakarta.jms.ConnectionFactory)
})
-public class CalculatorBean \{
-
- //...
-
+public class CalculatorBean {
+ // ...
}
+----
-===
-
-image:annotations-8.png[image]
-
-javax.annotation.PostConstruct
+=== jakarta.annotation.PostConstruct
The _PostConstruct_ annotation is used on a
method that needs to be executed after dependency injection is done to
@@ -930,82 +583,56 @@
- The method MUST NOT have any para meters.
-- The return type of the method MUST be
-_void_ .
+- The return type of the method MUST be _void_ .
-- The method MUST NOT throw a checked
-exception.
+- 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.
+- 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.
+- If the method throws an unchecked exception the class MUST NOT be put into service.
+[source,java]
+----
+package jakarta.annotation;
-
-package javax.annotation;
-
-import static
-java.lang.annotation.ElementType.*;
-
-import static
-java.lang.annotation.RetentionPolicy.*;
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
@Target(METHOD)
-
@Retention(RUNTIME)
-
-public @interface PostConstruct \{
+public @interface PostConstruct {
}
+----
+The following example shows the usage of the annotation defined above:
-
-The following example shows the usage of the
-annotation defined above:
-
+[source,java]
+----
@Resource
-
-private void setMyDB(DataSource ds) \{
-
- myDB = ds;
-
+private void setMyDB(DataSource ds) {
+ myDB = ds;
}
-
-
@PostConstruct
-
-private void initialize() \{
-
- //Initialize the connection object from the
-DataSource
-
- connection = myDB.getConnection();
-
+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
+=== jakarta.annotation.PreDestroy
The _PreDestroy_ annotation is used on a
method as a callback notification to signal that the instance is in the
@@ -1018,15 +645,11 @@
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 return type of the method MUST be _void_ .
-- The method MUST NOT throw a checked
-exception.
+- The method MUST NOT throw a checked exception.
- The method on which _PreDestroy_ is applied
MAY be _public_ , _protected_ , package private or _private_ .
@@ -1037,76 +660,48 @@
However, other specifications are permitted to relax this requirement on
a per-component basis.
-- If the method throws an unchecked exception
-it is ignored.
+- If the method throws an unchecked exception it is ignored.
+[source,java]
+----
+package jakarta.annotation;
-
-package javax.annotation;
-
-import static
-java.lang.annotation.ElementType.*;
-
-import static
-java.lang.annotation.RetentionPolicy.*;
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
@Target(METHOD)
-
@Retention(RUNTIME)
-
-public @interface PreDestroy \{
+public @interface PreDestroy {
}
+----
+The following example shows the usage of the annotation defined above:
-
-The following example shows the usage of the
-annotation defined above:
-
-
-
+[source,java]
+----
@Resource
-
-private void setMyDB(DataSource ds) \{
-
- myDB = ds;
-
+private void setMyDB(DataSource ds) {
+ myDB = ds;
}
-
-
@PostConstruct
-
-private void initialize() \{
-
- //Initialize the connection object from the
-DataSource
-
- connection = myDB.getConnection();
-
+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 void cleanup() {
+ // Close the connection to the DataSource.
+ connection.close();
}
-
-
private DataSource myDB;
-
private Connection connection;
+----
-===
-
-image:annotations-8.png[image]
-
-javax.annotation.Priority
+=== jakarta.annotation.Priority
The _Priority_ annotation can be applied to
classes or parameters to indicate in what order they should be used. The
@@ -1123,108 +718,62 @@
_Priority_ annotation may define the range of allowed priorities and any
priority values with special meaning.
-
-
-package javax.annotation;
+[source,java]
+----
+package jakarta.annotation;
import java.lang.annotation.*;
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
-import static
-java.lang.annotation.ElementType.*;
-
-import static
-java.lang.annotation.RetentionPolicy.*;
-
-
-
-@Target(\{TYPE, PARAMETER})
-
+@Target({TYPE, PARAMETER})
@Retention(RUNTIME)
-
@Documented
-
-public @interface Priority \{
-
- /**
-
- * The priority value.
-
- */
-
- int value();
-
+public @interface Priority {
+ // The priority value.
+ int value();
}
+----
-
-
-===
-
-image:annotations-8.png[image]
-
-javax.annotation.security.RunAs
+=== jakarta.annotation.security.RunAs
The _RunAs_ annotation defines the security
-role of the application during execution in a Java EE container. It can
+role of the application during execution in a Jakarta 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.
+[source,java]
+----
+package jakarta.annotation.security;
-
-package javax.annotation.security;
-
-import static
-java.lang.annotation.ElementType.*;
-
-import static
-java.lang.annotation.RetentionPolicy.*;
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
@Target(TYPE)
-
@Retention(RUNTIME)
-
-public @interface RunAs \{
-
- String value();
-
+public @interface RunAs {
+ String value();
}
+----
+|===
+|Element |Description |Default
+|value |Security role of the application during execution in a Jakarta EE container |
+|===
+The following example shows the usage of the annotation defined above:
-===
-
-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:
-
+[source,java]
+----
@RunAs("Admin")
-
-public class Calculator \{
-
- //....
-
+public class Calculator {
+ // ...
}
+----
-===
-
-image:annotations-8.png[image]
-
-javax.annotation.security.RolesAllowed
+=== jakarta.annotation.security.RolesAllowed
The _RolesAllowed_ annotation specifies the
security roles permitted to access method(s) in an application. The
@@ -1238,65 +787,39 @@
both the class and method level, the method value overrides the class
value.
+[source,java]
+----
+package jakarta.annotation.security;
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
-package javax.annotation.security;
-
-import static
-java.lang.annotation.ElementType.*;
-
-import static
-java.lang.annotation.RetentionPolicy.*;
-
-@Target(\{TYPE,METHOD})
-
+@Target({TYPE,METHOD})
@Retention(RUNTIME)
-
-public @interface RolesAllowed \{
-
- String[] value();
-
+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:
-===
-
-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:
-
+[source,java]
+----
@RolesAllowed("Users")
-
-public class Calculator \{
-
- @RolesAllowed("Administrator")
-
- public void setNewRate(int rate) \{
-
- //...
-
+public class Calculator {
+ @RolesAllowed("Administrator")
+ public void setNewRate(int rate) {
+ // ...
+ }
}
+----
-===
-
-image:annotations-8.png[image]
-
-javax.annotation.security.PermitAll
+=== jakarta.annotation.security.PermitAll
The _PermitAll_ annotation specifies that all
security roles are allowed to invoke the specified method(s), that is,
@@ -1305,114 +828,82 @@
all methods of the class. If specified at the method level, it only
affects that method.
+[source,java]
+----
+package jakarta.annotation.security;
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
-package javax.annotation.security;
-
-import static
-java.lang.annotation.ElementType.*;
-
-import static
-java.lang.annotation.RetentionPolicy.*;
-
-@Target(\{TYPE,METHOD})
-
+@Target({TYPE,METHOD})
@Retention(RUNTIME)
-
-public @interface PermitAll \{
+public @interface PermitAll {
}
+----
-The following example shows the usage of the
-annotation defined above:
+The following example shows the usage of the annotation defined above:
-import javax.annotation.security.*;
+[source,java]
+----
+import jakarta.annotation.security.*;
@RolesAllowed("Users")
+public class Calculator {
+ @RolesAllowed("Administrator")
+ public void setNewRate(int rate) {
+ // ...
+ }
-public class Calculator \{
-
- @RolesAllowed("Administrator")
-
- public void setNewRate(int rate) \{
-
- //...
-
- }
-
- @PermitAll
-
- public long convertCurrency(long amount) \{
-
- //...
-
- }
-
+ @PermitAll
+ public long convertCurrency(long amount) {
+ // ...
+ }
}
+----
-
-
-===
-
-image:annotations-8.png[image]
-
-javax.annotation.security.DenyAll
+=== jakarta.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
+that the method(s) are to be excluded from execution in the Jakarta EE
container.
+[source,java]
+----
+package jakarta.annotation.security;
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
-package javax.annotation.security;
-
-import static
-java.lang.annotation.ElementType.*;
-
-import static
-java.lang.annotation.RetentionPolicy.*;
-
-@Target(\{TYPE, METHOD})
-
+@Target({TYPE, METHOD})
@Retention(RUNTIME)
-
-public @interface DenyAll \{
+public @interface DenyAll {
}
+----
-The following example shows the usage of the
-annotation defined above:
+The following example shows the usage of the annotation defined above:
-import javax.annotation.security.*;
+[source,java]
+----
+import jakarta.annotation.security.*;
@RolesAllowed("Users")
+public class Calculator {
+ @RolesAllowed("Administrator")
+ public void setNewRate(int rate) {
+ // ...
+ }
-public class Calculator \{
-
- @RolesAllowed("Administrator")
-
- public void setNewRate(int rate) \{
-
- //...
-
- }
-
- @DenyAll
-
- public long convertCurrency(long amount) \{
-
- //...
-
- }
-
+ @DenyAll
+ public long convertCurrency(long amount) {
+ // ...
+ }
}
+----
-===
-
-image:annotations-8.png[image]
-
-PermitAll, DenyAll and RolesAllowed interactions
+=== PermitAll, DenyAll and RolesAllowed interactions
The _PermitAll_ , _DenyAll_ and
_RolesAllowed_ annotations all define which security roles are allowed
@@ -1426,11 +917,7 @@
over any class level annotations of type _PermitAll_ , _DenyAll_ and
_RolesAllowed_ .
-===
-
-image:annotations-8.png[image]
-
-javax.annotation.security.DeclareRoles
+=== jakarta.annotation.security.DeclareRoles
The _DeclareRoles_ annotation is used to
specify security roles used by the application. It can be specified on a
@@ -1440,73 +927,42 @@
implicitly declared as the result of their use in a _RolesAllowed_
annotation on the class or a method of the class.
+[source,java]
+----
+package jakarta.annotation.security;
-
-package javax.annotation.security;
-
-import static
-java.lang.annotation.ElementType.*;
-
-import static
-java.lang.annotation.RetentionPolicy.*;
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
@Target(TYPE)
-
@Retention(RUNTIME)
-
-public @interface DeclareRoles\{
-
- String[] value();
-
+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:
-===
-
-Element
-
-Description
-
-Default
-
- _value_
-
-List of security roles specified by the
-application
-
-
-
-
-
-The following example shows the usage of the
-annotation defined above:
-
+[source,java]
+----
@DeclareRoles("BusinessAdmin")
+public class Calculator {
+ public void convertCurrency() {
+ if (x.isUserInRole("BusinessAdmin")) {
+ // ...
+ }
+ }
-public class Calculator \{
-
- public void convertCurrency() \{
-
- if(x.isUserInRole("BusinessAdmin")) \{
-
- //....
-
- }
-
- }
-
- //...
-
+ // ...
}
+----
-
-
-===
-
-image:annotations-8.png[image]
-
-javax.annotation.sql.DataSourceDefinition
+=== jakarta.annotation.sql.DataSourceDefinition
The _DataSourceDefinition_ annotation is used
to define a container _DataSource_ to be registered with JNDI. The
@@ -1514,7 +970,7 @@
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
+the _name_ element. It may be defined to be in any valid Jakarta 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
@@ -1538,7 +994,7 @@
with or used to override standard data source properties defined using
this annotation.
- _DataSource_ properties that are specified
+_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.
@@ -1547,288 +1003,140 @@
The _password_ element in the annotation is provided as a convenience
for ease of development.
-
-
-package javax.annotation.sql;
+[source,java]
+----
+package jakarta.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})
-
+@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;
-
+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
+|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:
+[source,java]
+----
+@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="com.foobar.MyDataSource",
-
- portNumber=6689,
-
- serverName="myserver.com",
-
- user="lance",
-
- password="secret")
-
-
+----
Using a URL:
+[source,java]
+----
+@DataSourceDefinition(
+ name="java:global/MyApp/MyDataSource",
+ className="org.apache.derby.jdbc.ClientDataSource",
+ url="jdbc:derby://localhost:1527/myDB",
+ 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")
-
-
-
-===
-
-image:annotations-8.png[image]
-
-javax.annotation.sql.DataSourceDefinitions
+=== jakarta.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;
+[source,java]
+----
+package jakarta.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})
-
+@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
-
-public @interface DataSourceDefinitions \{
-
- DataSourceDefinition[] value ();
-
+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:
-===
+[source,java]
+----
+@DataSourceDefinitions ({
+ @DataSourceDefinition(name="java:global/MyApp/MyDataSource",
+ className="com.foobar.MyDataSource",
+ portNumber=6689,
+ serverName="myserver.com",
+ user="lance",
+ password="secret"),
-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")
-
+ @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 \{
-
- //...
-
+public class CalculatorBean {
+ // ...
}
+----
-===
-
-image:annotations-8.png[image]
-
-javax.annotation.ManagedBean
+=== jakarta.annotation.ManagedBean
The _ManagedBean_ annotation is used to
declare a Managed Bean as specified in the _Managed Beans_
@@ -1837,67 +1145,36 @@
callbacks and interceptors. A Managed Bean may optionally have a name, a
_String_ specified via the _value_ element.
+[source,java]
+----
+package jakarta.annotation;
-
-package javax.annotation;
-
-import static
-java.lang.annotation.ElementType.*;
-
-import static
-java.lang.annotation.RetentionPolicy.*;
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
@Target(TYPE)
-
@Retention(RUNTIME)
-
-public @interface ManagedBean \{
-
- boolean value() default "";
-
+public @interface ManagedBean {
+ boolean value() default "";
}
+----
-}
-
-===
-
-Element
-
-Description
-
-Default
-
- _value_
-
-Name of the Managed Bean
-
-""
-
-
-
-
+|===
+|Element |Description |Default
+|value |Name of the Managed Bean |""
+|===
Examples:
+[source,java]
+----
@ManagedBean("cart")
-
-public class ShoppingCart \{
-
-...
-
-
-
+public class ShoppingCart {
+ // ...
}
+----
-===
-
-===
-
-image:annotations-9.png[image]
-
-References
-
-image:annotations-10.png[image]
+== References
JSR 175: A Metadata Facility for the Java
Programming Language. http://jcp.org/en/jsr/detail?id=175
