001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2015 ForgeRock AS.
015 */
016
017package org.forgerock.util.query;
018
019import java.util.List;
020
021/**
022 * A visitor of {@code QueryFilter}s, in the style of the visitor design
023 * pattern.
024 * <p>
025 * Classes implementing this interface can query filters in a type-safe manner.
026 * When a visitor is passed to a filter's accept method, the corresponding visit
027 * method most applicable to that filter is invoked.
028 *
029 * @param <R>
030 *            The return type of this visitor's methods. Use
031 *            {@link java.lang.Void} for visitors that do not need to return
032 *            results.
033 * @param <P>
034 *            The type of the additional parameter to this visitor's methods.
035 *            Use {@link java.lang.Void} for visitors that do not need an
036 *            additional parameter.
037 * @param <F>
038 *            The type of the field definitions in this visitor's methods.
039 */
040public interface QueryFilterVisitor<R, P, F> {
041
042    /**
043     * Visits an {@code and} filter.
044     * <p>
045     * <b>Implementation note</b>: for the purposes of matching, an empty
046     * sub-filter list should always evaluate to {@code true}.
047     *
048     * @param p
049     *            A visitor specified parameter.
050     * @param subFilters
051     *            The unmodifiable list of sub-filters.
052     * @return Returns a visitor specified result.
053     */
054    R visitAndFilter(P p, List<QueryFilter<F>> subFilters);
055
056    /**
057     * Visits a boolean literal filter.
058     *
059     * @param p
060     *            A visitor specified parameter.
061     * @param value
062     *            The boolean literal value.
063     * @return Returns a visitor specified result.
064     */
065    R visitBooleanLiteralFilter(P p, boolean value);
066
067    /**
068     * Visits a {@code contains} filter.
069     *
070     * @param p
071     *            A visitor specified parameter.
072     * @param field
073     *            A definition of the field to be compared.
074     * @param valueAssertion
075     *            The value assertion.
076     * @return Returns a visitor specified result.
077     */
078    R visitContainsFilter(P p, F field, Object valueAssertion);
079
080    /**
081     * Visits a {@code equality} filter.
082     *
083     * @param p
084     *            A visitor specified parameter.
085     * @param field
086     *            A definition of the field to be compared.
087     * @param valueAssertion
088     *            The value assertion.
089     * @return Returns a visitor specified result.
090     */
091    R visitEqualsFilter(P p, F field, Object valueAssertion);
092
093    /**
094     * Visits a {@code comparison} filter.
095     *
096     * @param p
097     *            A visitor specified parameter.
098     * @param field
099     *            A definition of the field to be compared.
100     * @param operator
101     *            The operator to use for the comparison, which will not be one of
102     *            the core operator names.
103     * @param valueAssertion
104     *            The value assertion.
105     * @return Returns a visitor specified result.
106     */
107    R visitExtendedMatchFilter(P p, F field, String operator, Object valueAssertion);
108
109    /**
110     * Visits a {@code greater than} filter.
111     *
112     * @param p
113     *            A visitor specified parameter.
114     * @param field
115     *            A definition of the field to be compared.
116     * @param valueAssertion
117     *            The value assertion.
118     * @return Returns a visitor specified result.
119     */
120    R visitGreaterThanFilter(P p, F field, Object valueAssertion);
121
122    /**
123     * Visits a {@code greater than or equal to} filter.
124     *
125     * @param p
126     *            A visitor specified parameter.
127     * @param field
128     *            A definition of the field to be compared.
129     * @param valueAssertion
130     *            The value assertion.
131     * @return Returns a visitor specified result.
132     */
133    R visitGreaterThanOrEqualToFilter(P p, F field, Object valueAssertion);
134
135    /**
136     * Visits a {@code less than} filter.
137     *
138     * @param p
139     *            A visitor specified parameter.
140     * @param field
141     *            A definition of the field to be compared.
142     * @param valueAssertion
143     *            The value assertion.
144     * @return Returns a visitor specified result.
145     */
146    R visitLessThanFilter(P p, F field, Object valueAssertion);
147
148    /**
149     * Visits a {@code less than or equal to} filter.
150     *
151     * @param p
152     *            A visitor specified parameter.
153     * @param field
154     *            A definition of the field to be compared.
155     * @param valueAssertion
156     *            The value assertion.
157     * @return Returns a visitor specified result.
158     */
159    R visitLessThanOrEqualToFilter(P p, F field, Object valueAssertion);
160
161    /**
162     * Visits a {@code not} filter.
163     *
164     * @param p
165     *            A visitor specified parameter.
166     * @param subFilter
167     *            The sub-filter.
168     * @return Returns a visitor specified result.
169     */
170    R visitNotFilter(P p, QueryFilter<F> subFilter);
171
172    /**
173     * Visits an {@code or} filter.
174     * <p>
175     * <b>Implementation note</b>: for the purposes of matching, an empty
176     * sub-filter list should always evaluate to {@code false}.
177     *
178     * @param p
179     *            A visitor specified parameter.
180     * @param subFilters
181     *            The unmodifiable list of sub-filters.
182     * @return Returns a visitor specified result.
183     */
184    R visitOrFilter(P p, List<QueryFilter<F>> subFilters);
185
186    /**
187     * Visits a {@code present} filter.
188     *
189     * @param p
190     *            A visitor specified parameter.
191     * @param field
192     *            A definition of the field to be compared.
193     * @return Returns a visitor specified result.
194     */
195    R visitPresentFilter(P p, F field);
196
197    /**
198     * Visits a {@code starts with} filter.
199     *
200     * @param p
201     *            A visitor specified parameter.
202     * @param field
203     *            A definition of the field to be compared.
204     * @param valueAssertion
205     *            The value assertion.
206     * @return Returns a visitor specified result.
207     */
208    R visitStartsWithFilter(P p, F field, Object valueAssertion);
209
210}