| = Aries Transaction Control JPA Provider (Local) |
| |
| The Aries Local JPA provider implementation is available at the following maven coordinates: |
| |
| <dependency> |
| <groupId>org.apache.aries.tx-control</groupId> |
| <artifactId>tx-control-provider-jpa-local</artifactId> |
| <version>${aries.tx.control.version}</version> |
| </dependency> |
| |
| This module is a prototype implementation of the OSGi Transaction Control JPA resource provider using Local transactions. |
| It supports JPA 2.1, and is tested against Hibernate 5.0.9 and EclipseLink 2.6.0. |
| It also supports JPA 2.0, and is tested against OpenJPA 2.4.1. |
| |
| == Quick Start |
| |
| A configured `JPAEntityManagerProvider` can be created quickly using Configuration Admin, the OSGi JPA Service, and the OSGi JDBC Service. |
| |
| . Package the persistence unit in a persistence bundle |
| . Find and install a JPA provider (for example Hibernate) |
| . Find and install a JDBC Service implementation for your chosen database (e.g. |
| the org.h2 bundle for H2) |
| . Install a JPA service extender, such as the Apache Aries JPA container |
| . Create a factory configuration using the factory pid `org.apache.aries.tx.control.jpa.local` and add the following properties: |
| ** _osgi.jdbc.driver.class_ :- The driver class name for your database(e.g. |
| org.h2.Driver) |
| ** _url_ :- The JDBC URL to use to connect to the database |
| ** _osgi.unit.name_ :- The name of the persistence unit |
| |
| When the DataSourceFactory for the named `osgi.jdbc.driver.class` and the `EntityManagerFactoryBuilder` for the named `osgi.unit.name` become available the Local JPA Resource Provider will create a JPAEntityManagerProvider and register it in the OSGi service registry. |
| All configuration properties (apart from the database password) will be registered as properties of the JPAEntityManagerProvider service. |
| These properties can be used to select a ResourceProvider if more than one is present in the Service Registry. |
| |
| == When should I use this module? |
| |
| If you wish to use entirely lightweight, resource-local transactions then it is best to pair this module with the `tx-control-service-local` bundle. |
| |
| If two-phase commit is needed across multiple resources then the `tx-control-service-xa` and `tx-control-provider-jpa-xa` bundles should be used. |
| |
| == Using the JPA Provider bundle |
| |
| This Resource Provider is used in conjunction with a TransactionControl service to provide scoped access to a JPA EntityManager. |
| |
| == Prerequisites |
| |
| In order to use scoped JPA access the runtime must contain a JPA provider (for example Hibernate), an implementation of the OSGi JPA service (e.g. |
| Aries JPA), and a persistence bundle. |
| |
| === Suitable Persistence bundles |
| |
| OSGi Persistence bundles contain the persistence descriptor (typically an XML file called META-INF/persistence.xml), all of the JPA Entities, and a Meta-Persistence header pointing at the persistence descriptor. |
| (See the JPA service specification for more details). |
| |
| Unlike "normal" JPA it is usually best not to fully declare the persistence unit in the persistence descriptor. |
| In particular it is a good idea to avoid putting any database configuration in the persistence unit. |
| By not configuring the database inside the bundle the persistence unit remains decoupled, and can be reconfigured for any database at runtime. |
| |
| For example the following persistence unit: |
| |
| <persistence-unit name="test-unit"/> |
| |
| can be reconfigured to use any database and to create/drop tables as appropriate. |
| Configuration for the persistence unit can be provided using Configuration Admin and the EntityManagerFactoryBuilder. |
| |
| == Creating a resource programmatically |
| |
| Preparing a resource for use is very simple. |
| Create a JPAEntityManagerProvider using the the JPAEntityManagerProviderFactory, then connect the provider to a TransactionControl service. |
| This will return a thread-safe JPA EntityManager that can then be used in any ongoing scoped work. |
| |
| The normal inputs to a JPAEntityManagerProviderFactory are an EntityManagerFactoryBuilder, some JPA properties to connect to the database with, and some properties to control the resource provider. |
| |
| === Declarative Services Example |
| |
| .... |
| @Component |
| public class TransactionalJPAComponent { |
| @Reference |
| TransactionControl txControl; |
| |
| @Reference |
| DataSourceFactory dsf; |
| |
| @Reference |
| EntityManagerFactoryBuilder emfb; |
| |
| @Reference |
| JPAEntityManagerProviderFactory providerFactory; |
| |
| EntityManager em; |
| |
| @Activate |
| void start(Config config) { |
| |
| Properties jdbcProps = new Properties(); |
| jdbcProps.put(JDBC_URL, config.url()); |
| jdbcProps.put(JDBC_USER, config.user()); |
| jdbcProps.put(JDBC_PASSWORD, config._password()); |
| |
| Map<String, Object> jpaProps = new HashMap<>(); |
| jpaProps.put("javax.persistence.nonJtaDataSource", |
| dsf.createDataSource(jdbcProps)); |
| |
| em = providerFactory.getProviderFor(emfb, jpaProps, |
| null).getResource(txControl); |
| } |
| |
| public void findUserName(String id) { |
| txControl.required(() -> { |
| // Use the EntityManager in here |
| }); |
| } } |
| .... |
| |
| If the JPA EntityManagerFactory is already configured then it can be passed into the JPAEntityManagerProviderFactory instead of an EntityManagerFactoryBuilder and JPA configuration. |
| |
| == Creating a resource using a factory configuration |
| |
| Whilst it is simple to use a EntityManagerFactoryBuilder it does require some lifecycle code to be written. |
| It is therefore possible to directly create JPA resources using factory configurations. |
| When created, the factory service will listen for an applicable EntityManagerFactoryBuilder and potentially also a DataSourceFactory. |
| Once suitable services are available then a JPAEntityManagerProvider service will be published. |
| |
| Configuration properties (except the JPA/JDBC password) are set as service properties for the registered JPAEntityManagerProvider. |
| These properties may therefore be used in filters to select a particular provider. |
| |
| .... |
| @Component |
| public class TransactionalJDBCComponent { |
| @Reference |
| TransactionControl control; |
| |
| EntityManager em; |
| |
| @Reference(target="(osgi.unit.name=test-unit)") |
| void setProvider(JPAEntityManagerProvider provider) { |
| em = provider.getResource(control); |
| } |
| |
| public void findUserName(String id) { |
| txControl.required(() -> { |
| // Use the connection in here |
| }); |
| } } |
| .... |
| |
| The factory pid is _org.apache.aries.tx.control.jpa.local_ and it may use the following properties (all optional aside from _osgi.unit.name_): |
| |
| === Resource Provider properties |
| |
| * _osgi.unit.name_ : The name of the persistence unit that this configuration relates to. |
| * _aries.emf.builder.target.filter_ : The target filter to use when searching for an EntityManagerFactoryBuilder. |
| If not specified then any builder for the named persistence unit will be used. |
| * _aries.jpa.property.names_ : The names of the properties to pass to the EntityManagerFactoryBuilder when creating the EntityManagerFactory. |
| By default all properties are copied. |
| * _aries.dsf.target.filter_ : The target filter to use when searching for a DataSourceFactory. |
| If not specified then _osgi.jdbc.driver.class_ must be specified. |
| * _aries.jdbc.property.names_ : The names of the properties to pass to the DataSourceFactory when creating the JDBC resources. |
| * _osgi.jdbc.driver.class_ : Used to locate the DataSourceFactory service if the _aries.dsf.target.filter_ is not set. |
| * _osgi.local.enabled_ : Defaults to true. |
| If false then resource creation will fail |
| * _osgi.xa.enabled_ : Defaults to false. |
| If true then resource creation will fail |
| * _osgi.connection.pooling.enabled_ : Defaults to true. |
| If true then the Database connections will be pooled. |
| * _osgi.connection.max_ : Defaults to 10. |
| The maximum number of connections that should be kept in the pool |
| * _osgi.connection.min_ : Defaults to 10. |
| The minimum number of connections that should be kept in the pool |
| * _osgi.connection.timeout_ : Defaults to 30,000 (30 seconds). |
| The maximum time in milliseconds to block when waiting for a database connection |
| * _osgi.idle.timeout_ : Defaults to 180,000 (3 minutes). |
| The time in milliseconds before an idle connection is eligible to be closed. |
| * _osgi.connection.timeout_ : Defaults to 10,800,000 (3 hours). |
| The maximum time in milliseconds that a connection may remain open before being closed. |
| * _osgi.use.driver_ : Defaults to false. |
| If true then use the createDriver method to connect to the database. |
| |
| === JDBC properties |
| |
| The following properties will automatically be passed to the DataSourceFactory if they are present. |
| The list of properties may be overridden using the _aries.jdbc.property.names_ property if necessary. |
| |
| * _databaseName_ : The name of the database |
| * _dataSourceName_ : The name of the dataSource that will be created |
| * _description_ : A description of the dataSource being created |
| * _networkProtocol_ : The network protocol to use. |
| * _portNumber_ : The port number to use |
| * _roleName_ : The name of the JDBC role |
| * _serverName_ : The name of the database server |
| * _url_ : The JDBC url to use (often used instead of other properties such as _serverName_, _portNumber_ and _databaseName_). |
| * _user_ : The JDBC user |
| * _password_ : The JDBC password |
| |
| === JPA properties |
| |
| The following properties are potentially useful when configuring JPA: |
| |
| _javax.persistence.schema-generation.database.action_ : May be used to automatically create the database tables (see the OSGi spec) |
| |
| * Other provider specific properties, for example configuring second-level caching. |