KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > openide > util > lookup > Lookups


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */

19
20 package org.openide.util.lookup;
21
22 import java.util.Arrays JavaDoc;
23 import java.util.Collections JavaDoc;
24 import org.openide.util.Lookup;
25
26 /**
27  * Static factory methods for creating common lookup implementations.
28  *
29  * @author David Strupl
30  * @since 2.21
31  */

32 public class Lookups {
33
34     /** static methods only */
35     private Lookups() {}
36
37     /**
38      * Creates a singleton lookup. It means lookup that contains only
39      * one object specified via the supplied parameter. The lookup will
40      * either return the object or null if the supplied template does
41      * not match the class. If the specified argument is null the method
42      * will end with NullPointerException.
43      * @return Fully initialized lookup object ready to use
44      * @throws NullPointerException if the supplied argument is null
45      * @since 2.21
46      */

47     public static Lookup singleton(Object JavaDoc objectToLookup) {
48         if (objectToLookup == null) {
49             throw new NullPointerException JavaDoc();
50         }
51
52         // performance of the resulting lookup might be further
53
// improved by providing specialized singleton result (and lookup)
54
// instead of using SimpleResult
55
return new SimpleLookup(Collections.singleton(objectToLookup));
56     }
57
58     /**
59      * Creates a lookup that contains an array of objects specified via the
60      * parameter. The resulting lookup is fixed in the following sense: it
61      * contains only fixed set of objects passed in by the array parameter.
62      * Its contents never changes so registering listeners on such lookup
63      * does not have any observable effect (the listeners are never called).
64      *
65      * @param objectsToLookup list of objects to include
66      * @return Fully initialized lookup object ready to use
67      * @throws NullPointerException if the supplied argument is null
68      * @since 2.21
69      *
70      */

71     public static Lookup fixed(Object JavaDoc... objectsToLookup) {
72         if (objectsToLookup == null) {
73             throw new NullPointerException JavaDoc();
74         }
75
76         return new SimpleLookup(Arrays.asList(objectsToLookup));
77     }
78
79     /**
80      * Creates a lookup that contains an array of objects specified via the
81      * parameter. The resulting lookup is fixed in the following sense: it
82      * contains only fixed set of objects passed in by the array parameter.
83      * The objects returned from this lookup are converted to real objects
84      * before they are returned by the lookup.
85      * Its contents never changes so registering listeners on such lookup
86      * does not have any observable effect (the listeners are never called).
87      *
88      * @return Fully initialized lookup object ready to use
89      * @throws NullPointerException if the any of the arguments is null
90      * @since 2.21
91      *
92      */

93     public static <T,R> Lookup fixed(T[] keys, InstanceContent.Convertor<? super T,R> convertor) {
94         if (keys == null) {
95             throw new NullPointerException JavaDoc();
96         }
97
98         if (convertor == null) {
99             throw new NullPointerException JavaDoc();
100         }
101
102         return new SimpleLookup(Arrays.asList(keys), convertor);
103     }
104
105     /** Creates a lookup that delegates to another one but that one can change
106      * from time to time. The returned lookup checks every time somebody calls
107      * <code>lookup</code> or <code>lookupItem</code> method whether the
108      * provider still returns the same lookup. If not, it updates state of
109      * all <code>Lookup.Result</code>s that it created (and that still exists).
110      * <P>
111      * The user of this method has to implement its provider's <code>getLookup</code>
112      * method (must be thread safe and fast, will be called often and from any thread)
113      * pass it to this method and use the returned lookup. Whenever the user
114      * changes the return value from the <code>getLookup</code> method and wants
115      * to notify listeners on the lookup about that it should trigger the event
116      * firing, for example by calling <code>lookup.lookup (Object.class)</code>
117      * that forces check of the return value of <code>getLookup</code>.
118      *
119      * @param provider the provider that returns a lookup to delegate to
120      * @return lookup delegating to the lookup returned by the provider
121      * @since 3.9
122      */

123     public static Lookup proxy(Lookup.Provider provider) {
124         return new SimpleProxyLookup(provider);
125     }
126
127     /** Returns a lookup that implements the JDK1.3 JAR services mechanism and delegates
128      * to META-INF/services/name.of.class files.
129      * <p>Note: It is not dynamic - so if you need to change the classloader or JARs,
130      * wrap it in a {@link ProxyLookup} and change the delegate when necessary.
131      * Existing instances will be kept if the implementation classes are unchanged,
132      * so there is "stability" in doing this provided some parent loaders are the same
133      * as the previous ones.
134      * @since 3.35
135      */

136     public static Lookup metaInfServices(ClassLoader JavaDoc classLoader) {
137         return new MetaInfServicesLookup(classLoader);
138     }
139
140     /** Creates a lookup that wraps another one and filters out instances
141      * of specified classes. If you have a lookup and
142      * you want to remove all instances of ActionMap you can use:
143      * <pre>
144      * l = Lookups.exclude(lookup, ActionMap.class);
145      * </pre>
146      * Then anybody who asks for <code>l.lookup(ActionMap.class)</code> or
147      * subclass will get <code>null</code>. Even if the original lookup contains the
148      * value.
149      * To create empty lookup (well, just an example, otherwise use {@link Lookup#EMPTY}) one could use:
150      * <pre>
151      * Lookup.exclude(anyLookup, Object.class);
152      * </pre>
153      * as any instance in any lookup is of type Object and thus would be excluded.
154      * <p>
155      * The complete behavior can be described as <code>classes</code> being
156      * a barrier. For an object not to be excluded, there has to be an inheritance
157      * path between the queried class and the actual class of the instance,
158      * that is not blocked by any of the excluded classes:
159      * <pre>
160      * interface A {}
161      * interface B {}
162      * class C implements A, B {}
163      * Object c = new C();
164      * Lookup l1 = Lookups.singleton(c);
165      * Lookup l2 = Lookups.exclude(l1, A.class);
166      * assertNull("A is directly excluded", l2.lookup(A.class));
167      * assertEquals("Returns C as A.class is not between B and C", c, l2.lookup(B.class));
168      * </pre>
169      * For more info check the
170      * <a HREF="http://www.netbeans.org/source/browse/openide/util/test/unit/src/org/openide/util/lookup/ExcludingLookupTest.java">
171      * excluding lookup tests</a> and the discussion in issue
172      * <a HREF="http://openide.netbeans.org/issues/show_bug.cgi?id=53058">53058</a>.
173      *
174      * @param lookup the original lookup that should be filtered
175      * @param classes array of classes those instances should be excluded
176      * @since 5.4
177      */

178     public static Lookup exclude(Lookup lookup, Class JavaDoc... classes) {
179         return new ExcludingLookup(lookup, classes);
180     }
181
182     /** Creates <code>Lookup.Item</code> representing the instance passed in.
183      *
184      * @param instance the object for which Lookup.Item should be creted
185      * @param id unique identification of the object, for details see {@link org.openide.util.Lookup.Item#getId},
186      * can be <code>null</code>
187      * @return lookup item representing instance
188      * @since 4.8
189      */

190     public static <T> Lookup.Item<T> lookupItem(T instance, String JavaDoc id) {
191         return new LookupItem<T>(instance, id);
192     }
193
194     private static class LookupItem<T> extends Lookup.Item<T> {
195         private String JavaDoc id;
196         private T instance;
197
198         public LookupItem(T instance) {
199             this(instance, null);
200         }
201
202         public LookupItem(T instance, String JavaDoc id) {
203             this.id = id;
204             this.instance = instance;
205         }
206
207         public String JavaDoc getDisplayName() {
208             return getId();
209         }
210
211         public String JavaDoc getId() {
212             return (id == null) ? instance.toString() : id;
213         }
214
215         public T getInstance() {
216             return instance;
217         }
218
219         @SuppressWarnings JavaDoc("unchecked")
220         public Class JavaDoc<? extends T> getType() {
221             return (Class JavaDoc<? extends T>)instance.getClass();
222         }
223
224         public boolean equals(Object JavaDoc object) {
225             if (object instanceof LookupItem) {
226                 return instance == ((LookupItem) object).getInstance();
227             }
228
229             return false;
230         }
231
232         public int hashCode() {
233             return instance.hashCode();
234         }
235     }
236      // End of LookupItem class
237
}
238
Popular Tags