KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > osgi > framework > Filter


1 /*
2  * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/Filter.java,v 1.16 2007/02/21 16:49:05 hargrave Exp $
3  *
4  * Copyright (c) OSGi Alliance (2000, 2007). All Rights Reserved.
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 package org.osgi.framework;
19
20 import java.util.Dictionary JavaDoc;
21
22 /**
23  * An RFC 1960-based Filter.
24  * <p>
25  * <code>Filter</code> objects can be created by calling
26  * {@link BundleContext#createFilter} with the chosen filter string.
27  * <p>
28  * A <code>Filter</code> object can be used numerous times to determine if the
29  * match argument matches the filter string that was used to create the
30  * <code>Filter</code> object.
31  * <p>
32  * Some examples of LDAP filters are:
33  *
34  * <pre>
35  * &quot;(cn=Babs Jensen)&quot;
36  * &quot;(!(cn=Tim Howes))&quot;
37  * &quot;(&amp;(&quot; + Constants.OBJECTCLASS + &quot;=Person)(|(sn=Jensen)(cn=Babs J*)))&quot;
38  * &quot;(o=univ*of*mich*)&quot;
39  * </pre>
40  *
41  * @since 1.1
42  * @see "Core Specification, section 5.5, for a description of the filter string
43  * syntax."
44  * @ThreadSafe
45  * @version $Revision: 1.16 $
46  */
47 public interface Filter {
48     /**
49      * Filter using a service's properties.
50      * <p>
51      * The filter is executed using the keys and values of the referenced
52      * service's properties. The keys are case insensitively matched with the
53      * filter.
54      *
55      * @param reference The reference to the service whose properties are used
56      * in the match.
57      *
58      * @return <code>true</code> if the service's properties match this
59      * filter; <code>false</code> otherwise.
60      */
61     public boolean match(ServiceReference reference);
62
63     /**
64      * Filter using a <code>Dictionary</code> object. The Filter is executed
65      * using the <code>Dictionary</code> object's keys and values. The keys
66      * are case insensitively matched with the filter.
67      *
68      * @param dictionary The <code>Dictionary</code> object whose keys are
69      * used in the match.
70      *
71      * @return <code>true</code> if the <code>Dictionary</code> object's
72      * keys and values match this filter; <code>false</code>
73      * otherwise.
74      *
75      * @throws IllegalArgumentException If <code>dictionary</code> contains
76      * case variants of the same key name.
77      */
78     public boolean match(Dictionary JavaDoc dictionary);
79
80     /**
81      * Returns this <code>Filter</code> object's filter string.
82      * <p>
83      * The filter string is normalized by removing whitespace which does not
84      * affect the meaning of the filter.
85      *
86      * @return Filter string.
87      */
88     public String JavaDoc toString();
89
90     /**
91      * Compares this <code>Filter</code> object to another object.
92      *
93      * @param obj The object to compare against this <code>Filter</code>
94      * object.
95      *
96      * @return If the other object is a <code>Filter</code> object, then
97      * returns <code>this.toString().equals(obj.toString()</code>;<code>false</code>
98      * otherwise.
99      */
100     public boolean equals(Object JavaDoc obj);
101
102     /**
103      * Returns the hashCode for this <code>Filter</code> object.
104      *
105      * @return The hashCode of the filter string; that is,
106      * <code>this.toString().hashCode()</code>.
107      */
108     public int hashCode();
109
110     /**
111      * Filter with case sensitivity using a <code>Dictionary</code> object.
112      * The Filter is executed using the <code>Dictionary</code> object's keys
113      * and values. The keys are case sensitively matched with the filter.
114      *
115      * @param dictionary The <code>Dictionary</code> object whose keys are
116      * used in the match.
117      *
118      * @return <code>true</code> if the <code>Dictionary</code> object's
119      * keys and values match this filter; <code>false</code>
120      * otherwise.
121      *
122      * @since 1.3
123      */
124     public boolean matchCase(Dictionary JavaDoc dictionary);
125 }
126
Popular Tags