/*******************************************************************************
* Copyright (c) 1998, 2015 Oracle and/or its affiliates. All rights reserved.
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
* which accompanies this distribution.
* The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
* and the Eclipse Distribution License is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*
* Contributors:
* 06/08/2008-1.0M9 Andrei Ilitchev
* - New file introduced for bug 235433: Can't customize ConnectionPolicy through JPA.
******************************************************************************/
package org.eclipse.persistence.config;
/**
*
* This property could be specified while creating either EntityManagerFactory
* (createEntityManagerFactory or persistence.xml)
* or EntityManager (createEntityManager); the latter overrides the former.
*
* The "isolated case" mentioned below is the case of some (or all) entities requiring isolated cache.
* That could be achieved either by specifying the property for one or more entities:
* eclipselink.cache.shared.Employee {@literal ->} "false"
* or for all entities:
* eclipselink.cache.shared.default {@literal ->} "false"
* Note that this property(es) could be specified only on persistence unit level (cannot be passed to createEntityManager method).
*
* <p>JPA persistence property Usage:
*
* <p><code>properties.add(PersistenceUnitProperties.EXCLUSIVE_CONNECTION_MODE, ExclusiveConnectionMode.Isolated);</code>
*
* <p>Values are case-insensitive.
* "" could be used instead of default value ExclusiveConnectionMode.DEFAULT.
*
* @see PersistenceUnitProperties
*/
public class ExclusiveConnectionMode {
/**
* The value causes creation of
* IsolatedClientSession in isolated case
* and ClientSession otherwise.
* Connection is kept exclusive for the duration of Eclipselink transaction.
* Inside Eclipselink transaction all writes and reads performed through the exclusive connection.
* Outside Eclipselink transaction a new connection is acquired from connection pool
* for each read and released back immediately after the query is executed.
*
* Note that Eclipselink transaction usually starts later then JTA transaction does,
* or entityManager.beginTransaction method is called: Eclipselink usually waits until
* it's about to perform a query that potentially alters data base's state to start
* Exclipselink transaction. That reflects in connection usage in Transactional mode.
* Example:
* // Eclipselink transaction is not started yet - readQuery1 acquires and immediately releases connection.
* readQuery1.getResultList();
* entityManager.getTransaction().begin();
* // Eclipselink transaction still not started yet - readQuery2 acquires and immediately releases connection.
* readQuery2.getResultList();
* entityManager.persist(new Employee());
* // Eclipselink transaction is not started yet - readQuery3 acquires and immediately releases connection.
* readQuery3.getResultList();
* entityManager.flush();
* // Before the flushing is performed Exclipselink transaction is started:
* // connection is acquired that will be kept until the end of transaction and used for all reads and writes.
* readQuery4.getResultList();
* entityManager.commit();
* // Eclipselink transaction is completed, the connection used by Eclipselink transaction is released;
* // readQuery5 acquires and immediately releases connection.
* readQuery5.getResultList();
*
* There's a way to force beginning of Eclipselink transaction right before executing the first query after em.getTransaction().begin():
* "eclipselink.transaction.join-existing" {@literal ->} true.
* In the example that setting would force Exclipselink transaction top begin right before readQuery2 is executed
* and therefore cause execution of readQuery2 and readQuery3 through the exclusive connection
* (of course the same connection would be used by readQuery4 and flush, too).
* However this approach could hardly be recommended:
* none of the objects read after Eclipselink transaction begins
* get into the shared cache unless altered therefore seriously reducing benefits of Eclipselink shared cache.
*/
public static final String Transactional = "Transactional";
/**
* The value causes creation of
* ExclusiveIsolatedClientSession in isolated case
* and throws exception otherwise.
* Connection is kept exclusive for the whole lifetime of the owning EntityManager.
* Inside Eclipselink transaction all writes and reads performed through the exclusive connection.
* Outside Eclipelink transaction only isolated entities are read through the exclusive connection;
* for non isolated entities a new connection is acquired from connection pool
* for each read and released back immediately after the query is executed.
*
* In the example presented above all five readQueries
* would read isolated entity through the exclusive connection,
* however non-isolated entity would be read the same as in Transactional mode.
*/
public static final String Isolated = "Isolated";
/**
* The value causes creation of ExclusiveIsolatedClientSession
* in both isolated and non-isolated cases.
* Connection is kept exclusive for the whole lifetime of the owning EntityManager.
* All writes and reads performed through the exclusive connection.
*
* In the example presented above all five readQueries
* would read all entity through the exclusive connection.
*
* Note that though all entities use the exclusive connection
* only isolated entities use isolated cache; non-isolated entities use shared cache.
*/
public static final String Always = "Always";
public static final String DEFAULT = Transactional;
}