Skip to content

Commit

Permalink
define persistence.xml elements for use in dependency injection (#460)
Browse files Browse the repository at this point in the history 
* define how a CDI container should provide native support for Jakarta Persistence

see #377, #456, #309

and just wave hands generically about "dependency injection"

* add qualifier/scope to the new XSD
  • Loading branch information
@gavinking
gavinking authored Feb 28, 2024
1 parent 32ab6cf commit 2840bd8
Show file tree
Hide file tree
Showing 4 changed files with 222 additions and 99 deletions.
19 changes: 19 additions & 0 deletions api/src/main/java/jakarta/persistence/spi/PersistenceUnitInfo.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,25 @@ public interface PersistenceUnitInfo {
*/
String getPersistenceProviderClassName();

/**
* Returns the fully-qualified class name of an annotation annotated
* {@code Scope} or {@code NormalScope}. Corresponds to the {@code scope}
* element in {@code persistence.xml}.
* @return the fully-qualified class name of the scope annotation,
* or null if no scope was explicitly specified
*/
public String getScopeAnnotationName();

/**
* Returns the fully-qualified class names of annotations annotated
* {@code Qualifier}. Corresponds to the {@code qualifier} element in
* {@code persistence.xml}.
* @return the fully-qualified class names of the qualifier annotations,
* or an empty list if no qualifier annotations were explicitly
* specified
*/
public List<String> getQualifierAnnotationNames();

/**
* Returns the transaction type of the entity managers created by
* the {@link EntityManagerFactory}. The transaction type corresponds
Expand Down
26 changes: 26 additions & 0 deletions ...s/jakarta/persistence/persistence_3_1.xsd → ...s/jakarta/persistence/persistence_3_2.xsd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,32 @@

<!-- **************************************************** -->

<xsd:element name="qualifier" type="xsd:string"
minOccurs="0" maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation>

Qualifier annotation class used for dependency injection.

</xsd:documentation>
</xsd:annotation>
</xsd:element>

<!-- **************************************************** -->

<xsd:element name="scope" type="xsd:string"
minOccurs="0">
<xsd:annotation>
<xsd:documentation>

Scope annotation class used for dependency injection.

</xsd:documentation>
</xsd:annotation>
</xsd:element>

<!-- **************************************************** -->

<xsd:element name="jta-data-source" type="xsd:string"
minOccurs="0">
<xsd:annotation>
Expand Down
15 changes: 15 additions & 0 deletions spec/src/main/asciidoc/ch08-entity-packaging.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,21 @@ of `jakarta.persistence.spi.PersistenceProvider`. The `provider` element is
optional, but should be explicitly specified if the application depends on the
use of a particular persistence provider.

===== qualifier [[a12310]]

The `qualifier` element specifies the fully-qualified class name of
an annotation annotated `jakarta.inject.Qualifier`. This qualifier
annotation may be used to disambiguate the persistence unit for the
purposes of dependency injection.

===== scope [[a12311]]

The `scope` element specifies the fully-qualified class name of an
annotation annotated `jakarta.inject.Scope` or
`jakarta.enterprise.context.NormalScope`. This scope annotation may
be used to determine the scope of a persistence context for the
purposes of dependency injection.

===== jta-data-source, non-jta-data-source [[a12302]]

In Jakarta EE environments:
Expand Down
261 changes: 162 additions & 99 deletions spec/src/main/asciidoc/ch09-container-provider-contracts.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -862,6 +862,25 @@ public interface PersistenceUnitInfo {
*/
public String getPersistenceProviderClassName();
/**
* Returns the fully-qualified class name of an annotation annotated
* {@code Scope} or {@code NormalScope}. Corresponds to the {@code scope}
* element in {@code persistence.xml}.
* @return the fully-qualified class name of the scope annotation,
* or null if no scope was explicitly specified
*/
public String getScopeAnnotationName();
/**
* Returns the fully-qualified class names of annotations annotated
* {@code Qualifier}. Corresponds to the {@code qualifier} element in
* {@code persistence.xml}.
* @return the fully-qualified class names of the qualifier annotations,
* or an empty list if no qualifier annotations were explicitly
* specified
*/
public List<String> getQualifierAnnotationNames();
/**
* Returns the transaction type of the entity managers created by
* the <code>EntityManagerFactory</code>. The transaction type corresponds to
Expand Down Expand Up @@ -1377,106 +1396,150 @@ public class Persistence {
}
----

The `properties` argument passed to the
`createEntityManagerFactory` method is used to specify both standard and
vendor-specific properties and hints intended for use in creating the
entity manager factory.

The following properties correspond to the
elements and properties in the `persistence.xml` file. When any of these
properties are specified in the Map parameter passed to the
`createEntityManagerFactory` method, their values override the values of
the corresponding elements and properties in the `persistence.xml` file
for the named persistence unit. They also override any defaults that the
persistence provider might have applied.

* `jakarta.persistence.lock.timeout` — integer
value in milliseconds for pessimistic lock timeout or string
corresponding to integer value. This corresponds to the property of the
same name in the `persistence.xml`, and is a hint only. See <<a2132>>.
* `jakarta.persistence.query.timeout` — integer
value in milliseconds for query timeout or string corresponding to
integer value. This corresponds to the property of the same name in the
`persistence.xml`, and is a hint only. See <<a4391>>.
* `jakarta.persistence.provider` — string
corresponding to the `provider` element in the pe `rsistence.xml`. See
<<a12300>>.
* `jakarta.persistence.transactionType` — string
corresponding to the `transaction-type` attribute in the
`persistence.xml`. See <<a12296>>.
* `jakarta.persistence.jtaDataSource` — string
corresponding to the `jta-data-source` element in the `persistence.xml`.
See <<a12302>>.
* `jakarta.persistence.nonJtaDataSource` —
string corresponding to the `non-jta-data-source` element in the
`persistence.xml`. See <<a12302>>.
* `jakarta.persistence.sharedCache.mode`
— string corresponding to the `shared-cache-mode` element in the
`persistence.xml`. See <<a12380>>.
* `jakarta.persistence.validation.mode` — string
corresponding to the `validation-mode` element in the `persistence.xml`
. The value is " `auto` ", " `callback` ", or " `none` ". See
<<a12382>> and <<a2374>>.
* `jakarta.persistence.validation.group.pre-persist` — string corresponding
to the `jakarta.persistence.validation.group.pre-persist` property in the
`persistence.xml`. See <<a12384>> and <<a2380>>.
* `jakarta.persistence.validation.group.pre-update` — string corresponding
to the `jakarta.persistence.validation.group.pre-update` property in the
`persistence.xml`. See <<a12384>> and <<a2380>>.
* `jakarta.persistence.validation.group.pre-remove` — string corresponding
to the `jakarta.persistence.validation.group.pre-remove` property in the
`persistence.xml`. See <<a12384>> and <<a2380>>.
* `jakarta.persistence.schema-generation.create-script-source` — string
corresponding to the
`jakarta.persistence.schema-generation.create-script-source` property in
the `persistence.xml`. See <<a12384>>.
* `jakarta.persistence.schema-generation.drop-script-source` — string
corresponding to the
`jakarta.persistence.schema-generation.drop-script-source` property in
the `persistence.xml`. See <<a12384>>.
* `jakarta.persistence.sql-load-script-source` —
string corresponding to the `jakarta.persistence.sql-load-script-source`
property in the `persistence.xml`. See <<a12384>>.
* `jakarta.persistence.schema-generation.database.action` — string
corresponding to the
`jakarta.persistence.schema-generation.database.action` property in the
`persistence.xml`. See <<a12384>>.
* `jakarta.persistence.schema-generation.scripts.action` — string
corresponding to the
`jakarta.persistence.schema-generation.scripts.action` property in the
`persistence.xml`. See <<a12384>>.
* `jakarta.persistence.schema-generation.create-source` — string
corresponding to the `jakarta.persistence.schema-generation.create-source`
property in the `persistence.xml`. See <<a12384>>.
* `jakarta.persistence.schema-generation.drop-source` — string corresponding
to the `jakarta.persistence.schema-generation.drop-source` property in
the `persistence.xml`. See <<a12384>>.
* `jakarta.persistence.schema-generation.scripts.create-target` —string
corresponding to the
`jakarta.persistence.schema-generation.scripts.create-target` property in
the `persistence.xml`. See <<a12384>>.
* `jakarta.persistence.schema-generation.scripts.drop-target` — string
corresponding to the
`jakarta.persistence.schema-generation.scripts.drop-target` property in
the `persistence.xml`. See <<a12384>>.

The following additional standard properties
are defined by this specification for the configuration of the entity
manager factory:

* `jakarta.persistence.jdbc.driver` — value is
the fully qualified name of the driver class.
* `jakarta.persistence.jdbc.url` — string
corresponding to the driver-specific URL.
* `jakarta.persistence.jdbc.user` — value is the
username used by database connection.
* `jakarta.persistence.jdbc.password` — value is
the password for database connection validation.
* `jakarta.persistence.dataSource` — value is
instance of `javax.sql.DataSource` to be used for the specified
The `properties` argument passed to the `createEntityManagerFactory`
method is used to specify both standard and vendor-specific properties
and hints intended for use in creating the entity manager factory and
controlling its behavior.

The following properties correspond to the elements and attributes in the
`persistence.xml` file. When any of these properties are specified in the
`Map` parameter passed to the `createEntityManagerFactory` method, their
values override the values of the corresponding elements and attributes
in the `persistence.xml` file for the named persistence unit. They also
override any defaults that the persistence provider might have applied.

[cols="40,10,25,~"]
|===
| Property | Type | Corresponding element in `persistence.xml` | Notes

| `jakarta.persistence.provider`
| `String`
| `provider`
| See <<a12300>>.
| `jakarta.persistence.qualifiers`
| `String[]` | `qualifier`
| See <<a12310>>.
| `jakarta.persistence.scope`
| `String`
| `scope`
| See <<a12310>>.
| `jakarta.persistence.transactionType`
| `String`
| `transaction-type`
| See <<a12296>>.
| `jakarta.persistence.jtaDataSource`
| `String`
| `jta-data-source`
| See <<a12302>>.
| `jakarta.persistence.nonJtaDataSource`
| `String`
| `non-jta-data-source`
| See <<a12302>>.
| `jakarta.persistence.sharedCache.mode`
| `String`
| `shared-cache-mode`
| See <<a12380>>.
| `jakarta.persistence.validation.mode`
| `String`
| `validation-mode`
| Legal values are " `auto` ", " `callback` ", or " `none` ".
See <<a12382>> and <<a2374>>.
|===

The following properties correspond to the properties in the `persistence.xml`
ile. When any of these properties are specified in the `Map` parameter passed
to the `createEntityManagerFactory` method, their values override the values of
the corresponding properties in the `persistence.xml` file for the named
persistence unit. They also override any defaults that the persistence provider
might have applied.

[cols="35,10,35,~"]
|===
| Property | Type | Corresponding property in `persistence.xml` | Notes

| `jakarta.persistence.lock.timeout`
| `Integer` or `String`
| `jakarta.persistence.lock.timeout`
| Hint only.
Value in milliseconds for pessimistic lock timeout.
See <<a2132>>.
| `jakarta.persistence.query.timeout`
| `Integer` or `String`
| `jakarta.persistence.query.timeout`
| Hint only.
Value in milliseconds for query timeout.
See <<a4391>>.
| `jakarta.persistence.validation.group.pre-persist`
| `String`
| `jakarta.persistence.validation.group.pre-persist`
| See <<a12384>> and <<a2380>>.
| `jakarta.persistence.validation.group.pre-update`
| `String`
| `jakarta.persistence.validation.group.pre-update`
| See <<a12384>> and <<a2380>>.
| `jakarta.persistence.validation.group.pre-remove`
| `String`
| `jakarta.persistence.validation.group.pre-remove`
| See <<a12384>> and <<a2380>>.
| `jakarta.persistence.schema-generation.create-script-source`
| `String`
| `jakarta.persistence.schema-generation.create-script-source`
| See <<a12384>>.
| `jakarta.persistence.schema-generation.drop-script-source`
| `String`
| `jakarta.persistence.schema-generation.drop-script-source`
| See <<a12384>>.
| `jakarta.persistence.sql-load-script-source`
| `String`
| `jakarta.persistence.sql-load-script-source`
| See <<a12384>>.
| `jakarta.persistence.schema-generation.database.action`
| `String`
| `jakarta.persistence.schema-generation.database.action`
| See <<a12384>>.
| `jakarta.persistence.schema-generation.scripts.action`
| `String`
| `jakarta.persistence.schema-generation.scripts.action`
| See <<a12384>>.
| `jakarta.persistence.schema-generation.create-source`
| `String`
| `jakarta.persistence.schema-generation.create-source`
| See <<a12384>>.
| `jakarta.persistence.schema-generation.drop-source`
| `String`
| `jakarta.persistence.schema-generation.drop-source`
| See <<a12384>>.
| `jakarta.persistence.schema-generation.scripts.create-target`
| `String`
| `jakarta.persistence.schema-generation.scripts.create-target`
| See <<a12384>>.
| `jakarta.persistence.schema-generation.scripts.drop-target`
| `String`
| `jakarta.persistence.schema-generation.scripts.drop-target`
| See <<a12384>>.
|===

The following additional standard properties are defined by this specification
for the configuration of the entity manager factory:

[cols="40,~"]
|===
| Property | Value

| `jakarta.persistence.jdbc.driver`
| Fully qualified name of the driver class.
| `jakarta.persistence.jdbc.url`
| Driver-specific JDBC URL as a string.
| `jakarta.persistence.jdbc.user`
| Username for database connection.
| `jakarta.persistence.jdbc.password`
| Password for database connection authentication.
| `jakarta.persistence.dataSource`
| Instance of `javax.sql.DataSource` to be used for the specified
persistence unit.
* `jakarta.persistence.validation.factory` —
value is instance of `jakarta.validation.ValidatorFactory`.
| `jakarta.persistence.validation.factory`
| Instance of `jakarta.validation.ValidatorFactory`.
|===

Any number of vendor-specific properties may
also be included in the map. If a persistence provider does not
Expand Down

0 comments on commit 2840bd8

Please sign in to comment.