3.2. S2ApplicationContext Reference

3.2. S2ApplicationContext Reference
Prev	Chapter 3. S2Container.Ruby Reference	Next

The main functions of S2ApplicationContext become the next.

Generate S2Container which contains the registerd class as a component
Automatic setup of Aspect
Singleton S2Container instance management

3.2.1. Generation of S2ApplicationContext

You are able to generate S2ApplicationContext by the instance method.

S2ApplicationContext#instance

The Singleton instance returns when S2ApplicationContext is generated by the instance method. Please use the new method when you generate a new instance, as usual.

S2ApplicationContext#new

Also, the s2app method is defined as a short cut to S2ApplicationContext#instance.

3.2.2. Registration of a component

Registration of a component is performed by the s2component method

s2component(options = {}, &procedure)
alias s2comp s2component

1st arugument : component information (Hash)

Symbol :class => Class of component
When the s2component method is called within a class definition, the class is set up as a default value.

Symbol :name => name of component (String | Symbol)

Symbol :instance => instance management setup

Symbol :autobinding => automatic binding setup

Symbol :namespace => namespace setup (String)

2nd argument : Constructor Block
Constructor Block is passed to the s2component method. The evaluation result of the last of Constructor Block must fulfill the relation of is_a? with a component class which is specified by 1st argument.

The s2component method defines the class method "instance" in the component class. The "instance" class method gets the component from S2Container.
require 's2container'

class Action
  s2component
end

action = Action.instance     # s2app.get(Action) is called in the instance method (class method).

3.2.3. Generation of S2Container

Generation of S2Container instance is performed by the following method.

S2ApplicationContext#create(namespaces = [])

Generated S2Container has all the classes as a component which are registered by the s2component method. If the namespaces argument is given (String or Array of String vlaue), the S2Container instance including specified namespace is returned. As an example, S2Container is generated as follows, when there is Action class in global namespace (means without namespace) and Service class in "services" namespace.

Let's define the following classes.

module Example
  class Action
    s2comp
  end

  class Service
    s2comp :namespace => "services"
  end
end

Please create the following executable files.

require 's2container'
require 'example'

// generation of a global container
container = s2app.create
component = container.get(Example::Action)
p component
component = container.get(Example::Service)
p component


// generation of services namespace container
container = s2app.create("services")
begin
  component = container.get(Example::Action)  # -> error occured. because the component not exists.
rescue => err
  puts err.message
end
component = container.get(Example::Service)
p component

	NOTE
	This Example is located at "example/example04".

3.2.4. Selection of a component

A part can be chosen from the registered classes when generating S2Container by a create method.

default (no setting) : All the registered classes are treated as a component.
Include Pattern : Only what matches a pattern to a component is used.
Exclude Pattern : What matches a pattern to a component is excepted.
Include & Exclude : If both Include Pattern and Exclude Pattern are set, What matched Exclude Pattern is excepted from what matched Include Pattern.

include method definition.
S2ApplicationContext.include(pattern)
The 1st argument : include pattern

Regexp : used when Regexp matches to name of component or name of component class.

Class : used when Class equals to a component class.

String : used when String equals to name of component or name of component class.

Symbol : used when Symbol equals to name(Symbol) of component or name(Symbol) of component class.

exclude method definition.
S2ApplicationContext.exclude(pattern)
The 1st argument : exclude pattern

Regexp : excluded when Regexp matches to name of component or name of component class.

Class : excluded when Class equals to a component class.

String : excluded when String equals to name of component or name of component class.

Symbol : excluded when Symbol equals to name(Symbol) of component or name(Symbol) of component class.

3.2.5. Auto Aspect

An aspect is automatically applied to the component included by selection of the component. A setup of an automatic aspect is performed by the s2aspect method.

s2aspect(options, &procedure)

1st argument : Hash of aspect information.

Symbol :pattern => (Regexp /.+/ is a default value.)

Regexp : aspected when Regexp matches to name of component or name of component class.

Class : aspected when Class equals to a component class.

String : aspected when String equals to name of component or name of component class.

Symbol : aspected when Symbol equals to name(Symbol) of component or name(Symbol) of component class.

Symbol :pointcut => (Regexp /.+/ is a default value)

Regexp : aspected when Regexp matches to method name.

String : aspected when String equals to method name.

Symbol : aspected when Symbol equals to method name(Symbol).

Symbol :interceptor => Interceptor component name ot Interceptor instance

2nd argument : Interceptor Block
It is the block including Interceptor processing. An argument of Interceptor Block is MethodInvocation instance. By calling the proceed method of MethodInvocation class, following Interceptor or the method for Aspect is executed.

When an aspect method is performed within a class definition, a class name is set automatically as :pattern value of the 1st argument.

The case where the the TraceInterceptor is aspected to the index method of Action class is shown below. TraceInterceptor is beforehand registered as interceptor.trace.

module Example
  class Action
    s2comp
    s2aspect :interceptor => "interceptor.trace", :pointcut => :index
    def index
      s2logger.debug(self.class.superclass) {"index action called."}
    end
  end
end

Please create the following executable files.

require 's2container'
require 'example'

container = s2app.create
component = container.get(Example::Action)
component.index

	NOTE
	This Example is located at "example/example06".

Next, the case where the the Interceptor is aspected to the index method of Action class by Brock is shown.

module Example
  class Action
    s2comp :name => :action
    def index
      s2logger.debug(self.class.superclass) {"index action called."}
    end
  end
end

Please create the following executable files.

require 's2container'
require 'example'

s2aspect(:pattern => :action, :pointcut => :index) {|invocation|
  s2logger.debug(invocation.component_class) {"before"}
  result = invocation.proceed
  s2logger.debug(invocation.component_class) {"after "}
  next result
}

container = s2app.create
component = container.get(:action)
component.index

	NOTE
	This Example is located at "example/example07".

3.2.6. Management of Singleton S2Container instance

S2ApplicationContext generates and manages Singleton S2Container in a namespace unit. Access to Singleton S2Container is performed by the following method.

get_component method.
S2ApplicationContext#get_component(key, namespaces = [])
alias component get_component
alias get get_component
The 1st argument : name of component

the 2nd argument : namespaces of S2Container

The component specified by the 1st argument is acquired. If Singleton S2Container including namespaces specified by the 2nd argument has not been created, S2Continer is generated using S2ApplicationContext.create method.

get_component_def method.
S2ApplicationContext#get_component_def(key, namespaces = [])
The 1st argument : name of component

the 2nd argument : namespace of S2Container

The component definition specified by the 1st argument is acquired. If Singleton S2Container including namespaces specified by the 2nd argument has not been created, S2Continer is generated using S2ApplicationContext.create method.

As an example, Action class is in global namespace (without a namespace), and when Service class is services namesace, each component can be acquired as follows.

Let's define the following classes.

module Example
  class Action
    s2comp
  end

  class Service
    s2comp :namespace => "services"
  end
end

Please create the following executable files.

require 's2container'
require 'example'

global_action = s2app.get(Example::Action)
p global_action
global_service = s2app.get(Example::Service)
p global_service

begin
  services_action = s2app.get(Example::Action, "services")
rescue => err
  puts err.message                # -> component [Example::Action] not found.
end
services_service = s2app.get(Example::Service, "services")
p services_service
p global_service == services_service       # -> false

	Caution
	When a global Singleton container is generated, the container of example namespace is also generated, and it is held as a child container, but it is an instance different from the singleton container of example namespace.

	NOTE
	This Example is located at "example/example07".