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