content: /*
   * Copyright (c) OSGi Alliance (2008, 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.blueprint.container;
  
  import java.util.Collection;
  import java.util.Set;
  
  import org.osgi.service.blueprint.reflect.BeanMetadata;
  import org.osgi.service.blueprint.reflect.ComponentMetadata;
  import org.osgi.service.blueprint.reflect.ReferenceListMetadata;
  import org.osgi.service.blueprint.reflect.ReferenceMetadata;
  import org.osgi.service.blueprint.reflect.ServiceMetadata;
  import org.osgi.service.blueprint.reflect.ServiceReferenceMetadata;
  
  /**
   * A Blueprint Container represents the managed state of a Blueprint bundle.
   * 
   * A Blueprint Container provides access to all managed components. These are
   * the beans, services, and service references. Only bundles in the
   * <code>ACTIVE</code> state (and also the <code>STARTING</code> state for
   * bundles awaiting lazy activation) can have an associated Blueprint Container.
   * A given Bundle Context has at most one associated Blueprint Container.
   * 
   * A Blueprint Container can be obtained by injecting the predefined
   * &quot;blueprintContainer&quot; component id. The Blueprint Container is also
   * registered as a service and its managed components can be queried.
   * 
   * @ThreadSafe
   * @version $Revision$
   */
  public interface BlueprintContainer {
  	/**
  	 * Returns the set of component ids managed by this Blueprint Container.
  	 * 
  	 * @return An immutable Set of Strings, containing the ids of all of the
  	 *         components managed within this Blueprint Container.
  	 */
  	Set<String> getComponentIds();
  
  	/**
  	 * Return the component instance for the specified component id.
  	 * 
  	 * If the component's manager has not yet been activated, calling this
  	 * operation will atomically activate it. If the component has singleton
  	 * scope, the activation will cause the component instance to be created and
  	 * initialized. If the component has prototype scope, then each call to this
  	 * method will return a new component instance.
  	 * 
  	 * @param id The component id for the requested component instance.
  	 * @return A component instance for the component with the specified
  	 *         component id.
  	 * @throws NoSuchComponentException If no component with the specified
  	 *         component id is managed by this Blueprint Container.
  	 */
  	Object getComponentInstance(String id);
  
  	/**
  	 * Return the Component Metadata object for the component with the specified
  	 * component id.
  	 * 
  	 * @param id The component id for the requested Component Metadata.
  	 * @return The Component Metadata object for the component with the
  	 *         specified component id.
  	 * @throws NoSuchComponentException If no component with the specified
  	 *         component id is managed by this Blueprint Container.
  	 */
  	ComponentMetadata getComponentMetadata(String id);
  
  	/**
  	 * Return all {@link ComponentMetadata} objects of the specified Component
  	 * Metadata type. The supported Component Metadata types are
  	 * {@link ComponentMetadata} (which returns the Component Metadata for all
  	 * defined manager types), {@link BeanMetadata} ,
  	 * {@link ServiceReferenceMetadata} (which returns both
  	 * {@link ReferenceMetadata} and {@link ReferenceListMetadata} objects), and
  	 * {@link ServiceMetadata}. The collection will include all Component
  	 * Metadata objects of the requested type, including components that are
  	 * declared inline.
  	 * 
  	 * @param type The super type or type of the requested Component Metadata
  	 *        objects.
  	 * @return An immutable collection of Component Metadata objects of the
  	 *         specified type.
  	 */
  	<T extends ComponentMetadata> Collection<T> getMetadata(
  			Class<T> type);
  }
  