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  ;
23  import java.util.Collections  ;
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   objectToLookup) {
48          if (objectToLookup == null) {
49              throw new NullPointerException  ();
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  ... objectsToLookup) {
72          if (objectsToLookup == null) {
73              throw new NullPointerException  ();
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  ();
96          }
97  
98          if (convertor == null) {
99              throw new NullPointerException  ();
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   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  ... 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   id) {
191         return new LookupItem<T>(instance, id);
192     }
193 
194     private static class LookupItem<T> extends Lookup.Item<T> {
195         private String   id;
196         private T instance;
197 
198         public LookupItem(T instance) {
199             this(instance, null);
200         }
201 
202         public LookupItem(T instance, String   id) {
203             this.id = id;
204             this.instance = instance;
205         }
206 
207         public String   getDisplayName() {
208             return getId();
209         }
210 
211         public String   getId() {
212             return (id == null) ? instance.toString() : id;
213         }
214 
215         public T getInstance() {
216             return instance;
217         }
218 
219         @SuppressWarnings  ("unchecked")
220         public Class  <? extends T> getType() {
221             return (Class  <? extends T>)instance.getClass();
222         }
223 
224         public boolean equals(Object   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags