0
# Service Provider Interface
1

2
Complete reference for implementing custom persistence providers and integrating with Jakarta Persistence SPI.
3

4
## Imports
5

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

10
## Capabilities
11

12
### PersistenceProvider
13

14
Interface implemented by persistence providers.
15

16
```java { .api }
17
/**
18
 * Interface implemented by persistence providers
19
 * @since 1.0
20
 */
21
public interface PersistenceProvider {
22
    EntityManagerFactory createEntityManagerFactory(String emName, Map map);
23
    EntityManagerFactory createContainerEntityManagerFactory(PersistenceUnitInfo info, Map map);
24
    void generateSchema(PersistenceUnitInfo info, Map map);
25
    boolean generateSchema(String persistenceUnitName, Map map);
26
    ProviderUtil getProviderUtil();
27
}
28

29
/**
30
 * Persistence unit information
31
 * @since 1.0
32
 */
33
public interface PersistenceUnitInfo {
34
    String getPersistenceUnitName();
35
    String getPersistenceProviderClassName();
36
    PersistenceUnitTransactionType getTransactionType();
37
    DataSource getJtaDataSource();
38
    DataSource getNonJtaDataSource();
39
    List<String> getMappingFileNames();
40
    List<URL> getJarFileUrls();
41
    URL getPersistenceUnitRootUrl();
42
    List<String> getManagedClassNames();
43
    boolean excludeUnlistedClasses();
44
    SharedCacheMode getSharedCacheMode();
45
    ValidationMode getValidationMode();
46
    Properties getProperties();
47
    String getPersistenceXMLSchemaVersion();
48
    ClassLoader getClassLoader();
49
    void addTransformer(ClassTransformer transformer);
50
    ClassLoader getNewTempClassLoader();
51
}
52

53
/**
54
 * Provider utility methods
55
 * @since 2.0
56
 */
57
public interface ProviderUtil {
58
    LoadState isLoadedWithoutReference(Object entity, String attributeName);
59
    LoadState isLoadedWithReference(Object entity, String attributeName);
60
    LoadState isLoaded(Object entity);
61
}
62

63
/**
64
 * Class transformer for bytecode enhancement
65
 * @since 1.0
66
 */
67
public interface ClassTransformer {
68
    byte[] transform(ClassLoader loader, String className, Class<?> classBeingRedefined,
69
                    ProtectionDomain protectionDomain, byte[] classfileBuffer)
70
        throws TransformerException;
71
}
72

73
/**
74
 * Load state enumeration
75
 * @since 2.0
76
 */
77
public enum LoadState {
78
    LOADED,
79
    NOT_LOADED,
80
    UNKNOWN
81
}
82

83
/**
84
 * Persistence unit transaction type
85
 * @since 1.0
86
 */
87
public enum PersistenceUnitTransactionType {
88
    JTA,
89
    RESOURCE_LOCAL
90
}
91

92
/**
93
 * Persistence provider resolver holder
94
 * @since 2.0
95
 */
96
public class PersistenceProviderResolverHolder {
97
    public static PersistenceProviderResolver getPersistenceProviderResolver();
98
    public static void setPersistenceProviderResolver(PersistenceProviderResolver resolver);
99
}
100

101
/**
102
 * Persistence provider resolver interface
103
 * @since 2.0
104
 */
105
public interface PersistenceProviderResolver {
106
    List<PersistenceProvider> getPersistenceProviders();
107
    void clearCachedProviders();
108
}
109

110
/**
111
 * Transformer exception
112
 * @since 1.0
113
 */
114
public class TransformerException extends Exception {
115
    public TransformerException();
116
    public TransformerException(String message);
117
    public TransformerException(String message, Throwable cause);
118
    public TransformerException(Throwable cause);
119
}
120
```
121

122
**Usage Example:**
123

124
```java
125
// Custom persistence provider
126
public class CustomPersistenceProvider implements PersistenceProvider {
127
    @Override
128
    public EntityManagerFactory createEntityManagerFactory(String emName, Map map) {
129
        // Implementation
130
        return new CustomEntityManagerFactory();
131
    }
132

133
    @Override
134
    public EntityManagerFactory createContainerEntityManagerFactory(
135
            PersistenceUnitInfo info, Map map) {
136
        // Implementation
137
        return new CustomEntityManagerFactory();
138
    }
139

140
    @Override
141
    public ProviderUtil getProviderUtil() {
142
        return new CustomProviderUtil();
143
    }
144
}
145

146
// Register custom provider
147
PersistenceProviderResolver resolver = new CustomPersistenceProviderResolver();
148
PersistenceProviderResolverHolder.setPersistenceProviderResolver(resolver);
149
```
150

151
[Complete documentation in index.md](./index.md)
152