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

/**
 * コンポーネントのインスタンスをどのように管理するのかを定義します。diconファイルのcomponentタグのinstance属性に指定します。コンポーネントインスタンス定義の種類は「singleton」、「prototype」、「application」、「request」、「session」、「outer」があります。
 * <dl>
 * <dt>singleton(default)</dt>
 * <dd><code>{@link S2Container#getComponent(Object)}</code>を何度呼び出しても同じインスタンスが返されます。</dd>
 * <dt>prototype</dt>
 * <dd><code>{@link S2Container#getComponent(Object)}</code>を呼び出すたびに新たなインスタンスが返されます。</dd>
 * <dt>application</dt>
 * <dd><code>{@link javax.servlet.Servlet}</code>を使う場合は､<code>{@link javax.servlet.ServletContext}</code>毎に1つのインスタンスが作成されます。diconファイルのcomponentタグのname属性に指定した名前で、コンポーネントが<code>{@link javax.servlet.ServletContext}</code>に格納されます。applicationを使う場合は、<code>{@link org.seasar.framework.container.filter.S2ContainerFilter}</code>を設定する必要があります。</dd>
 * <dt>request</dt>
 * <dd>リクエスト毎に1つのインスタンスが作成されます。diconファイルのcomponentタグのname属性に指定した名前で、コンポーネントがリクエストに格納されます。requestを使う場合は、<code>{@link org.seasar.framework.container.filter.S2ContainerFilter}</code>を設定する必要があります。</dd>
 * <dt>session</dt>
 * <dd>セッション毎に1つのインスタンスが作成されます。diconファイルのcomponentタグのname属性に指定した名前で、コンポーネントがセッションに格納されます。sessionを使う場合は、<code>{@link org.seasar.framework.container.filter.S2ContainerFilter}</code>を設定する必要があります。</dd>
 * <dt>outer</dt>
 * <dd>コンポーネントのインスタンスは、<code>{@link S2Container}</code>外で作成し、DIだけを行ないます。アスペクト、コンストラクタ・インジェクションは適用できません。</dd>
 * </dl>
 * 
 * @author higa
 * @author goto(Javadoc)
 */
public interface InstanceDef {

    /**
     * コンポーネントインスタンス定義「singleton」を表す定数です。
     */
    String SINGLETON_NAME = "singleton";

    /**
     * コンポーネントインスタンス定義「prototype」を表す定数です。
     */
    String PROTOTYPE_NAME = "prototype";

    /**
     * コンポーネントインスタンス定義「application」を表す定数です。
     */
    String APPLICATION_NAME = "application";

    /**
     * コンポーネントインスタンス定義「request」を表す定数です。
     */
    String REQUEST_NAME = "request";

    /**
     * コンポーネントインスタンス定義「session」を表す定数です。
     */
    String SESSION_NAME = "session";

    /**
     * コンポーネントインスタンス定義「outer」を表す定数です。
     */
    String OUTER_NAME = "outer";

    /**
     * コンポーネントインスタンス定義を返します。
     * 
     * @return コンポーネントインスタンス定義
     */
    String getName();

    /**
     * コンポーネントインスタンス定義に基づいた<code>{@link ComponentDeployer}</code>を返します。
     * 
     * @param componentDef
     *            コンポーネント定義
     * @return コンポーネントの生成やDIを行なうオブジェクト
     */
    ComponentDeployer createComponentDeployer(ComponentDef componentDef);
}