335 lines
11 KiB
ReStructuredText
335 lines
11 KiB
ReStructuredText
|
|
.. _spring-module:
|
|
|
|
####################
|
|
Spring Integration
|
|
####################
|
|
|
|
Module stability: **STABLE**
|
|
|
|
Akkas integration with the `Spring Framework <http://www.springsource.org>`_ supplies the Spring way of using the Typed Actor Java API and for CamelService configuration for :ref:`camel-spring-applications`. It uses Spring's custom namespaces to create Typed Actors, supervisor hierarchies and a CamelService in a Spring environment.
|
|
|
|
Contents:
|
|
|
|
.. contents:: :local:
|
|
|
|
To use the custom name space tags for Akka you have to add the XML schema definition to your spring configuration. It is available at `http://akka.io/akka-1.0.xsd <http://akka.io/akka.xsd>`_. The namespace for Akka is:
|
|
|
|
.. code-block:: xml
|
|
|
|
xmlns:akka="http://akka.io/schema/akka"
|
|
|
|
Example header for Akka Spring configuration:
|
|
|
|
.. code-block:: xml
|
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<beans xmlns="http://www.springframework.org/schema/beans"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xmlns:akka="http://akka.io/schema/akka"
|
|
xsi:schemaLocation="
|
|
http://www.springframework.org/schema/beans
|
|
http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
|
|
http://akka.io/schema/akka
|
|
http://akka.io/akka-1.0.xsd">
|
|
|
|
-
|
|
|
|
Actors
|
|
------
|
|
|
|
Actors in Java are created by extending the 'UntypedActor' class and implementing the 'onReceive' method.
|
|
|
|
Example how to create Actors with the Spring framework:
|
|
|
|
.. code-block:: xml
|
|
|
|
<akka:untyped-actor id="myActor"
|
|
implementation="com.biz.MyActor"
|
|
scope="singleton"
|
|
autostart="false"
|
|
depends-on="someBean"> <!-- or a comma-separated list of beans -->
|
|
<property name="aProperty" value="somePropertyValue"/>
|
|
<property name="aDependency" ref="someBeanOrActorDependency"/>
|
|
</akka:untyped-actor>
|
|
|
|
Supported scopes are singleton and prototype. Dependencies and properties are set with Springs ``<property/>`` element.
|
|
A dependency can be either a ``<akka:untyped-actor/>`` or a regular ``<bean/>``.
|
|
|
|
Get the Actor from the Spring context:
|
|
|
|
.. code-block:: java
|
|
|
|
ApplicationContext context = new ClassPathXmlApplicationContext("akka-spring-config.xml");
|
|
ActorRef actorRef = (ActorRef) context.getBean("myActor");
|
|
|
|
Typed Actors
|
|
------------
|
|
|
|
Here are some examples how to create Typed Actors with the Spring framework:
|
|
|
|
Creating a Typed Actor:
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. code-block:: xml
|
|
|
|
<beans>
|
|
<akka:typed-actor id="myActor"
|
|
interface="com.biz.MyPOJO"
|
|
implementation="com.biz.MyPOJOImpl"
|
|
transactional="true"
|
|
timeout="1000"
|
|
scope="singleton"
|
|
depends-on="someBean"> <!-- or a comma-separated list of beans -->
|
|
<property name="aProperty" value="somePropertyValue"/>
|
|
<property name="aDependency" ref="someBeanOrActorDependency"/>
|
|
</akka:typed-actor>
|
|
</beans>
|
|
|
|
Supported scopes are singleton and prototype. Dependencies and properties are set with Springs ``<property/>`` element.
|
|
A dependency can be either a ``<akka:typed-actor/>`` or a regular ``<bean/>``.
|
|
|
|
Get the Typed Actor from the Spring context:
|
|
|
|
.. code-block:: java
|
|
|
|
ApplicationContext context = new ClassPathXmlApplicationContext("akka-spring-config.xml");
|
|
MyPojo myPojo = (MyPojo) context.getBean("myActor");
|
|
|
|
Remote Actors
|
|
-------------
|
|
|
|
For details on server managed and client managed remote actors see Remote Actor documentation.
|
|
|
|
Configuration for a client managed remote Actor
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
<akka:untyped-actor id="remote-untyped-actor"
|
|
implementation="com.biz.MyActor"
|
|
timeout="2000">
|
|
<akka:remote host="localhost" port="9992" managed-by="client"/>
|
|
</akka:untyped-actor>
|
|
|
|
The default for 'managed-by' is "client", so in the above example it could be left out.
|
|
|
|
Configuration for a server managed remote Actor
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Server side
|
|
***********
|
|
|
|
::
|
|
|
|
<akka:untyped-actor id="server-managed-remote-untyped-actor"
|
|
implementation="com.biz.MyActor">
|
|
<akka:remote host="localhost" port="9990" managed-by="server"/>
|
|
</akka:untyped-actor>
|
|
|
|
<!-- register with custom service name -->
|
|
<akka:untyped-actor id="server-managed-remote-untyped-actor-custom-id"
|
|
implementation="com.biz.MyActor">
|
|
<akka:remote host="localhost" port="9990" service-name="my-service"/>
|
|
</akka:untyped-actor>
|
|
|
|
If the server specified by 'host' and 'port' does not exist it will not be registered.
|
|
|
|
Client side
|
|
***********
|
|
|
|
::
|
|
|
|
<!-- service-name could be custom name or class name -->
|
|
<akka:actor-for id="client-1" host="localhost" port="9990" service-name="my-service"/>
|
|
|
|
|
|
Configuration for a client managed remote Typed Actor
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. code-block:: xml
|
|
|
|
<akka:typed-actor id="remote-typed-actor"
|
|
interface="com.biz.MyPojo"
|
|
implementation="com.biz.MyPojoImpl"
|
|
timeout="2000">
|
|
<akka:remote host="localhost" port="9999" />
|
|
</akka:typed-actor>
|
|
|
|
Configuration for a server managed remote Typed Actor
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Sever side setup
|
|
****************
|
|
|
|
::
|
|
|
|
<akka:typed-actor id="server-managed-remote-typed-actor-custom-id"
|
|
interface="com.biz.IMyPojo"
|
|
implementation="com.biz.MyPojo"
|
|
timeout="2000">
|
|
<akka:remote host="localhost" port="9999" service-name="mypojo-service"/>
|
|
</akka:typed-actor>
|
|
|
|
Client side setup
|
|
*****************
|
|
|
|
::
|
|
|
|
<!-- always specify the interface for typed actor -->
|
|
<akka:actor-for id="typed-client"
|
|
interface="com.biz.MyPojo"
|
|
host="localhost"
|
|
port="9999"
|
|
service-name="mypojo-service"/>
|
|
|
|
Dispatchers
|
|
-----------
|
|
|
|
Configuration for a Typed Actor or Untyped Actor with a custom dispatcher
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
If you don't want to use the default dispatcher you can define your own dispatcher in the spring configuration. For more information on dispatchers have a look at Dispatchers documentation.
|
|
|
|
.. code-block:: xml
|
|
|
|
<akka:typed-actor id="remote-typed-actor"
|
|
interface="com.biz.MyPOJO"
|
|
implementation="com.biz.MyPOJOImpl"
|
|
timeout="2000">
|
|
<akka:dispatcher id="my-dispatcher" type="executor-based-event-driven" name="myDispatcher">
|
|
<akka:thread-pool queue="unbounded-linked-blocking-queue" capacity="100" />
|
|
</akka:dispatcher>
|
|
</akka:typed-actor>
|
|
|
|
<akka:untyped-actor id="untyped-actor-with-thread-based-dispatcher"
|
|
implementation="com.biz.MyActor">
|
|
<akka:dispatcher type="thread-based" name="threadBasedDispatcher"/>
|
|
</akka:untyped-actor>
|
|
|
|
If you want to or have to share the dispatcher between Actors you can define a dispatcher and reference it from the Typed Actor configuration:
|
|
|
|
.. code-block:: xml
|
|
|
|
<akka:dispatcher id="dispatcher-1"
|
|
type="executor-based-event-driven"
|
|
name="myDispatcher">
|
|
<akka:thread-pool queue="bounded-array-blocking-queue"
|
|
capacity="100"
|
|
fairness="true"
|
|
core-pool-size="1"
|
|
max-pool-size="20"
|
|
keep-alive="3000"
|
|
rejection-policy="caller-runs-policy"/>
|
|
</akka:dispatcher>
|
|
|
|
<akka:typed-actor id="typed-actor-with-dispatcher-ref"
|
|
interface="com.biz.MyPOJO"
|
|
implementation="com.biz.MyPOJOImpl"
|
|
timeout="1000">
|
|
<akka:dispatcher ref="dispatcher-1"/>
|
|
</akka:typed-actor>
|
|
|
|
The following dispatcher types are available in spring configuration:
|
|
|
|
* executor-based-event-driven
|
|
* executor-based-event-driven-work-stealing
|
|
* thread-based
|
|
|
|
The following queue types are configurable for dispatchers using thread pools:
|
|
|
|
* bounded-linked-blocking-queue
|
|
* unbounded-linked-blocking-queue
|
|
* synchronous-queue
|
|
* bounded-array-blocking-queue
|
|
|
|
If you have set up your IDE to be XSD-aware you can easily write your configuration through auto-completion.
|
|
|
|
Stopping Typed Actors and Untyped Actors
|
|
----------------------------------------
|
|
|
|
Actors with scope singleton are stopped when the application context is closed. Actors with scope prototype must be stopped by the application.
|
|
|
|
Supervisor Hierarchies
|
|
----------------------
|
|
|
|
The supervisor configuration in Spring follows the declarative configuration for the Java API. Have a look at Akka's approach to fault tolerance.
|
|
|
|
Example spring supervisor configuration
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. code-block:: xml
|
|
|
|
<beans>
|
|
<akka:supervision id="my-supervisor">
|
|
|
|
<akka:restart-strategy failover="AllForOne"
|
|
retries="3"
|
|
timerange="1000">
|
|
<akka:trap-exits>
|
|
<akka:trap-exit>java.io.IOException</akka:trap-exit>
|
|
</akka:trap-exits>
|
|
</akka:restart-strategy>
|
|
|
|
<akka:typed-actors>
|
|
<akka:typed-actor interface="com.biz.MyPOJO"
|
|
implementation="com.biz.MyPOJOImpl"
|
|
lifecycle="permanent"
|
|
timeout="1000"/>
|
|
<akka:typed-actor interface="com.biz.AnotherPOJO"
|
|
implementation="com.biz.AnotherPOJOImpl"
|
|
lifecycle="temporary"
|
|
timeout="1000"/>
|
|
<akka:typed-actor interface ="com.biz.FooBar"
|
|
implementation ="com.biz.FooBarImpl"
|
|
lifecycle="permanent"
|
|
transactional="true"
|
|
timeout="1000" />
|
|
</akka:typed-actors>
|
|
</akka:supervision>
|
|
|
|
<akka:supervision id="supervision-untyped-actors">
|
|
<akka:restart-strategy failover="AllForOne" retries="3" timerange="1000">
|
|
<akka:trap-exits>
|
|
<akka:trap-exit>java.io.IOException</akka:trap-exit>
|
|
<akka:trap-exit>java.lang.NullPointerException</akka:trap-exit>
|
|
</akka:trap-exits>
|
|
</akka:restart-strategy>
|
|
<akka:untyped-actors>
|
|
<akka:untyped-actor implementation="com.biz.PingActor"
|
|
lifecycle="permanent"/>
|
|
<akka:untyped-actor implementation="com.biz.PongActor"
|
|
lifecycle="permanent"/>
|
|
</akka:untyped-actors>
|
|
</akka:supervision>
|
|
|
|
</beans>
|
|
|
|
Get the TypedActorConfigurator from the Spring context
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. code-block:: java
|
|
|
|
TypedActorConfigurator myConfigurator = (TypedActorConfigurator) context.getBean("my-supervisor");
|
|
MyPojo myPojo = (MyPOJO) myConfigurator.getInstance(MyPojo.class);
|
|
|
|
Property Placeholders
|
|
---------------------
|
|
|
|
The Akka configuration can be made available as property placeholders by using a custom property placeholder configurer for Configgy:
|
|
|
|
::
|
|
|
|
<akka:property-placeholder location="akka.conf"/>
|
|
|
|
<akka:untyped-actor id="actor-1" implementation="com.biz.MyActor" timeout="${akka.actor.timeout}">
|
|
<akka:remote host="${akka.cluster.server.hostname}" port="${akka.cluster.server.port}"/>
|
|
</akka:untyped-actor>
|
|
|
|
Camel configuration
|
|
-------------------
|
|
|
|
For details refer to the :ref:`camel-module` documentation:
|
|
|
|
* CamelService configuration for :ref:`camel-spring-applications`
|
|
* Access to Typed Actors :ref:`camel-typed-actors-using-spring`
|