Package: Query

Query

Coverage

1: /**
2: * Copyright (C) 2016 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.net.URI;
23: import java.util.Collection;
24: import java.util.List;
25: import java.util.Set;
26:
27: public interface Query {
28:
29: /**
30: * Execute an update or delete statement.
31: *
32: * @throws IllegalStateException if called for a SELECT statement or for a criteria query
33: * @throws TransactionRequiredException if there is no transaction or the persistence context has not been joined to
34: * the transaction
35: * @throws OWLPersistenceException if the query execution exceeds the query timeout value set and the
36: * transaction is rolled back
37: */
38: void executeUpdate();
39:
40: /**
41: * Execute a SELECT query and return the query results as an untyped List.
42: *
43: * @return a list of the results
44: * @throws IllegalStateException if called for a Java Persistence query language UPDATE or DELETE statement
45: * @throws TransactionRequiredException if a lock mode has been set and there is no transaction
46: * @throws OWLPersistenceException if the query execution exceeds the query timeout value set and the
47: * transaction is rolled back
48: */
49: List getResultList();
50:
51: /**
52: * Execute a SELECT query that returns a single result.
53: *
54: * @return Query result
55: * @throws NoResultException There is no result
56: * @throws NoUniqueResultException There are more than one results
57: */
58: Object getSingleResult();
59:
60: /**
61: * Adds URI of context against which this query will be executed. </p>
62: * <p>
63: * If no context was specified, the query is run against the default repository context.
64: *
65: * @param context Context URI
66: * @return This instance
67: */
68: Query addContext(URI context);
69:
70: /**
71: * Adds URIs of contexts against which this query will be executed. </p>
72: * <p>
73: * If no context was specified, the query is run against the default repository context.
74: *
75: * @param contexts Context URIs
76: * @return This instance
77: */
78: Query addContexts(Collection<URI> contexts);
79:
80: /**
81: * Clears the previously set contexts.
82: *
83: * @return This instance
84: * @see #addContext(URI)
85: * @see #addContexts(Collection)
86: */
87: Query clearContexts();
88:
89: /**
90: * Set the maximum number of results to retrieve.
91: *
92: * @param maxResult maximum number of results
93: * @return the same query instance
94: * @throws IllegalArgumentException if the argument is negative
95: */
96: Query setMaxResults(int maxResult);
97:
98: /**
99: * The maximum number of results the query object was set to retrieve. </p>
100: * <p>
101: * Returns Integer.MAX_VALUE if {@link #setMaxResults(int)} was not applied to the query object.
102: *
103: * @return maximum number of results
104: */
105: int getMaxResults();
106:
107: /**
108: * Gets the parameter object corresponding to the declared positional parameter with the given position. This method
109: * is not required to be supported for native queries.
110: *
111: * @param position position
112: * @return parameter object
113: * @throws IllegalArgumentException If the parameter with the specified position does not exist
114: */
115: Parameter<?> getParameter(int position);
116:
117: /**
118: * Gets the parameter object corresponding to the declared parameter of the given name. This method is not required
119: * to be supported for native queries.
120: *
121: * @param name Parameter name
122: * @return parameter object
123: * @throws IllegalArgumentException If the parameter of the specified name does not exist
124: */
125: Parameter<?> getParameter(String name);
126:
127: /**
128: * Gets the parameter objects corresponding to the declared parameters of the query. Returns empty set if the query
129: * has no parameters. This method is not required to be supported for native queries.
130: *
131: * @return set of parameter objects
132: */
133: Set<Parameter<?>> getParameters();
134:
135: /**
136: * Returns a boolean indicating whether a value has been bound to the parameter.
137: *
138: * @param parameter parameter object
139: * @return boolean indicating whether parameter has been bound
140: */
141: boolean isBound(Parameter<?> parameter);
142:
143: /**
144: * Returns the input value bound to the positional parameter.
145: *
146: * @param position position
147: * @return parameter value
148: * @throws IllegalStateException If the parameter has not been bound
149: * @throws IllegalArgumentException If the parameter with the specified position does not exist
150: */
151: Object getParameterValue(int position);
152:
153: /**
154: * Returns the input value bound to the named parameter.
155: *
156: * @param name parameter name
157: * @return parameter value
158: * @throws IllegalStateException If the parameter has not been bound
159: * @throws IllegalArgumentException If the parameter with the specified name does not exist
160: */
161: Object getParameterValue(String name);
162:
163: /**
164: * Returns the input value bound to the parameter.
165: *
166: * @param parameter parameter object
167: * @return parameter value
168: * @throws IllegalStateException If the parameter has not been bound
169: * @throws IllegalArgumentException If the parameter is not a parameter of the query
170: */
171: <T> T getParameterValue(Parameter<T> parameter);
172:
173: /**
174: * Binds an argument value to a positional parameter.
175: *
176: * @param position position
177: * @param value parameter value
178: * @return this query instance
179: * @throws IllegalArgumentException If position does not correspond to a positional parameter of the query or if the
180: * argument is of incorrect type
181: */
182: Query setParameter(int position, Object value);
183:
184: /**
185: * Binds a String argument value to a positional parameter.
186: *
187: * @param position position
188: * @param value parameter value
189: * @param language language tag for the 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: */
194: Query setParameter(int position, String value, String language);
195:
196: /**
197: * Binds an argument value to a named parameter.
198: *
199: * @param name parameter name
200: * @param value parameter value
201: * @return this query instance
202: * @throws IllegalArgumentException If the parameter name does not correspond to a parameter of the query or if the
203: * argument is of incorrect type
204: */
205: Query setParameter(String name, Object value);
206:
207: /**
208: * Binds a String argument value to a named parameter.
209: *
210: * @param name parameter name
211: * @param value parameter value
212: * @param language language tag for the 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: */
217: Query setParameter(String name, String value, String language);
218:
219: /**
220: * Binds the value of a Parameter object.
221: *
222: * @param parameter parameter object
223: * @param value parameter value
224: * @return this query instance
225: * @throws IllegalArgumentException If the parameter does not correspond to a parameter of the query
226: */
227: <T> Query setParameter(Parameter<T> parameter, T value);
228:
229: /**
230: * Binds the value of a String Parameter.
231: *
232: * @param parameter parameter object
233: * @param value parameter value
234: * @param language language tag for the parameter value
235: * @return this query instance
236: * @throws IllegalArgumentException If the parameter does not correspond to a parameter of the query
237: */
238: Query setParameter(Parameter<String> parameter, String value, String language);
239: }