FELIX-4785 : Incompatible SCR API
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@1657502 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/scr/src/main/java/org/apache/felix/scr/Component.java b/scr/src/main/java/org/apache/felix/scr/Component.java
new file mode 100644
index 0000000..eb4bc23
--- /dev/null
+++ b/scr/src/main/java/org/apache/felix/scr/Component.java
@@ -0,0 +1,403 @@
+/*
+ * 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();
+
+}