Jenkins

1: /**
2:  * Copyright (C) 2020 Czech Technical University in Prague
3:  *
4:  * This program is free software: you can redistribute it and/or modify it under
5:  * the terms of the GNU General Public License as published by the Free Software
6:  * Foundation, either version 3 of the License, or (at your option) any
7:  * later version.
8:  *
9:  * This program is distributed in the hope that it will be useful, but WITHOUT
10:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
11:  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
12:  * details. You should have received a copy of the GNU General Public License
13:  * along with this program. If not, see <http://www.gnu.org/licenses/>.
14:  */
15: package cz.cvut.kbss.jopa.model.query;
16: 
17: import cz.cvut.kbss.jopa.exceptions.NoResultException;
18: import cz.cvut.kbss.jopa.exceptions.NoUniqueResultException;
19: import cz.cvut.kbss.jopa.exceptions.OWLPersistenceException;
20: import cz.cvut.kbss.jopa.exceptions.TransactionRequiredException;
21: 
22: import java.util.List;
23: import java.util.Set;
24: import java.util.stream.Stream;
25: 
26: public interface Query {
27: 
28:     /**
29:      * Execute an update or delete statement.
30:      *
31:      * @throws IllegalStateException        if called for a SELECT statement or for a criteria query
32:      * @throws TransactionRequiredException if there is no transaction or the persistence context has not been joined to
33:      *                                      the transaction
34:      * @throws OWLPersistenceException      if the query execution exceeds the query timeout value set and the
35:      *                                      transaction is rolled back
36:      */
37:     void executeUpdate();
38: 
39:     /**
40:      * Execute a SELECT query and return the query results as an untyped List.
41:      *
42:      * @return a list of the results
43:      * @throws IllegalStateException        if called for a Java Persistence query language UPDATE or DELETE statement
44:      * @throws TransactionRequiredException if a lock mode has been set and there is no transaction
45:      * @throws OWLPersistenceException      if the query execution exceeds the query timeout value set and the
46:      *                                      transaction is rolled back
47:      */
48:     List getResultList();
49: 
50:     /**
51:      * Execute a SELECT query and return the query results as an untyped java.util.stream.Stream.
52:      * <p>
53:      * By default this method delegates to getResultList().stream(), however persistence provider may choose to override
54:      * this method to provide additional capabilities.
55:      *
56:      * @return a stream of the results
57:      * @throws IllegalStateException        if called for a SELECT statement or for a criteria query
58:      * @throws TransactionRequiredException if there is no transaction or the persistence context has not been joined to
59:      *                                      the transaction
60:      * @throws OWLPersistenceException      if the query execution exceeds the query timeout value set and the
61:      *                                      transaction is rolled back
62:      */
63:     default Stream getResultStream() {
64:         return getResultList().stream();
65:     }
66: 
67:     /**
68:      * Execute a SELECT query that returns a single result.
69:      *
70:      * @return Query result
71:      * @throws NoResultException       There is no result
72:      * @throws NoUniqueResultException There are more than one results
73:      */
74:     Object getSingleResult();
75: 
76:     /**
77:      * Set the maximum number of results to retrieve.
78:      *
79:      * @param maxResult maximum number of results
80:      * @return the same query instance
81:      * @throws IllegalArgumentException if the argument is negative
82:      */
83:     Query setMaxResults(int maxResult);
84: 
85:     /**
86:      * The maximum number of results the query object was set to retrieve.
87:      * <p>
88:      * Returns Integer.MAX_VALUE if {@link #setMaxResults(int)} was not applied to the query object.
89:      *
90:      * @return maximum number of results
91:      */
92:     int getMaxResults();
93: 
94:     /**
95:      * Set the position of the first result to retrieve.
96:      *
97:      * @param startPosition position of the first result, numbered from 0
98:      * @return the same query instance
99:      * @throws IllegalArgumentException If the argument is negative
100:      */
101:     Query setFirstResult(int startPosition);
102: 
103:     /**
104:      * The position of the first result the query object was set to retrieve.
105:      * <p>
106:      * Returns 0 if {@code setFirstResult} was not applied to the query object.
107:      *
108:      * @return position of the first result
109:      */
110:     int getFirstResult();
111: 
112:     /**
113:      * Gets the parameter object corresponding to the declared positional parameter with the given position. This method
114:      * is not required to be supported for native queries.
115:      *
116:      * @param position position
117:      * @return parameter object
118:      * @throws IllegalArgumentException If the parameter with the specified position does not exist
119:      */
120:     Parameter<?> getParameter(int position);
121: 
122:     /**
123:      * Gets the parameter object corresponding to the declared parameter of the given name. This method is not required
124:      * to be supported for native queries.
125:      *
126:      * @param name Parameter name
127:      * @return parameter object
128:      * @throws IllegalArgumentException If the parameter of the specified name does not exist
129:      */
130:     Parameter<?> getParameter(String name);
131: 
132:     /**
133:      * Gets the parameter objects corresponding to the declared parameters of the query. Returns empty set if the query
134:      * has no parameters. This method is not required to be supported for native queries.
135:      *
136:      * @return set of parameter objects
137:      */
138:     Set<Parameter<?>> getParameters();
139: 
140:     /**
141:      * Returns a boolean indicating whether a value has been bound to the parameter.
142:      *
143:      * @param parameter parameter object
144:      * @return boolean indicating whether parameter has been bound
145:      */
146:     boolean isBound(Parameter<?> parameter);
147: 
148:     /**
149:      * Returns the input value bound to the positional parameter.
150:      *
151:      * @param position position
152:      * @return parameter value
153:      * @throws IllegalStateException    If the parameter has not been bound
154:      * @throws IllegalArgumentException If the parameter with the specified position does not exist
155:      */
156:     Object getParameterValue(int position);
157: 
158:     /**
159:      * Returns the input value bound to the named parameter.
160:      *
161:      * @param name parameter name
162:      * @return parameter value
163:      * @throws IllegalStateException    If the parameter has not been bound
164:      * @throws IllegalArgumentException If the parameter with the specified name does not exist
165:      */
166:     Object getParameterValue(String name);
167: 
168:     /**
169:      * Returns the input value bound to the parameter.
170:      *
171:      * @param parameter parameter object
172:      * @return parameter value
173:      * @throws IllegalStateException    If the parameter has not been bound
174:      * @throws IllegalArgumentException If the parameter is not a parameter of the query
175:      */
176:     <T> T getParameterValue(Parameter<T> parameter);
177: 
178:     /**
179:      * Binds an argument value to a positional parameter.
180:      * <p>
181:      * This version exploits the type of the parameter value and maps it to the corresponding XSD datatype (if it
182:      * exists).
183:      *
184:      * @param position position
185:      * @param value    parameter value
186:      * @return this query instance
187:      * @throws IllegalArgumentException If position does not correspond to a positional parameter of the query or if the
188:      *                                  argument is of incorrect type
189:      * @see #setUntypedParameter(int, Object)
190:      */
191:     Query setParameter(int position, Object value);
192: 
193:     /**
194:      * Binds a String argument value to a positional parameter.
195:      *
196:      * @param position position
197:      * @param value    parameter value
198:      * @param language language tag for the parameter value
199:      * @return this query instance
200:      * @throws IllegalArgumentException If position does not correspond to a positional parameter of the query or if the
201:      *                                  argument is of incorrect type
202:      */
203:     Query setParameter(int position, String value, String language);
204: 
205:     /**
206:      * Binds an argument value to a named parameter.
207:      * <p>
208:      * This version exploits the type of the parameter value and maps it to the corresponding XSD datatype (if it
209:      * exists).
210:      *
211:      * @param name  parameter name
212:      * @param value parameter value
213:      * @return this query instance
214:      * @throws IllegalArgumentException If the parameter name does not correspond to a parameter of the query or if the
215:      *                                  argument is of incorrect type
216:      * @see #setUntypedParameter(String, Object)
217:      */
218:     Query setParameter(String name, Object value);
219: 
220:     /**
221:      * Binds a String argument value to a named parameter.
222:      *
223:      * @param name     parameter name
224:      * @param value    parameter value
225:      * @param language language tag for the parameter value
226:      * @return this query instance
227:      * @throws IllegalArgumentException If the parameter name does not correspond to a parameter of the query or if the
228:      *                                  argument is of incorrect type
229:      */
230:     Query setParameter(String name, String value, String language);
231: 
232:     /**
233:      * Binds the value of a Parameter object.
234:      * <p>
235:      * This version exploits the type of the parameter value and maps it to the corresponding XSD datatype (if it
236:      * exists).
237:      *
238:      * @param parameter parameter object
239:      * @param value     parameter value
240:      * @return this query instance
241:      * @throws IllegalArgumentException If the parameter does not correspond to a parameter of the query
242:      * @see #setUntypedParameter(Parameter, Object)
243:      */
244:     <T> Query setParameter(Parameter<T> parameter, T value);
245: 
246:     /**
247:      * Binds the value of a String Parameter.
248:      *
249:      * @param parameter parameter object
250:      * @param value     parameter value
251:      * @param language  language tag for the parameter value
252:      * @return this query instance
253:      * @throws IllegalArgumentException If the parameter does not correspond to a parameter of the query
254:      */
255:     Query setParameter(Parameter<String> parameter, String value, String language);
256: 
257:     /**
258:      * Binds an argument value to a positional parameter.
259:      * <p>
260:      * This version does not express the type of the value in the query. Instead, it inserts the value directly into the
261:      * query string. Can be useful e.g. for specifying OFFSET or LIMIT values.
262:      *
263:      * @param position position
264:      * @param value    parameter value
265:      * @return this query instance
266:      * @throws IllegalArgumentException If position does not correspond to a positional parameter of the query or if the
267:      *                                  argument is of incorrect type
268:      */
269:     Query setUntypedParameter(int position, Object value);
270: 
271:     /**
272:      * Binds an argument value to a named parameter.
273:      * <p>
274:      * This version does not express the type of the value in the query. Instead, it inserts the value directly into the
275:      * query string. Can be useful e.g. for specifying OFFSET or LIMIT values.
276:      *
277:      * @param name  parameter name
278:      * @param value parameter value
279:      * @return this query instance
280:      * @throws IllegalArgumentException If parameter name does not correspond to a parameter of the query or if the
281:      *                                  argument is of incorrect type
282:      */
283:     Query setUntypedParameter(String name, Object value);
284: 
285:     /**
286:      * Binds the value of a Parameter object.
287:      * <p>
288:      * This version does not express the type of the value in the query. Instead, it inserts the value directly into the
289:      * query string. Can be useful e.g. for specifying OFFSET or LIMIT values.
290:      *
291:      * @param parameter parameter object
292:      * @param value     parameter value
293:      * @return this query instance
294:      * @throws IllegalArgumentException If the parameter does not correspond to a parameter of the query
295:      */
296:     <T> Query setUntypedParameter(Parameter<T> parameter, T value);
297: }