Annotation guide and complete reference

J7M's annotations describe ordinary application code while the host supplies trusted capabilities, finite profiles and lifecycle ownership. The public API currently contains 80 annotation types under org.j7m.middleware.annotations. BindingRefresh is a helper enum and is not an annotation.

Start with components and injection, then follow the family relevant to your application. The pattern guide shows how declarations fit a working distributed design and compares them with explicit API code.

How to read an entry

Each entry identifies valid Java targets, required attributes and defaults, a usage example and the real consumer or limitation. Code fragments focus on the declaration: imports, application collaborators and host configuration may be supplied by the surrounding application. The executable example projects provide complete verified entry points.

Declaration is not installation. A named policy selects a trusted registered profile; it never installs a factory or grants credentials. Generated managed metadata is validated before construction. Unsupported or conflicting combinations fail rather than silently promising an unavailable behavior.

Declarations need an installed capability. Some markers are descriptive metadata, and @SwitchLevel is explicitly reserved. Each family below shows application code, the required host boundary and the resulting behavior. Use the practical scenarios to assemble the declarations into a working design; a reserved marker has no runtime operation to activate.

Common combinations

Task	Typical combination	Required host boundary
Refreshable remote dependency	@Inject + @ServiceRef	Binding factory, discovery, admission and named policy
Safe pre-delivery retry	@Idempotent + @Retry	Qualified client retry interceptor and finite profile
Durable command replay	@Deduplicated + @IdempotencyKey	Durable invocation policy and stable namespace
Database-backed message handling	@DurableQueueConsumer + @InboxHandler + @JdbcTransaction	Exact shared JDBC registration and INBOX queue strategy
Recoverable mutable job	@DurableJob + @Checkpoint + @Restore	Job factory/profile and explicit checkpoint safe points
Persistent occurrence	@DurableJob + @Schedule	Durable trigger, clock and overlap/missed-fire policy
Recoverable workflow	@SagaDefinition + @SagaStep + optional inverses/reconciliation	Saga factory, exact program identity and explicit administrative grant

Validation and precedence

Use public interface declarations for client-visible calling semantics. Implementation-only metadata must not silently redefine that contract. Ordinary self-invocation does not create interception. Exact qualifier values and policy identities matter; a similarly configured second factory is not necessarily the same required policy instance.

Keep defaults explicit when they affect safety. refresh=NEVER does not mean cluster failover; idempotent=false does not authorize automatic replay; version=1 is a logical contract version rather than a deployment instance number. See configuration profiles and failure semantics.

Alphabetical index: all 80 annotations

Annotation	Purpose
@Async	Logical asynchronous result
@Audit	Host-selected safe audit policy
@Backpressure	Concurrent admission metadata
@BackpressureAware	Backpressure cooperation marker
@Benchmark	Optional safe latency-sampling method
@Bulkhead	Dependency admission budget
@Callback	Remote-reference callback intent
@Cancellable	Cooperative cancellation contract
@Checkpoint	Explicit job state snapshot hook
@CircuitBreaker	Connection-availability breaker policy
@Compensation	Named inverse saga callback
@Confidential	Confidential-handling declaration
@ConfigProperties	Immutable configuration record
@ConfigValue	Configuration key binding
@CurrentApplication	Safe application context
@CurrentInvocation	Current owned invocation context
@CurrentPrincipal	Authenticated current principal
@DataLocality	Eligible same-group endpoint preference
@DeadLetterHandler	Observational DLQ callback
@Deadline	Method timeout metadata
@Deduplicated	Durable invocation replay policy
@Drain	Application drain callback
@DurableJob	Durable POJO job entry
@DurableQueueConsumer	Durable payload handler
@EventSubscription	Durable cursor callback
@HealthCheck	Component health callback
@HighAvailability	Availability selection intent
@IdempotencyKey	Stable logical operation identity
@Idempotent	Safe-repeat application contract
@InboxHandler	Same-Connection delivery marker
@Initialize	Initialization callback
@Inject	Managed dependency resolution
@IsolationProfile	Installed isolation/resource profile
@J7mApplication	Application coordinates
@J7mComponent	Generated component definition
@J7mResource	Authorized host capability binding
@J7mService	Managed service declaration
@JdbcTransaction	One-Connection JDBC unit of work
@LeaderTask	Leadership-gated work
@LeaseGuard	Fenced lease policy
@LocalOnly	Local contract boundary
@LongRunning	Long-work declaration
@Named	Exact dependency name
@NoRemoteExport	Non-export declaration
@NonIdempotent	Unsafe-repeat contract
@Observed	Application observation policy
@OneWay	Bounded local enqueue
@OrderedBy	Explicit per-key ordering selector
@OutboxPublisher	Transactional SQL staging producer
@PartitionHandler	Pure encoded state reducer
@PreferLocal	Eligible local-candidate preference
@Priority	Workload priority metadata
@Produces	Typed factory product
@Progress	Bounded progress hook
@Qualifier	Custom dependency qualifier marker
@QueuePublisher	Typed durable producer
@RateLimited	Rate-policy scope
@ReadinessCheck	New-work readiness callback
@ReconciliationHandler	Evidence-based UNKNOWN resolution
@RemoteMethod	Remote method declaration
@RemoteService	Remote service intent
@RequiresPermission	Action/resource authorization requirement
@RequiresRole	Caller role requirement
@RequiresTrustDomain	Caller trust-domain requirement
@ResourceRequirement	Resource policy requirement
@ResourceTransaction	Native resource 2PC policy
@Restore	Checkpoint restoration hook
@Retry	Bounded pre-delivery retry declaration
@SagaDefinition	Versioned durable workflow
@SagaStep	Ordered forward callback
@Schedule	Persistent trigger selection
@SchemaType	Stable allowlisted record schema
@Scope	Activation/CALL/prototype lifetime
@Sensitive	Redaction-aware value declaration
@ServiceRef	Refreshable business-interface binding
@ShardKey	Canonical routing selector
@Shutdown	Final resource-release callback
@Startup	Startup callback
@SwitchLevel	Reserved, currently non-executing marker
@WireField	Stable schema field identity

The inventory is derived from the current source declarations, not from names remembered by the guide. Changes to that package must update this index and the corresponding examples together.