/*
 * Copyright 2004-2006 the Seasar Foundation and the Others.
 *
 * 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.seasar.framework.container;

/**
 * S2コンテナ上で管理されるアプリケーション構成部品であるコンポーネントを表すインターフェースです。
 * <p>
 * コンポーネント定義は、 コンポーネントの管理に必要な以下の情報を保持します。
 * <dl>
 * <dt>ライフサイクル</dt>
 * <dd>コンポーネントの生成と消滅は、 このコンポーネントの{@link InstanceDef インスタンス定義}により設定されます。</dd>
 * <dt>コンフィギュレーション</dt>
 * <dd>定数などのパラーメータは、 {@link Expression <var>OGNL</var>式}により設定されます。</dd>
 * <dt>依存性注入(<var>Dependency Injection</var>)</dt>
 * <dd>コンポーネントが必要とする、 他のコンポーネントの情報は、 コンポーネント{@link ArgDef 引数}、
 * {@link InitMethod 初期化メソッド定義}、 {@link PropertyDef プロパティ定義}などにより保持されます。 </dd>
 * <dt>アスペクト</dt>
 * <dd>コンポーネントのメソッドに織り込む共通的な処理の情報は、 {@link AspectDef アスペクト定義}により保持します。</dd>
 * </dl>
 * </p>
 * <p>
 * S2コンテナは、 これらの情報を使用してコンポーネントを管理します。
 * </p>
 * 
 * @author higa
 * @author belltree (Javadoc)
 * 
 * @see ArgDef
 * @see InterTypeDef
 * @see PropertyDef
 * @see InitMethodDef
 * @see DestroyMethodDef
 * @see AspectDef
 * @see MetaDef
 */
public interface ComponentDef extends ArgDefAware, InterTypeDefAware,
        PropertyDefAware, InitMethodDefAware, DestroyMethodDefAware,
        AspectDefAware, MetaDefAware {

    /**
     * このコンポーネント定義に基づいて、 実装コンポーネントを返します。
     * 
     * @return 実装コンポーネント
     * @throws TooManyRegistrationRuntimeException
     *             実装コンポーネントが複数ある場合
     * @throws CyclicReferenceRuntimeException
     *             コンポーネント間に循環参照がある場合
     * 
     * @see TooManyRegistrationComponentDef
     */
    Object getComponent() throws TooManyRegistrationRuntimeException,
            CyclicReferenceRuntimeException;

    /**
     * 指定された外部コンポーネントに、 依存オブジェクトをインジェクションします。
     * 
     * @param outerComponent
     *            外部コンポーネント
     */
    void injectDependency(Object outerComponent);

    /**
     * このコンポーネント定義を所有するS2コンテナを返します。
     * 
     * @return S2コンテナ
     */
    S2Container getContainer();

    /**
     * このコンポーネント定義を所有するS2コンテナを設定します。
     * 
     * @param container
     *            S2コンテナ
     */
    void setContainer(S2Container container);

    /**
     * このコンポーネントの{@link java.lang.Class クラス}を返します。
     * 
     * @return コンポーネントのクラス。
     */
    Class getComponentClass();

    /**
     * S2コンテナ上のコンポーネント名を返します。
     * 
     * @return コンポーネント名
     */
    String getComponentName();

    /**
     * S2コンテナ上のコンポーネント名を設定します。
     * 
     * @param componentName
     *            コンポーネント名
     */
    void setComponentName(String componentName);

    /**
     * インスタンス化が可能な{@link java.lang.Class クラス}を返します。
     * 
     * @return インスタンス化が可能なクラス
     */
    Class getConcreteClass();

    /**
     * 自動バインディング定義を返します。
     * 
     * @return 自動バインディング定義
     */
    AutoBindingDef getAutoBindingDef();

    /**
     * 自動バインディング定義を設定します。
     * 
     * @param autoBindingDef
     *            自動バインディング定義
     */
    void setAutoBindingDef(AutoBindingDef autoBindingDef);

    /**
     * インスタンス定義を返します。
     * 
     * @return インスタンス定義
     */
    InstanceDef getInstanceDef();

    /**
     * インスタンス定義を設定します。
     * 
     * @param instanceDef
     *            インスタンス定義
     */
    void setInstanceDef(InstanceDef instanceDef);

    /**
     * <var>OGNL</var>式を返します。
     * 
     * @return <var>OGNL</var>式
     */
    Expression getExpression();

    /**
     * <var>OGNL</var>式を設定します。
     * 
     * @param Expression
     *            <var>OGNL</var>式
     */
    void setExpression(Expression expression);

    /**
     * コンポーネント定義を初期化します。
     */
    void init();

    /**
     * コンポーネント定義を破棄します。
     */
    void destroy();
}