001// Copyright 2011, 2014 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007// http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry5.jpa;
016
017import javax.persistence.SharedCacheMode;
018import javax.persistence.ValidationMode;
019import javax.persistence.spi.PersistenceUnitInfo;
020import javax.persistence.spi.PersistenceUnitTransactionType;
021import java.net.URL;
022import java.util.Map;
023
024/**
025 * Tapestry's mutable extension of {@link PersistenceUnitInfo} interface used for XML-less configuration
026 * of persistence units.
027 *
028 * @since 5.3
029 */
030public interface TapestryPersistenceUnitInfo extends PersistenceUnitInfo
031{
032    /**
033     * Set the the fully qualified name of the persistence provider implementation class.
034     * Corresponds to the <code>provider</code> element in the <code>persistence.xml</code> file.
035     *
036     * @param persistenceProviderClassName
037     *         persistence provider's class name
038     */
039    TapestryPersistenceUnitInfo persistenceProviderClassName(String persistenceProviderClassName);
040
041    /**
042     * Set the transaction type of the entity managers. Corresponds to
043     * the <code>transaction-type</code> attribute in the <code>persistence.xml</code> file.
044     *
045     * @param transactionType
046     *         transition type to set
047     */
048    TapestryPersistenceUnitInfo transactionType(PersistenceUnitTransactionType transactionType);
049
050    /**
051     * Set the non-JTA-enabled data source to be used by the persistence provider for accessing data outside a JTA
052     * transaction. Corresponds to the named <code>non-jta-data-source</code> element in the
053     * <code>persistence.xml</code> file.
054     *
055     * @param nonJtaDataSource
056     *         data source to set
057     */
058    TapestryPersistenceUnitInfo nonJtaDataSource(String nonJtaDataSource);
059
060    /**
061     * Set the JTA-enabled data source to be used by the persistence provider for accessing data outside a JTA
062     * transaction. Corresponds to the named <code>jta-data-source</code> element in the
063     * <code>persistence.xml</code> file.
064     *
065     * @param jtaDataSource
066     *         data source to set
067     */
068    TapestryPersistenceUnitInfo jtaDataSource(String jtaDataSource);
069
070    /**
071     * Add a managed class name to be used by persistence provider.
072     * Corresponds to a named <code>class</code> element in the <code>persistence.xml</code> file.
073     *
074     * @param className
075     *         class name to add
076     * @see #addManagedClass(Class)
077     */
078    TapestryPersistenceUnitInfo addManagedClassName(String className);
079
080    /**
081     * Add a managed class to be used by persistence provider.
082     * Corresponds to a named <code>class</code> element in the <code>persistence.xml</code> file.
083     *
084     * @param clazz
085     *         class to add
086     * @see #addManagedClassName(String)
087     */
088    TapestryPersistenceUnitInfo addManagedClass(Class<?> clazz);
089
090    /**
091     * Defines how the persistence provider must use a second-level cache for the persistence unit.
092     * Corresponds to the <code>shared-cache-mode</code> element in the <code>persistence.xml</code> file.
093     *
094     * @param cacheMode
095     *         cache mode to set
096     */
097    TapestryPersistenceUnitInfo sharedCacheMode(SharedCacheMode cacheMode);
098
099    /**
100     * Set the validation mode to be used by the persistence provider for the persistence unit.
101     * Corresponds to the <code>validation-mode</code> element in the <code>persistence.xml</code> file.
102     *
103     * @param validationMode
104     *         validation mode to set
105     */
106    TapestryPersistenceUnitInfo validationMode(ValidationMode validationMode);
107
108    /**
109     * Add a mapping file to be loaded by the persistence provider to determine the mappings for
110     * the entity classes. Corresponds to a <code>mapping-file</code> element in the <code>persistence.xml</code> file.
111     *
112     * @param fileName
113     *         mapping file name to add
114     */
115    TapestryPersistenceUnitInfo addMappingFileName(String fileName);
116
117    /**
118     * Add a URLs for the jar file or exploded jar file directory that the persistence provider must examine
119     * for managed classes of the persistence unit. Corresponds to a <code>jar-file</code> element in the
120     * <code>persistence.xml</code> file.
121     *
122     * @param url
123     *         url to add
124     */
125    TapestryPersistenceUnitInfo addJarFileUrl(URL url);
126
127    /**
128     * Add a URLs for the jar file or exploded jar file directory that the persistence provider must examine
129     * for managed classes of the persistence unit. Corresponds to a <code>jar-file</code> element in the
130     * <code>persistence.xml</code> file.
131     *
132     * @param url
133     *         url to add
134     */
135    TapestryPersistenceUnitInfo addJarFileUrl(String url);
136
137    /**
138     * Add a property. Corresponds to a <code>property</code> element in the <code>persistence.xml</code> file.
139     *
140     * @param name
141     *         property's name
142     * @param value
143     *         property's value
144     */
145    TapestryPersistenceUnitInfo addProperty(String name, String value);
146
147    /**
148     * Defines whether classes in the root of the persistence unit that have not been explicitly listed
149     * are to be included in the set of managed classes. Corresponds to the <code>exclude-unlisted-classes</code>
150     * element in the <code>persistence.xml</code> file.
151     *
152     * @param exclude
153     *         defines whether to exclude or not
154     */
155    TapestryPersistenceUnitInfo excludeUnlistedClasses(boolean exclude);
156
157    /**
158     * {@link javax.persistence.spi.PersistenceProvider} allows creating an {@link javax.persistence.EntityManagerFactory}
159     * with a default EntityManager properties map. This operation allows contributing default properties for
160     * EntityManager.
161     *
162     * @param properties
163     *         properties to initialize EntityManagerFactory with
164     *         @since 5.4
165     */
166    TapestryPersistenceUnitInfo setEntityManagerProperties(Map properties);
167
168    /**
169     * @return Returns the supplied EntityManagerFactory properties. Returns null if not set.
170     * @since 5.4
171     */
172    Map getEntityManagerProperties();
173}