0
# Jakarta Annotations
1

2
Jakarta Annotations defines a collection of annotations representing common semantic concepts that enable a declarative style of programming that applies across a variety of Java technologies. This API provides annotations for resource injection, lifecycle callbacks, security annotations, and generated code marking.
3

4
## Package Information
5

6
- **Package Name**: jakarta.annotation-api
7
- **Package Type**: maven
8
- **Group ID**: jakarta.annotation
9
- **Artifact ID**: jakarta.annotation-api
10
- **Language**: Java
11
- **Installation**: 
12
  ```xml
13
  <dependency>
14
      <groupId>jakarta.annotation</groupId>
15
      <artifactId>jakarta.annotation-api</artifactId>
16
      <version>3.0.0</version>
17
  </dependency>
18
  ```
19

20
## Core Imports
21

22
```java
23
import jakarta.annotation.*;
24
import jakarta.annotation.security.*;
25
import jakarta.annotation.sql.*;
26
```
27

28
For specific annotations:
29

30
```java
31
import jakarta.annotation.PostConstruct;
32
import jakarta.annotation.PreDestroy;
33
import jakarta.annotation.Resource;
34
import jakarta.annotation.security.RolesAllowed;
35
import jakarta.annotation.sql.DataSourceDefinition;
36
```
37

38
## Basic Usage
39

40
```java
41
import jakarta.annotation.*;
42
import jakarta.annotation.security.*;
43

44
@RolesAllowed({"admin", "user"})
45
public class UserService {
46
    
47
    @Resource(name = "jdbc/UserDB")
48
    private DataSource dataSource;
49
    
50
    @PostConstruct
51
    public void initialize() {
52
        // Initialization logic after dependency injection
53
        System.out.println("UserService initialized");
54
    }
55
    
56
    @PreDestroy
57
    public void cleanup() {
58
        // Cleanup logic before instance destruction
59
        System.out.println("UserService cleanup");
60
    }
61
    
62
    @RolesAllowed("admin")
63
    public void deleteUser(String userId) {
64
        // Admin-only operation
65
    }
66
    
67
    @PermitAll
68
    public List<User> getUsers() {
69
        // Public operation
70
        return userRepository.findAll();
71
    }
72
}
73
```
74

75
## Architecture
76

77
Jakarta Annotations provides three main functional areas:
78

79
- **Core Annotations** (`jakarta.annotation`): Lifecycle management, resource injection, nullability constraints, code generation markers, and priority ordering
80
- **Security Annotations** (`jakarta.annotation.security`): Declarative authorization and role-based access control for methods and classes
81
- **SQL Annotations** (`jakarta.annotation.sql`): Database DataSource configuration and JNDI registration
82

83
The annotations are designed to work across the Jakarta EE ecosystem, providing consistent behavior in application servers, dependency injection frameworks, and other Jakarta EE-compliant containers.
84

85
## Capabilities
86

87
### Core Annotations
88

89
Fundamental annotations for lifecycle management, resource injection, nullability, code generation, and priority ordering. These form the foundation for dependency injection and container-managed components.
90

91
```java { .api }
92
@PostConstruct
93
public void methodName() { }
94

95
@PreDestroy  
96
public void methodName() { }
97

98
@Resource(name = "resource/name")
99
private ResourceType resource;
100

101
@Generated(value = "com.example.Generator")
102
public class GeneratedClass { }
103

104
@Priority(100)
105
public class PriorityComponent { }
106

107
@Nonnull
108
public String nonNullMethod(@Nullable String param) { }
109
```
110

111
[Core Annotations](./core-annotations.md)
112

113
### Security Annotations
114

115
Declarative security annotations for role-based access control. These annotations enable method-level and class-level authorization without programmatic security checks.
116

117
```java { .api }
118
@RolesAllowed({"admin", "user"})
119
public class SecureService { }
120

121
@DenyAll
122
public void restrictedMethod() { }
123

124
@PermitAll  
125
public void publicMethod() { }
126

127
@RunAs("system")
128
public class SystemService { }
129

130
@DeclareRoles({"admin", "user", "guest"})
131
public class Application { }
132
```
133

134
[Security Annotations](./security-annotations.md)
135

136
### SQL DataSource Configuration
137

138
Annotations for defining and configuring database DataSources with JNDI registration. These annotations enable declarative database configuration without external configuration files.
139

140
```java { .api }
141
@DataSourceDefinition(
142
    name = "java:global/MyDataSource",
143
    className = "com.mysql.cj.jdbc.MysqlDataSource", 
144
    url = "jdbc:mysql://localhost:3306/mydb",
145
    user = "user",
146
    password = "password"
147
)
148
public class DatabaseConfig { }
149

150
@DataSourceDefinitions({
151
    @DataSourceDefinition(name = "java:global/DB1", className = "..."),
152
    @DataSourceDefinition(name = "java:global/DB2", className = "...")
153
})
154
public class MultiDatabaseConfig { }
155
```
156

157
[SQL Annotations](./sql-annotations.md)
158

159