#pragma camel off

= カスタムスコープ =

カスタムスコープの仕組みについてマニュアルに一応の説明があるが、これは非常にわかりづらい。
しかし、誤解を恐れずに一言で言えば、「その時の条件に応じたプロバイダを返すオブジェクト」と言えるかと思う。
この動きをつぶさに追ってみる。

== 単純な例 ==
{{{
package sample;

import com.google.inject.*;

public class Scope1 { 
  
  public static final Scope SCOPE_OBJECT = new Scope() { 
    public <T> Provider<T> scope(Key<T> key, Provider<T> provider) {     
      System.out.println("scope callled!");  
      return provider;
    }
  };
    
  public static class Person {} 
  
  public static void main(String[] args) {     
    Injector injector = Guice.createInjector(new AbstractModule() { 
      protected void configure() { 
        bind(Person.class).in(SCOPE_OBJECT); 
      } 
    }); 
    System.out.println(injector.getInstance(Person.class)); 
    System.out.println(injector.getInstance(Person.class));    
  } 
}
}}}
これは非常に単純な例である。bind(Person.class).in(SCOPE_OBJECT)としているが、このSCOPE_OBJECTがこの場合はProvider<Person>を返すオブジェクト（スコープの実態）である。しかし、この例ではあまりスコープらしくない。
ともあれ、上記を実行すると、
{{{
scope called!
sample.Scope1$Person@1ccb029
sample.Scope1$Person@1415de6
}}}
となる。この例ではスコープを使った意味が全くない。ただし、「scope called!」が一行しか表示されていないことに注意。

== アノテーションを使う例 ==

次に専用のアノテーション(SampleScoped)を登場させ、それをbindScope()でスコープオブジェクトにバインドする。
そして、スコープオブジェクトが返すプロバイダはただ一つのPersonオブジェクトを返すようにしてみる。
しかし、injector.getInstance(Person.class)するたびに異なるPersonが返される。
{{{
package sample;

import java.lang.annotation.*;

import com.google.inject.*;

public class Scope2 { 
  
  @Target({ ElementType.TYPE })
  @Retention(RetentionPolicy.RUNTIME)
  @ScopeAnnotation
  public @interface SampleScoped {}
  
  public static final Scope SCOPE_OBJECT = new Scope() { 
    public <T> Provider<T> scope(Key<T> key, final Provider<T> provider) { 
      System.out.println("scope called!");      
      return new Provider<T>() {
        private T person;
        @SuppressWarnings("unchecked")
        public T get() {
          if (person == null) person = provider.get();
          return (T)person;
        }
      };
    }
  };
    
  public static class Person {} 
  
  public static void main(String[] args) {     
    Injector injector = Guice.createInjector(new AbstractModule() { 
      protected void configure() { 
        bindScope(SampleScoped.class, SCOPE_OBJECT);
      } 
    }); 
    System.out.println(injector.getInstance(Person.class)); 
    System.out.println(injector.getInstance(Person.class)); 
  } 
} 
}}}
結果は
{{{
sample.Scope2$Person@fd54d6
sample.Scope2$Person@1ccb029
}}}
となる。「scope called!」が表示されていないことに注意。
なぜなら、SampleScopedというスコープアノテーションがスコープオブジェクトにバインドされているため、Personは無関係と判断されているからである。そこで、Personに@SampleScopedを付加する。
{{{
  @SampleScoped
  public static class Person {} 
}}}
結果は、
{{{
scope called!
sample.Scope2$Person@443226
sample.Scope2$Person@443226
}}}
となり、「scope called!」が呼び出され、二度のgetInstance()で同じPersonオブジェクトが返されることがわかる。

== @Singletonの仕組み ==

