KickJava   Java API By Example, From Geeks To Geeks.

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


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 org.eclipse.ui.internal.components.NullDisposable;
14
15 /**
16  * A handle to a component. Components are ordinary java objects that are created by an
17  * <code>ComponentFactory</code>. The handle knows how to clean up after the object when
18  * it is no longer needed.
19  *
20  * Most handles point to a unique instance of a component, but it is also possible for
21  * many handles to point to the same singleton or reference-counted object.
22  *
23  * <p>In most cases, factories return handles to components that either implement IDisposable
24  * or don't require explicit disposal. In this situation, the standard <code>ComponentHandle</code>
25  * class is sufficient. Clients only need to subclass this class if they need to specialize
26  * the disposal behavior. For example, a subclass of <code>ComponentHandle</code> could
27  * decrement a reference count rather than calling IDisposable.dispose() on the component.
28  * </p>
29  *
30  * <p>
31  * Clients should use the following criteria when selecting what type of ComponentHandle
32  * to create:
33  * </p>
34  *
35  * <ul>
36  * <li>If the component is owned by the handle and implements IDisposable, use ComponentHandle</li>
37  * <li>If the component does not implement IDisposable and does not require disposal, use ComponentHandle</li>
38  * <li>If the component is a singleton or shared object that is being managed outside the framework, use NonDisposingHandle</li>
39  * <li>If the component is a temporary object which should be GC'd as soon as possible, use NonDisposingHandle</li>
40  * <li>If the component requires explicit disposal but does not implement IDisposable, use a custom subclass of ComponentHandle</li>
41  * <li>If the component is reference-counted, use a custom subclass of ComponentHandle</li>
42  * </ul>
43  *
44  * <p>EXPERIMENTAL: The components framework is currently under active development. All
45  * aspects of this class including its existence, name, and public interface are likely
46  * to change during the development of Eclipse 3.1</p>
47  *
48  * @since 3.1
49  */
50 public class ComponentHandle {
51     
52     private Object JavaDoc component;
53     
54     /**
55      * Creates a handle for the given component
56      *
57      * @param component
58      */
59     public ComponentHandle(Object JavaDoc component) {
60         this.component = component;
61     }
62     
63     /**
64      * Returns the component instance.
65      *
66      * @return the component instance. Never null.
67      */
68     public final Object JavaDoc getInstance() {
69         return component;
70     }
71     
72     /**
73      * Returns an interface that can be used to dispose the handle. The owner of the handle
74      * must call getDisposable().dispose() when they are done with the component.
75      *
76      * <p>Note that if requiresDisposal() returns false the owner of the handle may, at its option,
77      * choose to ignore this method.</p>
78      *
79      * @return an IDisposable interface that should be used to dispose the handle
80      * when no longer needed
81      */
82     public IDisposable getDisposable() {
83         if (component instanceof IDisposable) {
84             return (IDisposable)component;
85         }
86         
87         return NullDisposable.instance;
88     }
89     
90     /**
91      * Hint to the owner of the handle. If this returns true, the owner of the handle must
92      * call getDisposable().dispose() when they are done with the handle.
93      *
94      * <p>
95      * If this method returns false the owner of the handle may, at its option, choose to
96      * discard the handle and the component at any time without disposing it.
97      * </p>
98      *
99      * @return true iff the owner of the handle may discard the handle without explicit
100      * disposal.
101      */
102     public boolean requiresDisposal() {
103         return true;
104     }
105     
106 }
107
Popular Tags