Core Annotations

/**
 * Marks a method for post-construction callback.
 * The method is invoked after dependency injection is completed.
 * Only one method per class can be annotated with PostConstruct.
 * 
 * Method requirements:
 * - void return type
 * - no parameters (except InvocationContext for interceptors)
 * - can be any access modifier (public, protected, package-private, private)
 * - must not be static (except in application client)
 * - should not be final
 * - if method throws unchecked exception, class must not be put into service
 */
@Target(METHOD)
@Retention(RUNTIME)
public @interface PostConstruct {
}

import jakarta.annotation.PostConstruct;

public class EmailService {
    private ConnectionPool connectionPool;
    
    @PostConstruct
    public void initialize() {
        connectionPool = new ConnectionPool();
        connectionPool.start();
        System.out.println("Email service initialized");
    }
}

// Private method example
public class DatabaseService {
    @PostConstruct
    private void setupConnection() {
        // Initialization logic
    }
}

/**
 * Marks a method for pre-destruction callback.
 * The method is invoked before the instance is removed by the container.
 * Used to release resources or perform cleanup.
 * 
 * Method requirements:
 * - void return type
 * - no parameters (except InvocationContext for interceptors)
 * - can be any access modifier (public, protected, package-private, private)  
 * - must not be static
 * - should not be final
 * - if method throws unchecked exception, it is ignored by container
 */
@Target(METHOD)
@Retention(RUNTIME)
public @interface PreDestroy {
}

import jakarta.annotation.PreDestroy;

public class CacheService {
    private CacheManager cacheManager;
    
    @PreDestroy
    public void cleanup() {
        if (cacheManager != null) {
            cacheManager.shutdown();
            System.out.println("Cache service cleaned up");
        }
    }
}

/**
 * Marks a resource needed by the application.
 * Can be used for field injection, setter injection, or class-level declaration.
 */
@Target({TYPE, FIELD, METHOD})
@Retention(RUNTIME)
@Repeatable(Resources.class)
public @interface Resource {
    /**
     * JNDI name of the resource. Default is field name or JavaBeans property name.
     */
    String name() default "";
    
    /**
     * Resource reference lookup name (global JNDI names).
     */  
    String lookup() default "";
    
    /**
     * Java type of the resource.
     */
    Class<?> type() default Object.class;
    
    /**
     * Authentication type for the resource connection.
     */
    AuthenticationType authenticationType() default AuthenticationType.CONTAINER;
    
    /**
     * Whether the resource can be shared between components.
     */
    boolean shareable() default true;
    
    /**
     * Product-specific name for resource mapping (not portable).
     */
    String mappedName() default "";
    
    /**
     * Description of the resource.
     */
    String description() default "";
    
    /**
     * Authentication type enumeration.
     */
    public enum AuthenticationType {
        CONTAINER,   // Container manages authentication
        APPLICATION  // Application manages authentication
    }
}

import jakarta.annotation.Resource;

// Field injection
public class OrderService {
    @Resource(name = "jdbc/OrderDB")
    private DataSource dataSource;
    
    @Resource
    private EntityManager entityManager;  // Uses field name
    
    @Resource(lookup = "java:global/jms/OrderQueue")
    private Queue orderQueue;
}

// Method injection
public class PaymentService {
    private DataSource paymentDB;
    
    @Resource(name = "jdbc/PaymentDB")
    public void setPaymentDataSource(DataSource ds) {
        this.paymentDB = ds;
    }
}

// Class-level declaration
@Resource(name = "jdbc/AppDB", type = DataSource.class, 
         description = "Main application database")
public class Application {
}

/**
 * Container for multiple @Resource annotations.
 */
@Target(TYPE)
@Retention(RUNTIME)
public @interface Resources {
    /**
     * Array of Resource annotations.
     */
    Resource[] value();
}

import jakarta.annotation.Resources;
import jakarta.annotation.Resource;

@Resources({
    @Resource(name = "jdbc/UserDB", type = DataSource.class),
    @Resource(name = "jms/NotificationQueue", type = Queue.class),
    @Resource(name = "mail/Session", type = Session.class)
})
public class MultiResourceService {
}

/**
 * The annotated element must not be null.
 * Annotated fields must not be null after construction has completed.
 * When applied to a method, applies to the method return value.
 * 
 * No @Target specified - can be applied to any program element.
 */
@Documented
@Retention(RUNTIME)
public @interface Nonnull {
}

/**
 * The annotated element could be null under some circumstances.
 * Useful mostly for overriding a @Nonnull annotation.
 * When applied to a method, applies to the method return value.
 * 
 * No @Target specified - can be applied to any program element.
 */
@Documented
@Retention(RUNTIME)
public @interface Nullable {
}

import jakarta.annotation.Nonnull;
import jakarta.annotation.Nullable;

public class UserService {
    
    @Nonnull
    public User createUser(@Nonnull String name, @Nullable String email) {
        // Method guarantees non-null return
        // name parameter must not be null
        // email parameter may be null
        return new User(name, email);
    }
    
    @Nullable
    public User findUser(String id) {
        // Method may return null if user not found
        return userRepository.findById(id);
    }
}

/**
 * Marks source code as generated by tools.
 * Used to differentiate user-written code from generated code.
 */
@Documented
@Target({PACKAGE, TYPE, ANNOTATION_TYPE, METHOD, CONSTRUCTOR, FIELD, LOCAL_VARIABLE, PARAMETER})
@Retention(SOURCE)
public @interface Generated {
    /**
     * Name of the code generator (required).
     * Recommended: fully qualified class name.
     */
    String[] value();
    
    /**
     * Date when source was generated.
     * ISO 8601 format (e.g., "2001-07-04T12:08:56.235-0700").
     */
    String date() default "";
    
    /**
     * Comments from the code generator.
     */
    String comments() default "";
}

import jakarta.annotation.Generated;

@Generated(value = "com.example.MyGenerator", 
          date = "2023-12-01T10:30:00.000Z",
          comments = "Generated from schema v2.1")
public class GeneratedEntity {
    
    @Generated("com.example.PropertyGenerator")
    private String generatedField;
    
    @Generated(value = "com.example.MethodGenerator", 
               comments = "Auto-generated getter")
    public String getGeneratedField() {
        return generatedField;
    }
}

/**
 * Indicates priority order for program elements.
 * Lower values indicate higher priority.
 */
@Documented
@Retention(RUNTIME)
public @interface Priority {
    /**
     * Priority value (should generally be non-negative).
     * Lower values indicate higher priority.
     */
    int value();
}

import jakarta.annotation.Priority;

@Priority(100)
public class HighPriorityInterceptor {
    // Will be executed before lower priority interceptors
}

@Priority(500)  
public class LowPriorityInterceptor {
    // Will be executed after higher priority interceptors
}

// Common priority constants (from Jakarta Interceptors specification)
@Priority(Interceptor.Priority.PLATFORM_BEFORE)  // 0
public class PlatformInterceptor { }

@Priority(Interceptor.Priority.LIBRARY_BEFORE)   // 1000
public class LibraryInterceptor { }

@Priority(Interceptor.Priority.APPLICATION)      // 2000  
public class ApplicationInterceptor { }