org.osgi.framework.ServiceRegistration 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) OSGi Alliance (2000, 2014). 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.framework;

import java.util.Dictionary;
import org.osgi.annotation.versioning.ProviderType;

/**
 * A registered service.
 * 
 * 
 * The Framework returns a {@code ServiceRegistration} object when a
 * {@code BundleContext.registerService} method invocation is successful. The
 * {@code ServiceRegistration} object is for the private use of the registering
 * bundle and should not be shared with other bundles.
 * 

 * The {@code ServiceRegistration} object may be used to update the properties
 * of the service or to unregister the service.
 * 
 * @param  Type of Service.
 * @see BundleContext#registerService(String[],Object,Dictionary)
 * @ThreadSafe
 * @author $Id: 0bc5bfa68ae7cb4a409c066585d3ab4077d80eeb $
 */
@ProviderType
public interface ServiceRegistration {
	/**
	 * Returns a {@code ServiceReference} object for a service being registered.
	 * 

	 * The {@code ServiceReference} object may be shared with other bundles.
	 * 
	 * @throws IllegalStateException If this {@code ServiceRegistration} object
	 *         has already been unregistered.
	 * @return {@code ServiceReference} object.
	 */
	public ServiceReference getReference();

	/**
	 * Updates the properties associated with a service.
	 * 
	 * 

	 * The {@link Constants#OBJECTCLASS}, {@link Constants#SERVICE_BUNDLEID},
	 * {@link Constants#SERVICE_ID} and {@link Constants#SERVICE_SCOPE} keys
	 * cannot be modified by this method. These values are set by the Framework
	 * when the service is registered in the OSGi environment.
	 * 
	 * 

	 * The following steps are required to modify service properties:
	 * 

	 * The service's properties are replaced with the provided properties.
	 * A service event of type {@link ServiceEvent#MODIFIED} is fired.
	 * 

	 * 
	 * @param properties The properties for this service. See {@link Constants}
	 *        for a list of standard service property keys. Changes should not
	 *        be made to this object after calling this method. To update the
	 *        service's properties this method should be called again.
	 * 
	 * @throws IllegalStateException If this {@code ServiceRegistration} object
	 *         has already been unregistered.
	 * @throws IllegalArgumentException If {@code properties} contains case
	 *         variants of the same key name.
	 */
	public void setProperties(Dictionary properties);

	/**
	 * Unregisters a service. Remove a {@code ServiceRegistration} object from
	 * the Framework service registry. All {@code ServiceReference} objects
	 * associated with this {@code ServiceRegistration} object can no longer be
	 * used to interact with the service once unregistration is complete.
	 * 
	 * 
	 * The following steps are required to unregister a service:
	 * 

	 * The service is removed from the Framework service registry so that it
	 * can no longer be obtained.
	 * A service event of type {@link ServiceEvent#UNREGISTERING} is fired
	 * so that bundles using this service can release their use of the service.
	 * Once delivery of the service event is complete, the
	 * {@code ServiceReference} objects for the service may no longer be used to
	 * get a service object for the service.
	 * For each bundle whose use count for this service is greater than
	 * zero:
	 * 
	 * The bundle's use count for this service is set to zero.
	 * If the service was registered with a {@link ServiceFactory} object,
	 * the {@code ServiceFactory.ungetService} method is called to release the
	 * service object for the bundle.
	 * 
	 * 
	 * 
	 * 
	 * @throws IllegalStateException If this {@code ServiceRegistration} object
	 *         has already been unregistered.
	 * @see BundleContext#ungetService(ServiceReference)
	 * @see ServiceFactory#ungetService(Bundle, ServiceRegistration, Object)
	 */
	public void unregister();
}