基本は上述したようなものである。この例では@SampleScopedは、まるで@Singletonと同じような機能を持つ。
また、Personクラスのみならず別のクラスを@SampleScopedでアノテートすると、同様の結果になる。
{{{
@SampleScoped
public static class Animal() {}
....
    System.out.println(injector.getInstance(Animal.class)); 
    System.out.println(injector.getInstance(Animal.class)); 
}}}
とやっても、二回の呼び出しに対してただ一つのAnimalオブジェクトが返される。
ちなみに、@Singletonのスコープはスレッドセーフに設計されている。
これはcom.google.inject.Scopesというクラス内にある。
{{{
  /**
   * One instance per {@link Injector}. Also see {@code @}{@link Singleton}.
   */
  public static final Scope SINGLETON = new Scope() {
    public <T> Provider<T> scope(Key<T> key, final Provider<T> creator) {
      return new Provider<T>() {

        private volatile T instance;

        // DCL on a volatile is safe as of Java 5, which we obviously require.
        @SuppressWarnings("DoubleCheckedLocking")
        public T get() {
          if (instance == null) {
            /*
             * Use a pretty coarse lock. We don't want to run into deadlocks
             * when two threads try to load circularly-dependent objects.
             * Maybe one of these days we will identify independent graphs of
             * objects and offer to load them in parallel.
             */
            synchronized (InjectorImpl.class) {
              if (instance == null) {
                instance = creator.get();
              }
            }
          }
          return instance;
        }

        public String toString() {
          return String.format("%s[%s]", creator, SINGLETON);
        }
      };
    }

    @Override public String toString() {
      return "Scopes.SINGLETON";
    }
  };
}}}
{{{
 binder.bindScope(Singleton.class, SINGLETON);
}}}

== ここまでのまとめ ==
一般的にカスタムスコープを作成するには、次のような作業が必要になる。

 * スコープアノテーションを定義する。上の例では@SampleScopedである。
 * Scopeインターフェースの実装を作成する。上ので例ではこれを作成してSCOPE_OBJECTという変数に入れている。
 * スコープアノテーションを実装にアタッチする。上の例ではモジュール内でbindScope()を呼び出している。

== @Singleton以外のスコープ ==

@Singletonスコープは単純であるので、スレッドに気をつければすぐに独自の実装ができる。
しかし、@Singleton以外のスコープはどのように実現すればよいのだろうか？これは要求によって異なるのだが、Scopeインターフェースの実装を変更すればよいことにはすぐ気がつくだろう。要求には以下のようなものがあるかもしれない。

　* スレッドごとに唯一のオブジェクトを返すようにする。@RequestScopedはこのパターン。
 * 現在の「状態」ごとに唯一のオブジェクトを返すようにする、スレッドは複数でもよい。@SessionScopedはこのパターン。
 * 明示的に「開始」と「終了」呼び出しを行い、その間で唯一のオブジェクトを返すようにする。たぶん単一スレッドだが、複数になるかもしれない。
 * 常に異なるオブジェクトを返すが、何らかの条件によってそれぞれのオブジェクトが別のセットアップになるようにしたい。

他にも様々なパターンが考えられるが、結局のところScopedインターフェースの実装でこれを実現することには変わりがない。

== @SessionScopedの仕組み ==

SessionScopedはcom.google.inject.servlet.InternalServletModule及びcom.google.inject.ServletScopesで実現されている。非常に短いのでこれらのクラスを全文引用する。

