KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > internal > components > framework > Components


1 /*******************************************************************************
2  * Copyright (c) 2005 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/

11 package org.eclipse.ui.internal.components.framework;
12
13
14 import org.eclipse.core.runtime.IAdaptable;
15 import org.eclipse.osgi.util.NLS;
16 import org.eclipse.ui.internal.WorkbenchPlugin;
17 import org.eclipse.ui.internal.components.Assert;
18 import org.eclipse.ui.internal.components.ComponentMessages;
19 import org.eclipse.ui.internal.components.util.ServiceMap;
20
21 /**
22  * Contains static helper methods for managing components.
23  *
24  * Not intended to be subclassed or instantiated.
25  *
26  * <p>EXPERIMENTAL: The components framework is currently under active development. All
27  * aspects of this class including its existence, name, and public interface are likely
28  * to change during the development of Eclipse 3.1</p>
29  *
30  * @since 3.1
31  */

32 public final class Components {
33     
34     private Components() {
35     }
36     
37     /**
38      * Returns a service provider that provides no services
39      */

40     public static final IServiceProvider EMPTY_PROVIDER = new ServiceMap();
41
42     /**
43      * If it is possible to adapt the given object to the given type, this
44      * returns the adapter. Performs the following checks:
45      *
46      * <ol>
47      * <li>Returns <code>sourceObject</code> if it is an instance of the adapter type.</li>
48      * <li>If sourceObject implements IAdaptable, it is queried for adapters.</li>
49      * <li>If sourceObject implements IComponentProvider, it is queried for a component that
50      * uses the adapter type as a key. Any exceptions are logged immediately.</li>
51      * </ol>
52      *
53      * Otherwise returns null.
54      *
55      * @param sourceObject object to adapt
56      * @param adapter type to adapt to
57      * @return a representation of sourceObject that is assignable to the adapter type, or null
58      * if no such representation exists
59      */

60     public static Object JavaDoc getAdapter(Object JavaDoc sourceObject, Class JavaDoc adapter) {
61         if (adapter.isInstance(sourceObject)) {
62             return sourceObject;
63         }
64         
65         if (sourceObject instanceof IAdaptable) {
66             IAdaptable adaptable = (IAdaptable)sourceObject;
67             
68             Object JavaDoc result = adaptable.getAdapter(adapter);
69             if (result != null) {
70                 // Sanity-check
71
Assert.isTrue(adapter.isInstance(result));
72                 return result;
73             }
74         }
75         
76         if (sourceObject instanceof IServiceProvider) {
77             try {
78                 return ((IServiceProvider)sourceObject).getService(adapter);
79             } catch (ComponentException e) {
80                 WorkbenchPlugin.log(e);
81             }
82         }
83         
84         return null;
85     }
86     
87     /**
88      * Queries the given IAdaptable for a required adapter. Throws an exception if the adapter
89      * does not exist or is of an unexpected type.
90      *
91      * @param toQuery adaptable to query for interfaces
92      * @param interf interface to request
93      * @return an object that implements the given interface. Does not return null.
94      * @throws ComponentException if the given adapter does not exist.
95      */

96     public static Object JavaDoc queryInterface(IAdaptable toQuery, Class JavaDoc interf) throws ComponentException {
97         Object JavaDoc result = toQuery.getAdapter(interf);
98         
99         if (result == null) {
100             throw new ComponentException(NLS.bind(ComponentMessages.Components_missing_required,
101                    interf.toString()), null);
102         }
103         
104         if (!interf.isInstance(result)) {
105             throw new ComponentException(interf,
106                     NLS.bind(ComponentMessages.Components_wrong_type,interf.getName(), result.getClass().getName()),
107                     null);
108         }
109         
110         return result;
111     }
112     
113     /**
114      * Queries a service provider for the service identified by the given key.
115      * Throws a <code>ComponentException</code> if no such component exists.
116      *
117      * <p>
118      * By convention, the following keys have special meanings:
119      * </p>
120      * <ul>
121      * <li>If the key is a Class instance, then the result must be an instance of that class</li>
122      * <li>If the key is IServiceProvider.class, then this method returns the service provider itself</li>
123      * <li>If the key is an instance of IComponentScope, then this method will throw an exception
124      * unless the given service provider includes the given scope</li>
125      * </ul>
126      *
127      * @param toQuery service provider to query
128      * @param key component being requested
129      * @return the component for the given key (does not return null)
130      * @throws ComponentException if no such component exists
131      */

132     public static Object JavaDoc queryInterface(IServiceProvider toQuery, Object JavaDoc key) throws ComponentException {
133         Object JavaDoc result = toQuery.getService(key);
134         
135         if (key == IServiceProvider.class) {
136             return toQuery;
137         }
138         
139         if (result == null) {
140             throw new ComponentException(key, NLS.bind(ComponentMessages.Components_missing_required,
141                     key.toString()), null);
142         }
143         
144         if (key instanceof Class JavaDoc) {
145             Class JavaDoc c = (Class JavaDoc)key;
146             if (!c.isInstance(result)) {
147                 throw new ComponentException(key,
148                        NLS.bind(ComponentMessages.Components_wrong_type,
149                                 c.getName(), result.getClass().getName()),
150                         null);
151             }
152         }
153         
154         return result;
155     }
156     
157     /**
158      * Requests a set of services from the given service provider. Returns all of the requested
159      * interfaces or throws a ComponentException if any service is missing. This
160      * can be used to reduce tedious error-checking in situations where the application relies on
161      * one or more interfaces from a container.
162      *
163      * For example:
164      * <code>
165      * Container myContainer = new Container(Components.getContext("org.eclipse.core.components.plugin"));
166      * try {
167      * Object[] interfaces = Components.queryInterfaces(myContainer, new Object[] {ISystemLog.class, IStatusFactory.class});
168      * ISystemLog interface1 = (ISystemLog) interfaces[0];
169      * IStatusFactory interface2 = (IStatusFactory) interfaces[1];
170      *
171      * // Do something with interface1 and interface2
172      * // ...
173      *
174      * } catch (ComponentException e) {
175      * // The container did not have implementations for the expected interfaces.
176      * } finally {
177      * // Clean up when done
178      * myContainer.dispose();
179      * }
180      * </code>
181      *
182      * @param toQuery service provider that is expected to contain the given components
183      * @param requiredKeys array of interface types. The order of the classes in this array
184      * corresponds to the order of instances in the return value. For example, if requiredInterfaces[1] == String.class
185      * then result[1] will be an instance of String.
186      * @return an array of interfaces. All entries are non-null. The order and size of this array is determined by requiredInterfaces.
187      * If requiredInterfaces[n] contains type T, then the result will contain an instance of T at index n.
188      * @throws ComponentException if any of the requested interfaces are missing from the container
189      */

190     public static Object JavaDoc[] queryInterfaces(IServiceProvider toQuery, Object JavaDoc[] requiredKeys) throws ComponentException {
191         Object JavaDoc[] result = new Object JavaDoc[requiredKeys.length];
192         
193         for (int i = 0; i < result.length; i++) {
194             result[i] = queryInterface(toQuery, requiredKeys[i]);
195         }
196         
197         return result;
198     }
199     
200 }
201
Popular Tags