Package: Query

Query

name	instruction	branch	complexity	line	method
getResultStream()	M: 4 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 1 C: 0 0%	M: 1 C: 0 0%

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.query;
19:
20: import cz.cvut.kbss.jopa.exceptions.NoResultException;
21: import cz.cvut.kbss.jopa.exceptions.NoUniqueResultException;
22: import cz.cvut.kbss.jopa.exceptions.OWLPersistenceException;
23: import cz.cvut.kbss.jopa.exceptions.TransactionRequiredException;
24:
25: import java.util.List;
26: import java.util.Map;
27: import java.util.Set;
28: import java.util.stream.Stream;
29:
30: public interface Query {
31:
32: /**
33: * Execute an update or delete statement.
34: *
35: * @throws IllegalStateException if called for a SELECT statement or for a criteria query
36: * @throws TransactionRequiredException if there is no transaction or the persistence context has not been joined to
37: * the transaction
38: * @throws OWLPersistenceException if the query execution exceeds the query timeout value set and the
39: * transaction is rolled back
40: */
41: void executeUpdate();
42:
43: /**
44: * Execute a SELECT query and return the query results as an untyped List.
45: *
46: * @return a list of the results
47: * @throws IllegalStateException if called for a Java Persistence query language UPDATE or DELETE statement
48: * @throws TransactionRequiredException if a lock mode has been set and there is no transaction
49: * @throws OWLPersistenceException if the query execution exceeds the query timeout value set and the
50: * transaction is rolled back
51: */
52: List getResultList();
53:
54: /**
55: * Execute a SELECT query and return the query results as an untyped java.util.stream.Stream.
56: * <p>
57: * By default this method delegates to getResultList().stream(), however persistence provider may choose to override
58: * this method to provide additional capabilities.
59: *
60: * @return a stream of the results
61: * @throws IllegalStateException if called for a SELECT statement or for a criteria query
62: * @throws TransactionRequiredException if there is no transaction or the persistence context has not been joined to
63: * the transaction
64: * @throws OWLPersistenceException if the query execution exceeds the query timeout value set and the
65: * transaction is rolled back
66: */
67: default Stream getResultStream() {
68: return getResultList().stream();
69: }
70:
71: /**
72: * Execute a SELECT query that returns a single result.
73: *
74: * @return Query result
75: * @throws NoResultException There is no result
76: * @throws NoUniqueResultException There are more than one results
77: */
78: Object getSingleResult();
79:
80: /**
81: * Set the maximum number of results to retrieve.
82: *
83: * @param maxResult maximum number of results
84: * @return the same query instance
85: * @throws IllegalArgumentException if the argument is negative
86: */
87: Query setMaxResults(int maxResult);
88:
89: /**
90: * The maximum number of results the query object was set to retrieve.
91: * <p>
92: * Returns Integer.MAX_VALUE if {@link #setMaxResults(int)} was not applied to the query object.
93: *
94: * @return maximum number of results
95: */
96: int getMaxResults();
97:
98: /**
99: * Set the position of the first result to retrieve.
100: *
101: * @param startPosition position of the first result, numbered from 0
102: * @return the same query instance
103: * @throws IllegalArgumentException If the argument is negative
104: */
105: Query setFirstResult(int startPosition);
106:
107: /**
108: * The position of the first result the query object was set to retrieve.
109: * <p>
110: * Returns 0 if {@code setFirstResult} was not applied to the query object.
111: *
112: * @return position of the first result
113: */
114: int getFirstResult();
115:
116: /**
117: * Gets the parameter object corresponding to the declared positional parameter with the given position. This method
118: * is not required to be supported for native queries.
119: *
120: * @param position position
121: * @return parameter object
122: * @throws IllegalArgumentException If the parameter with the specified position does not exist
123: */
124: Parameter<?> getParameter(int position);
125:
126: /**
127: * Gets the parameter object corresponding to the declared parameter of the given name. This method is not required
128: * to be supported for native queries.
129: *
130: * @param name Parameter name
131: * @return parameter object
132: * @throws IllegalArgumentException If the parameter of the specified name does not exist
133: */
134: Parameter<?> getParameter(String name);
135:
136: /**
137: * Gets the parameter objects corresponding to the declared parameters of the query. Returns empty set if the query
138: * has no parameters. This method is not required to be supported for native queries.
139: *
140: * @return set of parameter objects
141: */
142: Set<Parameter<?>> getParameters();
143:
144: /**
145: * Returns a boolean indicating whether a value has been bound to the parameter.
146: *
147: * @param parameter parameter object
148: * @return boolean indicating whether parameter has been bound
149: */
150: boolean isBound(Parameter<?> parameter);
151:
152: /**
153: * Returns the input value bound to the positional parameter.
154: *
155: * @param position position
156: * @return parameter value
157: * @throws IllegalStateException If the parameter has not been bound
158: * @throws IllegalArgumentException If the parameter with the specified position does not exist
159: */
160: Object getParameterValue(int position);
161:
162: /**
163: * Returns the input value bound to the named parameter.
164: *
165: * @param name parameter name
166: * @return parameter value
167: * @throws IllegalStateException If the parameter has not been bound
168: * @throws IllegalArgumentException If the parameter with the specified name does not exist
169: */
170: Object getParameterValue(String name);
171:
172: /**
173: * Returns the input value bound to the parameter.
174: *
175: * @param parameter parameter object
176: * @return parameter value
177: * @throws IllegalStateException If the parameter has not been bound
178: * @throws IllegalArgumentException If the parameter is not a parameter of the query
179: */
180: <T> T getParameterValue(Parameter<T> parameter);
181:
182: /**
183: * Binds an argument value to a positional parameter.
184: * <p>
185: * This version exploits the type of the parameter value and maps it to the corresponding XSD datatype (if it
186: * exists).
187: *
188: * @param position position
189: * @param value parameter value
190: * @return this query instance
191: * @throws IllegalArgumentException If position does not correspond to a positional parameter of the query or if the
192: * argument is of incorrect type
193: * @see #setUntypedParameter(int, Object)
194: */
195: Query setParameter(int position, Object value);
196:
197: /**
198: * Binds a String argument value to a positional parameter.
199: *
200: * @param position position
201: * @param value parameter value
202: * @param language language tag for the parameter value
203: * @return this query instance
204: * @throws IllegalArgumentException If position does not correspond to a positional parameter of the query or if the
205: * argument is of incorrect type
206: */
207: Query setParameter(int position, String value, String language);
208:
209: /**
210: * Binds an argument value to a named parameter.
211: * <p>
212: * This version exploits the type of the parameter value and maps it to the corresponding XSD datatype (if it
213: * exists).
214: *
215: * @param name parameter name
216: * @param value parameter value
217: * @return this query instance
218: * @throws IllegalArgumentException If the parameter name does not correspond to a parameter of the query or if the
219: * argument is of incorrect type
220: * @see #setUntypedParameter(String, Object)
221: */
222: Query setParameter(String name, Object value);
223:
224: /**
225: * Binds a String argument value to a named parameter.
226: *
227: * @param name parameter name
228: * @param value parameter value
229: * @param language language tag for the parameter value
230: * @return this query instance
231: * @throws IllegalArgumentException If the parameter name does not correspond to a parameter of the query or if the
232: * argument is of incorrect type
233: */
234: Query setParameter(String name, String value, String language);
235:
236: /**
237: * Binds the value of a Parameter object.
238: * <p>
239: * This version exploits the type of the parameter value and maps it to the corresponding XSD datatype (if it
240: * exists).
241: *
242: * @param parameter parameter object
243: * @param value parameter value
244: * @return this query instance
245: * @throws IllegalArgumentException If the parameter does not correspond to a parameter of the query
246: * @see #setUntypedParameter(Parameter, Object)
247: */
248: <T> Query setParameter(Parameter<T> parameter, T value);
249:
250: /**
251: * Binds the value of a String Parameter.
252: *
253: * @param parameter parameter object
254: * @param value parameter value
255: * @param language language tag for the parameter value
256: * @return this query instance
257: * @throws IllegalArgumentException If the parameter does not correspond to a parameter of the query
258: */
259: Query setParameter(Parameter<String> parameter, String value, String language);
260:
261: /**
262: * Binds an argument value to a positional parameter.
263: * <p>
264: * This version does not express the type of the value in the query. Instead, it inserts the value directly into the
265: * query string. Can be useful e.g. for specifying OFFSET or LIMIT values.
266: *
267: * @param position position
268: * @param value parameter value
269: * @return this query instance
270: * @throws IllegalArgumentException If position does not correspond to a positional parameter of the query or if the
271: * argument is of incorrect type
272: */
273: Query setUntypedParameter(int position, Object value);
274:
275: /**
276: * Binds an argument value to a named parameter.
277: * <p>
278: * This version does not express the type of the value in the query. Instead, it inserts the value directly into the
279: * query string. Can be useful e.g. for specifying OFFSET or LIMIT values.
280: *
281: * @param name parameter name
282: * @param value parameter value
283: * @return this query instance
284: * @throws IllegalArgumentException If parameter name does not correspond to a parameter of the query or if the
285: * argument is of incorrect type
286: */
287: Query setUntypedParameter(String name, Object value);
288:
289: /**
290: * Binds the value of a Parameter object.
291: * <p>
292: * This version does not express the type of the value in the query. Instead, it inserts the value directly into the
293: * query string. Can be useful e.g. for specifying OFFSET or LIMIT values.
294: *
295: * @param parameter parameter object
296: * @param value parameter value
297: * @return this query instance
298: * @throws IllegalArgumentException If the parameter does not correspond to a parameter of the query
299: */
300: <T> Query setUntypedParameter(Parameter<T> parameter, T value);
301:
302: /**
303: * Sets a query hint.
304: * <p>
305: * The hints elements may be used to specify query properties and hints. Vendor-specific hints that are not
306: * recognized by a provider are silently ignored.
307: *
308: * @param hintName Name of the query hint
309: * @param value Value of the query hint
310: * @return this query instance
311: * @throws IllegalArgumentException If the value is not valid for the hint implementation
312: */
313: Query setHint(String hintName, Object value);
314:
315: /**
316: * Gets the hints and associated values that are in effect for this query instance.
317: *
318: * @return Map of query hints with values
319: */
320: Map<String, Object> getHints();
321: }