Copyright (c) 2004, 2008 IBM Corporation and others.
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
Contributors:
    IBM Corporation - initial API and implementation
/*******************************************************************************
 * Copyright (c) 2004, 2008 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.core.runtime.dynamichelpers;

import org.eclipse.core.internal.runtime.ReferenceHashSet;
import org.eclipse.core.runtime.IExtension;

An extension tracker keeps associations between extensions and their derived objects on an extension basis.
All extensions being added in a tracker will automatically be removed when the extension is uninstalled from the registry.
Users interested in extension removal can register a handler that will let them know when an object is being removed.

This interface can be used without OSGi running.

This interface is not intended to be implemented by clients.

Since:
3.1
@noimplement
This interface is not intended to be implemented by clients./**
 * An extension tracker keeps associations between extensions and their derived objects on an extension basis.
 * All extensions being added in a tracker will automatically be removed when the extension is uninstalled from the registry.
 * Users interested in extension removal can register a handler that will let them know when an object is being removed.
 * <p>
 * This interface can be used without OSGi running.
 * </p><p>
 * This interface is not intended to be implemented by clients.
 * </p>
 * @since 3.1
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IExtensionTracker {

	
Constant for strong (normal) reference holding.
Value 1.
/**
	 * Constant for strong (normal) reference holding.
	 *
	 * Value <code>1</code>.
	 */
	public static final int REF_STRONG = ReferenceHashSet.HARD;

	
Constant for soft reference holding.
Value 2.
/**
	 * Constant for soft reference holding.
	 *
	 * Value <code>2</code>.
	 */
	public static final int REF_SOFT = ReferenceHashSet.SOFT;

	
Constant for weak reference holding.
Value 3.
/**
	 * Constant for weak reference holding.
	 *
	 * Value <code>3</code>.
	 */
	public static final int REF_WEAK = ReferenceHashSet.WEAK;

	
Register an extension change handler with this tracker using the given filter.
Params:
handler – the handler to be registered
filter – the filter to use to choose interesting changes/**
	 * Register an extension change handler with this tracker using the given filter.
	 *
	 * @param handler the handler to be registered
	 * @param filter the filter to use to choose interesting changes
	 */
	public void registerHandler(IExtensionChangeHandler handler, IFilter filter);

	
Unregister the given extension change handler previously registered with this tracker.
Params:
handler – the handler to be unregistered/**
	 * Unregister the given extension change handler previously registered with this tracker.
	 *
	 * @param handler the handler to be unregistered
	 */
	public void unregisterHandler(IExtensionChangeHandler handler);

	
Create an association between the given extension and the given object. The referenceType indicates how strongly the object is being kept in memory. There is 3 possible values: REF_STRONG, REF_SOFT, REF_WEAK. 
Params:
extension – the extension
object – the object to associate with the extension
referenceType – one of REF_STRONG, REF_SOFT, REF_WEAK
See Also:
REF_STRONG
REF_SOFT
REF_WEAK/**
	 * Create an association between the given extension and the given object.
	 * The referenceType indicates how strongly the object is being kept in memory.
	 * There is 3 possible values: {@link #REF_STRONG}, {@link #REF_SOFT}, {@link #REF_WEAK}.
	 *
	 * @param extension the extension
	 * @param object the object to associate with the extension
	 * @param referenceType one of REF_STRONG, REF_SOFT, REF_WEAK
	 * @see #REF_STRONG
	 * @see #REF_SOFT
	 * @see #REF_WEAK
	 */
	public void registerObject(IExtension extension, Object object, int referenceType);

	
Remove an association between the given extension and the given object.
Params:
extension – the extension under which the object has been registered
object – the object to unregister/**
	 * Remove an association between the given extension and the given object.
	 *
	 * @param extension the extension under which the object has been registered
	 * @param object the object to unregister
	 */
	public void unregisterObject(IExtension extension, Object object);

	
Remove all the objects associated with the given extension. Return
the removed objects.
Params:
extension – the extension for which the objects are removed
Returns:
the objects that were associated with the extension/**
	 * Remove all the objects associated with the given extension. Return
	 * the removed objects.
	 *
	 * @param extension the extension for which the objects are removed
	 * @return the objects that were associated with the extension
	 */
	public Object[] unregisterObject(IExtension extension);

	
Return all the objects that have been associated with the given extension.
All objects registered strongly will be return unless they have been unregistered.
The objects registered softly or weakly may not be returned if they have been garbage collected.
Return an empty array if no associations exist.
Params:
extension – the extension for which the object must be returned
Returns:
the array of associated objects/**
	 * Return all the objects that have been associated with the given extension.
	 * All objects registered strongly will be return unless they have been unregistered.
	 * The objects registered softly or weakly may not be returned if they have been garbage collected.
	 * Return an empty array if no associations exist.
	 *
	 * @param extension the extension for which the object must be returned
	 * @return the array of associated objects
	 */
	public Object[] getObjects(IExtension extension);

	
Close the tracker. All registered objects are freed and all handlers are being automatically removed.
/**
	 * Close the tracker. All registered objects are freed and all handlers are being automatically removed.
	 */
	public void close();
}