diff options
Diffstat (limited to 'bundles/org.eclipse.equinox.ds/src/org/apache/felix/scr/Component.java')
| -rw-r--r-- | bundles/org.eclipse.equinox.ds/src/org/apache/felix/scr/Component.java | 334 |
1 files changed, 334 insertions, 0 deletions
diff --git a/bundles/org.eclipse.equinox.ds/src/org/apache/felix/scr/Component.java b/bundles/org.eclipse.equinox.ds/src/org/apache/felix/scr/Component.java new file mode 100644 index 000000000..ba7165cfd --- /dev/null +++ b/bundles/org.eclipse.equinox.ds/src/org/apache/felix/scr/Component.java @@ -0,0 +1,334 @@ +/* + * 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 * @deprecated clients should use {@link org.osgi.service.component.runtime.dto.ComponentDescriptionDTO} instead. + */ +@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 + */ + 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. + */ + 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). + */ + 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 be 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. + */ + 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 + */ + 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 + */ + 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}. + */ + 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 + * not 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 behavior 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(); + + /** + * 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(); + +} |