Java Annotations Demystified, Part 2: Method-Level Security Link to heading

From Data Validation to Method-Level Control Link to heading

In Part 1, we explored how Java annotations can be used to validate fields in your data objects. We created custom annotations like @Email, @StringLength, and @IpAddress to declaratively define validation rules right alongside our fields.

Today, we’ll take our understanding of annotations to the next level by tackling a common enterprise challenge: method-level security. We’ll demonstrate how annotations can be used not just to validate data, but to control access to entire methods based on user permissions.

The Power of Method Annotations Link to heading

Method annotations are particularly powerful because they allow you to:

Decorate behavior: Add cross-cutting concerns to methods without modifying their core logic
Control invocation: Intercept method calls to perform pre/post-processing
Generate documentation: Automatically document method requirements
Apply AOP concepts: Implement Aspect-Oriented Programming without heavy frameworks

Real-World Example: Building a Method-Level Security Framework Link to heading

Imagine you’re developing a banking application where different operations require different security permissions. Some users can view accounts, others can deposit money, and privileged users can transfer funds.

Instead of littering our business logic with security checks, we’ll use annotations to declaratively specify which permissions are required for each operation. This approach:

Keeps security concerns separate from business logic
Makes permission requirements explicit and visible
Centralizes security enforcement logic
Facilitates security audits

Let’s dive into our implementation.

1. Defining the Security Annotation Link to heading

First, we define our custom annotation that will mark methods with required permissions:

package notes.language.annotations.method;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface RequiresPermission {
    String[] value();

    LogicalOperator operator() default LogicalOperator.AND;

    enum LogicalOperator {
        AND, OR
    }
}

This annotation:

Uses @Target(ElementType.METHOD) to specify it can only be applied to methods
Uses @Retention(RetentionPolicy.RUNTIME) so it’s available during execution
Accepts an array of permission strings via the value() method
Provides an optional logical operator to determine if ALL permissions are required (AND) or if ANY permission is sufficient (OR)
Defaults to requiring ALL permissions (LogicalOperator.AND)

2. Creating the Domain Model Link to heading

Let’s define our banking domain objects:

package notes.language.annotations.method;

public class Account {
    private final String id;

    public Account(String id) {
        this.id = id;
    }

    public String getId() {
        return id;
    }
}

package notes.language.annotations.method;

public class User {
    private final String name;
    private final List<String> permissions;

    public User(String name, List<String> permissions) {
        this.name = name;
        this.permissions = permissions;
    }

    public String getName() {
        return name;
    }
    public List<String> getPermissions() {
        return permissions;
    }
}

3. Defining the Service Interface Link to heading

Our banking application has a service interface with various operations:

package notes.language.annotations.method;

public interface AccountService {
    Account getAccountDetails(String accountId);
    void transferFunds(String fromAccount, String toAccount, double amount);
    void depositFunds(String accountId, double amount);
}

4. Implementing the Service with Annotations Link to heading

Now we can implement this interface and apply our security annotations:

package notes.language.annotations.method;

public class AccountServiceImpl implements AccountService {
    @Override
    @RequiresPermission("account.view")
    public Account getAccountDetails(String accountId) {
        // Implementation
        return new Account(accountId);
    }

    @Override
    @RequiresPermission({"account.transfer", "account.withdraw"})
    public void transferFunds(String fromAccount, String toAccount, double amount) {
        // Implementation
    }

    @Override
    @RequiresPermission("account.deposit")
    public void depositFunds(String accountId, double amount) {
        // Implementation
    }
}

Notice how we’ve decorated each method with the appropriate permission requirements:

Viewing an account requires the account.view permission
Transferring funds requires both account.transfer AND account.withdraw permissions
Depositing money requires the account.deposit permission

5. Creating the Security Manager Link to heading

We need a way to check if the current user has the required permissions:

package notes.language.annotations.method;

import static notes.language.annotations.method.RequiresPermission.*;

// Custom security manager
public class SecurityManager {
    private static SecurityManager instance;
    private User currentUser;

    private SecurityManager() {}

    public static SecurityManager getInstance() {
        if (instance == null) {
            instance = new SecurityManager();
        }
        return instance;
    }

    public void setCurrentUser(User user) {
        this.currentUser = user;
    }

    public User getCurrentUser() {
        return currentUser;
    }

