Skip to content

Commit

Permalink
improvements to PersistenceConfiguration
Browse files Browse the repository at this point in the history 
1. add constructor taking name, and make name immutable
2. clarify rules for vendor subclasses
3. add constant property names
4. improve javadoc

see jakartaee#481, jakartaee#139
  • Loading branch information
@gavinking
gavinking committed Aug 22, 2023
1 parent 7af8183 commit f89b60c
Show file tree
Hide file tree
Showing 5 changed files with 169 additions and 19 deletions.
3 changes: 2 additions & 1 deletion api/src/main/java/jakarta/persistence/Persistence.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
*/

// Contributors:
// Gavin King - 3.2
// Linda DeMichiel - 2.1
// Linda DeMichiel - 2.0

Expand Down Expand Up @@ -130,7 +131,7 @@ public static EntityManagerFactory createEntityManagerFactory(PersistenceConfigu
* @param map properties for schema generation; these may
* also contain provider-specific properties. The
* value of these properties override any values that
* may have been configured elsewhere..
* may have been configured elsewhere.
* @throws PersistenceException if insufficient or inconsistent
* configuration information is provided or if schema
* generation otherwise fails.
Expand Down
177 changes: 160 additions & 17 deletions api/src/main/java/jakarta/persistence/PersistenceConfiguration.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;

/**
* Represents a configuration of a persistence unit, allowing programmatic
Expand Down Expand Up @@ -61,13 +62,124 @@
* }
* </pre>
*
* <p>It is intended that persistence providers define subclasses of
* this class with vendor-specific configuration options. A provider
* must support configuration via any instance of this class or of any
* subclass of this class.
*
* @see Persistence#createEntityManagerFactory(PersistenceConfiguration)
*
* @since 3.2
*/
public class PersistenceConfiguration {

private String name;
/**
* Fully qualified name of the JDBC driver class.
*/
public static final String JDBC_DRIVER = "jakarta.persistence.jdbc.driver";
/**
* JDBC URL.
*/
public static final String JDBC_URL = "jakarta.persistence.jdbc.url";
/**
* Username for JDBC authentication.
*/
public static final String JDBC_USER = "jakarta.persistence.jdbc.user";
/**
* Password for JDBC authentication.
*/
public static final String JDBC_PASSWORD = "jakarta.persistence.jdbc.password";
/**
* An instance of {@code javax.sql.DataSource}.
*/
public static final String JDBC_DATASOURCE = "jakarta.persistence.dataSource";

/**
* Default pessimistic lock timeout hint.
*/
public static final String LOCK_TIMEOUT = "jakarta.persistence.lock.timeout";
/**
* Default query timeout hint.
*/
public static final String QUERY_TIMEOUT = "jakarta.persistence.query.timeout";

/**
* The action to be performed against the database.
*
* <p>Standard actions are: {@code none}, {@code create},
* {@code drop}, {@code drop-and-create}, {@code validate}.
*/
public static final String SCHEMAGEN_DATABASE_ACTION = "jakarta.persistence.schema-generation.database.action";
/**
* The action to be generated as a SQL script.
*
* <p>The script is generated in the location specified by
* {@value #SCHEMAGEN_CREATE_TARGET} or {@value #SCHEMAGEN_DROP_TARGET}.
*
* <p>Standard actions are: {@code none}, {@code create},
* {@code drop}, {@code drop-and-create}.
*/
public static final String SCHEMAGEN_SCRIPTS_ACTION = "jakarta.persistence.schema-generation.scripts.action";
/**
* The source of artifacts to be created.
*
* <p>Standard sources are: {@code metadata}, {@code script},
* {@code metadata-then-script}, {@code script-then-metadata}.
*
* <p>The location of the script source is specified by
* {@value #SCHEMAGEN_CREATE_SCRIPT_SOURCE}.
*/
public static final String SCHEMAGEN_CREATE_SOURCE = "jakarta.persistence.schema-generation.create-source";
/**
* The source of artifacts to be dropped.
*
* <p>Standard sources are: {@code metadata}, {@code script},
* {@code metadata-then-script}, {@code script-then-metadata}.
*
* <p>The location of the script source is specified by
* {@value #SCHEMAGEN_DROP_SCRIPT_SOURCE}.
*/
public static final String SCHEMAGEN_DROP_SOURCE = "jakarta.persistence.schema-generation.drop-source";
/**
* An application-provided SQL script to be executed when the
* schema is created.
*/
public static final String SCHEMAGEN_CREATE_SCRIPT_SOURCE = "jakarta.persistence.schema-generation.create-script-source";
/**
* An application-provided SQL script to be executed when the
* schema is dropped.
*/
public static final String SCHEMAGEN_DROP_SCRIPT_SOURCE = "jakarta.persistence.schema-generation.drop-script-source";
/**
* The provider-generated SQL script which creates the schema
* when {@value SCHEMAGEN_SCRIPTS_ACTION} is set.
*/
public static final String SCHEMAGEN_CREATE_TARGET = "jakarta.persistence.schema-generation.create-target";
/**
* The provider-generated SQL script which drops the schema
* when {@value SCHEMAGEN_SCRIPTS_ACTION} is set.
*/
public static final String SCHEMAGEN_DROP_TARGET = "jakarta.persistence.schema-generation.drop-target";

/**
* An instance of {@code jakarta.validation.ValidatorFactory},
*/
public static final String VALIDATION_FACTORY = "jakarta.persistence.validation.factory";
/**
* Target groups for validation at {@link PrePersist}.
*/
public static final String VALIDATION_GROUP_PRE_PERSIST = "jakarta.persistence.validation.group.pre-persist";
/**
* Target groups for validation at {@link PreUpdate}.
*/
public static final String VALIDATION_GROUP_PRE_UPDATE = "jakarta.persistence.validation.group.pre-update";
/**
* Target groups for validation at {@link PreRemove}.
*/
public static final String VALIDATION_GROUP_PRE_REMOVE = "jakarta.persistence.validation.group.pre-remove";

private final String name;

private String provider;
private String jtaDataSource;
private String nonJtaDataSource;
Expand All @@ -76,27 +188,35 @@ public class PersistenceConfiguration {
private ValidationMode validationMode = ValidationMode.AUTO;
private PersistenceTransactionType transactionType = PersistenceTransactionType.RESOURCE_LOCAL;

private List<Class<?>> managedClasses = new ArrayList<>();
private List<String> mappingFileNames = new ArrayList<>();
private Map<String,Object> properties = new HashMap<>();
private final List<Class<?>> managedClasses = new ArrayList<>();
private final List<String> mappingFileNames = new ArrayList<>();
private final Map<String,Object> properties = new HashMap<>();

/**
* Create a new {@link EntityManagerFactory} based on this configuration.
* @throws IllegalStateException if required configuration is missing
* Create a new empty configuration. An empty configuration does not
* typically hold enough information for successful invocation of
* {@link #createEntityManagerFactory()}.
*
* @param name the name of the persistence unit, which may be used by
* the persistence provider for logging and error reporting
*/
public EntityManagerFactory createEntityManagerFactory() {
return Persistence.createEntityManagerFactory(this);
public PersistenceConfiguration(String name) {
Objects.requireNonNull(name, "Persistence unit name should not be null");
this.name = name;
}

/**
* Specify the name of the persistence unit.
* Create a new {@link EntityManagerFactory} based on this configuration.
* @throws PersistenceException if required configuration is missing or
* if the factory could not be created
*/
public PersistenceConfiguration name(String name) {
this.name = name;
return this;
public EntityManagerFactory createEntityManagerFactory() {
return Persistence.createEntityManagerFactory(this);
}

/**
* The name of the persistence unit, which may be used by the persistence
* provider for logging and error reporting.
* @return the name of the persistence unit.
*/
public String name() {
Expand All @@ -114,6 +234,8 @@ public PersistenceConfiguration provider(String providerClassName) {
}

/**
* The fully-qualified name of a concrete class implementing
* {@link jakarta.persistence.spi.PersistenceProvider}.
* @return the qualified name of the persistence provider class.
*/
public String provider() {
Expand All @@ -131,7 +253,8 @@ public PersistenceConfiguration jtaDataSource(String dataSourceJndiName) {
}

/**
* @return the configured JTA datasource, if any
* The JNDI name of a JTA {@code javax.sql.DataSource}.
* @return the configured JTA datasource, if any, or null
*/
public String jtaDataSource() {
return jtaDataSource;
Expand All @@ -148,15 +271,17 @@ public PersistenceConfiguration nonJtaDataSource(String dataSourceJndiName) {
}

/**
* @return the configured non-JTA datasource, if any
* The JNDI name of a non-JTA {@code javax.sql.DataSource}.
* @return the configured non-JTA datasource, if any, or null
*/
public String nonJtaDataSource() {
return nonJtaDataSource;
}

/**
* Add a managed class (an {@link Entity}, {@link Embeddable}, or
* {@link MappedSuperclass}) to the configuration.
* Add a managed class (an {@link Entity}, {@link Embeddable},
* {@link MappedSuperclass}, or {@link Converter}) to the
* configuration.
* @param managedClass the managed class
* @return this configuration
*/
Expand All @@ -166,14 +291,17 @@ public PersistenceConfiguration managedClass(Class<?> managedClass) {
}

/**
* The configured managed classes, that is, a list of classes
* annotated {@link Entity}, {@link Embeddable},
* {@link MappedSuperclass}, or {@link Converter}.
* @return all configured managed classes
*/
public List<Class<?>> managedClasses() {
return managedClasses;
}

/**
* Add an {@code orm.xml} mapping file name to the configuration.
* Add an XML mapping file name to the configuration.
* @param name the file path of the mapping file
* @return this configuration
*/
Expand All @@ -183,6 +311,7 @@ public PersistenceConfiguration mappingFile(String name) {
}

/**
* The configured XML mapping files.
* @return all configured mapping file names
*/
public List<String> mappingFiles() {
Expand All @@ -200,6 +329,16 @@ public PersistenceConfiguration transactionType(PersistenceTransactionType trans
}

/**
* The {@linkplain PersistenceTransactionType transaction type}.
* <ul>
* <li>If {@link PersistenceTransactionType#JTA}, a JTA data
* source must be provided via {@link #jtaDataSource()},
* or by the container.
* <li>If {@link PersistenceTransactionType#RESOURCE_LOCAL},
* database connection properties may be specified via
* {@link #properties()}, or a non-JTA datasource may be
* provided via {@link #nonJtaDataSource()}.
* </ul>
* @return the transaction type
*/
public PersistenceTransactionType transactionType() {
Expand All @@ -217,6 +356,8 @@ public PersistenceConfiguration sharedCacheMode(SharedCacheMode sharedCacheMode)
}

/**
* The shared cache mode. The default behavior is unspecified
* and {@linkplain SharedCacheMode#UNSPECIFIED provider-specific}.
* @return the shared cache mode
*/
public SharedCacheMode sharedCacheMode() {
Expand All @@ -234,6 +375,7 @@ public PersistenceConfiguration validationMode(ValidationMode validationMode) {
}

/**
* The validation mode, {@link ValidationMode#AUTO} by default.
* @return the validation mode
*/
public ValidationMode validationMode() {
Expand Down Expand Up @@ -262,6 +404,7 @@ public PersistenceConfiguration properties(Map<String,?> properties) {
}

/**
* Standard and vendor-specific property settings.
* @return the configured properties
*/
public Map<String, Object> properties() {
Expand Down
1 change: 0 additions & 1 deletion api/src/main/java/jakarta/persistence/SharedCacheMode.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,6 @@ public enum SharedCacheMode {
DISABLE_SELECTIVE,

/**
*
* Caching behavior is undefined: provider-specific defaults may apply.
*/
UNSPECIFIED
Expand Down
1 change: 1 addition & 0 deletions api/src/main/java/jakarta/persistence/spi/PersistenceProvider.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
*/

// Contributors:
// Gavin King - 3.2
// Linda DeMichiel - 2.1
// Linda DeMichiel - 2.0

Expand Down
6 changes: 6 additions & 0 deletions spec/src/main/asciidoc/ch09-container-provider-contracts.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1504,6 +1504,12 @@ environment.footnote:[Persistence units defined programmatically using the
_PersistenceConfiguration_ class do not support JNDI lookup or injection via
the _PersistenceContext_ or _PersistenceUnit_ annotations.]

A persistence provider may define a subclass of _PersistenceConfiguration_
with vendor-specific configuration options. A provider must support
configuration via any instance of _PersistenceConfiguration_ or of any
subclass of _PersistenceConfiguration_. If a subclass defines configuration
options the provider does not recognize, it should ignore those options.

=== PersistenceUtil Interface

This interface is used to determine load
Expand Down

0 comments on commit f89b60c

Please sign in to comment.