public class GuiceAgentModule<PARAMS extends IAgentParameters>
extends com.google.inject.AbstractModule
AbstractModule, provides a way to hierarchically specify the bindings
for interfaces and classes.
The module is a place where you assemble the pieces of the dependency puzzle. You're specifying which implementor should be created for specific interface, etc. This sounds good but then you find out that it is somehow hard to override once set bindings.
The GuiceAgentModule solves this by providing addModule(AbstractModule) method
that should be called from configureModules() (see their javadocs). The configureModules()
is meant to be overridden in every descendant of the GuiceAgentModule where it should call super.configureModules()
and than add another module to the queue via addModule(AbstractModule). We're simply collecting
respective modules in every configureModules() implementation. These collected modules are than applied inside
standard Guice's method configure() where they are applied in the order they have been added (that's
why you have to call super.configureModules as a first command in the descendants).
Additionally, we're introducing AgentScope under annotation AgentScoped (concrete scope implementation can
be changed by in descendants via overriding createAgentScope()) and convenient providers for IAgentId
and IAgentParameters exposed via getAgentIdProvider() and getAgentParamsProvider().
IMPORTANT the GuiceAgentModule introduces public method prepareNewAgent(IAgentParameters) that
is meant to configure run-time dependencies inside the module before another agent is instantiated (i.e., for passing run-time
parameters such as IAgentParameters. The method contains only one parameter - PARAMS, therefore it forces you to create
new descendants of IAgentParameters if you want to introduce new run-time parameters (which follows the philosophy that
every AbstractAgent implementation should also defines: 1) own parameters (IAgentParameters descendants), 2) own module (GuiceAgentModule descendants), 3) own runners (AgentRunner descendants).
NOTE that this method MUST BE CALLED before the factory creates another agent (but rest assured, it's already done in GuiceAgentFactory for
you automatically}).
FINALLY the module is providing basic bindings that are always needed for AbstractAgent
| Mapped class | Target | Description | |
|---|---|---|---|
IComponentBus | -> | ComponentBus | Agent bus synchronizing starting/stopping/etc. events. |
IAgentId | -> | provided by the agentIdProvider. |
Id that is provided during runtime, you may use AgentId implementation of IAgentId. |
IAgentParameters | -> | provided by the agentParamsProvider. |
|
IAgentLogger | -> | AgentLogger | Takes care about logging. |
To have successful module the descendant must specify these missing bindings:
| Mapped class | Description |
|---|---|
IAgent | Agent that should be instantiated (preferable descendant of AbstractAgent. |
... don't forget to call super.configureModules() in the subclasses. ;-)
| Constructor and Description |
|---|
GuiceAgentModule()
Initializes
agentScope via createAgentScope(). |
| Modifier and Type | Method and Description |
|---|---|
protected void |
addModule(com.google.inject.AbstractModule module)
Adds next modules containing new bindings that extend (and/or override) previous bindings.
|
protected void |
configure()
Binds
agentScope into the module and then it iterates over modules and
adds all their bindings to the module - each module always overrides previous ones (uses Modules.override(Module...)). |
protected void |
configureModules()
Meant to introduce new
AbstractModule into the module's queue modules via addModule(AbstractModule). |
protected IAgentScope |
createAgentScope()
Method called from the
GuiceAgentModule() to initialize the agentScope,
override if you need you own AgentScope implementation. |
protected IAgentScope |
createAgentTeamScope()
Method called from the
GuiceAgentModule() to initialize the agentTeamScope,
override if you need you own AgentScope implementation. |
protected AdaptableProvider<IAgentId> |
getAgentIdProvider()
Returns a provider for the
IAgentId interface. |
protected AdaptableProvider<PARAMS> |
getAgentParamsProvider()
Returns a provider for the
IAgentParameters interface. |
IAgentScope |
getAgentScope()
AgentScope that is holding agent-scope-singletons (classes annotated with
AgentScoped). |
IAgentScope |
getAgentTeamScope()
AgentTeamScope that is holding agent-team-scope-singletons (classes annotated with
AgentTeamScoped). |
void |
prepareNewAgent(PARAMS agentParameters)
Must be called before another agent instance can be created.
|
addError, addError, addError, bind, bind, bind, bindConstant, binder, bindInterceptor, bindListener, bindScope, configure, convertToTypes, currentStage, getMembersInjector, getMembersInjector, getProvider, getProvider, install, requestInjection, requestStaticInjection, requireBinding, requireBindingpublic GuiceAgentModule()
agentScope via createAgentScope().public void prepareNewAgent(PARAMS agentParameters)
agentScope
and binds IAgentParameters.getAgentId() to the agentIdProvider.
Whenever you create your own IAgentParameters you may need to override this method to utilize your new
run-time dependencies. In such case, always call super.prepareNewAgent(agentParameters) as a first command.
agentParameters - protected final void addModule(com.google.inject.AbstractModule module)
Designed to be used from configureModules().
module - protected void configureModules()
AbstractModule into the module's queue modules via addModule(AbstractModule).
See configureModules() source code for the example (utilizes anonymous class instantiation,
instantiating AbstractModule where you only have to override AbstractModule.configure() method where
you use AbstractModule.bind(Class) method to specify the bindings).
protected IAgentScope createAgentScope()
GuiceAgentModule() to initialize the agentScope,
override if you need you own AgentScope implementation.protected IAgentScope createAgentTeamScope()
GuiceAgentModule() to initialize the agentTeamScope,
override if you need you own AgentScope implementation.public IAgentScope getAgentScope()
AgentScoped).
Use AgentScope.clearScope() to release the objects thus preparing the scope for the next initialization
of the IAgent (automatically called from prepareNewAgent(IAgentParameters).
public IAgentScope getAgentTeamScope()
AgentTeamScoped).
Use IAgentScope.clearScope() to release the objects thus preparing the scope for the next team initialization.
protected AdaptableProvider<IAgentId> getAgentIdProvider()
IAgentId interface. Use when utilizing descendants of IAgentId
to provide the same instance for new interface/implementors.protected AdaptableProvider<PARAMS> getAgentParamsProvider()
IAgentParameters interface. Use when utilizing descendants of IAgentParameters
to provide the same instace for new interface/implementors.protected final void configure()
agentScope into the module and then it iterates over modules and
adds all their bindings to the module - each module always overrides previous ones (uses Modules.override(Module...)).
The advantage over classical AbstractModule.configure() method is that you may easily re-bind already bound classes
(which is unachievable by simple subclassing).
configure in class com.google.inject.AbstractModuleCopyright © 2012 AMIS research group, Faculty of Mathematics and Physics, Charles University in Prague, Czech Republic. All Rights Reserved.