    public boolean hasPermission(String permission) {
        if (currentUser == null) {
            return false;
        }

        for (String userPermission : currentUser.getPermissions()) {
            if (userPermission.equals(permission)) {
                return true;
            }
        }

        return false;
    }

    public boolean checkPermissions(String[] permissions, LogicalOperator operator) {
        if (permissions.length == 0) {
            return true;
        }

        if (operator == LogicalOperator.AND) {
            // All permissions required
            for (String permission : permissions) {
                if (!hasPermission(permission)) {
                    return false;
                }
            }
            return true;
        } else {
            // At least one permission required
            for (String permission : permissions) {
                if (hasPermission(permission)) {
                    return true;
                }
            }
            return false;
        }
    }
}

This singleton Security Manager:

Tracks the current user
Provides methods to check permissions
Supports both AND and OR logical operations for permission checks

6. Enforcing Security with Dynamic Proxies Link to heading

The most interesting part is how we actually enforce these security requirements. We’ll use Java’s dynamic proxy mechanism to intercept method calls and check permissions before allowing the method to execute:

package notes.language.annotations.method;

import java.lang.reflect.InvocationHandler;
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;
import java.util.Arrays;

public class SecurityProxy {
    @SuppressWarnings("unchecked")
    public static <T> T newInstance(final T target) {
        return (T) Proxy.newProxyInstance(
                target.getClass().getClassLoader(),
                target.getClass().getInterfaces(),
                new InvocationHandler() {
                    @Override
                    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
                        // This is the key - its the part where we look for the annotations on the target class AccountServiceImpl
                        Method targetMethod = target.getClass().getMethod(
                                method.getName(), method.getParameterTypes());

                        if (targetMethod.isAnnotationPresent(RequiresPermission.class)) {
                            RequiresPermission annotation = targetMethod.getAnnotation(RequiresPermission.class);
                            boolean hasPermission = SecurityManager.getInstance().checkPermissions(
                                    annotation.value(), annotation.operator());

                            if (!hasPermission) {
                                throw new SecurityException("Access denied. Required permissions: "
                                        + Arrays.toString(annotation.value()));
                            }
                        }

                        // Finally, the "real" method (AccountServiceImpl) is invoked here
                        return method.invoke(target, args);
                    }
                }
        );
    }
}

This SecurityProxy class:

Creates a dynamic proxy that wraps our service implementation
Intercepts all method calls via the invoke method
Uses reflection to check if the target method has our @RequiresPermission annotation
If found, extracts the required permissions and checks them against the current user
Throws a SecurityException if the user doesn’t have sufficient permissions
Otherwise, allows the method call to proceed to the target object

7. Putting It All Together Link to heading

Finally, let’s see our solution in action:

package notes.language.annotations.method;

import java.util.Arrays;

public class BankingApplication {
    public static void main(String[] args) {
        // Set up security
        User user = new User("john.doe",
                Arrays.asList("account.view", "account.deposit"));
        SecurityManager.getInstance().setCurrentUser(user);

        // Create service with security proxy
        AccountService service = SecurityProxy.newInstance(new AccountServiceImpl());

        try {
            // This will work - user has "account.view" permission
            Account account = service.getAccountDetails("1234567890");
            System.out.println("Account found: " + account.getId());

            // This will throw SecurityException - user doesn't have "account.withdraw"
            service.transferFunds("1234567890", "0987654321", 1000.00);

            // This will work - user has "account.deposit" permission
            service.depositFunds("1234567890", 500.00);
            System.out.println("Deposit successful");

        } catch (SecurityException e) {
            System.err.println("Security error: " + e.getMessage());
        }
    }
}

When we run this application:

We create a user with only account.view and account.deposit permissions
The call to getAccountDetails succeeds because the user has the required permission
The call to transferFunds fails with a SecurityException because the user lacks the account.withdraw permission
The call to depositFunds would succeed, but it’s never reached due to the exception

How It All Works: The Magic of Annotation Processing Link to heading

Let’s take a moment to understand the mechanics behind our solution:

Annotation Definition: We define a custom annotation with specific retention and target parameters
Annotation Placement: We apply the annotation to methods, specifying required permissions
Runtime Processing: At runtime, our proxy uses reflection to:
- Find annotations on methods
- Extract permission requirements
- Check against the current user’s permissions
- Allow or deny method execution

