Package: EntityManagerFactory

EntityManagerFactory

Coverage

1: /*
2: * JOPA
3: * Copyright (C) 2023 Czech Technical University in Prague
4: *
5: * This library is free software; you can redistribute it and/or
6: * modify it under the terms of the GNU Lesser General Public
7: * License as published by the Free Software Foundation; either
8: * version 3.0 of the License, or (at your option) any later version.
9: *
10: * This library is distributed in the hope that it will be useful,
11: * but WITHOUT ANY WARRANTY; without even the implied warranty of
12: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13: * Lesser General Public License for more details.
14: *
15: * You should have received a copy of the GNU Lesser General Public
16: * License along with this library.
17: */
18: package cz.cvut.kbss.jopa.model;
19:
20: import cz.cvut.kbss.jopa.exceptions.OWLPersistenceException;
21: import cz.cvut.kbss.jopa.model.metamodel.Metamodel;
22: import cz.cvut.kbss.jopa.model.query.Query;
23: import cz.cvut.kbss.jopa.model.query.criteria.CriteriaBuilder;
24: import cz.cvut.kbss.jopa.model.query.criteria.CriteriaQuery;
25:
26: import java.util.Map;
27:
28: public interface EntityManagerFactory extends AutoCloseable {
29: /**
30: * Create a new application-managed EntityManager. This method returns a new EntityManager instance each time it is
31: * invoked. The isOpen method will return true on the returned instance.
32: *
33: * @return entity manager instance
34: * @throws IllegalStateException if the entity manager factory has been closed
35: */
36: EntityManager createEntityManager();
37:
38: /**
39: * Create a new EntityManager with the specified Map of properties. This method returns a new EntityManager instance
40: * each time it is invoked. The isOpen method will return true on the returned instance.
41: *
42: * @param map properties for entity manager
43: * @return entity manager instance
44: */
45: EntityManager createEntityManager(Map<String, String> map);
46:
47: /**
48: * Returns an instance of {@link CriteriaBuilder} which may be used to construct {@link CriteriaQuery} objects.
49: *
50: * @return an instance of {@code CriteriaBuilder}
51: * @throws IllegalStateException if the entity manager factory has been closed
52: */
53: CriteriaBuilder getCriteriaBuilder();
54:
55: /**
56: * Return an instance of Metamodel interface for access to the metamodel of the persistence unit.
57: *
58: * @return Metamodel instance
59: * @throws IllegalStateException if the entity manager factory has been closed
60: */
61: Metamodel getMetamodel();
62:
63: /**
64: * Close the factory, releasing any resources that it holds. After a factory instance is closed, all methods invoked
65: * on it will throw an IllegalStateException, except for isOpen, which will return false. Once an
66: * EntityManagerFactory has been closed, all its entity managers are considered to be in the closed state.
67: *
68: * @throws IllegalStateException if the entity manager factory has been closed
69: */
70: void close();
71:
72: /**
73: * Indicates whether the factory is open. Returns true until the factory has been closed.
74: *
75: * @return true if the entity manager is open
76: * @throws IllegalStateException if the entity manager factory has been closed
77: */
78: boolean isOpen();
79:
80: /**
81: * Get the properties and associated values that are in effect for the entity manager factory.
82: * <p>
83: * Changing the contents of the map does not change the configuration in effect.
84: *
85: * @return properties
86: * @throws IllegalStateException if the entity manager factory has been closed
87: */
88: Map<String, String> getProperties();
89:
90: /**
91: * Access the cache that is associated with the entity manager factory (the "second level cache").
92: *
93: * @return instance of the Cache interface
94: * @throws IllegalStateException if the entity manager factory has been closed
95: */
96: Cache getCache();
97:
98: /**
99: * Return interface providing access to utility methods for the persistence unit.
100: *
101: * @return {@code PersistenceUnitUtil} interface
102: * @throws IllegalStateException if the entity manager factory has been closed
103: */
104: PersistenceUnitUtil getPersistenceUnitUtil();
105:
106: /**
107: * Define the query or typed query as a named query such that future query objects can be created from it using the
108: * {@code createNamedQuery} method. Any configuration of the query object (except for actual parameter binding) in
109: * effect when the named query is added is retained as part of the named query definition. This includes
110: * configuration information such as max results and result set mapping information.
111: * <p>
112: * When the query is executed, information that can be set by means of the query APIs can be overridden. Information
113: * that is overridden does not affect the named query as registered with the entity manager factory, and thus does
114: * not affect subsequent query objects created from it by means of the {@code createNamedQuery} method.
115: * <p>
116: * If a named query of the same name has been previously defined, either statically via metadata or via this method,
117: * that query definition is replaced.
118: *
119: * @param name name for the query
120: * @param query {@code Query} or {@code TypedQuery} object
121: * @since JPA 2.1
122: */
123: void addNamedQuery(String name, Query query);
124:
125: /**
126: * Return an object of the specified type to allow access to the provider-specific API. If the provider's
127: * EntityManagerFactory implementation does not support the specified class, the {@link OWLPersistenceException} is
128: * thrown.
129: *
130: * @param cls The class of the object to be returned. This can be also an implementation of the underlying driver
131: * @return an instance of the specified class
132: * @throws OWLPersistenceException If the provider does not support the specified class
133: */
134: <T> T unwrap(Class<T> cls);
135: }