001// Copyright 2011 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 java.net.URL;
018import java.util.Map;
019
020import javax.persistence.SharedCacheMode;
021import javax.persistence.ValidationMode;
022import javax.persistence.spi.PersistenceUnitInfo;
023import javax.persistence.spi.PersistenceUnitTransactionType;
024
025/**
026 * Tapestry's mutable extension of {@link PersistenceUnitInfo} interface used for XML-less configuration
027 * of persistence units.
028 *
029 * @since 5.3
030 */
031public interface TapestryPersistenceUnitInfo extends PersistenceUnitInfo
032{
033    /**
034     * Set the the fully qualified name of the persistence provider implementation class.
035     * Corresponds to the <code>provider</code> element in the <code>persistence.xml</code> file.
036     *
037     * @param persistenceProviderClassName
038     *         persistence provider's class name
039     */
040    TapestryPersistenceUnitInfo persistenceProviderClassName(String persistenceProviderClassName);
041
042    /**
043     * Set the transaction type of the entity managers. Corresponds to
044     * the <code>transaction-type</code> attribute in the <code>persistence.xml</code> file.
045     *
046     * @param transactionType
047     *         transition type to set
048     */
049    TapestryPersistenceUnitInfo transactionType(PersistenceUnitTransactionType transactionType);
050
051    /**
052     * Set the non-JTA-enabled data source to be used by the persistence provider for accessing data outside a JTA
053     * transaction. Corresponds to the named <code>non-jta-data-source</code> element in the
054     * <code>persistence.xml</code> file.
055     *
056     * @param nonJtaDataSource
057     *         data source to set
058     */
059    TapestryPersistenceUnitInfo nonJtaDataSource(String nonJtaDataSource);
060
061    /**
062     * Set the JTA-enabled data source to be used by the persistence provider for accessing data outside a JTA
063     * transaction. Corresponds to the named <code>jta-data-source</code> element in the
064     * <code>persistence.xml</code> file.
065     *
066     * @param jtaDataSource
067     *         data source to set
068     */
069    TapestryPersistenceUnitInfo jtaDataSource(String jtaDataSource);
070
071    /**
072     * Add a managed class name to be used by persistence provider.
073     * Corresponds to a named <code>class</code> element in the <code>persistence.xml</code> file.
074     *
075     * @param className
076     *         class name to add
077     * @see #addManagedClass(Class)
078     */
079    TapestryPersistenceUnitInfo addManagedClassName(String className);
080
081    /**
082     * Add a managed class to be used by persistence provider.
083     * Corresponds to a named <code>class</code> element in the <code>persistence.xml</code> file.
084     *
085     * @param clazz
086     *         class to add
087     * @see #addManagedClassName(String)
088     */
089    TapestryPersistenceUnitInfo addManagedClass(Class<?> clazz);
090
091    /**
092     * Defines how the persistence provider must use a second-level cache for the persistence unit.
093     * Corresponds to the <code>shared-cache-mode</code> element in the <code>persistence.xml</code> file.
094     *
095     * @param cacheMode
096     *         cache mode to set
097     */
098    TapestryPersistenceUnitInfo sharedCacheMode(SharedCacheMode cacheMode);
099
100    /**
101     * Set the validation mode to be used by the persistence provider for the persistence unit.
102     * Corresponds to the <code>validation-mode</code> element in the <code>persistence.xml</code> file.
103     *
104     * @param validationMode
105     *         validation mode to set
106     */
107    TapestryPersistenceUnitInfo validationMode(ValidationMode validationMode);
108
109    /**
110     * Add a mapping file to be loaded by the persistence provider to determine the mappings for
111     * the entity classes. Corresponds to a <code>mapping-file</code> element in the <code>persistence.xml</code> file.
112     *
113     * @param fileName
114     *         mapping file name to add
115     */
116    TapestryPersistenceUnitInfo addMappingFileName(String fileName);
117
118    /**
119     * Add a URLs for the jar file or exploded jar file directory that the persistence provider must examine
120     * for managed classes of the persistence unit. Corresponds to a <code>jar-file</code> element in the
121     * <code>persistence.xml</code> file.
122     *
123     * @param url
124     *         url to add
125     */
126    TapestryPersistenceUnitInfo addJarFileUrl(URL url);
127
128    /**
129     * Add a URLs for the jar file or exploded jar file directory that the persistence provider must examine
130     * for managed classes of the persistence unit. Corresponds to a <code>jar-file</code> element in the
131     * <code>persistence.xml</code> file.
132     *
133     * @param url
134     *         url to add
135     */
136    TapestryPersistenceUnitInfo addJarFileUrl(String url);
137
138    /**
139     * Add a property. Corresponds to a <code>property</code> element in the <code>persistence.xml</code> file.
140     *
141     * @param name
142     *         property's name
143     * @param value
144     *         property's value
145     */
146    TapestryPersistenceUnitInfo addProperty(String name, String value);
147
148    /**
149     * Defines whether classes in the root of the persistence unit that have not been explicitly listed
150     * are to be included in the set of managed classes. Corresponds to the <code>exclude-unlisted-classes</code>
151     * element in the <code>persistence.xml</code> file.
152     *
153     * @param exclude
154     *         defines whether to exclude or not
155     */
156    TapestryPersistenceUnitInfo excludeUnlistedClasses(boolean exclude);
157
158    /**
159     * {@link javax.persistence.spi.PersistenceProvider} allows creating an {@alink javax.persistence.EntityManagerFactory}
160     * with a default EntityManager properties map. This operation allows contributing default properties for
161     * EntityManager.
162     *
163     * @param properties
164     *         properties to initialize EntityManagerFactory with
165     */
166    TapestryPersistenceUnitInfo setEntityManagerProperties(Map properties);
167
168    /**
169     * @return Returns the supplied EntityManagerFactory properties. Returns null if not set
170     */
171    Map getEntityManagerProperties();
172}