jakartaee / jakartaee/persistence

Add an EntityManager#getReference() method that takes an ID and a version

Open
#82 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Priority: Minor Type: Improvement
Dominant language
Java
Stars
268
Forks
78
Avg merge
1d 6h
Merged PRs (30d)
13

Description

Please consider adding an EntityManager#getReference(Class, Object, Object) method to the JPA specification.

The method's purpose should be to return an entity provided that its identifier _and version_ are equal to the supplied parameters.

It should be possible to pass null as the third parameter (version).

The javadoc could read something like the following:

```
/*
* Get an instance, whose state may be lazily fetched, provided that the
* supplied class, identifier and version parameters collectively identify the
* persistent representation of the entity in question.
*
*

If the requested instance does not exist in the database, an
* {@link EntityNotFoundException} is thrown when the instance state
* is first accessed. (The persistence provider runtime is permitted to throw
* the {@link EntityNotFoundException} when {@code getReference} is
* called.)


*
*

The application should not expect that the instance state will be
* available upon detachment, unless it was accessed by the application while
* the {@link EntityManager} was open.


*
* @param entityClass the {@link Class} of the entity being sought; must not
* be {@code null}
*
* @param primaryKey the identifier of the entity being sought; must not be
* {@code null}
*
* @param version the version of the entity being sought; may be {@code
* null} in which case this method will behave in exactly the same manner as
* the {@link #getReference(Class, Object)} method
*
* @return the found (non-{@code null}) entity reference
*
* @exception IllegalArgumentException if {@code entityClass} does not
* denote an entity type or {@code primaryKey} is not a valid type for that
* entity's primary key or is {@code null}
*
* @exception EntityNotFoundException if the entity state cannot be accessed
*/
```

The background for this issue can be accessed in the following email thread: [https://java.net/projects/jpa-spec/lists/users/archive/2014-06/message/0](https://java.net/projects/jpa-spec/lists/users/archive/2014-06/message/0)

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

Start by reviewing the existing JPA EntityManager#getReference(Class, Object) contract in the specification and then read the linked 2014 email thread for the proposal's background. Done would require a decided specification change covering the new ID-and-version signature, null-version behavior, and documented exceptions.

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
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.