jakartaee / jakartaee/cdi

Rename @Reserve to @Fallback (or @Primary/@Fallback pair) for clearer intent

Open
#985 7 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
240
Forks
83
PR merge metrics
No merged PRs in 30d

Description

The name `@Reserve` may not clearly convey its purpose to developers unfamiliar with it. The term “reserve” is generic and requires consulting the specification or Javadoc to learn that a reserve bean is used only when no non-reserve bean is available.

For example:

```java
@Reserve
@Dependent
public class DefaultOrderService implements OrderService {
}
```

This may prompt readers to ask:

> Reserve for what?

The intended meaning is closer to:

> Use this implementation only when no higher-priority candidate exists.

Proposed Alternatives:

## Option 1: Rename @Reserve to @Fallback

```java
@Fallback
@Dependent
public class DefaultOrderService implements OrderService {
}
```

The term “fallback” is widely recognized in software engineering and clearly indicates a default implementation used only when no preferred option is available.

## Option 2: Introduce a @Primary / @Fallback model

Alternatively, terminology similar to other dependency injection frameworks could be adopted:

```java
@Primary
public class PremiumOrderService implements OrderService {
}
@Fallback
public class DefaultOrderService implements OrderService {
}
```

This model makes bean selection intent explicit and easier to understand, especially for developers familiar with other frameworks.

Benefits

* Enhances discoverability and readability.
* Reduces the need to consult documentation to understand the annotation’s purpose.
* Aligns CDI terminology with concepts familiar to many developers.
* Makes code more self-documenting.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the current @Reserve definition and its specification or Javadoc wording. Compare the proposed @Fallback and @Primary/@Fallback models with existing CDI bean-selection rules, then document the chosen terminology and its impact on the shown examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.