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