Debian Codegraph @

bundles/org.eclipse.equinox.p2.metadata/src/org/eclipse/equinox/p2/query/QueryUtil.java

raw
1 /*******************************************************************************
2 * Copyright (c) 2010, 2023 Cloudsmith Inc. and others.
3 *
4 * This program and the accompanying materials
5 * are made available under the terms of the Eclipse Public License 2.0
6 * which accompanies this distribution, and is available at
7 * https://www.eclipse.org/legal/epl-2.0/
8 *
9 * SPDX-License-Identifier: EPL-2.0
10 *
11 * Contributors:
12 * Cloudsmith Inc. - initial API and implementation
13 * IBM Corporation - ongoing development
14 *******************************************************************************/
15 package org.eclipse.equinox.p2.query;
16
17 import java.util.ArrayList;
18 import java.util.Collection;
19 import java.util.List;
20 import org.eclipse.equinox.internal.p2.metadata.InstallableUnit;
21 import org.eclipse.equinox.internal.p2.metadata.expression.ContextExpression;
22 import org.eclipse.equinox.internal.p2.metadata.expression.Expression.VariableFinder;
23 import org.eclipse.equinox.internal.p2.metadata.expression.ExpressionFactory;
24 import org.eclipse.equinox.p2.metadata.IInstallableUnit;
25 import org.eclipse.equinox.p2.metadata.IInstallableUnitFragment;
26 import org.eclipse.equinox.p2.metadata.IVersionedId;
27 import org.eclipse.equinox.p2.metadata.MetadataFactory;
28 import org.eclipse.equinox.p2.metadata.Version;
29 import org.eclipse.equinox.p2.metadata.VersionRange;
30 import org.eclipse.equinox.p2.metadata.expression.ExpressionUtil;
31 import org.eclipse.equinox.p2.metadata.expression.IContextExpression;
32 import org.eclipse.equinox.p2.metadata.expression.IExpression;
33 import org.eclipse.equinox.p2.metadata.expression.IExpressionFactory;
34
35 /**
36 * Helper class for query related tasks.
37 *
38 * @since 2.0
39 */
40 public class QueryUtil {
41
42 public static final IQuery<IInstallableUnit> ALL_UNITS = QueryUtil.createMatchQuery(ExpressionUtil.TRUE_EXPRESSION);
43
44 public static final String ANY = "*"; //$NON-NLS-1$
45
46 public static final IQuery<IInstallableUnit> NO_UNITS = QueryUtil.createQuery("limit(0)"); //$NON-NLS-1$
47
48 public static final String PROP_TYPE_CATEGORY = "org.eclipse.equinox.p2.type.category"; //$NON-NLS-1$
49
50 public static final String PROP_TYPE_GROUP = "org.eclipse.equinox.p2.type.group"; //$NON-NLS-1$
51
52 public static final String PROP_TYPE_PATCH = "org.eclipse.equinox.p2.type.patch"; //$NON-NLS-1$
53
54 private static final IExpression matchesRequirementsExpression = ExpressionUtil.parse("$0.exists(r | this ~= r)"); //$NON-NLS-1$
55
56 private static final IExpression matchIU_ID = ExpressionUtil.parse("id == $0"); //$NON-NLS-1$
57 private static final IExpression matchIU_IDAndRange = ExpressionUtil.parse("id == $0 && version ~= $1"); //$NON-NLS-1$
58 private static final IExpression matchIU_IDAndVersion = ExpressionUtil.parse("id == $0 && version == $1"); //$NON-NLS-1$
59 private static final IExpression matchIU_Range = ExpressionUtil.parse("version ~= $0"); //$NON-NLS-1$
60 private static final IExpression matchIU_Version = ExpressionUtil.parse("version == $0"); //$NON-NLS-1$
61 private static final IExpression matchIU_propAny = ExpressionUtil.parse("properties[$0] != null"); //$NON-NLS-1$
62 private static final IExpression matchIU_propNull = ExpressionUtil.parse("properties[$0] == null"); //$NON-NLS-1$
63 private static final IExpression matchIU_propTrue = ExpressionUtil.parse("properties[$0] == true"); //$NON-NLS-1$
64 private static final IExpression matchIU_propValue = ExpressionUtil.parse("properties[$0] == $1"); //$NON-NLS-1$
65
66 /**
67 * Creates a queryable that combines the given collection of input queryables
68 *
69 * @param queryables The collection of queryables to be combined
70 */
71 public static <T> IQueryable<T> compoundQueryable(Collection<? extends IQueryable<T>> queryables) {
72 // don't suppress the warning as it will cause warnings in the official build
73 // see bug 423628. Write this without unchecked conversion.
74 return new CompoundQueryable<>(queryables);
75 }
76
77 /**
78 * Creates a queryable that combines the two provided input queryables
79 *
80 * @param query1 The first queryable
81 * @param query2 The second queryable
82 */
83 public static <T> IQueryable<T> compoundQueryable(IQueryable<T> query1, IQueryable<T> query2) {
84 return new CompoundQueryable<>(List.of(query1, query2));
85 }
86
87 /**
88 * Creates a compound query that combines the given queries. If all queries
89 * are candidate match queries, then the queries will be concatenated as a
90 * boolean 'and' or a boolean 'or' expression depending on the <code>and</code>
91 * flag. If at least one query is a full query, all queries will instead be evaluated
92 * using intersection when <code>and</code> is <code>true</code> or a union.
93 *
94 * @param queries The queries to perform
95 * @param and <code>true</code> if this query represents an intersection or a
96 * logical 'and', and <code>false</code> if this query represents a union or
97 * a logical 'or'.
98 * @return A compound query
99 */
100 @SuppressWarnings("unchecked")
101 public static <T> IQuery<T> createCompoundQuery(Collection<? extends IQuery<? extends T>> queries, boolean and) {
102 IExpressionFactory factory = ExpressionUtil.getFactory();
103 int top = queries.size();
104 if (top == 1)
105 return (IQuery<T>) queries.iterator().next();
106
107 Class<? extends T> elementClass = (Class<T>) Object.class;
108 if (top == 0)
109 return QueryUtil.createMatchQuery(elementClass, ExpressionUtil.TRUE_EXPRESSION);
110
111 IExpression[] expressions = new IExpression[top];
112 boolean justBooleans = true;
113 boolean justContexts = true;
114 int idx = 0;
115 for (IQuery<? extends T> query : queries) {
116 if (query instanceof IMatchQuery<?>)
117 justContexts = false;
118 else
119 justBooleans = false;
120
121 IExpression expr = query.getExpression();
122 if (expr == null)
123 expr = factory.toExpression(query);
124
125 Class<? extends T> ec = ExpressionQuery.getElementClass(query);
126 if (elementClass == null)
127 elementClass = ec;
128 else if (elementClass != ec) {
129 if (elementClass.isAssignableFrom(ec)) {
130 if (and)
131 // Use most restrictive class
132 elementClass = ec;
133 } else if (ec.isAssignableFrom(elementClass)) {
134 if (!and)
135 // Use least restrictive class
136 elementClass = ec;
137 }
138 }
139 expressions[idx++] = expr;
140 }
141
142 if (justBooleans) {
143 IExpression compound = and ? factory.and(expressions) : factory.or(expressions);
144 return QueryUtil.createMatchQuery(elementClass, compound);
145 }
146
147 if (!justContexts) {
148 // Mix of boolean queries and context queries. All must be converted into context then.
149 for (idx = 0; idx < expressions.length; ++idx)
150 expressions[idx] = makeContextExpression(factory, expressions[idx]);
151 }
152
153 IExpression compound = expressions[0];
154 for (idx = 1; idx < expressions.length; ++idx)
155 compound = and ? factory.intersect(compound, expressions[idx]) : factory.union(compound, expressions[idx]);
156 return QueryUtil.createQuery(elementClass, compound);
157 }
158
159 /**
160 * Creates a compound query that combines the two queries. If both queries
161 * are candidate match queries, then the queries will be concatenated as a
162 * boolean 'and' or a boolean 'or' expression depending on the <code>and</code>
163 * flag. If at least one query is a full query, all queries will instead be evaluated
164 * using intersection when <code>and</code> is <code>true</code> or a union.
165 *
166 * @param query1 the first query
167 * @param query2 the second query
168 * @param and <code>true</code> if this query represents an intersection or a
169 * logical 'and', and <code>false</code> if this query represents a union or
170 * a logical 'or'.
171 * @return A compound query
172 */
173 public static <T> IQuery<T> createCompoundQuery(IQuery<? extends T> query1, IQuery<T> query2, boolean and) {
174 ArrayList<IQuery<? extends T>> queries = new ArrayList<>(2);
175 queries.add(query1);
176 queries.add(query2);
177 return createCompoundQuery(queries, and);
178 }
179
180 /**
181 * Returns a query that matches all {@link InstallableUnit} elements
182 */
183 public static IQuery<IInstallableUnit> createIUAnyQuery() {
184 return ALL_UNITS;
185 }
186
187 /**
188 * Creates a new query that will return the members of the
189 * given <code>category</code>. If the specified {@link IInstallableUnit}
190 * is not a category, then no installable unit will satisfy the query.
191 *
192 * @param category The category
193 * @return A query that returns category members
194 */
195 public static IQuery<IInstallableUnit> createIUCategoryMemberQuery(IInstallableUnit category) {
196 if (QueryUtil.isCategory(category))
197 return QueryUtil.createMatchQuery(matchesRequirementsExpression, category.getRequirements());
198 return NO_UNITS;
199 }
200
201 /**
202 * Creates a query matching every {@link IInstallableUnit} that is a category.
203 * @return The query that matches categories
204 * @since 2.0
205 */
206 public static IQuery<IInstallableUnit> createIUCategoryQuery() {
207 return createIUPropertyQuery(QueryUtil.PROP_TYPE_CATEGORY, Boolean.TRUE.toString());
208 }
209
210 /**
211 * Creates a query matching every {@link IInstallableUnit} that is a group.
212 * @return a query that matches all groups
213 */
214 public static IQuery<IInstallableUnit> createIUGroupQuery() {
215 return createIUPropertyQuery(PROP_TYPE_GROUP, Boolean.TRUE.toString());
216 }
217
218 /**
219 * Creates an {@link IInstallableUnit} that will match all patches.
220 * @return The created query
221 */
222 public static IQuery<IInstallableUnit> createIUPatchQuery() {
223 return createIUPropertyQuery(QueryUtil.PROP_TYPE_PATCH, Boolean.TRUE.toString());
224 }
225
226 /**
227 * Creates an {@link IInstallableUnit} that will match all products.
228 * @return The created query
229 * @since 2.2
230 */
231 public static IQuery<IInstallableUnit> createIUProductQuery() {
232 return createIUPropertyQuery(MetadataFactory.InstallableUnitDescription.PROP_TYPE_PRODUCT, Boolean.TRUE.toString());
233 }
234
235 /**
236 * Creates a query that searches for {@link IInstallableUnit} instances that have
237 * a property whose value matches the provided value. If no property name is
238 * specified, then all {@link IInstallableUnit} instances are accepted.
239 * @param propertyName The key of the property to match or <code>null</code> to match all
240 * @param propertyValue The value of the property. Can be {@link #ANY} to match all values
241 * except <code>null</code>
242 * @return The query matching properties
243 */
244 public static IQuery<IInstallableUnit> createIUPropertyQuery(String propertyName, String propertyValue) {
245 if (propertyName == null)
246 return QueryUtil.createMatchQuery(ExpressionUtil.TRUE_EXPRESSION);
247 if (propertyValue == null)
248 return QueryUtil.createMatchQuery(matchIU_propNull, propertyName);
249 if (ANY.equals(propertyValue))
250 return QueryUtil.createMatchQuery(matchIU_propAny, propertyName);
251 if (Boolean.parseBoolean(propertyValue))
252 return QueryUtil.createMatchQuery(matchIU_propTrue, propertyName);
253 return QueryUtil.createMatchQuery(matchIU_propValue, propertyName, propertyValue);
254 }
255
256 /**
257 * Creates a query that will match any {@link IInstallableUnit} with the given
258 * id and version.
259 *
260 * @param versionedId The precise id/version combination that a matching unit must have
261 * @return a query that matches IU's by id and version
262 */
263 public static IQuery<IInstallableUnit> createIUQuery(IVersionedId versionedId) {
264 return createIUQuery(versionedId.getId(), versionedId.getVersion());
265 }
266
267 /**
268 * Creates a query that will match any {@link IInstallableUnit} with the given
269 * id, regardless of version.
270 *
271 * @param id The installable unit id to match, or <code>null</code> to match any id
272 * @return a query that matches IU's by id
273 */
274 public static IQuery<IInstallableUnit> createIUQuery(String id) {
275 return id == null ? ALL_UNITS : QueryUtil.createMatchQuery(matchIU_ID, id);
276 }
277
278 /**
279 * Creates a query that will match any {@link IInstallableUnit} with the given
280 * id and version.
281 *
282 * @param id The installable unit id to match, or <code>null</code> to match any id
283 * @param version The precise version that a matching unit must have or <code>null</code>
284 * to match any version
285 * @return a query that matches IU's by id and version
286 */
287 public static IQuery<IInstallableUnit> createIUQuery(String id, Version version) {
288 if (version == null || version.equals(Version.emptyVersion))
289 return createIUQuery(id);
290 if (id == null)
291 return QueryUtil.createMatchQuery(matchIU_Version, version);
292 return QueryUtil.createMatchQuery(matchIU_IDAndVersion, id, version);
293 }
294
295 /**
296 * Creates a query that will match any {@link IInstallableUnit} with the given
297 * id, and whose version falls in the provided range.
298 *
299 * @param id The installable unit id to match, or <code>null</code> to match any id
300 * @param range The version range to match or <code>null</code> to match any range.
301 * @return a query that matches IU's by id and range
302 */
303 public static IQuery<IInstallableUnit> createIUQuery(String id, VersionRange range) {
304 if (range == null || range.equals(VersionRange.emptyRange))
305 return createIUQuery(id);
306 if (id == null)
307 return QueryUtil.createMatchQuery(matchIU_Range, range);
308 return QueryUtil.createMatchQuery(matchIU_IDAndRange, id, range);
309 }
310
311 /**
312 * Creates a query that returns the latest version for each unique id of an {@link IVersionedId}.
313 * All other elements are discarded.
314 * @return A query matching the latest version for each id.
315 */
316 public static IQuery<IInstallableUnit> createLatestIUQuery() {
317 return QueryUtil.createQuery(ExpressionUtil.getFactory().latest(ExpressionFactory.EVERYTHING));
318 }
319
320 /**
321 * Creates a query that returns the latest version for each unique id of an {@link IVersionedId}
322 * from the collection produced by <code>query</code>.
323 * All other elements are discarded.
324 * @param query The query that precedes the latest query when evaluating.
325 * @return A query matching the latest version for each id.
326 */
327 public static <T extends IVersionedId> IQuery<T> createLatestQuery(IQuery<T> query) {
328 IContextExpression<T> ctxExpr = ExpressionQuery.createExpression(query);
329 IExpressionFactory factory = ExpressionUtil.getFactory();
330 @SuppressWarnings("unchecked")
331 Class<T> elementClass = (Class<T>) IVersionedId.class;
332 return QueryUtil.createQuery(elementClass, factory.latest(((ContextExpression<?>) ctxExpr).operand), ctxExpr.getParameters());
333 }
334
335 /**
336 * Creates a limit query that can be used to limit the number of query results returned. Once
337 * the limit is reached, the query is terminated.
338 * @param query The query that should be limited
339 * @param limit A positive integer denoting the limit
340 * @return A limited query
341 * @since 2.0
342 */
343 public static <T> IQuery<T> createLimitQuery(IQuery<T> query, int limit) {
344 IContextExpression<T> ctxExpr = ExpressionQuery.createExpression(query);
345 IExpressionFactory factory = ExpressionUtil.getFactory();
346 return QueryUtil.createQuery(ExpressionQuery.getElementClass(query), factory.limit(((ContextExpression<T>) ctxExpr).operand, limit), ctxExpr.getParameters());
347 }
348
349 /**
350 * Creates an {@link IInstallableUnit} query that will iterate over all candidates and discriminate by
351 * applying the boolean <code>matchExpression</code> on each candidate.
352 * @param matchExpression The boolean expression used for filtering one candidate
353 * @param parameters Values for parameter substitution
354 * @return The created query
355 */
356 public static IQuery<IInstallableUnit> createMatchQuery(IExpression matchExpression, Object... parameters) {
357 return new ExpressionMatchQuery<>(IInstallableUnit.class, matchExpression, parameters);
358 }
359
360 /**
361 * Parses the <code>matchExpression</code> and creates an {@link IInstallableUnit} query that will
362 * iterate over all candidates and discriminate by applying the boolean <code>matchExpression</code>
363 * on each candidate.
364 * @param matchExpression The boolean expression used for filtering one candidate
365 * @param parameters Values for parameter substitution
366 * @return The created query
367 */
368 public static IQuery<IInstallableUnit> createMatchQuery(String matchExpression, Object... parameters) {
369 return new ExpressionMatchQuery<>(IInstallableUnit.class, matchExpression, parameters);
370 }
371
372 /**
373 * Creates an query that will iterate over all candidates and discriminate all
374 * candidates that are not instances of <code>matchingClass</code> or for which
375 * the boolean <code>matchExpression</code> returns false.
376 * @param matchingClass The class that matching candidates must be an instance of
377 * @param matchExpression The boolean expression used for filtering one candidate
378 * @param parameters Values for parameter substitution
379 * @return The created query
380 */
381 public static <T> IQuery<T> createMatchQuery(Class<? extends T> matchingClass, IExpression matchExpression, Object... parameters) {
382 return new ExpressionMatchQuery<>(matchingClass, matchExpression, parameters);
383 }
384
385 /**
386 * Parses the <code>matchExpression</code> and creates an query that will iterate over
387 * all candidates and discriminate all candidates that are not instances of
388 * <code>matchingClass</code> or for which the boolean <code>matchExpression</code>
389 * returns false.
390 *
391 * @param <T> The type of input object that the created query accepts
392 * @param matchingClass The class that matching candidates must be an instance of
393 * @param matchExpression The boolean expression used for filtering one candidate
394 * @param parameters Values for parameter substitution
395 * @return The created query
396 */
397 public static <T> IQuery<T> createMatchQuery(Class<? extends T> matchingClass, String matchExpression, Object... parameters) {
398 return new ExpressionMatchQuery<>(matchingClass, matchExpression, parameters);
399 }
400
401 /**
402 * <p>Creates a piped query based on the provided input queries.</p>
403 * <p>A pipe is a composite query in which each sub-query is executed in succession.
404 * The results from the ith sub-query are piped as input into the i+1th sub-query. The
405 * query will short-circuit if any query returns an empty result set.</p>
406 *
407 * @param queries the ordered list of queries to perform
408 * @return A query pipe
409 */
410 @SuppressWarnings("unchecked")
411 public static <T> IQuery<T> createPipeQuery(Collection<? extends IQuery<? extends T>> queries) {
412 IExpressionFactory factory = ExpressionUtil.getFactory();
413 int top = queries.size();
414 IExpression[] expressions = new IExpression[top];
415 int idx = 0;
416 for (IQuery<? extends T> query : queries) {
417 IExpression expr = query.getExpression();
418 if (expr == null)
419 expr = factory.toExpression(query);
420 expressions[idx++] = expr;
421 }
422 IExpression pipe = factory.pipe(expressions);
423 VariableFinder finder = new VariableFinder(ExpressionFactory.EVERYTHING);
424 pipe.accept(finder);
425 return finder.isFound() ? QueryUtil.createQuery((Class<T>) Object.class, pipe) : QueryUtil.createMatchQuery((Class<T>) Object.class, pipe);
426 }
427
428 /**
429 * <p>Creates a piped query based on the provided input queries.</p>
430 * <p>A pipe is a composite query in which each sub-query is executed in succession.
431 * The results from the ith sub-query are piped as input into the i+1th sub-query. The
432 * query will short-circuit if any query returns an empty result set.</p>
433 *
434 * @param query1 the first query
435 * @param query2 the second query
436 * @return A query pipe
437 */
438 public static <T> IQuery<T> createPipeQuery(IQuery<? extends T> query1, IQuery<? extends T> query2) {
439 ArrayList<IQuery<? extends T>> queries = new ArrayList<>(2);
440 queries.add(query1);
441 queries.add(query2);
442 return createPipeQuery(queries);
443 }
444
445 /**
446 * Creates an {@link IInstallableUnit} query based on an <code>expression</code> that
447 * uses all candidates as input.
448 * @param expression The query expression
449 * @param parameters Values for parameter substitution
450 * @return The created query
451 */
452 public static IQuery<IInstallableUnit> createQuery(IExpression expression, Object... parameters) {
453 return new ExpressionQuery<>(IInstallableUnit.class, expression, parameters);
454 }
455
456 /**
457 * Parses the <code>expression</code> and creates an {@link IInstallableUnit} query. The
458 * <code>expression</code> is expected to use all candidates as input.
459 * @param expression The query expression
460 * @param parameters Values for parameter substitution
461 * @return The created query
462 */
463 public static IQuery<IInstallableUnit> createQuery(String expression, Object... parameters) {
464 return new ExpressionQuery<>(IInstallableUnit.class, expression, parameters);
465 }
466
467 /**
468 * Creates a query that will limit the result to instances of the <code>matchingClass</code>. The
469 * <code>expression</code> is expected to use all candidates as input.
470 * @param matchingClass The class used as discriminator for the result
471 * @param expression The query expression
472 * @param parameters Values for parameter substitution
473 * @return The created query
474 */
475 public static <T> IQuery<T> createQuery(Class<? extends T> matchingClass, IExpression expression, Object... parameters) {
476 return new ExpressionQuery<>(matchingClass, expression, parameters);
477 }
478
479 /**
480 * Parses the <code>expression</code> and creates a query that will limit the result
481 * to instances of the <code>matchingClass</code>. The <code>expression</code> is expected
482 * to use all candidates as input.
483 * @param matchingClass The class used as discriminator for the result
484 * @param expression The query expression
485 * @param parameters Values for parameter substitution
486 * @return The created query
487 */
488 public static <T> IQuery<T> createQuery(Class<? extends T> matchingClass, String expression, Object... parameters) {
489 return new ExpressionQuery<>(matchingClass, expression, parameters);
490 }
491
492 /**
493 * Test if the {@link IInstallableUnit} is a category.
494 * @param iu the element being tested.
495 * @return <code>true</code> if the parameter is a category.
496 */
497 public static boolean isCategory(IInstallableUnit iu) {
498 String value = iu.getProperty(PROP_TYPE_CATEGORY);
499 if (value != null && (value.equals(Boolean.TRUE.toString())))
500 return true;
501 return false;
502 }
503
504 /**
505 * Test if the {@link IInstallableUnit} is a fragment.
506 * @param iu the element being tested.
507 * @return <code>true</code> if the parameter is a fragment.
508 */
509 public static boolean isFragment(IInstallableUnit iu) {
510 return iu instanceof IInstallableUnitFragment;
511 }
512
513 /**
514 * Test if the {@link IInstallableUnit} is a group.
515 * @param iu the element being tested.
516 * @return <code>true</code> if the parameter is a group.
517 */
518 public static boolean isGroup(IInstallableUnit iu) {
519 String value = iu.getProperty(PROP_TYPE_GROUP);
520 if (value != null && (value.equals(Boolean.TRUE.toString())))
521 return true;
522 return false;
523 }
524
525 /**
526 * Test if the {@link IInstallableUnit} is a product.
527 * @param iu the element being tested.
528 * @return <code>true</code> if the parameter is a group.
529 * @since 2.2
530 */
531 public static boolean isProduct(IInstallableUnit iu) {
532 String value = iu.getProperty(MetadataFactory.InstallableUnitDescription.PROP_TYPE_PRODUCT);
533 if (value != null && (value.equals(Boolean.TRUE.toString())))
534 return true;
535 return false;
536 }
537
538 /**
539 * Test if the {@link IInstallableUnit} is a patch.
540 * @param iu the element being tested.
541 * @return <code>true</code> if the parameter is a patch.
542 */
543 public static boolean isPatch(IInstallableUnit iu) {
544 String value = iu.getProperty(PROP_TYPE_PATCH);
545 if (value != null && (value.equals(Boolean.TRUE.toString())))
546 return true;
547 return false;
548 }
549
550 private static IExpression makeContextExpression(IExpressionFactory factory, IExpression expr) {
551 VariableFinder finder = new VariableFinder(ExpressionFactory.EVERYTHING);
552 expr.accept(finder);
553 if (!finder.isFound())
554 expr = factory.select(ExpressionFactory.EVERYTHING, factory.lambda(ExpressionFactory.THIS, expr));
555 return expr;
556 }
557 }