This demonstrates the three key elements of working with annotations:

Definition: Creating the annotation type
Application: Applying annotations to code elements
Processing: Reading and acting on annotations at compile-time or runtime

Beyond Simple Security: Advanced Applications Link to heading

Our method-level security example is just one application of method annotations. Here are other powerful use cases:

1. Transaction Management Link to heading

@Transactional(propagation = Propagation.REQUIRED, isolation = Isolation.READ_COMMITTED)
public void createOrder(Order order) {
    // Method executes within a transaction
}

2. Caching Link to heading

@Cacheable(value = "products", key = "#productId")
public Product getProductById(Long productId) {
    // Result will be cached
}

3. API Documentation Link to heading

@Operation(
    summary = "Get user by ID",
    description = "Retrieves a user by their unique identifier",
    responses = {
        @ApiResponse(responseCode = "200", description = "User found"),
        @ApiResponse(responseCode = "404", description = "User not found")
    }
)
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    // Handler logic
}

4. Asynchronous Execution Link to heading

@Async
public CompletableFuture<Results> processLargeDataset(Dataset data) {
    // Method will execute on a separate thread
}

Comparing Method Annotations with Field Annotations Link to heading

Let’s compare method annotations with the field validation annotations we saw in Part 1:

Aspect	Field Annotations	Method Annotations
Target	Data validation	Behavior modification
When applied	Object state	Method invocation
Common uses	Data validation, serialization	Security, transactions, logging
Processing time	Often at object creation	Method execution time
Implementation	Often uses field reflection	Often uses proxies or AOP

Integration with Frameworks Link to heading

While our example shows how to build a custom annotation processing system from scratch, most enterprise applications leverage existing frameworks:

Spring Framework Link to heading

Spring provides excellent support for method annotations:

@Service
public class UserService {
    @Secured("ROLE_ADMIN") 
    public void createUser(User user) {
        // Only administrators can create users
    }
    
    @PreAuthorize("hasPermission(#user.id, 'User', 'EDIT')")
    public void updateUser(User user) {
        // Custom permission expression
    }
}

Jakarta EE (formerly Java EE) Link to heading

Jakarta EE offers declarative security via annotations:

@DeclareRoles({"Manager", "Employee"})
@WebServlet("/secure/admin")
public class AdminServlet extends HttpServlet {
    @RolesAllowed("Manager")
    public void doGet(HttpServletRequest req, HttpServletResponse resp) {
        // Only managers can access this
    }
}

Best Practices for Method Annotations Link to heading

Based on our exploration, here are some best practices:

Keep annotations focused: Design annotations to do one thing well
Document clearly: Use good naming and Javadoc to explain annotation purpose and parameters
Provide reasonable defaults: Make annotations easy to use with sensible default values
Consider compile-time validation: When possible, validate annotation usage at compile time
Balance declarative and imperative: Don’t try to push all logic into annotations
Test annotation processing: Write tests specifically for your annotation processors
Be mindful of performance: Reflection can be expensive, consider caching metadata

Performance Considerations Link to heading

Our security proxy implementation uses reflection on every method call, which could impact performance in high-throughput applications. In production environments, consider:

Metadata caching: Cache the results of reflection to avoid repeated lookups
Compile-time processing: Generate proxy classes at compile time instead of runtime
Optimized proxies: Use specialized libraries like ByteBuddy or CGLib for better proxy performance
Selective application: Apply proxies only where necessary rather than wrapping everything

Conclusion: The Declarative Power of Annotations Link to heading

Through our two-part series, we’ve seen how Java annotations transform code from imperative to declarative. Whether validating fields or securing methods, annotations let us express intent directly in our code.

By building our own annotation processors, we’ve gained insight into how modern Java frameworks work under the hood. This knowledge empowers us to:

Better understand how existing frameworks use annotations
Create custom annotations for domain-specific needs
Make more informed decisions about when to use annotations

Java annotations represent a powerful paradigm shift in how we structure and organize code. By separating cross-cutting concerns from business logic, they lead to more maintainable, readable, and secure applications.

Resources Link to heading

Java Reflection API
Java Dynamic Proxies
Spring Security Annotations
Jakarta Security
AspectJ - An extension of Java that adds aspect-oriented programming capabilities