Package: QueryHolder

QueryHolder

Coverage

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