org.apache.felix.scr.Component Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.apache.felix.scr.compat Show documentation
Show all versions of org.apache.felix.scr.compat Show documentation
Extensions of the DS Implementation to provide compatibility with API from older Apache Felix DS implementations.
The newest version!
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you 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.apache.felix.scr;
import java.util.Dictionary;
import org.osgi.framework.Bundle;
import org.osgi.service.component.ComponentInstance;
/**
* The Component interface represents a single component managed
* by the Service Component Runtime. Management agents may access the Component
* instances through the {@link ScrService}.
*
* @deprecated Use the ServiceComponentRuntime service.
*/
@Deprecated
public interface Component
{
/**
* The Component has just been created and is still disabled or it has
* been disabled by calling the {@link #disable()} method (value is 1).
*/
static final int STATE_DISABLED = 1;
/**
* The Component is being enabled (value is 512). After the component has
* been enabled it enters the {@link #STATE_UNSATISFIED} state.
* @since 1.2
* @deprecated since 1.8.0
*/
@Deprecated
static final int STATE_ENABLING = 512;
/**
* The Component has been enabled and is now going to be activated (value
* is 2).
* @deprecated as of version 1.2 the enabled state is collapsed into the
* {@link #STATE_UNSATISFIED} state. This status code is never returned
* from the {@link #getState()} method.
*/
@Deprecated
static final int STATE_ENABLED = 2;
/**
* The Component activation failed because any dependency is not satisfied
* (value is 4).
*/
static final int STATE_UNSATISFIED = 4;
/**
* The Component is currently being activated either because it has been
* enabled or because any dependency which was previously unsatisfied has
* become satisfied (value is 8).
* @deprecated since 1.8.0 transient states are no longer used
*/
@Deprecated
static final int STATE_ACTIVATING = 8;
/**
* The Component has successfully been activated and is fully functional
* (value is 16). This is the state of immediate components after
* successful activation. Delayed and Service Factory Components enter
* this state when the service instance has actually been instantiated because
* the service has been acquired.
*/
static final int STATE_ACTIVE = 16;
/**
* The Component has successfully been activated but is a Delayed or Service
* Factory Component pending instantiation on first use (value is 32).
*/
static final int STATE_REGISTERED = 32;
/**
* The Component is a Component Factory ready to create Component instances
* with the ComponentFactory.newInstance(Dictionary) method
* or (if enabled with the ds.factory.enabled configuration) to
* manage Component instances from configuration data received from the
* Configuration Admin Service (value is 64).
*/
static final int STATE_FACTORY = 64;
/**
* The Component is being deactivated either because it is being disabled
* or because a dependency is not satisfied any more (value is 128). After
* deactivation the Component enters the {@link #STATE_UNSATISFIED} state.
* @deprecated since 1.8.0 transient states are no longer used
*/
@Deprecated
static final int STATE_DEACTIVATING = 128;
/**
* The Component is being disabled (value is 1024). After the component has
* been disabled it enters the {@link #STATE_DISABLED} state.
* @since 1.2
* @deprecated since 1.8.0 transient states are no longer used
*/
@Deprecated
static final int STATE_DISABLING = 1024;
/**
* The Component is being disposed off (value is 2048). After the component
* has been disposed off it enters the {@link #STATE_DESTROYED} state.
* @since 1.2
* @deprecated since 1.8.0 transient states are no longer used
*/
@Deprecated
static final int STATE_DISPOSING = 2048;
/**
* The Component has been destroyed and cannot be used any more (value is
* 256). This state is only used when the bundle declaring the component
* is being stopped and all components have to be removed.
* @deprecated as of version 1.2 this constant has been renamed to
* {@link #STATE_DISPOSED}.
*/
@Deprecated
static final int STATE_DESTROYED = 256;
/**
* The Component has been disposed off and cannot be used any more (value is
* 256). This state is used when the bundle declaring the component
* is being stopped and all components have to be removed. This status is
* also the final status of a component after the
* ComponentInstance.dispose() method has been called.
* @since 1.2
*/
static final int STATE_DISPOSED = 256;
/**
* Returns the component ID of this component. This ID is managed by the
* SCR. If the component is not currently enabled the ID might not be
* assigned to the component (yet) and this method will return -1 in this
* case.
*/
long getId();
/**
* Returns the name of the component, which is also used as the service PID.
* This method provides access to the name attribute of the
* component element.
*/
String getName();
/**
* Returns the current state of the Component, which is one of the
* STATE_* constants defined in this interface.
*/
int getState();
/**
* Returns the Bundle declaring this component.
*/
Bundle getBundle();
/**
* Returns the component factory name or null if this component
* is not defined as a component factory. This method provides access to
* the factory attribute of the component
* element.
*/
String getFactory();
/**
* Returns true if this component is a service factory. This
* method returns the value of the serviceFactory attribute of
* the service element. If the component has no service
* element, this method returns false.
*/
boolean isServiceFactory();
/**
* Returns the class name of the Component implementation. This method
* provides access to the class attribute of the
* implementation element.
*/
String getClassName();
/**
* Returns whether the Component is declared to be enabled initially. This
* method provides access to the enabled attribute of the
* component element.
*/
boolean isDefaultEnabled();
/**
* Returns whether the Component is an Immediate or a Delayed Component.
* This method provides access to the immediate attribute of
* the component element.
*/
boolean isImmediate();
/**
* Returns an array of service names provided by this Component or
* null if the Component is not registered as a service. This
* method provides access to the interface attributes of the
* provide elements.
*/
String[] getServices();
/**
* Returns the properties of the Component. The Dictionary returned is a
* private copy of the actual properties and contains the same entries as
* are used to register the Component as a service and are returned by
* the ComponentContext.getProperties() method.
*/
Dictionary getProperties();
/**
* Returns an array of {@link Reference} instances representing the service
* references (or dependencies) of this Component. If the Component has no
* references, null is returned.
*/
Reference[] getReferences();
/**
* Returns the org.osgi.service.component.ComponentInstance
* representing this component or null if this component
* is not been activated yet.
*
* @since 1.2
*/
ComponentInstance getComponentInstance();
/**
* Returns the name of the method to be called when the component is being
* activated.
*
* This method never returns null, that is, if this method is
* not declared in the component descriptor this method returns the
* default value activate.
*
* @since 1.2
*/
String getActivate();
/**
* Returns true if the name of the method to be called on
* component activation (see {@link #getActivate()} is declared in the
* component descriptor or not.
*
* For a component declared in a Declarative Services 1.0 descriptor, this
* method always returns false.
*
* @since 1.2
*/
boolean isActivateDeclared();
/**
* Returns the name of the method to be called when the component is being
* deactivated.
*
* This method never returns null, that is, if this method is
* not declared in the component descriptor this method returns the
* default value deactivate.
*
* @since 1.2
*/
String getDeactivate();
/**
* Returns true if the name of the method to be called on
* component deactivation (see {@link #getDeactivate()} is declared in the
* component descriptor or not.
*
* For a component declared in a Declarative Services 1.0 descriptor, this
* method always returns false.
*
* @since 1.2
*/
boolean isDeactivateDeclared();
/**
* Returns the name of the method to be called when the component
* configuration has been updated or null if such a method is
* not declared in the component descriptor.
*
* For a component declared in a Declarative Services 1.0 descriptor, this
* method always returns null.
*
* @since 1.2
*/
String getModified();
/**
* Returns the configuration policy declared in the component descriptor.
* If the component descriptor is a Declarative Services 1.0 descriptor or
* no configuration policy has been declared, the default value
* optional is returned.
*
* The returned string is one of the three policies defined in the
* Declarative Services specification 1.1:
*
* - optional
* - Configuration from the Configuration Admin service is supplied to
* the component if available. Otherwise the component is activated without
* Configuration Admin configuration. This is the default value reflecting
* the behaviour of Declarative Services 1.0
* - require
* - Configuration is required. The component remains unsatisfied until
* configuration is available from the Configuration Admin service.
* - ignore
* - Configuration is ignored. No Configuration Admin service
* configuration is supplied to the component.
*
*
* @since 1.2
*/
String getConfigurationPolicy();
/**
* Returns the configuration pid declared in the component descriptor.
* The value is used to retrieve the component configuration from the
* OSGi configuration admin service. The value returned by this method
* depends on the Declarative Service namespace used by the component:
*
*
* - DS 1.0
* - The component name is returned.
* - DS 1.1
* - The component name is returned, if it has been specified. If not specified,
* then the default component name is returned (that is the fully qualified component
* class name).
*
- DS 1.2
* - The value of the configuration-pid attribute is returned if it has been specified.
* If not specified, then the same DS 1.1 rules are applied.
*
*
* @since 1.2
*/
String getConfigurationPid();
/**
* Returns whether the configuration-pid has been declared in the descriptor
* or not.
*
* @return whether the configuration-pid has method has been declared in the descriptor
* or not.
* @since DS 1.2
*/
boolean isConfigurationPidDeclared();
/**
* Enables this Component if it is disabled. If the Component is not
* currently {@link #STATE_DISABLED disabled} this method has no effect. If
* the Component is {@link #STATE_DESTROYED destroyed}, this method throws
* an IllegalStateException.
*
* @throws IllegalStateException If the Component is destroyed.
*/
void enable();
/**
* Disables this Component if it is enabled. If the Component is already
* {@link #STATE_DISABLED disabled} this method has no effect. If the
* Component is {@link #STATE_DESTROYED destroyed}, this method throws an
* IllegalStateException.
*
* @throws IllegalStateException If the Component is destroyed.
*/
void disable();
}