Package io.fluxcapacitor.javaclient.tracking.handling.authentication

Annotation Interface RequiresUser

@Documented
@Target({TYPE,CONSTRUCTOR,METHOD,ANNOTATION_TYPE,PACKAGE})
@Retention(RUNTIME)
@Inherited
@RequiresAnyRole
public @interface RequiresUser

Indicates that a handler or message requires the presence of an authenticated user.

This annotation ensures that:

• A message handler will only be invoked if User.getCurrent() is not null.
• If placed on a message payload, a UnauthenticatedException is thrown if the message is handled without a user context.

This annotation is implemented as a meta-annotation over RequiresAnyRole, but without specifying any explicit roles. Its presence implies that any user, regardless of their role, is required.

Usage Examples

Handler requiring an authenticated user

 @HandleQuery
 @RequiresUser
 public UserProfile handle(GetUserProfile query) {
     return userService.getProfileFor(User.getCurrent());
 }
 

Payload requiring an authenticated user

 @Value
 @RequiresUser
 public class UpdateAccountSettings {
     AccountId accountId;
     AccountSettings settings;
 }
 

In this case, if an anonymous user attempts to invoke a command with this payload, a UnauthenticatedException will be thrown.

Notes

• This annotation can be used on types, methods, constructors, annotations, and packages.
• Like RequiresAnyRole, it is composable and inherited, so it can be placed at a high level (e.g., package or class) to apply broadly.

This annotation may also be placed on a parent or root package, via a package-info.java file. When applied in this way, the rule is inherited by all message handlers, payloads, and classes within that package and its subpackages, unless explicitly overridden. This allows you to enforce authentication requirements across entire modules or layers of your application.

Example usage:

 // In com/example/secure/package-info.java
 @RequiresUser
 package com.example.secure;
 

See Also:

• RequiresAnyRole
• User
• UnauthenticatedException

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
boolean	throwIfUnauthorized	Determines whether an exception should be thrown when the authorization check fails.

Element Details

throwIfUnauthorized

boolean throwIfUnauthorized

Determines whether an exception should be thrown when the authorization check fails.

If true (the default), an UnauthenticatedException will be thrown if no user is present.

If false, the annotated handler or message will be silently skipped instead. This opt-out strategy is useful for conditionally invoked handlers where fallback behavior or a timeout is preferred.

Defaults to true.

Default:

true