KickJava   Java API By Example, From Geeks To Geeks.

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


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 import java.util.Collection JavaDoc;
14
15 /**
16  * Factory for services. Services are defined here to be "an object that can be
17  * requested by key from an IServiceProvider". That is, a service is any object that
18  * can be used to satisfy a component's dependencies. Any sort of java object
19  * may be used as a service key as long as the service factory and the code using it agree on the
20  * meaning of each key. The framework normally uses Class objects as keys, and always
21  * returns services that implement that Class.
22  *
23  * <p>
24  * A service factory is different from a service provider: A service factory creates new
25  * services whereas a service provider returns existing services.
26  * </p>
27  *
28  * <p>
29  * A service factory will often contain many component factories. The service factory
30  * will typically use the key to select a specific component factory and delegate to
31  * the component factory to create the actual service.
32  * </p>
33  *
34  * <p>EXPERIMENTAL: The components framework is currently under active development. All
35  * aspects of this class including its existence, name, and public interface are likely
36  * to change during the development of Eclipse 3.1</p>
37  *
38  * @since 3.1
39  */
40 public abstract class ServiceFactory {
41     /**
42      * Returns a component handle for the given key or null if this context does not
43      * recognize the given key. The handle will point to a component that is fully initialized
44      * and has all of its dependencies satisfied.
45      *
46      * <p>
47      * By convention, if the key is a Class instance then the resulting component must be
48      * an instance of that class.
49      * </p>
50      *
51      * @param key identifier for the service to create. This is typically a Class object for
52      * a class listed as a component interface in the org.eclipse.core.components.services
53      * extension point
54      * @param services available dependencies for the service
55      * @return a newly created component handle or null if the key is not known to this factory
56      * @throws ComponentException if unable to create the service
57      */
58     public abstract ComponentHandle createHandle(Object JavaDoc key, IServiceProvider services) throws ComponentException;
59     
60     /**
61      * Returns true iff the receiver knows how to create handles for the given service key. If
62      * this method returns true, createHandle should not return null for the given key in normal
63      * circumstances.
64      *
65      * @param componentKey key to check
66      * @return true iff this factory knows about the given key
67      */
68     public abstract boolean hasService(Object JavaDoc componentKey);
69     
70     /**
71      * Returns the set of missing dependencies for this factory. Missing dependencies are keys that may
72      * be requested by services in this factory but which this factory cannot construct directly. Any
73      * service provider that is passed to createHandle should be able to satisfy all of the keys in
74      * this set.
75      *
76      * @return a set of service keys that are required by this factory
77      */
78     public abstract Collection JavaDoc getMissingDependencies();
79     
80 }
81
Popular Tags