Package: QueryHolder

QueryHolder

Coverage

1: /**
2: * Copyright (C) 2016 Czech Technical University in Prague
3: * <p>
4: * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public
5: * License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later
6: * version.
7: * <p>
8: * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
9: * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
10: * details. You should have received a copy of the GNU General Public License along with this program. If not, see
11: * <http://www.gnu.org/licenses/>.
12: */
13: package cz.cvut.kbss.jopa.query;
14:
15: import cz.cvut.kbss.jopa.model.query.Parameter;
16:
17: import java.util.Set;
18:
19: /**
20: * Represents a caretaker of a query, enabling parameter setting and final assembly of the query.
21: */
22: public interface QueryHolder {
23:
24: /**
25: * Gets the original query string.
26: *
27: * @return Gets the original unparsed query
28: */
29: String getQuery();
30:
31: /**
32: * Gets a collection of parameters in the query.
33: *
34: * @return Parameter names
35: */
36: Set<Parameter<?>> getParameters();
37:
38: /**
39: * Gets a parameter with the specified name.
40: *
41: * @param name Parameter name
42: * @return Parameter object
43: * @throws IllegalArgumentException If the parameter of the specified name does not exist
44: */
45: Parameter<?> getParameter(String name);
46:
47: /**
48: * Gets a parameter with the specified position.
49: *
50: * @param position Parameter position
51: * @return Parameter object
52: * @throws IllegalArgumentException If the parameter at the specified position does not exist
53: */
54: Parameter<?> getParameter(int position);
55:
56: /**
57: * Gets value bound to the specified parameter.
58: *
59: * @param parameter Parameter
60: * @return parameter value
61: * @throws IllegalArgumentException If there is no parameter with the specified name
62: */
63: Object getParameterValue(Parameter<?> parameter);
64:
65: /**
66: * Sets value of the specified parameter in the query.
67: * <p>
68: * If a value was already specified for the parameter, it is overwritten by the new one. This version expresses the
69: * value type information using XSD datatype in the query string.
70: *
71: * @param parameter Parameter object
72: * @param value Value to use
73: * @throws IllegalArgumentException If there is no such parameter in the query
74: * @see #setUntypedParameter(Parameter, Object)
75: */
76: <T> void setParameter(Parameter<T> parameter, Object value);
77:
78: /**
79: * Sets value of the specified parameter in the query.
80: * <p>
81: * If a value was already specified for the parameter, it is overwritten by the new one.
82: *
83: * @param parameter Parameter object
84: * @param value String value to use
85: * @param language Parameter language
86: * @throws IllegalArgumentException If there is no such parameter in the query
87: */
88: <T> void setParameter(Parameter<T> parameter, String value, String language);
89:
90: /**
91: * Sets value of the specified parameter in the query.
92: * <p>
93: * If a value was already specified for the parameter, it is overwritten by the new one. This version inserts the
94: * string representation of the value directly into the query, without any type information.
95: *
96: * @param parameter Parameter object
97: * @param value Value to use
98: * @throws IllegalArgumentException If there is no such parameter in the query
99: * @see #setParameter(Parameter, Object)
100: */
101: <T> void setUntypedParameter(Parameter<T> parameter, Object value);
102:
103: /**
104: * Sets the position of the first result to retrieve.
105: *
106: * @param startPosition The position to set, starting at 0
107: */
108: void setFirstResult(int startPosition);
109:
110: /**
111: * Gets the currently set first result position.
112: *
113: * @return the first result position, 0 if none was set
114: */
115: int getFirstResult();
116:
117: /**
118: * Sets the maximum number of results the query should retrieve.
119: *
120: * @param maxResults The maximum number of results
121: */
122: void setMaxResults(int maxResults);
123:
124: /**
125: * Gets the currently set maximum number of results to retrieve
126: *
127: * @return Maximum results value, {@code Integer.MAX_VALUE} when none was set
128: */
129: int getMaxResults();
130:
131: /**
132: * Clears any previously set value of the specified parameter.
133: *
134: * @param parameter Parameter object
135: * @throws IllegalArgumentException If there is no such parameter in the query
136: */
137: void clearParameter(Parameter<?> parameter);
138:
139: /**
140: * Clears any previously set parameter values in this query.
141: */
142: void clearParameters();
143:
144: /**
145: * Assembles the query, using any parameter values specified, and returns it as a string.
146: *
147: * @return Assembled query
148: */
149: String assembleQuery();
150: }