/*
 * 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>
 * コンポーネントのインスタンスをどのように管理するのかを定義します。
 * </p>
 * <p>
 * コンポーネントインスタンス定義の種類は「<code>singleton</code>」、「<code>prototype</code>」、「<code>application</code>」、「<code>request</code>」、「<code>session</code>」、「<code>outer</code>」があります。
 * </p>
 * <dl>
 * <dt><code>singleton</code>(default)</dt>
 * <dd>S2コンテナ上で唯一のインスタンスが生成されます。{@link S2Container#getComponent(Object)}を何度呼び出しても同じインスタンスが返されます。</dd>
 * <dt><code>prototype</code></dt>
 * <dd>{@link S2Container#getComponent(Object)}を呼び出すたびに新たなインスタンスが生成されます。</dd>
 * <dt><code>application</code></dt>
 * <dd>コンテキスト毎に1つのインスタンスが生成されます。{@link javax.servlet.Servlet}を使う場合、コンポーネントは{@link javax.servlet.ServletContext}に格納されます。
 * </dd>
 * <dt><code>request</code></dt>
 * <dd>リクエスト毎に1つのインスタンスが生成されます。{@link javax.servlet.Servlet}を使う場合、コンポーネントは{@link javax.servlet.ServletRequest}に格納されます。</dd>
 * <dt><code>session</code></dt>
 * <dd>セッション毎に1つのインスタンスが生成されます。{@link javax.servlet.Servlet}を使う場合、コンポーネントは{@link javax.servlet.http.HttpSession}に格納されます。</dd>
 * <dt><code>outer</code></dt>
 * <dd>コンポーネントのインスタンスは{@link S2Container}外で生成し、DIだけを行ないます。アスペクト、コンストラクタ・インジェクションは適用できません。</dd>
 * </dl>
 * <p>
 * diconファイルではcomponentタグのinstance属性で指定します。<br/>
 * Tigerアノテーションでは&#064;Componentのinstance値で指定します。<br/>
 * backport175アノテーションでは&#064;org.seasar.framework.container.annotation.backport175.Componentのinstance値で指定します。<br/>
 * コンポーネントインスタンス定義を省略した場合は<code>singleton</code>を指定したことになります。
 * </p>
 * <p>「<code>application</code>」、「<code>request</code>」、「<code>session</code>」を使う場合は、Webコンテナ上で{@link org.seasar.framework.container.servlet.S2ContainerListener}・{@link org.seasar.framework.container.servlet.S2ContainerServlet}のいずれかと{@link org.seasar.framework.container.filter.S2ContainerFilter}を設定する必要があります。
 * </p>
 * 
 * @author higa
 * @author goto(Javadoc)
 */
public interface InstanceDef {

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

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

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

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

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

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

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

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