/* * Copyright (c) OSGi Alliance (2000, 2015). All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.osgi.framework; import java.util.Dictionary; import java.util.Map; import org.osgi.annotation.versioning.ProviderType; /** * An RFC 1960-based Filter. *
* {@code Filter}s can be created by calling * {@link BundleContext#createFilter(String)} or * {@link FrameworkUtil#createFilter(String)} with a filter string. *
* A {@code Filter} can be used numerous times to determine if the match * argument matches the filter string that was used to create the {@code Filter}. *
* Some examples of LDAP filters are: * *
* "(cn=Babs Jensen)" * "(!(cn=Tim Howes))" * "(&(" + Constants.OBJECTCLASS + "=Person)(|(sn=Jensen)(cn=Babs J*)))" * "(o=univ*of*mich*)" ** * @since 1.1 * @see "Core Specification, Filters, for a description of the filter string syntax." * @ThreadSafe * @author $Id$ */ @ProviderType public interface Filter { /** * Filter using a service's properties. *
* This {@code Filter} is executed using the keys and values of the
* referenced service's properties. The keys are looked up in a case
* insensitive manner.
*
* @param reference The reference to the service whose properties are used
* in the match.
* @return {@code true} if the service's properties match this
* {@code Filter}; {@code false} otherwise.
*/
boolean match(ServiceReference> reference);
/**
* Filter using a {@code Dictionary} with case insensitive key lookup. This
* {@code Filter} is executed using the specified {@code Dictionary}'s keys
* and values. The keys are looked up in a case insensitive manner.
*
* @param dictionary The {@code Dictionary} whose key/value pairs are used
* in the match.
* @return {@code true} if the {@code Dictionary}'s values match this
* filter; {@code false} otherwise.
* @throws IllegalArgumentException If {@code dictionary} contains case
* variants of the same key name.
*/
boolean match(Dictionary
* The filter string is normalized by removing whitespace which does not
* affect the meaning of the filter.
*
* @return This {@code Filter}'s filter string.
*/
@Override
String toString();
/**
* Compares this {@code Filter} to another {@code Filter}.
*
*
* This implementation returns the result of calling
* {@code this.toString().equals(obj.toString())}.
*
* @param obj The object to compare against this {@code Filter}.
* @return If the other object is a {@code Filter} object, then returns the
* result of calling {@code this.toString().equals(obj.toString())};
* {@code false} otherwise.
*/
@Override
boolean equals(Object obj);
/**
* Returns the hashCode for this {@code Filter}.
*
*
* This implementation returns the result of calling
* {@code this.toString().hashCode()}.
*
* @return The hashCode of this {@code Filter}.
*/
@Override
int hashCode();
/**
* Filter using a {@code Dictionary}. This {@code Filter} is executed using
* the specified {@code Dictionary}'s keys and values. The keys are looked
* up in a normal manner respecting case.
*
* @param dictionary The {@code Dictionary} whose key/value pairs are used
* in the match.
* @return {@code true} if the {@code Dictionary}'s values match this
* filter; {@code false} otherwise.
* @since 1.3
*/
boolean matchCase(Dictionary