/*
 * Copyright 2005-2010 the original author or authors.
 * 
 * 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.wamblee.system.core;

import java.util.List;

/**
 * A component represents a part of a system that requires a number of
 * interfaces and provides a number of interfaces.
 * 
 * The component interface provides the meta-data for a component. After calling
 * {@link #start(Scope)}, an actual runtime representation of the component can
 * be created which is independent of this component. As a special case, the
 * runtime representation may be identical to the component instance but in
 * general it is not. This allows a component to be used as a factory for
 * creating objects.
 * 
 * 
 * @author Erik Brakkee
 */
public interface Component<Type> {
    /**
     * Gets the name of the subsystem.
     * 
     * @return Subsystem name.
     */
    String getName();

    /**
     * Prepends the context with a super context.
     * 
     */
    void addContext(String aContext);

    /**
     * Getst the context.
     * 
     * @return Context or null if not set.
     */
    String getContext();

    /**
     * Gets the fully qualified name of the component which includes the context
     * of the component. This method can only be used after the component has
     * started.
     * 
     * @return Qualified name.
     */
    String getQualifiedName();

    /**
     * Gets a description of the provided interfaces.
     * 
     * @return Provided interfaces.
     */
    List<ProvidedInterface> getProvidedInterfaces();

    /**
     * Gets a description of the required interfaces.
     * 
     * @return Required interfaces.
     */
    List<RequiredInterface> getRequiredInterfaces();

    /**
     * Initialises the subsystem by starting all the services that it described
     * as provided.
     * 
     * @param aScope
     *            Scope with external interface implementations that are
     *            available. The component must publish its runtime and its
     *            provided interfaces in this scope.
     * 
     * @return Gets an object representing the runtime of the component.
     */
    Type start(Scope aScope);

    /**
     * Stops a component.
     * 
     * @param aRuntime
     *            THe runtime part of the component.
     */
    void stop(Type aRuntime);
}