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 2009 Sun Microsystems, Inc.
015 */
016
017package org.forgerock.opendj.ldap;
018
019import java.util.List;
020
021/**
022 * A visitor of {@code Filter}s, in the style of the visitor design 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 */
037public interface FilterVisitor<R, P> {
038
039    /**
040     * Visits an {@code and} filter.
041     * <p>
042     * <b>Implementation note</b>: for the purposes of matching an empty
043     * sub-filter list should always evaluate to {@code true} as per RFC 4526.
044     *
045     * @param p
046     *            A visitor specified parameter.
047     * @param subFilters
048     *            The unmodifiable list of sub-filters.
049     * @return Returns a visitor specified result.
050     */
051    R visitAndFilter(P p, List<Filter> subFilters);
052
053    /**
054     * Visits an {@code approximate match} filter.
055     *
056     * @param p
057     *            A visitor specified parameter.
058     * @param attributeDescription
059     *            The attribute description.
060     * @param assertionValue
061     *            The assertion value.
062     * @return Returns a visitor specified result.
063     */
064    R visitApproxMatchFilter(P p, String attributeDescription, ByteString assertionValue);
065
066    /**
067     * Visits an {@code equality match} filter.
068     *
069     * @param p
070     *            A visitor specified parameter.
071     * @param attributeDescription
072     *            The attribute description.
073     * @param assertionValue
074     *            The assertion value.
075     * @return Returns a visitor specified result.
076     */
077    R visitEqualityMatchFilter(P p, String attributeDescription, ByteString assertionValue);
078
079    /**
080     * Visits an {@code extensible} filter.
081     *
082     * @param p
083     *            A visitor specified parameter.
084     * @param matchingRule
085     *            The matching rule name, may be {@code null} if
086     *            {@code attributeDescription} is specified.
087     * @param attributeDescription
088     *            The attribute description, may be {@code null} if
089     *            {@code matchingRule} is specified.
090     * @param assertionValue
091     *            The assertion value.
092     * @param dnAttributes
093     *            Indicates whether DN matching should be performed.
094     * @return Returns a visitor specified result.
095     */
096    R visitExtensibleMatchFilter(P p, String matchingRule, String attributeDescription,
097            ByteString assertionValue, boolean dnAttributes);
098
099    /**
100     * Visits a {@code greater or equal} filter.
101     *
102     * @param p
103     *            A visitor specified parameter.
104     * @param attributeDescription
105     *            The attribute description.
106     * @param assertionValue
107     *            The assertion value.
108     * @return Returns a visitor specified result.
109     */
110    R visitGreaterOrEqualFilter(P p, String attributeDescription, ByteString assertionValue);
111
112    /**
113     * Visits a {@code less or equal} filter.
114     *
115     * @param p
116     *            A visitor specified parameter.
117     * @param attributeDescription
118     *            The attribute description.
119     * @param assertionValue
120     *            The assertion value.
121     * @return Returns a visitor specified result.
122     */
123    R visitLessOrEqualFilter(P p, String attributeDescription, ByteString assertionValue);
124
125    /**
126     * Visits a {@code not} filter.
127     *
128     * @param p
129     *            A visitor specified parameter.
130     * @param subFilter
131     *            The sub-filter.
132     * @return Returns a visitor specified result.
133     */
134    R visitNotFilter(P p, Filter subFilter);
135
136    /**
137     * Visits an {@code or} filter.
138     * <p>
139     * <b>Implementation note</b>: for the purposes of matching an empty
140     * sub-filter list should always evaluate to {@code false} as per RFC 4526.
141     *
142     * @param p
143     *            A visitor specified parameter.
144     * @param subFilters
145     *            The unmodifiable list of sub-filters.
146     * @return Returns a visitor specified result.
147     */
148    R visitOrFilter(P p, List<Filter> subFilters);
149
150    /**
151     * Visits a {@code present} filter.
152     *
153     * @param p
154     *            A visitor specified parameter.
155     * @param attributeDescription
156     *            The attribute description.
157     * @return Returns a visitor specified result.
158     */
159    R visitPresentFilter(P p, String attributeDescription);
160
161    /**
162     * Visits a {@code substrings} filter.
163     *
164     * @param p
165     *            A visitor specified parameter.
166     * @param attributeDescription
167     *            The attribute description.
168     * @param initialSubstring
169     *            The initial sub-string, may be {@code null}.
170     * @param anySubstrings
171     *            The unmodifiable list of any sub-strings, may be empty.
172     * @param finalSubstring
173     *            The final sub-string, may be {@code null}.
174     * @return Returns a visitor specified result.
175     */
176    R visitSubstringsFilter(P p, String attributeDescription, ByteString initialSubstring,
177            List<ByteString> anySubstrings, ByteString finalSubstring);
178
179    /**
180     * Visits an {@code unrecognized} filter.
181     *
182     * @param p
183     *            A visitor specified parameter.
184     * @param filterTag
185     *            The ASN.1 tag.
186     * @param filterBytes
187     *            The filter content.
188     * @return Returns a visitor specified result.
189     */
190    R visitUnrecognizedFilter(P p, byte filterTag, ByteString filterBytes);
191
192}