001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036:
037: package javax.persistence.spi;
038:
039: import javax.sql.DataSource;
040: import java.net.URL;
041: import java.util.List;
042: import java.util.Properties;
043:
044: /**
045: * Interface implemented by the container and used by the persistence provider
046: * when creating an {@link javax.persistence.EntityManagerFactory}.
047: *
048: * @since Java Persistence 1.0
049: */
050: public interface PersistenceUnitInfo {
051: /**
052: * Returns the name of the persistence unit. Corresponds to the name attribute
053: * in the persistence.xml file.
054: * @return The name of the persistence unit. Corresponds to the name attribute
055: * in the persistence.xml file.
056: */
057: public String getPersistenceUnitName();
058:
059: /**
060: * Returns the fully qualified name of the persistence provider
061: * implementation class. Corresponds to the <provider> element in
062: * the persistence.xml file.
063: * @return The fully qualified name of the persistence provider
064: * implementation class. Corresponds to the <provider> element in
065: * the persistence.xml file.
066: */
067: public String getPersistenceProviderClassName();
068:
069: /**
070: * Returns the transaction type of the entity managers created by the
071: * EntityManagerFactory. The transaction type corresponds to the
072: * transaction-type attribute in the persistence.xml file.
073: * @return The transaction type of the entity managers created by the
074: * EntityManagerFactory. The transaction type corresponds to the
075: * transaction-type attribute in the persistence.xml file.
076: */
077: public PersistenceUnitTransactionType getTransactionType();
078:
079: /**
080: * Returns the JTA-enabled data source to be used by the persistence
081: * provider. The data source corresponds to the <jta-data-source>
082: * element in the persistence.xml file or is provided at deployment
083: * or by the container.
084: * @return the JTA-enabled data source to be used by the persistence
085: * provider. The data source corresponds to the <jta-data-source>
086: * element in the persistence.xml file or is provided at deployment
087: * or by the container.
088: */
089: public DataSource getJtaDataSource();
090:
091: /**
092: * Returns the non-JTA-enabled data source to be used by the persistence
093: * provider for accessing data outside a JTA transaction. The data
094: * source corresponds to the named <non-jta-data-source> element in
095: * the persistence.xml file or provided at deployment or by the
096: * container.
097: * @return The non-JTA-enabled data source to be used by the persistence
098: * provider for accessing data outside a JTA transaction. The data
099: * source corresponds to the named <non-jta-data-source> element in
100: * the persistence.xml file or provided at deployment or by the
101: * container.
102: */
103: public DataSource getNonJtaDataSource();
104:
105: /**
106: * Returns the list of mapping file names that the persistence provider must
107: * load to determine the mappings for the entity classes. The
108: * mapping files must be in the standard XML mapping format, be
109: * uniquely named and be resource-loadable from the application
110: * classpath. This list will not include the orm.xml file if one was
111: * specified. Each mapping file name corresponds to a <mapping-file>
112: * element in the persistence.xml file.
113: * @return The list of mapping file names that the persistence provider must
114: * load to determine the mappings for the entity classes. The
115: * mapping files must be in the standard XML mapping format, be
116: * uniquely named and be resource-loadable from the application
117: * classpath. This list will not include the orm.xml file if one was
118: * specified. Each mapping file name corresponds to a <mapping-file>
119: * element in the persistence.xml file.
120: */
121: public List<String> getMappingFileNames();
122:
123: /**
124: * Returns a list of URLs for the jar files or exploded jar
125: * file directories that the persistence provider must examine
126: * for managed classes of the persistence unit. Each URL
127: * corresponds to a named <jar-file> element in the
128: * persistence.xml file. A URL will either be a file:
129: * URL referring to a jar file or referring to a directory
130: * that contains an exploded jar file, or some other URL from
131: * which an InputStream in jar format can be obtained.
132: *
133: * @return a list of URL objects referring to jar files or
134: * directories.
135: */
136: public List<URL> getJarFileUrls();
137:
138: /**
139: * Returns the URL for the jar file or directory that is the
140: * root of the persistence unit. (If the persistence unit is
141: * rooted in the WEB-INF/classes directory, this will be the
142: * URL of that directory.)
143: * The URL will either be a file: URL referring to a jar file
144: * or referring to a directory that contains an exploded jar
145: * file, or some other URL from which an InputStream in jar
146: * format can be obtained.
147: *
148: * @return a URL referring to a jar file or directory.
149: */
150: public URL getPersistenceUnitRootUrl();
151:
152: /**
153: * Returns the list of the names of the classes that the persistence
154: * provider must add it to its set of managed classes. Each name
155: * corresponds to a named <class> element in the persistence.xml
156: * file.
157: * @return The list of the names of the classes that the persistence
158: * provider must add it to its set of managed classes. Each name
159: * corresponds to a named <class> element in the persistence.xml
160: * file.
161: */
162: public List<String> getManagedClassNames();
163:
164: /**
165: * Returns whether classes in the root of the persistence unit that have not
166: * been explicitly listed are to be included in the set of managed
167: * classes. This value corresponds to the <exclude-unlisted-classes>
168: * element in the persistence.xml file.
169: * @return Whether classes in the root of the persistence unit that have not
170: * been explicitly listed are to be included in the set of managed
171: * classes. This value corresponds to the <exclude-unlisted-classes>
172: * element in the persistence.xml file.
173: */
174: public boolean excludeUnlistedClasses();
175:
176: /**
177: * Returns properties object. Each property corresponds to a <property>
178: * element in the persistence.xml file
179: * @return Properties object. Each property corresponds to a <property>
180: * element in the persistence.xml file
181: */
182: public Properties getProperties();
183:
184: /**
185: * Returns ClassLoader that the provider may use to load any classes,
186: * resources, or open URLs.
187: * @return ClassLoader that the provider may use to load any classes,
188: * resources, or open URLs.
189: */
190: public ClassLoader getClassLoader();
191:
192: /**
193: * Add a transformer supplied by the provider that will be called for every
194: * new class definition or class redefinition that gets loaded by
195: * the loader returned by the {@link PersistenceUnitInfo#getClassLoader} method. The
196: * transformer has no effect on the result returned by the
197: * {@link PersistenceUnitInfo#getNewTempClassLoader} method. Classes are
198: * only transformed once within the same classloading scope, regardless of
199: * how many persistence units they may be a part of.
200: *
201: * @param transformer A provider-supplied transformer that the Container
202: * invokes at class-(re)definition time
203: */
204: public void addTransformer(ClassTransformer transformer);
205:
206: /**
207: * Return a new instance of a ClassLoader that the provider
208: * may use to temporarily load any classes, resources, or
209: * open URLs. The scope and classpath of this loader is
210: * exactly the same as that of the loader returned by
211: * {@link PersistenceUnitInfo#getClassLoader}. None of the classes loaded
212: * by this class loader will be visible to application
213: * components. The provider may only use this ClassLoader
214: * within the scope of the {@link PersistenceProvider#createContainerEntityManagerFactory}
215: * call.
216: *
217: * @return Temporary ClassLoader with same visibility as current
218: * loader
219: */
220: public ClassLoader getNewTempClassLoader();
221: }
|