org.eclipse.core.resources.IResourceChangeListener Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of aspectjtools Show documentation

AspectJ tools most notably contains the AspectJ compiler (AJC). AJC applies aspects to Java classes during compilation, fully replacing Javac for plain Java classes and also compiling native AspectJ or annotation-based @AspectJ syntax. Furthermore, AJC can weave aspects into existing class files in a post-compile binary weaving step. This library is a superset of AspectJ weaver and hence also of AspectJ runtime.

There is a newer version: 1.9.22.1

Show newest version

/*******************************************************************************
 *  Copyright (c) 2000, 2017 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
 *     Lars Vogel  - Bug 527657
 *******************************************************************************/
package org.eclipse.core.resources;

import java.util.*;

/**
 * A resource change listener is notified of changes to resources in the
 * workspace. These changes arise from direct manipulation of resources, or
 * indirectly through re-synchronization with the local file system.
 * 
 * Clients may implement this interface.
 * 
 *
 * There are two ways to register a listener:
 * 
 * One could direct registration with
 * IWorkspace#addResourceChangeListener(IResourceChangeListener, int) users
 * should note that they are responsible to remove the listener if no longer
 * needed to prevent memory leaks.
 * One could register an OSGi Service making and it will automatically be
 * picked up leveraging the Whiteboard
 * Pattern. Services registered with an {@link #PROPERTY_EVENT_MASK}
 * property can be used to receive a sub-set of the events, by registering the
 * value with the
 * {@link IWorkspace#addResourceChangeListener(IResourceChangeListener, int)}
 * method. This allows (for example) {@link IResourceChangeEvent#POST_CHANGE}
 * events to be received by setting event.mask=1 in the service
 * registration.
 * 
 * 
 * For example the services can be registered with Declarative Services, which
 * allows a bundle to not require that the Workspace bundle be started prior to
 * accessing the resources, as until the IWorkspace is available the bundle will
 * not need any callbacks. This will also save potential NPEs when the
 * {@link IWorkspace} shuts down, because the OSGi runtime will handle the
 * deregistration of services automatically:
 * 
 *
 * <?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.4.0" immediate="true" name="ExampleResourceListener">
   <implementation class="org.example.ExampleResourceListener"/>
   <service>
      <provide interface="org.eclipse.core.resources.IResourceChangeListener"/>
   </service>
   <!-- 1 == IResourceChangeEvent.POST_CHANGE -->
   <property name="event.mask" type="Integer" value="1"/>
</scr:component>
 * 
 *
 * 
 * If you choose to register it with the core OSGi API (e.g. in an activator)
 * you can use the following pattern:
 * 
 *
 *  * bundleContext.registerService(IResourceChangeListener.class, myListener, IResourceChangeListener.getMaskProperties(
 * 		IResourceChangeEvent.POST_CHANGE | IResourceChangeEvent.PRE_CLOSE | IResourceChangeEvent.PRE_DELETE));
 * 
 *
 *
 *
 * @see IResourceDelta
 */

@FunctionalInterface
public interface IResourceChangeListener extends EventListener {

	/**
	 * @since 3.17
	 */
	String PROPERTY_EVENT_MASK = "event.mask"; //$NON-NLS-1$

	/**
	 * Notifies this listener that some resource changes
	 * are happening, or have already happened.
	 * 
	 * The supplied event gives details. This event object (and the
	 * resource delta within it) is valid only for the duration of
	 * the invocation of this method.
	 * 
	 * 
	 * Note: This method is called by the platform; it is not intended
	 * to be called directly by clients.
	 * 

	 * Note that during resource change event notification, further changes
	 * to resources may be disallowed.
	 * 
	 *
	 * @param event the resource change event
	 * @see IResourceDelta
	 */
	void resourceChanged(IResourceChangeEvent event);

	/**
	 * Creates a {@link Dictionary} suitable to be used when registering a
	 * {@link IResourceChangeListener} as an OSGi service.
	 *
	 * @param mask see
	 *             {@link IWorkspace#addResourceChangeListener(IResourceChangeListener, int)}
	 * @return a new {@link Dictionary} representing the OSGi service properties for
	 *         the given mask
	 * @since 3.17
	 */
	static Dictionary getMaskProperties(int mask) {
		Dictionary properties = new Hashtable<>();
		properties.put(PROPERTY_EVENT_MASK, mask);
		return properties;
	}
}