KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > runtime > dynamichelpers > IExtensionTracker


1 /*******************************************************************************
2  * Copyright (c) 2004, 2006 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.core.runtime.dynamichelpers;
12
13 import org.eclipse.core.internal.runtime.ReferenceHashSet;
14 import org.eclipse.core.runtime.IExtension;
15
16 /**
17  * An extension tracker keeps associations between extensions and their derived objects on an extension basis.
18  * All extensions being added in a tracker will automatically be removed when the extension is uninstalled from the registry.
19  * Users interested in extension removal can register a handler that will let them know when an object is being removed.
20  * <p>
21  * This interface can be used without OSGi running.
22  * </p><p>
23  * This interface is not intended to be implemented by clients.
24  * </p>
25  * @since 3.1
26  */
27 public interface IExtensionTracker {
28
29     /**
30      * Constant for strong (normal) reference holding.
31      *
32      * Value <code>1</code>.
33      */
34     public static final int REF_STRONG = ReferenceHashSet.HARD;
35
36     /**
37      * Constant for soft reference holding.
38      *
39      * Value <code>2</code>.
40      */
41     public static final int REF_SOFT = ReferenceHashSet.SOFT;
42
43     /**
44      * Constant for weak reference holding.
45      *
46      * Value <code>3</code>.
47      */
48     public static final int REF_WEAK = ReferenceHashSet.WEAK;
49
50     /**
51      * Register an extension change handler with this tracker using the given filter.
52      *
53      * @param handler the handler to be registered
54      * @param filter the filter to use to choose interesting changes
55      */
56     public void registerHandler(IExtensionChangeHandler handler, IFilter filter);
57
58     /**
59      * Unregister the given extension change handler previously registered with this tracker.
60      *
61      * @param handler the handler to be unregistered
62      */
63     public void unregisterHandler(IExtensionChangeHandler handler);
64
65     /**
66      * Create an association between the given extension and the given object.
67      * The referenceType indicates how strongly the object is being kept in memory.
68      * There is 3 possible values: {@link #REF_STRONG}, {@link #REF_SOFT}, {@link #REF_WEAK}.
69      *
70      * @param extension the extension
71      * @param object the object to associate with the extension
72      * @param referenceType one of REF_STRONG, REF_SOFT, REF_WEAK
73      * @see #REF_STRONG
74      * @see #REF_SOFT
75      * @see #REF_WEAK
76      */
77     public void registerObject(IExtension extension, Object JavaDoc object, int referenceType);
78
79     /**
80      * Remove an association between the given extension and the given object.
81      *
82      * @param extension the extension under which the object has been registered
83      * @param object the object to unregister
84      */
85     public void unregisterObject(IExtension extension, Object JavaDoc object);
86
87     /**
88      * Remove all the objects associated with the given extension. Return
89      * the removed objects.
90      *
91      * @param extension the extension for which the objects are removed
92      * @return the objects that were associated with the extension
93      */
94     public Object JavaDoc[] unregisterObject(IExtension extension);
95
96     /**
97      * Return all the objects that have been associated with the given extension.
98      * All objects registered strongly will be return unless they have been unregistered.
99      * The objects registered softly or weakly may not be returned if they have been garbage collected.
100      * Return an empty array if no associations exist.
101      *
102      * @param extension the extension for which the object must be returned
103      * @return the array of associated objects
104      */
105     public Object JavaDoc[] getObjects(IExtension extension);
106
107     /**
108      * Close the tracker. All registered objects are freed and all handlers are being automatically removed.
109      */
110     public void close();
111 }
112
Popular Tags