/*
 * 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;

/**
 * コンポーネントの生成、 配備、 取得および、 外部コンポーネントへの依存コンポーネントのインジェクションを行う機能を提供するインターフェースです。
 * 
 * <p>
 * このインターフェースを実装するクラスは、 {@link InstanceDef コンポーネントインスタンス定義}に応じて、
 * 以下のような機能を提供します。
 * <dl>
 * <dt> シングルトン({@link org.seasar.framework.container.InstanceDef#SINGLETON_NAME singleton})の場合</dt>
 * <dd>
 * <ul>
 * <li>コンポーネントの生成とインスタンスホルダーへの配備</li>
 * <li>シングルトン・コンポーネントの提供</li>
 * </ul>
 * </dd>
 * <dt>プロトタイプ({@link org.seasar.framework.container.InstanceDef#PROTOTYPE_NAME prototype})の場合</dt>
 * <dd>
 * <ul>
 * <li>新しいコンポーネントインスタンスの生成と提供</li>
 * </ul>
 * </dd>
 * <dt>外部コンテキスト({@link org.seasar.framework.container.InstanceDef#APPLICATION_NAME application}、
 * {@link org.seasar.framework.container.InstanceDef#REQUEST_NAME request}、
 * {@link org.seasar.framework.container.InstanceDef#SESSION_NAME session})の場合</dt>
 * <dd>
 * <ul>
 * <li>コンポーネントインスタンスの生成と{@link ExternalContext 外部コンテキスト}への配備</li>
 * <li>外部コンテキストから取得したコンポーネントインスタンスの提供</li>
 * </ul>
 * </dd>
 * <dt> 外部コンポーネント({@link org.seasar.framework.container.InstanceDef#OUTER_NAME outer})の場合</dt>
 * <dd>
 * <ul>
 * <li>外部コンポーネントに対する、 依存コンポーネントのインジェクション</li>
 * <ul>
 * </dd>
 * </dl>
 * </p>
 * <p>
 * それぞれの{@link InstanceDef コンポーネントインスタンス定義}と有効なメソッドの対応表を以下に示します。 <table
 * border="1"> <caption></caption>
 * <tr>
 * <th colspan="6">コンポーネントインスタンス定義と有効なメソッドとの関係 (○:有効、 ×:無効)</th>
 * </tr>
 * <tr>
 * <th colspan="2">-</th>
 * <th colspan="4">メソッド</th>
 * </tr>
 * <tr>
 * <th colspan="2">{@link InstanceDef コンポーネントインスタンス定義}</th>
 * <th>{@link #deploy()}</th>
 * <th>{@link #injectDependency(Object)}</th>
 * <th>{@link #init()}</th>
 * <th>{@link #destroy()}</th>
 * </tr>
 * <tr>
 * <td>シングルトン</td>
 * <td>{@link org.seasar.framework.container.deployer.InstanceSingletonDef singleton}</td>
 * <td>{@link org.seasar.framework.container.deployer.SingletonComponentDeployer#deploy() ○}</td>
 * <td>×</td>
 * <td>{@link org.seasar.framework.container.deployer.SingletonComponentDeployer#init() ○}</td>
 * <td>{@link org.seasar.framework.container.deployer.SingletonComponentDeployer#destroy() ○}</td>
 * </tr>
 * <tr>
 * <td>プロトタイプ</td>
 * <td>{@link org.seasar.framework.container.deployer.InstancePrototypeDef prototype}</td>
 * <td>{@link org.seasar.framework.container.deployer.PrototypeComponentDeployer#deploy() ○}</td>
 * <td>×</td>
 * <td>×</td>
 * <td>×</td>
 * </tr>
 * <tr>
 * <td rowspan="3">外部コンテキスト</td>
 * <td>{@link org.seasar.framework.container.deployer.InstanceApplicationDef application}</td>
 * <td>{@link org.seasar.framework.container.deployer.ApplicationComponentDeployer#deploy() ○}</td>
 * <td>×</td>
 * <td>×</td>
 * <td>×</td>
 * </tr>
 * <tr>
 * <td>{@link org.seasar.framework.container.deployer.InstanceRequestDef request}</td>
 * <td>{@link org.seasar.framework.container.deployer.RequestComponentDeployer#deploy() ○}</td>
 * <td>×</td>
 * <td>×</td>
 * <td>×</td>
 * </tr>
 * <tr>
 * <td>{@link org.seasar.framework.container.deployer.InstanceSessionDef session}</td>
 * <td>{@link org.seasar.framework.container.deployer.SessionComponentDeployer#deploy() ○}</td>
 * <td>×</td>
 * <td>×</td>
 * <td>×</td>
 * </tr>
 * <tr>
 * <td>外部コンポーネント</td>
 * <td>{@link org.seasar.framework.container.deployer.InstanceOuterDef outer}</td>
 * <td>×</td>
 * <td>{@link org.seasar.framework.container.deployer.OuterComponentDeployer#injectDependency(Object) ○}</td>
 * <td>×</td>
 * <td>×</td>
 * </tr>
 * </table>
 * </p>
 * 
 * @author higa
 * @author belltree (Javacoc)
 */
public interface ComponentDeployer {

    /**
     * コンポーネントのインスタンスを返します。
     * 
     * @return コンポーネントのインスタンス
     * 
     * @see org.seasar.framework.container.deployer.SingletonComponentDeployer#deploy()
     * @see org.seasar.framework.container.deployer.ProtorypeComponentDeployer#deploy()
     * @see org.seasar.framework.container.deployer.ApplicationComponentDeployer#deploy()
     * @see org.seasar.framework.container.deployer.RequestComponentDeployer#deploy()
     * @see org.seasar.framework.container.deployer.SessionComponentDeployer#deploy()
     */
    public Object deploy();

    /**
     * 外部コンポーネント<code>outerComponent</code>に対し、 この{@link ComponentDeployer}の{@link ComponentDef コンポーネント定義}に基づいて、
     * S2コンテナ上のコンポーネントをインジェクションします。
     * 
     * @param outerComponent
     *            外部コンポーネント
     * 
     * @see org.seasar.framework.container.deployer.OuterComponentDeployer#injectDependency(Object)
     */
    public void injectDependency(Object outerComponent);

    /**
     * コンポーネントインスタンスを生成します。
     * <p>
     * {@link InstanceDef コンポーネントインスタンス定義}が<code>singleton</code>の場合には、
     * {@AspectDef アスペクト}を適用したインスタンスの生成、 配備、 プロパティ設定の後に、
     * {@link InitMethodDef initMethod}が呼ばれます。
     * </p>
     * 
     * @see org.seasar.framework.container.deployer.SingletonComponentDeployer#init()
     * @see org.seasar.framework.container.assembler.DefaultInitMethodAssembler#assemble(Object)
     */
    public void init();

    /**
     * コンポーネントインスタンスを破棄します。
     * <p>
     * {@link InstanceDef コンポーネントインスタンス定義}が<code>singleton</code>の場合には、
     * {@link DestroyMethodDef destoryMethod}が呼ばれます。
     * </p>
     * 
     * @see org.seasar.framework.container.deployer.SingletonComponentDeployer#destroy()
     * @see org.seasar.framework.container.assembler.DefaultDestroyMethodAssembler#assemble(Object)
     */
    public void destroy();
}