/*
* 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 <code>Component</code> 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 <code>ComponentFactory.newInstance(Dictionary)</code> method
* or (if enabled with the <code>ds.factory.enabled</code> 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
* <code>ComponentInstance.dispose()</code> 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 <code>name</code> attribute of the
* <code>component</code> element.
*/
String getName();
/**
* Returns the current state of the Component, which is one of the
* <code>STATE_*</code> constants defined in this interface.
*/
int getState();
/**
* Returns the <code>Bundle</code> declaring this component.
*/
Bundle getBundle();
/**
* Returns the component factory name or <code>null</code> if this component
* is not defined as a component factory. This method provides access to
* the <code>factory</code> attribute of the <code>component</code>
* element.
*/
String getFactory();
/**
* Returns <code>true</code> if this component is a service factory. This
* method returns the value of the <code>serviceFactory</code> attribute of
* the <code>service</code> element. If the component has no service
* element, this method returns <code>false</code>.
*/
boolean isServiceFactory();
/**
* Returns the class name of the Component implementation. This method
* provides access to the <code>class</code> attribute of the
* <code>implementation</code> element.
*/
String getClassName();
/**
* Returns whether the Component is declared to be enabled initially. This
* method provides access to the <code>enabled</code> attribute of the
* <code>component</code> element.
*/
boolean isDefaultEnabled();
/**
* Returns whether the Component is an Immediate or a Delayed Component.
* This method provides access to the <code>immediate</code> attribute of
* the <code>component</code> element.
*/
boolean isImmediate();
/**
* Returns an array of service names provided by this Component or
* <code>null</code> if the Component is not registered as a service. This
* method provides access to the <code>interface</code> attributes of the
* <code>provide</code> 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 <code>ComponentContext.getProperties()</code> 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, <code>null</code> is returned.
*/
Reference[] getReferences();
/**
* Returns the <code>org.osgi.service.component.ComponentInstance</code>
* representing this component or <code>null</code> 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.
* <p>
* This method never returns <code>null</code>, that is, if this method is
* not declared in the component descriptor this method returns the
* default value <i>activate</i>.
*
* @since 1.2
*/
String getActivate();
/**
* Returns <code>true</code> if the name of the method to be called on
* component activation (see {@link #getActivate()} is declared in the
* component descriptor or not.
* <p>
* For a component declared in a Declarative Services 1.0 descriptor, this
* method always returns <code>false</code>.
*
* @since 1.2
*/
boolean isActivateDeclared();
/**
* Returns the name of the method to be called when the component is being
* deactivated.
* <p>
* This method never returns <code>null</code>, that is, if this method is
* not declared in the component descriptor this method returns the
* default value <i>deactivate</i>.
*
* @since 1.2
*/
String getDeactivate();
/**
* Returns <code>true</code> if the name of the method to be called on
* component deactivation (see {@link #getDeactivate()} is declared in the
* component descriptor or not.
* <p>
* For a component declared in a Declarative Services 1.0 descriptor, this
* method always returns <code>false</code>.
*
* @since 1.2
*/
boolean isDeactivateDeclared();
/**
* Returns the name of the method to be called when the component
* configuration has been updated or <code>null</code> if such a method is
* not declared in the component descriptor.
* <p>
* For a component declared in a Declarative Services 1.0 descriptor, this
* method always returns <code>null</code>.
*
* @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
* <i>optional</i> is returned.
* <p>
* The returned string is one of the three policies defined in the
* Declarative Services specification 1.1:
* <dl>
* <dt>optional</dt>
* <dd>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</dd>
* <dt>require</dt>
* <dd>Configuration is required. The component remains unsatisfied until
* configuration is available from the Configuration Admin service.</dd>
* <dt>ignore</dt>
* <dd>Configuration is ignored. No Configuration Admin service
* configuration is supplied to the component.</dd>
* </dl>
*
* @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:
* <p>
* <dl>
* <dt>DS 1.0</dt>
* <dd>The component name is returned.</dd>
* <dt>DS 1.1</dt>
* <dd>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).
* <dt>DS 1.2</dt>
* <dd>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.</dd>
* </dl>
*
* @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 <code>IllegalStateException</code>.
*
* @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
* <code>IllegalStateException</code>.
*
* @throws IllegalStateException If the Component is destroyed.
*/
void disable();
}