/*
 * 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 インスタンス定義}で設定します。
 * このコンポーネントの{@link Expression}により、 コンポーネント生成の設定することも可能です。</dd>
 * <dt>依存性注入(Dependency Injection)</dt>
 * <dd>このコンポーネントが依存する他のコンポーネントやパラメータの定義は、 {@link ArgDef 引数定義}、
 * {@link InitMethod 初期化メソッド定義}、 {@link PropertyDef プロパティ定義}により設定されます。 </dd>
 * <dt>アスペクト</dt>
 * <dd>このコンポーネント{@link AspectDef アスペクト定義}により設定します。</dd>
 * <dt>メタ情報</dt>
 * <dd>{@link MetaDef メタ情報定義}により、 コンポーネントに付加情報を設定できます。 メタ情報は、
 * 特殊なコンポーネントであることを識別する場合などに利用します。</dd>
 * </dl>
 * </p>
 * <p>
 * S2コンテナは、 この{@link ComponentDef コンポーネント定義}を元にコンポーネントを管理します。
 * </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;

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

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

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

    /**
     * このコンポーネント定義上のクラスを返します。 このクラスは、
     * diconファイルのcomponentタグにおけるclass属性で指定されたクラスを表します。
     * 
     * @return コンポーネント定義上のクラス
     */
    Class getComponentClass();

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

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

    /**
     * 実際のクラスを返します。 このクラスは、 アスペクト適用後の実際にインスタンス化されるクラスを表します。
     * 
     * @return 実際のクラス
     */
    Class getConcreteClass();

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

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

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

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

    /**
     * コンポーネントを生成するための式を返します。
     * 
     * @return インスタンス生成式
     */
    Expression getExpression();

    /**
     * コンポーネントを生成するための式を設定します。
     * 
     * @param Expression
     *            インスタンス生成式
     */
    void setExpression(Expression expression);

    /**
     * 外部バインディングの真偽を返します。
     * 
     * @return 外部バインディングの真偽
     */
    boolean isExternalBinding();

    /**
     * 外部バインディングの真偽を設定します。
     * 
     * @param externalBinding
     *            外部バインディングの真偽
     */
    void setExternalBinding(boolean externalBinding);

    /**
     * {@link InstanceDef インスタンス定義}が<code>singleton</code>の場合、
     * コンポーネントのインスタンスを生成します。
     */
    void init();

    /**
     * {@link InstanceDef インスタンス定義}が<code>singleton</code>の場合、
     * コンポーネントのインスタンスを破棄します。
     */
    void destroy();
}