Package: QueryHolder

QueryHolder

Coverage

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.query;
16:
17: import cz.cvut.kbss.jopa.model.query.Parameter;
18:
19: import java.util.Set;
20:
21: /**
22: * Represents a caretaker of a query, enabling parameter setting and final assembly of the query.
23: */
24: public interface QueryHolder {
25:
26: /**
27: * Gets the original query string.
28: *
29: * @return Gets the original unparsed query
30: */
31: String getQuery();
32:
33: /**
34: * Gets a collection of parameters in the query.
35: *
36: * @return Parameter names
37: */
38: Set<Parameter<?>> getParameters();
39:
40: /**
41: * Gets a parameter with the specified name.
42: *
43: * @param name Parameter name
44: * @return Parameter object
45: * @throws IllegalArgumentException If the parameter of the specified name does not exist
46: */
47: Parameter<?> getParameter(String name);
48:
49: /**
50: * Gets a parameter with the specified position.
51: *
52: * @param position Parameter position
53: * @return Parameter object
54: * @throws IllegalArgumentException If the parameter at the specified position does not exist
55: */
56: Parameter<?> getParameter(int position);
57:
58: /**
59: * Gets value bound to the specified parameter.
60: *
61: * @param parameter Parameter
62: * @return parameter value
63: * @throws IllegalArgumentException If there is no parameter with the specified name
64: */
65: Object getParameterValue(Parameter<?> parameter);
66:
67: /**
68: * Sets value of the specified parameter in the query.
69: * <p>
70: * If a value was already specified for the parameter, it is overwritten by the new one. This version expresses the
71: * value type information using XSD datatype in the query string.
72: *
73: * @param parameter Parameter object
74: * @param value Value to use
75: * @throws IllegalArgumentException If there is no such parameter in the query
76: * @see #setUntypedParameter(Parameter, Object)
77: */
78: <T> void setParameter(Parameter<T> parameter, Object value);
79:
80: /**
81: * Sets value of the specified parameter in the query.
82: * <p>
83: * If a value was already specified for the parameter, it is overwritten by the new one.
84: *
85: * @param parameter Parameter object
86: * @param value String value to use
87: * @param language Parameter language
88: * @throws IllegalArgumentException If there is no such parameter in the query
89: */
90: <T> void setParameter(Parameter<T> parameter, String value, String language);
91:
92: /**
93: * Sets value of the specified parameter in the query.
94: * <p>
95: * If a value was already specified for the parameter, it is overwritten by the new one. This version inserts the
96: * string representation of the value directly into the query, without any type information.
97: *
98: * @param parameter Parameter object
99: * @param value Value to use
100: * @throws IllegalArgumentException If there is no such parameter in the query
101: * @see #setParameter(Parameter, Object)
102: */
103: <T> void setUntypedParameter(Parameter<T> parameter, Object value);
104:
105: /**
106: * Sets the position of the first result to retrieve.
107: *
108: * @param startPosition The position to set, starting at 0
109: */
110: void setFirstResult(int startPosition);
111:
112: /**
113: * Gets the currently set first result position.
114: *
115: * @return the first result position, 0 if none was set
116: */
117: int getFirstResult();
118:
119: /**
120: * Sets the maximum number of results the query should retrieve.
121: *
122: * @param maxResults The maximum number of results
123: */
124: void setMaxResults(int maxResults);
125:
126: /**
127: * Gets the currently set maximum number of results to retrieve
128: *
129: * @return Maximum results value, {@code Integer.MAX_VALUE} when none was set
130: */
131: int getMaxResults();
132:
133: /**
134: * Clears any previously set value of the specified parameter.
135: *
136: * @param parameter Parameter object
137: * @throws IllegalArgumentException If there is no such parameter in the query
138: */
139: void clearParameter(Parameter<?> parameter);
140:
141: /**
142: * Clears any previously set parameter values in this query.
143: */
144: void clearParameters();
145:
146: /**
147: * Assembles the query, using any parameter values specified, and returns it as a string.
148: *
149: * @return Assembled query
150: */
151: String assembleQuery();
152: }