{{{
package com.google.inject.servlet;

import com.google.inject.AbstractModule;
import com.google.inject.Provider;
import com.google.inject.TypeLiteral;
import static com.google.inject.servlet.ServletScopes.REQUEST;
import static com.google.inject.servlet.ServletScopes.SESSION;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.ServletContext;
import java.util.Map;

/**
 * This is a left-factoring of all ServletModules installed in the system.
 * In other words, this module contains the bindings common to all ServletModules,
 * and is bound exactly once per injector.
 *
 * @author dhanji@gmail.com (Dhanji R. Prasanna)
 */
final class InternalServletModule extends AbstractModule {

  @Override
  protected void configure() {
    // Scopes.
    bindScope(RequestScoped.class, REQUEST);
    bindScope(SessionScoped.class, SESSION);

    // Bind request.
    Provider<HttpServletRequest> requestProvider =
        new Provider<HttpServletRequest>() {
          public HttpServletRequest get() {
            return GuiceFilter.getRequest();
          }

          public String toString() {
            return "RequestProvider";
          }
        };
    bind(HttpServletRequest.class).toProvider(requestProvider);
    bind(ServletRequest.class).toProvider(requestProvider);

    // Bind response.
    Provider<HttpServletResponse> responseProvider =
        new Provider<HttpServletResponse>() {
          public HttpServletResponse get() {
            return GuiceFilter.getResponse();
          }

          public String toString() {
            return "ResponseProvider";
          }
        };
    bind(HttpServletResponse.class).toProvider(responseProvider);
    bind(ServletResponse.class).toProvider(responseProvider);

    // Bind session.
    bind(HttpSession.class).toProvider(new Provider<HttpSession>() {
      public HttpSession get() {
        return GuiceFilter.getRequest().getSession();
      }

      public String toString() {
        return "SessionProvider";
      }
    });

    // Bind servlet context.
    bind(ServletContext.class).toProvider(new Provider<ServletContext>() {
      public ServletContext get() {
        return GuiceFilter.getServletContext();
      }

      public String toString() {
        return "ServletContextProvider";
      }
    });

    // Bind request parameters.
    bind(new TypeLiteral<Map<String, String[]>>() {})
        .annotatedWith(RequestParameters.class)
        .toProvider(new Provider<Map<String, String[]>>() {
              @SuppressWarnings({"unchecked"})
              public Map<String, String[]> get() {
                return GuiceFilter.getRequest().getParameterMap();
              }

              public String toString() {
                return "RequestParametersProvider";
              }
            });

    // inject the pipeline into GuiceFilter so it can route requests correctly
    // Unfortunate staticness... =(
    requestStaticInjection(GuiceFilter.class);

    bind(ManagedServletPipeline.class);
    bind(FilterPipeline.class).to(ManagedFilterPipeline.class).asEagerSingleton();
  }

  @Override
  public boolean equals(Object o) {
    // Is only ever installed internally, so we don't need to check state.
    return o instanceof InternalServletModule;
  }

  @Override
  public int hashCode() {
    return InternalServletModule.class.hashCode();
  }
}
}}}
{{{
/**
 * Copyright (C) 2006 Google Inc.
 *
 * 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 com.google.inject.servlet;

import com.google.inject.Binding;
import com.google.inject.Key;
import com.google.inject.Provider;
import com.google.inject.Scope;
import com.google.inject.Scopes;
import com.google.inject.Singleton;
import com.google.inject.spi.DefaultBindingScopingVisitor;
import java.lang.annotation.Annotation;
import java.util.concurrent.atomic.AtomicBoolean;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpSession;

/**
 * Servlet scopes.
 *
 * @author crazybob@google.com (Bob Lee)
 */
public class ServletScopes {

  private ServletScopes() {}

  /**
   * HTTP servlet request scope.
   */
  public static final Scope REQUEST = new Scope() {
    public <T> Provider<T> scope(Key<T> key, final Provider<T> creator) {
      final String name = key.toString();
      return new Provider<T>() {
        public T get() {
          HttpServletRequest request = GuiceFilter.getRequest();
          synchronized (request) {
            @SuppressWarnings("unchecked")
            T t = (T) request.getAttribute(name);
            if (t == null) {
              t = creator.get();
              request.setAttribute(name, t);
            }
            return t;
          }
        }

        public String toString() {
          return String.format("%s[%s]", creator, REQUEST);
        }
      };
    }

    public String toString() {
      return "ServletScopes.REQUEST";
    }
  };

  /**
   * HTTP session scope.
   */
  public static final Scope SESSION = new Scope() {
    public <T> Provider<T> scope(Key<T> key, final Provider<T> creator) {
      final String name = key.toString();
      return new Provider<T>() {
        public T get() {
          HttpSession session = GuiceFilter.getRequest().getSession();
          synchronized (session) {
            @SuppressWarnings("unchecked")
            T t = (T) session.getAttribute(name);
            if (t == null) {
              t = creator.get();
              session.setAttribute(name, t);
            }
            return t;
          }
        }
        public String toString() {
          return String.format("%s[%s]", creator, SESSION);
        }
      };
    }

    public String toString() {
      return "ServletScopes.SESSION";
    }
  };

  static boolean isSingletonBinding(Binding<?> binding) {
    final AtomicBoolean isSingleton = new AtomicBoolean(true);
    binding.acceptScopingVisitor(new DefaultBindingScopingVisitor<Void>() {
      @Override
      public Void visitNoScoping() {
        isSingleton.set(false);

        return null;
      }

      @Override
      public Void visitScopeAnnotation(Class<? extends Annotation> scopeAnnotation) {
        if (null != scopeAnnotation && !Singleton.class.equals(scopeAnnotation)) {
          isSingleton.set(false);
        }

        return null;
      }

      @Override
      public Void visitScope(Scope scope) {
        if (null != scope && !Scopes.SINGLETON.equals(scope)) {
          isSingleton.set(false);
        }

        return null;
      }
    });

    return isSingleton.get();
  }
}

}}}