001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2009 Sun Microsystems, Inc.
025 */
026
027package org.forgerock.opendj.ldap;
028
029import java.util.List;
030
031/**
032 * A visitor of {@code Filter}s, in the style of the visitor design pattern.
033 * <p>
034 * Classes implementing this interface can query filters in a type-safe manner.
035 * When a visitor is passed to a filter's accept method, the corresponding visit
036 * method most applicable to that filter is invoked.
037 *
038 * @param <R>
039 *            The return type of this visitor's methods. Use
040 *            {@link java.lang.Void} for visitors that do not need to return
041 *            results.
042 * @param <P>
043 *            The type of the additional parameter to this visitor's methods.
044 *            Use {@link java.lang.Void} for visitors that do not need an
045 *            additional parameter.
046 */
047public interface FilterVisitor<R, P> {
048
049    /**
050     * Visits an {@code and} filter.
051     * <p>
052     * <b>Implementation note</b>: for the purposes of matching an empty
053     * sub-filter list should always evaluate to {@code true} as per RFC 4526.
054     *
055     * @param p
056     *            A visitor specified parameter.
057     * @param subFilters
058     *            The unmodifiable list of sub-filters.
059     * @return Returns a visitor specified result.
060     */
061    R visitAndFilter(P p, List<Filter> subFilters);
062
063    /**
064     * Visits an {@code approximate match} filter.
065     *
066     * @param p
067     *            A visitor specified parameter.
068     * @param attributeDescription
069     *            The attribute description.
070     * @param assertionValue
071     *            The assertion value.
072     * @return Returns a visitor specified result.
073     */
074    R visitApproxMatchFilter(P p, String attributeDescription, ByteString assertionValue);
075
076    /**
077     * Visits an {@code equality match} filter.
078     *
079     * @param p
080     *            A visitor specified parameter.
081     * @param attributeDescription
082     *            The attribute description.
083     * @param assertionValue
084     *            The assertion value.
085     * @return Returns a visitor specified result.
086     */
087    R visitEqualityMatchFilter(P p, String attributeDescription, ByteString assertionValue);
088
089    /**
090     * Visits an {@code extensible} filter.
091     *
092     * @param p
093     *            A visitor specified parameter.
094     * @param matchingRule
095     *            The matching rule name, may be {@code null} if
096     *            {@code attributeDescription} is specified.
097     * @param attributeDescription
098     *            The attribute description, may be {@code null} if
099     *            {@code matchingRule} is specified.
100     * @param assertionValue
101     *            The assertion value.
102     * @param dnAttributes
103     *            Indicates whether DN matching should be performed.
104     * @return Returns a visitor specified result.
105     */
106    R visitExtensibleMatchFilter(P p, String matchingRule, String attributeDescription,
107            ByteString assertionValue, boolean dnAttributes);
108
109    /**
110     * Visits a {@code greater or equal} filter.
111     *
112     * @param p
113     *            A visitor specified parameter.
114     * @param attributeDescription
115     *            The attribute description.
116     * @param assertionValue
117     *            The assertion value.
118     * @return Returns a visitor specified result.
119     */
120    R visitGreaterOrEqualFilter(P p, String attributeDescription, ByteString assertionValue);
121
122    /**
123     * Visits a {@code less or equal} filter.
124     *
125     * @param p
126     *            A visitor specified parameter.
127     * @param attributeDescription
128     *            The attribute description.
129     * @param assertionValue
130     *            The assertion value.
131     * @return Returns a visitor specified result.
132     */
133    R visitLessOrEqualFilter(P p, String attributeDescription, ByteString assertionValue);
134
135    /**
136     * Visits a {@code not} filter.
137     *
138     * @param p
139     *            A visitor specified parameter.
140     * @param subFilter
141     *            The sub-filter.
142     * @return Returns a visitor specified result.
143     */
144    R visitNotFilter(P p, Filter subFilter);
145
146    /**
147     * Visits an {@code or} filter.
148     * <p>
149     * <b>Implementation note</b>: for the purposes of matching an empty
150     * sub-filter list should always evaluate to {@code false} as per RFC 4526.
151     *
152     * @param p
153     *            A visitor specified parameter.
154     * @param subFilters
155     *            The unmodifiable list of sub-filters.
156     * @return Returns a visitor specified result.
157     */
158    R visitOrFilter(P p, List<Filter> subFilters);
159
160    /**
161     * Visits a {@code present} filter.
162     *
163     * @param p
164     *            A visitor specified parameter.
165     * @param attributeDescription
166     *            The attribute description.
167     * @return Returns a visitor specified result.
168     */
169    R visitPresentFilter(P p, String attributeDescription);
170
171    /**
172     * Visits a {@code substrings} filter.
173     *
174     * @param p
175     *            A visitor specified parameter.
176     * @param attributeDescription
177     *            The attribute description.
178     * @param initialSubstring
179     *            The initial sub-string, may be {@code null}.
180     * @param anySubstrings
181     *            The unmodifiable list of any sub-strings, may be empty.
182     * @param finalSubstring
183     *            The final sub-string, may be {@code null}.
184     * @return Returns a visitor specified result.
185     */
186    R visitSubstringsFilter(P p, String attributeDescription, ByteString initialSubstring,
187            List<ByteString> anySubstrings, ByteString finalSubstring);
188
189    /**
190     * Visits an {@code unrecognized} filter.
191     *
192     * @param p
193     *            A visitor specified parameter.
194     * @param filterTag
195     *            The ASN.1 tag.
196     * @param filterBytes
197     *            The filter content.
198     * @return Returns a visitor specified result.
199     */
200    R visitUnrecognizedFilter(P p, byte filterTag, ByteString filterBytes);
201
202}