1 /*
2 * ModeShape (http://www.modeshape.org)
3 * See the COPYRIGHT.txt file distributed with this work for information
4 * regarding copyright ownership. Some portions may be licensed
5 * to Red Hat, Inc. under one or more contributor license agreements.
6 * See the AUTHORS.txt file in the distribution for a full listing of
7 * individual contributors.
8 *
9 * ModeShape is free software. Unless otherwise indicated, all code in ModeShape
10 * is licensed to you under the terms of the GNU Lesser General Public License as
11 * published by the Free Software Foundation; either version 2.1 of
12 * the License, or (at your option) any later version.
13 *
14 * ModeShape is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this software; if not, write to the Free
21 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
22 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
23 */
24 package org.modeshape.graph.query;
25
26 import java.util.Collections;
27 import java.util.HashMap;
28 import java.util.Map;
29 import net.jcip.annotations.Immutable;
30 import org.modeshape.common.collection.Problems;
31 import org.modeshape.common.collection.SimpleProblems;
32 import org.modeshape.common.util.CheckArg;
33 import org.modeshape.graph.query.model.BindVariableName;
34 import org.modeshape.graph.query.model.TypeSystem;
35 import org.modeshape.graph.query.plan.PlanHints;
36 import org.modeshape.graph.query.validate.Schemata;
37
38 /**
39 * An immutable context in which queries are to be executed. Each query context defines the information that is available during
40 * query execution.
41 */
42 @Immutable
43 public class QueryContext {
44 private final TypeSystem typeSystem;
45 private final PlanHints hints;
46 private final Schemata schemata;
47 private final Problems problems;
48 private final Map<String, Object> variables;
49
50 /**
51 * Create a new context for query execution.
52 *
53 * @param schemata the schemata
54 * @param typeSystem the types system
55 * @param hints the hints, or null if there are no hints
56 * @param problems the problems container, or null if a new problems container should be created
57 * @param variables the mapping of variables and values, or null if there are no such variables
58 * @throws IllegalArgumentException if the values or schmata are null
59 */
60 public QueryContext( Schemata schemata,
61 TypeSystem typeSystem,
62 PlanHints hints,
63 Problems problems,
64 Map<String, Object> variables ) {
65 CheckArg.isNotNull(typeSystem, "typeSystem");
66 CheckArg.isNotNull(schemata, "schemata");
67 this.typeSystem = typeSystem;
68 this.hints = hints != null ? hints : new PlanHints();
69 this.schemata = schemata;
70 this.problems = problems != null ? problems : new SimpleProblems();
71 this.variables = variables != null ? Collections.<String, Object>unmodifiableMap(new HashMap<String, Object>(variables)) : Collections.<String, Object>emptyMap();
72 assert this.typeSystem != null;
73 assert this.hints != null;
74 assert this.schemata != null;
75 assert this.problems != null;
76 assert this.variables != null;
77 }
78
79 /**
80 * Create a new context for query execution.
81 *
82 * @param schemata the schemata
83 * @param typeSystem the types system
84 * @param hints the hints, or null if there are no hints
85 * @param problems the problems container, or null if a new problems container should be created
86 * @throws IllegalArgumentException if the values or schmata are null
87 */
88 public QueryContext( Schemata schemata,
89 TypeSystem typeSystem,
90 PlanHints hints,
91 Problems problems ) {
92 this(schemata, typeSystem, hints, problems, null);
93 }
94
95 /**
96 * Create a new context for query execution.
97 *
98 * @param schemata the schemata
99 * @param typeSystem the types system
100 * @param hints the hints, or null if there are no hints
101 * @throws IllegalArgumentException if the context or schmata are null
102 */
103 public QueryContext( Schemata schemata,
104 TypeSystem typeSystem,
105 PlanHints hints ) {
106 this(schemata, typeSystem, hints, null, null);
107 }
108
109 /**
110 * Create a new context for query execution.
111 *
112 * @param schemata the schemata
113 * @param typeSystem the types system
114 * @throws IllegalArgumentException if the values or schmata are null
115 */
116 public QueryContext( Schemata schemata,
117 TypeSystem typeSystem ) {
118 this(schemata, typeSystem, null, null, null);
119 }
120
121 /**
122 * Create a new context that is a copy of the supplied context. This constructor is useful for subclasses that wish to add
123 * store additional fields in a QueryContext.
124 *
125 * @param original the original context
126 * @throws IllegalArgumentException if the original is null
127 */
128 protected QueryContext( QueryContext original ) {
129 this(original.schemata, original.typeSystem, original.hints, original.problems, original.variables);
130 }
131
132 /**
133 * Get the interface for working with literal values and types.
134 *
135 * @return the type system; never null
136 */
137 public TypeSystem getTypeSystem() {
138 return typeSystem;
139 }
140
141 /**
142 * Get the plan hints.
143 *
144 * @return the plan hints; never null
145 */
146 public final PlanHints getHints() {
147 return hints;
148 }
149
150 /**
151 * Get the problem container used by this query context. Any problems that have been encountered will be accumlated in this
152 * container.
153 *
154 * @return the problem container; never null
155 */
156 public final Problems getProblems() {
157 return problems;
158 }
159
160 /**
161 * Get the definition of the tables available within this query context.
162 *
163 * @return the schemata; never null
164 */
165 public Schemata getSchemata() {
166 return schemata;
167 }
168
169 /**
170 * Get the variables that are to be substituted into the {@link BindVariableName} used in the query.
171 *
172 * @return immutable map of variable values keyed by their name; never null but possibly empty
173 */
174 public Map<String, Object> getVariables() {
175 return variables;
176 }
177
178 /**
179 * {@inheritDoc}
180 *
181 * @see java.lang.Object#equals(java.lang.Object)
182 */
183 @Override
184 public boolean equals( Object obj ) {
185 if (obj == this) return true;
186 if (obj instanceof QueryContext) {
187 QueryContext that = (QueryContext)obj;
188 if (!this.typeSystem.equals(that.getTypeSystem())) return false;
189 if (!this.schemata.equals(that.getSchemata())) return false;
190 if (!this.variables.equals(that.getVariables())) return false;
191 return true;
192 }
193 return false;
194 }
195
196 /**
197 * Obtain a copy of this context, except that the copy uses the supplied type system.
198 *
199 * @param typeSystem the type system that should be used in the new query context
200 * @return the new context; never null
201 * @throws IllegalArgumentException if the execution context reference is null
202 */
203 public QueryContext with( TypeSystem typeSystem ) {
204 CheckArg.isNotNull(typeSystem, "typeSystem");
205 return new QueryContext(schemata, typeSystem, hints, problems, variables);
206 }
207
208 /**
209 * Obtain a copy of this context, except that the copy uses the supplied schemata.
210 *
211 * @param schemata the schemata that should be used in the new context
212 * @return the new context; never null
213 * @throws IllegalArgumentException if the schemata reference is null
214 */
215 public QueryContext with( Schemata schemata ) {
216 CheckArg.isNotNull(schemata, "schemata");
217 return new QueryContext(schemata, typeSystem, hints, problems, variables);
218 }
219
220 /**
221 * Obtain a copy of this context, except that the copy uses the supplied hints.
222 *
223 * @param hints the hints that should be used in the new context
224 * @return the new context; never null
225 * @throws IllegalArgumentException if the hints reference is null
226 */
227 public QueryContext with( PlanHints hints ) {
228 CheckArg.isNotNull(hints, "hints");
229 return new QueryContext(schemata, typeSystem, hints, problems, variables);
230 }
231
232 /**
233 * Obtain a copy of this context, except that the copy uses the supplied problem container.
234 *
235 * @param problems the problems that should be used in the new context; may be null if a new problem container should be used
236 * @return the new context; never null
237 */
238 public QueryContext with( Problems problems ) {
239 return new QueryContext(schemata, typeSystem, hints, problems, variables);
240 }
241
242 /**
243 * Obtain a copy of this context, except that the copy uses the supplied variables.
244 *
245 * @param variables the variables that should be used in the new context; may be null if there are no such variables
246 * @return the new context; never null
247 */
248 public QueryContext with( Map<String, Object> variables ) {
249 return new QueryContext(schemata, typeSystem, hints, problems, variables);
250 }
251
252 }