Debian Codegraph @

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

raw
1 /*******************************************************************************
2 * Copyright (c) 2009, 2017 EclipseSource and others.
3 *
4 * This
5 * program and the accompanying materials are made available under the terms of
6 * the Eclipse Public License 2.0 which accompanies this distribution, and is
7 * available at
8 * https://www.eclipse.org/legal/epl-2.0/
9 *
10 * SPDX-License-Identifier: EPL-2.0
11 *
12 * Contributors:
13 * EclipseSource - initial API and implementation
14 * IBM Corporation - ongoing development
15 ******************************************************************************/
16 package org.eclipse.equinox.p2.query;
17
18 import java.util.Iterator;
19 import org.eclipse.equinox.p2.metadata.expression.IExpression;
20
21 /**
22 * This class represents a simple Java-based query. Clients may subclass and
23 * override the {@link #isMatch(Object)} method in order to write simple
24 * queries against p2 metadata.
25 * <p>
26 * Note that hand-written queries cannot be optimized for queryables containing
27 * indices, or for remote queryables. In general you should use one of the pre-defined
28 * queries found in {@link QueryUtil} if possible, to obtain queries optimized for indexing and
29 * remote execution. This class is intended for simple queries against small data
30 * sources where indexed lookup and remote query execution are not needed.
31 * </p>
32 * @deprecated If possible, use one of the predefined queries in {@link QueryUtil}
33 * or use the {@link QueryUtil#createMatchQuery(String, Object...)}
34 * to create a custom expression based query. If the query cannot be expressed using
35 * the p2QL, then use a predefined or custom expression query as a first filter
36 * (in worst case, use {@link QueryUtil#createIUAnyQuery()}) and then provide further filtering
37 * like so:<pre>
38 * for(iter = queryable.query(someExpressionQuery).iterator(); iter.hasNext();) {
39 * // do your match here
40 * }</pre>
41 * @since 2.0
42 */
43 @Deprecated
44 public abstract class MatchQuery<T> implements IMatchQuery<T> {
45
46 /**
47 * Returns whether the given object satisfies the parameters of this query.
48 *
49 * @param candidate The object to perform the query against
50 * @return <code>true</code> if the unit satisfies the parameters
51 * of this query, and <code>false</code> otherwise
52 *
53 * @noreference This method is not intended to be referenced by clients.
54 * Clients should call {@link #perform(Iterator)}
55 * @since 2.0
56 */
57 @Override
58 public abstract boolean isMatch(T candidate);
59
60 /**
61 * Performs this query on the given iterator, passing all objects in the iterator
62 * that match the criteria of this query to the given result.
63 */
64 @Override
65 public final IQueryResult<T> perform(Iterator<T> iterator) {
66 Collector<T> result = new Collector<>();
67 while (iterator.hasNext()) {
68 T candidate = iterator.next();
69 if (candidate != null && isMatch(candidate))
70 if (!result.accept(candidate))
71 break;
72 }
73 return result;
74 }
75
76 /**
77 * Execute any pre-processing that must be done before this query is performed against
78 * a particular iterator. This method may be used by subclasses to do any calculations,
79 * caching, or other preparation for the query.
80 * <p>
81 * This method is internal to the framework. Subclasses may override this method, but
82 * should not call this method.
83 *
84 * @noreference This method is not intended to be referenced by clients.
85 */
86 public void prePerform() {
87 // nothing to do by default
88 }
89
90 /**
91 * Execute any post-processing that must be done after this query has been performed against
92 * a particular iterator. This method may be used by subclasses to clear caches or any other
93 * cleanup that should occur after a query.
94 * <p>
95 * This method will be called even if the query does not complete successfully.
96 * <p>
97 * This method is internal to the framework. Subclasses may override this method, but
98 * should not call this method.
99 *
100 * @noreference This method is not intended to be referenced by clients.
101 */
102 public void postPerform() {
103 // nothing to do by default
104 }
105
106 @Override
107 public IExpression getExpression() {
108 return null;
109 }
110 }