org.osgi.service.component.ComponentContext Maven / Gradle / Ivy
Show all versions of org.osgi.compendium Show documentation
/*
* Copyright (c) OSGi Alliance (2004, 2009). 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.service.component;
import java.util.Dictionary;
import org.osgi.framework.Bundle;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;
/**
* A Component Context object is used by a component instance to interact with
* its execution context including locating services by reference name. Each
* component instance has a unique Component Context.
*
*
* A component instance may have an activate method. If a component instance has
* a suitable and accessible activate method, this method will be called when a
* component configuration is activated. If the activate method takes a
* ComponentContext argument, it will be passed the component
* instance's Component Context object. If the activate method takes a
* BundleContext argument, it will be passed the component
* instance's Bundle Context object. If the activate method takes a
* Map argument, it will be passed an unmodifiable Map containing
* the component properties.
*
*
* A component instance may have a deactivate method. If a component instance
* has a suitable and accessible deactivate method, this method will be called
* when the component configuration is deactivated. If the deactivate method
* takes a ComponentContext argument, it will be passed the
* component instance's Component Context object. If the deactivate method takes
* a BundleContext argument, it will be passed the component
* instance's Bundle Context object. If the deactivate method takes a
* Map argument, it will be passed an unmodifiable Map containing
* the component properties. If the deactivate method takes an int
* or Integer argument, it will be passed the reason code for the
* component instance's deactivation.
*
* @ThreadSafe
* @version $Revision: 6462 $
*/
public interface ComponentContext {
/**
* Returns the component properties for this Component Context.
*
* @return The properties for this Component Context. The Dictionary is read
* only and cannot be modified.
*/
public Dictionary getProperties();
/**
* Returns the service object for the specified reference name.
*
*
* If the cardinality of the reference is 0..n or
* 1..n and multiple services are bound to the reference, the
* service with the highest ranking (as specified in its
* Constants.SERVICE_RANKING property) is returned. If there is
* a tie in ranking, the service with the lowest service ID (as specified in
* its Constants.SERVICE_ID property); that is, the service
* that was registered first is returned.
*
* @param name The name of a reference as specified in a
* reference element in this component's description.
* @return A service object for the referenced service or null
* if the reference cardinality is 0..1 or
* 0..n and no bound service is available.
* @throws ComponentException If the Service Component Runtime catches an
* exception while activating the bound service.
*/
public Object locateService(String name);
/**
* Returns the service object for the specified reference name and
* ServiceReference.
*
* @param name The name of a reference as specified in a
* reference element in this component's description.
* @param reference The ServiceReference to a bound service.
* This must be a ServiceReference provided to the
* component via the bind or unbind method for the specified
* reference name.
* @return A service object for the referenced service or null
* if the specified ServiceReference is not a bound
* service for the specified reference name.
* @throws ComponentException If the Service Component Runtime catches an
* exception while activating the bound service.
*/
public Object locateService(String name, ServiceReference reference);
/**
* Returns the service objects for the specified reference name.
*
* @param name The name of a reference as specified in a
* reference element in this component's description.
* @return An array of service objects for the referenced service or
* null if the reference cardinality is
* 0..1 or 0..n and no bound service is
* available. If the reference cardinality is 0..1 or
* 1..1 and a bound service is available, the array
* will have exactly one element.
* @throws ComponentException If the Service Component Runtime catches an
* exception while activating a bound service.
*/
public Object[] locateServices(String name);
/**
* Returns the BundleContext of the bundle which contains this
* component.
*
* @return The BundleContext of the bundle containing this
* component.
*/
public BundleContext getBundleContext();
/**
* If the component instance is registered as a service using the
* servicefactory="true" attribute, then this method
* returns the bundle using the service provided by the component instance.
*
* This method will return null if:
*
* - The component instance is not a service, then no bundle can be using
* it as a service.
*
- The component instance is a service but did not specify the
*
servicefactory="true" attribute, then all bundles
* using the service provided by the component instance will share the same
* component instance.
* - The service provided by the component instance is not currently being
* used by any bundle.
*
*
* @return The bundle using the component instance as a service or
* null.
*/
public Bundle getUsingBundle();
/**
* Returns the Component Instance object for the component instance
* associated with this Component Context.
*
* @return The Component Instance object for the component instance.
*/
public ComponentInstance getComponentInstance();
/**
* Enables the specified component name. The specified component name must
* be in the same bundle as this component.
*
* @param name The name of a component or null to indicate all
* components in the bundle.
*/
public void enableComponent(String name);
/**
* Disables the specified component name. The specified component name must
* be in the same bundle as this component.
*
* @param name The name of a component.
*/
public void disableComponent(String name);
/**
* If the component instance is registered as a service using the
* service element, then this method returns the service
* reference of the service provided by this component instance.
*
* This method will return null if the component instance is
* not registered as a service.
*
* @return The ServiceReference object for the component
* instance or null if the component instance is not
* registered as a service.
*/
public ServiceReference getServiceReference();
}