org.osgi.util.tracker.ServiceTrackerCustomizer Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.osgi.compendium Show documentation
OSGi Service Platform Release 4 Version 4.3, Compendium Interfaces and Classes for use in compiling bundles.
There is a newer version: 5.0.0
/*
 * Copyright (c) OSGi Alliance (2000, 2008). All Rights Reserved.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.osgi.util.tracker;

import org.osgi.framework.ServiceReference;

/**
 * The ServiceTrackerCustomizer interface allows a
 * ServiceTracker to customize the service objects that are
 * tracked. A ServiceTrackerCustomizer is called when a service is
 * being added to a ServiceTracker. The
 * ServiceTrackerCustomizer can then return an object for the
 * tracked service. A ServiceTrackerCustomizer is also called when
 * a tracked service is modified or has been removed from a
 * ServiceTracker.
 * 
 * 
 * The methods in this interface may be called as the result of a
 * ServiceEvent being received by a ServiceTracker.
 * Since ServiceEvents are synchronously delivered by the
 * Framework, it is highly recommended that implementations of these methods do
 * not register (BundleContext.registerService), modify (
 * ServiceRegistration.setProperties) or unregister (
 * ServiceRegistration.unregister) a service while being
 * synchronized on any object.
 * 
 * 

 * The ServiceTracker class is thread-safe. It does not call a
 * ServiceTrackerCustomizer while holding any locks.
 * ServiceTrackerCustomizer implementations must also be
 * thread-safe.
 * 
 * @ThreadSafe
 * @version $Revision: 5874 $
 */
public interface ServiceTrackerCustomizer {
	/**
	 * A service is being added to the ServiceTracker.
	 * 
	 * 

	 * This method is called before a service which matched the search
	 * parameters of the ServiceTracker is added to the
	 * ServiceTracker. This method should return the service object
	 * to be tracked for the specified ServiceReference. The
	 * returned service object is stored in the ServiceTracker and
	 * is available from the getService and
	 * getServices methods.
	 * 
	 * @param reference The reference to the service being added to the
	 *        ServiceTracker.
	 * @return The service object to be tracked for the specified referenced
	 *         service or null if the specified referenced service
	 *         should not be tracked.
	 */
	public Object addingService(ServiceReference reference);

	/**
	 * A service tracked by the ServiceTracker has been modified.
	 * 
	 * 

	 * This method is called when a service being tracked by the
	 * ServiceTracker has had it properties modified.
	 * 
	 * @param reference The reference to the service that has been modified.
	 * @param service The service object for the specified referenced service.
	 */
	public void modifiedService(ServiceReference reference, Object service);

	/**
	 * A service tracked by the ServiceTracker has been removed.
	 * 
	 * 
	 * This method is called after a service is no longer being tracked by the
	 * ServiceTracker.
	 * 
	 * @param reference The reference to the service that has been removed.
	 * @param service The service object for the specified referenced service.
	 */
	public void removedService(ServiceReference reference, Object service);
}