0
# Caching and Locking
1

2
Complete reference for second-level caching and entity locking strategies in Jakarta Persistence.
3

4
## Imports
5

6
```java { .api }
7
import jakarta.persistence.*;
8
```
9

10
## Capabilities
11

12
### Cache Interface
13

14
Manage the second-level cache.
15

16
```java { .api }
17
/**
18
 * Interface for second-level cache management
19
 * @since 2.0
20
 */
21
public interface Cache {
22
    boolean contains(Class cls, Object primaryKey);
23
    void evict(Class cls, Object primaryKey);
24
    void evict(Class cls);
25
    void evictAll();
26
    <T> T unwrap(Class<T> cls);
27
}
28

29
/**
30
 * Specifies whether an entity should be cached
31
 * @since 2.0
32
 */
33
@Target({TYPE})
34
@Retention(RUNTIME)
35
public @interface Cacheable {
36
    boolean value() default true;
37
}
38

39
/**
40
 * Cache retrieve mode
41
 * @since 2.0
42
 */
43
public enum CacheRetrieveMode {
44
    USE,
45
    BYPASS
46
}
47

48
/**
49
 * Cache store mode
50
 * @since 2.0
51
 */
52
public enum CacheStoreMode {
53
    USE,
54
    BYPASS,
55
    REFRESH
56
}
57

58
/**
59
 * Shared cache mode
60
 * @since 2.0
61
 */
62
public enum SharedCacheMode {
63
    ALL,
64
    NONE,
65
    ENABLE_SELECTIVE,
66
    DISABLE_SELECTIVE,
67
    UNSPECIFIED
68
}
69
```
70

71
### Lock Modes
72

73
Control optimistic and pessimistic locking.
74

75
```java { .api }
76
/**
77
 * Lock mode types
78
 * @since 1.0
79
 */
80
public enum LockModeType {
81
    READ,
82
    WRITE,
83
    OPTIMISTIC,
84
    OPTIMISTIC_FORCE_INCREMENT,
85
    PESSIMISTIC_READ,
86
    PESSIMISTIC_WRITE,
87
    PESSIMISTIC_FORCE_INCREMENT,
88
    NONE
89
}
90

91
/**
92
 * Pessimistic lock scope
93
 * @since 2.0
94
 */
95
public enum PessimisticLockScope {
96
    NORMAL,
97
    EXTENDED
98
}
99
```
100

101
**Usage Example:**
102

103
```java
104
EntityManager em = emf.createEntityManager();
105

106
// Use cache
107
Cache cache = emf.getCache();
108
boolean inCache = cache.contains(User.class, 1L);
109
cache.evict(User.class, 1L);
110
cache.evictAll();
111

112
// Cache modes
113
Map<String, Object> props = new HashMap<>();
114
props.put("jakarta.persistence.cache.retrieveMode", CacheRetrieveMode.BYPASS);
115
props.put("jakarta.persistence.cache.storeMode", CacheStoreMode.REFRESH);
116
User user = em.find(User.class, 1L, props);
117

118
// Optimistic locking
119
em.getTransaction().begin();
120
User user = em.find(User.class, 1L, LockModeType.OPTIMISTIC);
121
user.setName("New Name");
122
em.getTransaction().commit();
123

124
// Pessimistic locking
125
em.getTransaction().begin();
126
User user = em.find(User.class, 1L, LockModeType.PESSIMISTIC_WRITE);
127
user.setName("New Name");
128
em.getTransaction().commit();
129

130
// Lock with timeout
131
Map<String, Object> lockProps = new HashMap<>();
132
lockProps.put("jakarta.persistence.lock.timeout", 5000);
133
lockProps.put("jakarta.persistence.lock.scope", PessimisticLockScope.EXTENDED);
134
em.lock(user, LockModeType.PESSIMISTIC_WRITE, lockProps);
135
```
136

137
[Complete documentation in index.md](./index.md)
138