Package: EntityManager

EntityManager

Coverage

1: /*
2: * JOPA
3: * Copyright (C) 2024 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.NonJPA;
21: import cz.cvut.kbss.jopa.exceptions.OWLEntityExistsException;
22: import cz.cvut.kbss.jopa.exceptions.OWLPersistenceException;
23: import cz.cvut.kbss.jopa.exceptions.TransactionRequiredException;
24: import cz.cvut.kbss.jopa.model.descriptors.Descriptor;
25: import cz.cvut.kbss.jopa.model.metamodel.FieldSpecification;
26: import cz.cvut.kbss.jopa.model.metamodel.Metamodel;
27: import cz.cvut.kbss.jopa.model.query.Query;
28: import cz.cvut.kbss.jopa.model.query.TypedQuery;
29: import cz.cvut.kbss.jopa.model.query.criteria.CriteriaQuery;
30: import cz.cvut.kbss.jopa.model.query.criteria.CriteriaBuilder;
31: import cz.cvut.kbss.jopa.transactions.EntityTransaction;
32:
33: import java.net.URI;
34: import java.util.List;
35: import java.util.Map;
36:
37: public interface EntityManager extends AutoCloseable {
38:
39: /**
40: * Make an instance managed and persistent.
41: * <p>
42: * The entity is persisted into the default context.
43: *
44: * @param entity entity instance
45: * @throws OWLEntityExistsException if the entity already exists. (The EntityExistsException may be thrown when
46: * the persist operation is invoked, or the EntityExistsException or another
47: * PersistenceException may be thrown at flush or commit time.)
48: * @throws IllegalArgumentException if not an entity
49: * @throws NullPointerException If {@code entity} is {@code null}
50: * @throws TransactionRequiredException if invoked on a container-managed entity manager of type
51: * PersistenceContextType.TRANSACTION and there is no transaction.
52: * @see #persist(Object, Descriptor)
53: */
54: void persist(final Object entity);
55:
56: /**
57: * Make an instance managed and persistent.
58: * <p>
59: * The {@code descriptor} represents repository and context into which the entity and its fields should be
60: * persisted.
61: *
62: * @param entity entity instance
63: * @param descriptor Entity descriptor
64: * @throws OWLEntityExistsException if the entity already exists. (The EntityExistsException may be thrown when
65: * the persist operation is invoked, or the EntityExistsException or another
66: * PersistenceException may be thrown at flush or commit time.)
67: * @throws IllegalArgumentException if not an entity
68: * @throws NullPointerException If {@code entity} or {@code descriptor} is {@code null}
69: * @throws TransactionRequiredException if invoked on a container-managed entity manager of type
70: * PersistenceContextType.TRANSACTION and there is no transaction.
71: */
72: void persist(final Object entity, final Descriptor descriptor);
73:
74: /**
75: * Merge the state of the given entity into the current persistence context.
76: * <p>
77: * The entity is merged into the default repository context.
78: *
79: * @param entity The entity to merge
80: * @return the instance that the state was merged to
81: * @throws IllegalArgumentException if instance is not an entity or is a removed entity
82: * @throws TransactionRequiredException if invoked on a container-managed entity manager of type
83: * PersistenceContextType.TRANSACTION and there is no transaction.
84: */
85: <T> T merge(final T entity);
86:
87: /**
88: * Merge the state of the given entity into the current persistence context and into the repository specified by
89: * {@code descriptor}.
90: *
91: * @param entity The entity to merge
92: * @param descriptor Entity descriptor
93: * @return the instance that the state was merged to
94: * @throws IllegalArgumentException if instance is not an entity or is a removed entity
95: * @throws TransactionRequiredException if invoked on a container-managed entity manager of type
96: * PersistenceContextType.TRANSACTION and there is no transaction.
97: */
98: <T> T merge(final T entity, Descriptor descriptor);
99:
100: /**
101: * Remove the entity instance.
102: *
103: * @param entity The instance to remove
104: * @throws IllegalArgumentException if not an entity or if a detached entity
105: * @throws TransactionRequiredException if invoked on a container-managed entity manager of type
106: * PersistenceContextType.TRANSACTION and there is no transaction.
107: */
108: void remove(final Object entity);
109:
110: /**
111: * Find by identifier.
112: * <p>
113: * Search for an entity of the specified class and identifier. If the entity instance is contained in the
114: * persistence context, it is returned from there.
115: *
116: * @param entityClass Entity class
117: * @param identifier Entity identifier
118: * @return the found entity instance or {@code null} if the entity does not exist in the given ontology context
119: * @throws IllegalArgumentException if the first argument does not denote an entity type or the second argument is
120: * not a valid type for that entity’s identifier
121: * @throws NullPointerException If {@code entityClass}, {@code identifier} is {@code null}
122: */
123: <T> T find(final Class<T> entityClass, final Object identifier);
124:
125: /**
126: * Find by identifier.
127: * <p>
128: * Search for an entity of the specified class and identifier. If the entity instance is contained in the
129: * persistence context, it is returned from there.
130: * <p>
131: * The {@code descriptor} parameter represents repository and context in which the entity should be looked for.
132: *
133: * @param entityClass Entity class
134: * @param identifier Entity identifier
135: * @param descriptor Entity descriptor
136: * @return the found entity instance or {@code null} if the entity does not exist in the given ontology context
137: * @throws IllegalArgumentException if the first argument does not denote an entity type or the second argument is
138: * not a valid type for that entity’s identifier
139: * @throws NullPointerException If {@code entityClass}, {@code identifier} or {@code contextUri} is {@code
140: * null}
141: * @see #getContexts()
142: */
143: <T> T find(final Class<T> entityClass, final Object identifier, final Descriptor descriptor);
144:
145: /**
146: * Get an instance, whose state may be lazily fetched.
147: * <p>
148: * If the requested instance does not exist in the database, {@code null} is returned.
149: * <p>
150: * The application should not expect that the instance state will be available upon detachment, unless it was
151: * accessed by the application while the entity manager was open.
152: *
153: * @param entityClass entity class
154: * @param identifier identifier of the instance
155: * @return the found entity instance
156: * @throws IllegalArgumentException if the first argument does not denote an entity type or the second argument is
157: * not a valid type for that entity’s identifier
158: */
159: <T> T getReference(final Class<T> entityClass, final Object identifier);
160:
161: /**
162: * Get an instance, whose state may be lazily fetched.
163: * <p>
164: * If the requested instance does not exist in the database, {@code null} is returned.
165: * <p>
166: * The application should not expect that the instance state will be available upon detachment, unless it was
167: * accessed by the application while the entity manager was open.
168: * <p>
169: * The {@code descriptor} parameter represents configuration of the entity loading (e.g., repository context).
170: *
171: * @param entityClass entity class
172: * @param identifier identifier of the instance
173: * @param descriptor Entity descriptor
174: * @return the found entity instance
175: * @throws IllegalArgumentException if the first argument does not denote an entity type or the second argument is
176: * not a valid type for that entity’s identifier
177: */
178: <T> T getReference(final Class<T> entityClass, final Object identifier, final Descriptor descriptor);
179:
180: /**
181: * Synchronize the persistence context to the underlying database.
182: *
183: * @throws TransactionRequiredException if there is no transaction
184: * @throws OWLPersistenceException if the flush fails
185: */
186: void flush();
187:
188: /**
189: * Refresh the state of the instance from the data source, overwriting changes made to the entity, if any.
190: *
191: * @param entity The entity instance to refresh
192: * @throws IllegalArgumentException if not an entity or entity is not managed
193: * @throws TransactionRequiredException if invoked on a container-managed entity manager of type
194: * PersistenceContextType.TRANSACTION and there is no transaction.
195: */
196: void refresh(final Object entity);
197:
198: /**
199: * Clear the persistence context, causing all managed entities to become detached. Changes made to entities that
200: * have not been flushed to the database will not be persisted.
201: */
202: void clear();
203:
204: /**
205: * Remove the given entity from the persistence context, causing a managed entity to become detached. Unflushed
206: * changes made to the entity if any (including removal of the entity), will not be synchronized to the database.
207: * Entities which previously referenced the detached entity will continue to reference it.
208: *
209: * @param entity The instance to detach
210: * @throws IllegalArgumentException if the instance is not an entity
211: */
212: void detach(Object entity);
213:
214: /**
215: * Check if the instance belongs to the current persistence context.
216: *
217: * @param entity The instance to check
218: * @return True if the instance is managed, false otherwise
219: * @throws IllegalArgumentException if not an entity
220: */
221: boolean contains(Object entity);
222:
223: /**
224: * Checks consistency of the specified context.
225: * <p>
226: * The context URI can be {@code null}, which indicates that consistency of the whole repository should be
227: * verified.
228: *
229: * @param context Context URI, can be {@code null}
230: * @return {@code true} if consistent, {@code false} otherwise
231: */
232: @NonJPA
233: boolean isConsistent(URI context);
234:
235: /**
236: * Checks whether the specified attribute value of the specified entity is inferred in the underlying repository.
237: * <p>
238: * Note that given the nature of the repository implementation, this method may return true if the corresponding
239: * statement is both inferred and asserted. Also note that this method will use the descriptor associated with the
240: * specified entity in this persistence context to resolve the repository context, but some underlying repositories
241: * do not store inferences in data contexts, so the attribute context may be ignored.
242: *
243: * @param entity Entity whose attribute to examine. Must be managed by this persistence context
244: * @param attribute Attribute whose value to examine
245: * @param value The value whose inference to examine
246: * @return {@code true} if the entity attribute value is inferred, {@code false} otherwise
247: */
248: <T> boolean isInferred(T entity, FieldSpecification<? super T, ?> attribute, Object value);
249:
250: /**
251: * Get the properties and hints and associated values that are in effect for the entity manager.
252: * <p>
253: * Changing the contents of the map does not change the configuration in effect.
254: *
255: * @return Map of properties and hints in effect for entity manager
256: */
257: Map<String, Object> getProperties();
258:
259: /**
260: * Set an entity manager property or hint.
261: * <p>
262: * If a vendor-specific property or hint is not recognized, it is silently ignored.
263: *
264: * @param propertyName Name of property or hint
265: * @param value Value for property or hint
266: * @throws IllegalArgumentException If the second argument is not valid for the implementation
267: */
268: void setProperty(String propertyName, Object value);
269:
270: /**
271: * Create an instance of Query for executing a Java Persistence query language statement.
272: *
273: * @param qlString a Java Persistence query string
274: * @return the new query instance
275: * @throws IllegalArgumentException if query string is not valid
276: */
277: @NonJPA
278: Query createQuery(String qlString);
279:
280: /**
281: * Create an instance of TypedQuery for executing a criteria query.
282: *
283: * @param criteriaQuery criteria query object
284: * @return the new query instance
285: */
286: @NonJPA
287: <T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery);
288:
289: /**
290: * Creates an instance of query for executing Java persistence query language statement.
291: *
292: * @param query query string
293: * @param resultClass result type
294: * @return the new query instance
295: */
296: @NonJPA
297: <T> TypedQuery<T> createQuery(String query, Class<T> resultClass);
298:
299:
300: /**
301: * Create an instance of Query for executing a named query (in native SPARQL).
302: *
303: * @param name the name of a query defined in metadata
304: * @return the new query instance
305: * @throws IllegalArgumentException if a query has not been defined with the given name
306: */
307: Query createNamedQuery(String name);
308:
309: /**
310: * Create an instance of TypedQuery for executing a SPARQL named query.
311: * <p>
312: * The select list of the query must contain only a single item, which must be assignable to the type specified by
313: * the resultClass argument.
314: *
315: * @param name the name of a query defined in metadata
316: * @param resultClass the type of the query result
317: * @return the new query instance
318: * @throws IllegalArgumentException if a query has not been defined with the given name or if the query string is
319: * found to be invalid or if the query result is found to not be assignable to the
320: * specified type
321: */
322: <T> TypedQuery<T> createNamedQuery(String name, Class<T> resultClass);
323:
324: /**
325: * Create an instance of Query for executing a native SPARQL(-DL) query in SPARQL syntax.
326: *
327: * @param sparqlString a native SPARQL query string
328: * @return the new query instance
329: */
330: Query createNativeQuery(String sparqlString);
331:
332: /**
333: * Create an instance of Query for executing a native SPARQL(-DL) query returning only specific object type.
334: *
335: * @param sparqlString a native SQL query string
336: * @param resultClass the class of the resulting instance(s)
337: * @return the new query instance
338: */
339: <T> TypedQuery<T> createNativeQuery(String sparqlString, Class<T> resultClass);
340:
341: /**
342: * Create an instance of Query for executing a native SPARQL query.
343: *
344: * @param sparqlString a native SQL query string
345: * @param resultSetMapping the name of the result set mapping
346: * @return the new query instance
347: */
348: Query createNativeQuery(String sparqlString, String resultSetMapping);
349:
350: /**
351: * Return an object of the specified type to allow access to the provider-specific API. If the provider's
352: * EntityManager implementation does not support the specified class, the {@link OWLPersistenceException} is
353: * thrown.
354: *
355: * @param cls The class of the object to be returned. This can be also an implementation of the underlying driver
356: * @return an instance of the specified class
357: * @throws OWLPersistenceException If the provider does not support the specified class
358: */
359: <T> T unwrap(Class<T> cls);
360:
361: /**
362: * Return the underlying provider object for the EntityManager, if available. The result of this method is
363: * implementation specific.
364: *
365: * @return underlying provider object for EntityManager
366: */
367: Object getDelegate();
368:
369: /**
370: * Close an application-managed EntityManager. After the close method has been invoked, all methods on the
371: * EntityManager instance and any Query objects obtained from it will throw the IllegalStateException except for
372: * getTransaction and isOpen (which will return false). If this method is called when the EntityManager is
373: * associated with an active transaction, the persistence context remains managed until the transaction completes.
374: *
375: * @throws IllegalStateException if the EntityManager is container-managed.
376: */
377: void close();
378:
379: /**
380: * Determine whether the EntityManager is open.
381: *
382: * @return true until the EntityManager has been closed.
383: */
384: boolean isOpen();
385:
386: /**
387: * Return the resource-level transaction object. The EntityTransaction instance may be used serially to begin and
388: * commit multiple transactions.
389: *
390: * @return EntityTransaction instance
391: * @throws IllegalStateException if invoked on a JTA EntityManager.
392: */
393: EntityTransaction getTransaction();
394:
395: /**
396: * Return the entity manager factory for the entity manager.
397: *
398: * @return EntityManagerFactory instance
399: * @since JPA 2.0
400: */
401: EntityManagerFactory getEntityManagerFactory();
402:
403: /**
404: * Returns a list of repository contexts available to this entity manager.
405: *
406: * @return List of repository context URIs
407: */
408: @NonJPA
409: List<URI> getContexts();
410:
411: /**
412: * Return a criteriaFactory for making CriteriaQuery.
413: *
414: * @return CriteriaBuilder instance
415: */
416: CriteriaBuilder getCriteriaBuilder();
417:
418: /**
419: * Return an instance of Metamodel interface for access to the metamodel of the persistence unit.
420: *
421: * @return Metamodel instance
422: */
423: Metamodel getMetamodel();
424: }