8/3/2019 Axia Actor Dev Guide
1/54
Axia Actor Development
March 2010Lars-Goran Forsberg
8/3/2019 Axia Actor Dev Guide
2/54
Topics
Concepts
Actor application artifacts
Start programming actors
Advanced actor programming
Deployment descriptor reference
API reference
8/3/2019 Axia Actor Dev Guide
3/54
ConceptsActor Applications
Actor applications are composed of one or moreActors that run in an Actor Container managing theirruntime environment.
Specifies an actor deployment descriptor that haveinstructions to the Actor Container to configure,
instantiate and start initial Actor instances.
Axia Applications Domain Node
Actor Container
App A App B
Actor5 Actor6Actor4
Axia Applications Domain Node
Actor Container
App A App B
Actor1 Actor2Actor3
Event BrokerEvent Broker
Event Broker
8/3/2019 Axia Actor Dev Guide
4/54
ConceptsActors
Group of objects centered around aJava object implementing the Actorinterface.
Instantiated by the Actor Container asinstructed by a deployment descriptor
or programmatic requests for creationby other Actors.
Actors have a lifecycle, managed viathe Actor interface by the container.
Each Actor runs in one JVM at any
specific time. An application willhowever likely have Actors running inmultiple JVMs.
Actors are given a thread safetyguarantee by the container.
Actor Container
App A
Actor interface extender class
Other actor class
8/3/2019 Axia Actor Dev Guide
5/54
ConceptsActors
No object references should be sharedbetween Actors.
Communication between Actors is doneexclusively using message passing.
Java method calls shall only be used withinthe object group of the Actor.
Runs in a private isolated environment,with their own private copy of container andplatform services including state storage.
An application may use anything from oneto thousands of Actors. To scale throughput
however, there must be more than a few. Design patterns examples:
Predefined number of Worker Actors created atstart of application.
Actor per session, created on demand by asmaller set of Factory Actors. Session Actor shutdown when it has run to completion.
App A
Allowed Java method callDisallowed Java method callMessage (always allowed)
8/3/2019 Axia Actor Dev Guide
6/54
ConceptsActor Context
An Actor Context is a contextholding Actor specific servicereferences. Used by Actors to access the container
and other platform services.
Given to the Actor instance wheninstantiated and started by thecontainer.
Actor Contexts are private to the owningActor instance, to maintain Actorisolation and thread safety guarantee.
All communication with outside world
shall be done using services retrievedfrom the Actors own Actor Contextinstance. This includes all types of eventregistrations, see coming slides fordetails.
Actor Container
App A
Actor1 Actor3
Actor
Context
Actor
Context
Svc
Svc
Svc
Svc
Svc
Svc
8/3/2019 Axia Actor Dev Guide
7/54
ConceptsEvents & Event Handler
An Event is a message sent betweencomponents Exists in an extensive type hierarchy, with the main
groups being Application, Protocol and TimerEvents.
Events are Serializable as they may be sent to aremote JVM.
An Event shall be immutable once published. Defines the communication contract of different Axia
components, such as Actors and Protocol Adapters.
An Event Handler is an interfaceimplemented by an Actor to receive
Events. Actor Event Handlers are included in the Actorsthread safety guarantee.
Event Handlers are the main entry point to executionof Actor code.
Event Handlers are used with Event Registrations,Scheduled Timers or Event Channels explained infollowing slides.
Actor Container
App A
Actor1
Event Handler
8/3/2019 Axia Actor Dev Guide
8/54
ConceptsEvent Registration
Actors can register Event Handlerswith the Event Broker to receiveEvents.
A registration yields a relatedRegistration Receipt used e.g. tounregister and clean up when doneprocessing events.
The EventHandlers are connected totheir related Actor instance by the ActorContext used when registered.
The registration is made for acombination of Event type andEvent Criteria to match a subset of
events of the specified type. Event type specifies an Event interface
to match, e.g. Inbound or ApplicationEvent interfaces.
Event Criteria specifies event attributevalues to match.
Axia Applications Domain Node
Actor Container
App A App B
Actor1 Actor2Actor3
Event Broker
Event Handler
Event Registration
8/3/2019 Axia Actor Dev Guide
9/54
ConceptsApplication Events
Actors can use Application Events to communicatewith other Actors. Actors can register Event Handlers for specific Event Criterias
which will match Application Events. Application Events are published with attributes to match such
Criterias. This class of Event registration allows any application component
to publish to it, provided it knows the attributes to use. Such aregistration enables an Actor to receive events from Actors orother application components that dont have a common ancestorof the receiving Actor, e.g. if running in a separate bundle.
Axia Applications Domain Node
Actor Container
App A App B
Actor5 Actor6Actor4
Axia Applications Domain Node
Actor Container
App A App B
Actor1 Actor2Actor3
Event BrokerEvent Broker Event Broker
Application Event Handler Event Registration Event
8/3/2019 Axia Actor Dev Guide
10/54
Event BrokerEvent Broker
ConceptsProtocol Events
Actors communicate with theoutside world (network) usingProtocol Events
The Actor can receive InboundProtocol Events by registering EventHandlers for Inbound Events andspecific Event Criterias.
The Actor can publish OutboundProtocol Events to Protocol Adaptersthrough the Event Broker.
Any communication with non Axiaentities (network) should alwaysbe done using Protocol Events to
and from a Prococol Adapter. Protocol Adapters define a
communication contract based onsubclasses of Inbound and OutboundEvents.
Examples of protocols are e.g. SIP,HTTP, Diameter, etc.
Axia ApplicationsDomain Node
Actor Container
App A
Actor5
Axia ProtocolAdaptersDomain Node
Protocol AdapterContainer
Event Broker
Outbound Protocol Event Handler
PA PA
Network
Inbound Protocol Event Handler
Event Registration Event
8/3/2019 Axia Actor Dev Guide
11/54
ConceptsTimers and Timer Events
Actors may schedule Timers Timers are executed as TimerEvents,
holding a correlator specified whenscheduled.
An Actor Event Handler is alwaysprovided by the scheduling Actor, and
this Event Handler will receive theTimerEvents.
Actor Timers shall always bescheduled using theEventBroker
Never should an Actor schedule Timersusing java.util.Timer orcommonj.TimerManager or similar, asthese arent integrated with the Actorthreading model and breaks the threadsafety guarantee.
Axia ApplicationsDomain Node
Actor Container
App A
Actor1
Event Broker
Timer Event Handler
Timer Schedule
8/3/2019 Axia Actor Dev Guide
12/54
ConceptsEvent Channel
Actors can use Event Channels to communicate with otherActors.
Typed many to one event communication channel that always refer to aspecific Actor instance.
Actors use Event Channels to expose a typed communication contract toother Actors by subscribing an Event Handler with it.
The owning Actor must share the channel reference to enable Events to bepublished over the channel. This means that the subscriber must have away to give the channel reference to publishers which may not always bepossible, in which case a plain Application Event registration is the solution.
Axia Applications Domain Node
Actor Container
App A App B
Actor5 Actor6Actor4
Axia Applications Domain Node
Actor Container
App A App B
Actor1 Actor2Actor3
Event BrokerEvent Broker Event Broker
Event Channel Handler Event Channel Reference Event
8/3/2019 Axia Actor Dev Guide
13/54
ConceptsActor Concurrency & Thread model
Actors are provided a thread safetyguarantee Only one event or lifecycle transition at a
time is processed by an Actor, across allregistrations and types of registrations,guaranteeing at most one single thread at a
time execute Actor code. Multiple events sent concurrently to an
Actor, even if arriving to different EventHandlers will be queued and processedserially.
Events arriving to different Actors mayhowever be processed in parallel.
Since the container provide thread safetyfor the Actor, it does not need to and shouldavoid using synchronization since this is anadded cost even when there is no lockcontention.
ActorContainer
App A
Actor2
Event Broker
Actor1
Event
Inbound Protocol Event Handler
8/3/2019 Axia Actor Dev Guide
14/54
ConceptsActor Lifecycle
Actor Runtime State The Actor Container keeps track of the runtime state of each live Actor. This includes aLifecycle State, Registration State, etc.
An Actor is always created by being transitioned from not existing into the RUNNINGstate.
When an Actor is shutdown, it is always transitioned from the RUNNING state to beingremoved from the runtime environment.
Each transition is done by the container invoking a method on the Actor class.
Actor creation An Actor is created by the Actor Container, either based on the Actor deploymentdescriptor listing it as a bootstrap actor, or a programmatic request from another Actor.
State transition sequence: New -> Start -> Resume -> RUNNING.
Actor shutdown Actors are shut down on its own request or because of an exception. If the Actor is not being shut down by an error (forced shutdown), it has a choice to
defer suspend to a later point, e.g. if its still awaiting additional events in a sessionbefore being able to perform a clean stop.
State transition sequence: RUNNING -> Suspend -> [DeferredSuspend ->]* -> Stop.
Actor migration An Actor may optionally migrate between JVMs in a cluster while it is in RUNNING
state. See the High Availability & Scalability later in the presentation for details. State transition sequence: [RUNNING -> Migrate -> . -> New -> Revive -> RUNNING].
* More details in notes
8/3/2019 Axia Actor Dev Guide
15/54
ConceptsActor Registration State
The Actor Container maintains arecord of registrations done bythe Actor Used by the container to clean up after
the Actor when its shutdown and
misbehaves not unregistering itshandlers or has a bug that prevents itfrom doing so.
Also used when an Actor is migrated,and given as parameter to the revivelifecycle method when an actor is
moved to a different JVM in the domain. When the Actor is revived, it must
associate a new event handler witheach registration found in theRegistration State.
Actor Container
App A
Actor1 Actor2
Runtime State (incl. Registration State)
8/3/2019 Axia Actor Dev Guide
16/54
ConceptsActor Storage
All state should be stored in an ActorStore. Actors may migrate or fail over to another JVM at any time.
Therefore all data required for the Actor to function must bestored in an ActorStore so it exists after the Actor is revived.
The ActorStore interface is based on the java.util.Map interfacewith some extensions.
Each Actor instance has its own views of the ActorStorecontent. Entries are only visible to the Actor instance that wrotethe data.
ActorStore data is collocated in the same JVM as the Actorinstance. This means that no network hops are required forreads from the Actor Store and at most one hop for writes(backup).
ActorStores are backed up to another JVM, and will alwaysmove between JVMs together with its owning Actor instance. All ActorStore data must be Serializable to support being backed
up.
8/3/2019 Axia Actor Dev Guide
17/54
ConceptsActor Storage
Axia Node
Actor Container
App AActor2
Axia Node
Actor Container
App AActor1
Event BrokerEvent Broker Event Broker
Backup
Storage
Storage
Backup
Storage
StorageActor2
Actor2
Actor1
Actor1
8/3/2019 Axia Actor Dev Guide
18/54
ConceptsActor Transactions
Processing of each event or lifecycle transition runs within aunique transaction boundary.
The transaction boundary spans Actor method calls. The transaction commits when Actor method returns and rolls back if the
method throws an exception.
Each action taken is buffered and committed at the end of the
transaction. Actions included in transaction: Published application/channel/outbound events. Register/unregister event handlers, including open/closing channels. Schedule/cancel timer(s). ActorStore clear/put/putAll/remove. Requests to create/shutdown actor(s).
An exception thrown from the Actor code causes a transactionrollback, and may optionally force shutdown of Actor (specifiedin actor settings of actor.xml).
* More details in notes
8/3/2019 Axia Actor Dev Guide
19/54
ConceptsActor Transactions
Actor Container Actor1 Actor2Event Broker ActorStore(A)
onEvent()
createActor(Actor2)
Transaction
commit()
ActorStore(A).put(X, Y)
EventBroker.publish(OutboundEvent)
onEvent()
return
createActor(Actor2)
ActorStore(A).put(X, Y)
publish(OutboundEvent)
new
8/3/2019 Axia Actor Dev Guide
20/54
ConceptsActor Scalability & High Availability
An Actor instance runs in the domain When an Actor is created, it will be started in the domain, meaning
it may end up running on any JVM in the domain.
An Actor is always running on one specific JVM at any time.
All events are delivered to the Actor in the JVM where it is running.
Redundancy The Actor state and its ActorStore data is backed up to one other
JVM to provide redundancy and failover support.
Migration/Failover
While an Actor is running, it may move within the domain due torebalancing or fail-over.
When Actor moves, its ActorStore data always move with it. Itsmember variables do not.
* More details in notes
8/3/2019 Axia Actor Dev Guide
21/54
ConceptsActor Scalability & High Availability
Axia Node
Actor Container
App A
Axia Node
Actor Container
App AActor1
Event BrokerEvent Broker Event Broker
Backup
Storage
Storage
Backup
Storage
Storage
Actor2
Actor1
Actor1
Actor2
Actor2
Actor1
8/3/2019 Axia Actor Dev Guide
22/54
Topics
Concepts
Actor application artifacts
Start programming actors
Advanced actor programming
Deployment descriptor reference
API reference
8/3/2019 Axia Actor Dev Guide
23/54
Actor application artifactsApplication bundle
OSGi bundle content OSGi bundle instructions in manifest (META-
INF/MANIFEST.MF).
Actor deployment descriptor (META-INF/config/actor.xml)that instructs Axia how to treat the applications actors.
Actor classes.
Optional configuration XSD, XML and classes.
Bundle deployment Bundle is deployed and started in application or basic
domain. Bundle start level should be greater than actor container
bundle start levels and lower than RUNNING start level.Default recommendation is >= 200 and
8/3/2019 Axia Actor Dev Guide
24/54
Actor application artifactsActor deployment descriptor
Actor deployment descriptor (actor.xml) META-INF/config/actor.xml.
Follows Actor.xsd found in oracle.axia.actor.utils.extenderbundle (META-INF/config/Actor.xsd).
Instructs Axia platform to configure the applications Actorenvironment.
Optionally configurable using administration console.
Bootstrap actor entries Points to an Actor class to instantiate, start and resume
when application is started in the domain. Optionally specifies constructor arguments.
8/3/2019 Axia Actor Dev Guide
25/54
Actor application artifactsActor classes
The application is responsible for implementing theActor logic. The following interfaces are theinterfaces implemented by most applications. oracle.axia.api.actor.Actor
Receives lifecycle related calls.
Receives injected service and context references.
oracle.axia.api.eventbroker.EventHandler
Registered with eventbroker or an event channel in order toreceive inbound or application events from external entities(protocol adapters, other actors, scheduled timers, etc).
oracle.axia.api.event.ApplicationEvent (optional)
Application events published to other Actor EventHandlers canbe implemented by the application.
8/3/2019 Axia Actor Dev Guide
26/54
Topics
Concepts
Actor application artifacts
Start programming actors
Advanced actor programming
Deployment descriptor reference
API reference
8/3/2019 Axia Actor Dev Guide
27/54
Start programming actorsConfiguring deployment descriptor
Implement the Actor interface and add class asbootstrap Actor in actor.xml. Tells actor container to automatically start listed Actor. Bootstrap Actor in turn usually creates other Actors and registers
event handlers programmatically. Constructor arguments can optionally be specified, and must match
the Actor class constructor signature.
Add event factory in actor.xml if the applicationconsumes Inbound Events. Tells the actor container to register event factory with event broker,
specifying load inbound event classes supported by the eventfactory. See deployment descriptor reference in a later slide fordetails.
Example: Actor class
public class MyHttpActor implements Actor { }
Actor.xml
8/3/2019 Axia Actor Dev Guide
28/54
Start programming actorsCreating child actors
Create Actors programmatically Once one or more Actors exist, they can dynamically create
other Actors programmatically using ActorFactory retrievedfrom the ActorContext.
Create actor method takes Actor class, followed byconstructor arguments which must match constructorsignature.
Example:public class SampleActor implements Actor {public void start(ActorContext context) {context.getActorFactory().createActor(SampleChildActor.class,ActorInstanceName);
}
}public class SampleChildActor implements Actor {private final String name;public SampleChildActor(String name) {this.name = name;
}
}
8/3/2019 Axia Actor Dev Guide
29/54
Start programming actorsUsing event channels
Event Channels are opened by an Actor and given to otherActors so they can publish to it
Opening the channel returns an event channel session object which holds aunique channel handle.
The channel session object is used to close the channel when done using it. The channel handle is passed to one or more other Actors as constructor
arguments or as content in Events.
The channel handle is used to publish events to the single Event Handlerassociated with the Event Channel session.
Example:public class SampleActor implements Actor {private EventChannelSession session;public void start(ActorContext context) {session= context.getEventChannelFactory().open(
StartedEvent.class, new EventChannelHandler());context.getActorFactory().createActor(SampleChildActor.class,
ActorInstanceName, session.getChannel());
}public void stop(ActorContext context) {session.close();
}
}
* More details in notes
8/3/2019 Axia Actor Dev Guide
30/54
Start programming actorsScheduling timers
Timers are scheduled usingActorEventBroker found on ActorContext Can be scheduled as simple delay timer or periodic timer. The Actor specifies a correlator when scheduling the timer.
The correlator is then passed back in the TimerEvent.
A receipt is returned when timer is scheduled, and can beused to cancel timer.
Example:public class SampleActor implements Actor {private ActorTimerReceipt timerReceipt;public void start(ActorContext context) {timerReceipt = context.getActorEventBroker().schedule(new TimerHandler(), new Byte(1), 10000);
}public void stop(ActorContext context) {timerReceipt.cancel();
}}
8/3/2019 Axia Actor Dev Guide
31/54
Start programming actorsRegistering for inbound events
Inbound Event Handlers are registered usingActorEventBroker found on ActorContext Registered using an event broker criteria to match events. Criteria is created using CriteriaFactory. A receipt is returned when handler is registered, and is used
to unregister event handler when done processing events. Usually requires event factory to be registered in actor.xml.
Example:public class SampleActor implements Actor {private ActorContext context;private ActorRegistrationReceipt inboundReceipt;public void resume() {
Criteria criteria = CriteriaFactory.createCriteria(HttpRequestInboundEvent.ATTR_REQUEST_URI, "/sample);inboundReceipt = context.getActorEventBroker().registerInboundEvent(HttpRequestInboundEvent.class,criteria, new HttpInboundEventHandler());
}public void suspend(SuspendRequest suspendRequest) {inboundReceipt.unregister();
}}
* More details in notes
8/3/2019 Axia Actor Dev Guide
32/54
Start programming actorsReceiving and publishing events
Events are received using an EventHandler Event Handler is registered using the Event Broker or by
opening an Event Channel.
Events are serialized and may require external class loading,achieved either by importing classes or registering an
EventFactory through actor.xml. Events may optionally implement DispatchableEvent to
support EventProcessor helper interface.
Publishing events
Events are published using the Event Broker found on theActor Context or an Event Channel handle received fromanother Actor.
8/3/2019 Axia Actor Dev Guide
33/54
Start programming actorsReceiving and publishing events
Publishing outbound events Outbound Events usually need to be created using a Protocol
Event Factory in order to for example automatically connect them toa session or request/response pair.
Protocol Event Factories are injected to Actor by having Actorimplement the ProtocolConsumer interface, and returning theProtocolBinding classes implementing the interface associated withthe protocols.
Protocol Event Factories have methods for creating outboundevents, such as response events, based on previous request eventand/or attributes found in previous events.
Example:public class SampleActor implements Actor, ProtocolConsumer {
private HttpOutboundEventFactory factory;public ProtocolBinding [] { new HttpBinding() };
}private final class HttpBinding implements HttpProtocolBinding {public void onBind(HttpOutboundEventFactory factory) {
this.factory = factory;}
}}
* More details in notes
8/3/2019 Axia Actor Dev Guide
34/54
Start programming actorsStoring actor state
State kept between different events must bestored in ActorStores Stores are retrieved using ActorStoreService found on
ActorContext using a name or key/value class pair.
ActorStore content is collocated with Actor and movestogether with Actor if migrated/failed over to other JVM, whilemember variables do not.
Objects stored in ActorStores must be Serializable.
Events needed in a later event transaction should not bestored in its original event form, but in its EventState form.
The EventState representation of the event is retrieved usingthe getStoredState method of the StoreStateProviderinterface implemented by the event class.
* More details in notes
8/3/2019 Axia Actor Dev Guide
35/54
Start programming actorsProgramming migratable actors
To support running in a cluster, an Actor mustsupport migration between JVMs All required state must be stored in and read from ActorStores,
since this data is backed up in the cluster and migrate/fail overtogether with its owning Actor.
The Actor must implement the revive method, and with thereceipts/sessions setHandler method associate new EventHandlerswith all receipts and sessions in the RegistrationState. This isrequired to activate the event registration on the new host JVM.
The Actor can use a correlator when registering that in revive isretrievable from the receipt/session to determine which handler touse.
If the Actor migrates from a functional JVM, the Actor is given a callto the migrate method. In most cases, this method shouldnt needto contain any logic, since the Actor must function with only a revivecall which will happen when a JVM crashes.
* More details in notes
8/3/2019 Axia Actor Dev Guide
36/54
Start programming actorsConfiguration service
Actors use ActorConfigurationService Actor applications can use the Axia Configuration Service to
maintain configuration.
Actors shall use the ActorConfigurationService to accessconfiguration to maintain the thread safety guarantee.
ActorConfigurationService is retrieved from theActorContext.
If an Actor has a configuration listener or validator, it must re-register listener/validator in the revive method.
See Configuration Service guide for more details on
configuration structure, etc.
8/3/2019 Axia Actor Dev Guide
37/54
Start programming actorsService MBeans in Actors
Actors use ActorManagementService Actor applications can use the Axia Management Service to
register Service MBeans.
Actors shall use the ActorManagementService to registerMBeans to maintain the thread safety guarantee.
ActorManagementService is retrieved from the ActorContext. If an Actor migrates or fails over, it must re-register its
MBean in the revive method.
8/3/2019 Axia Actor Dev Guide
38/54
Topics
Concepts
Actor application artifacts
Start programming actors
Advanced actor programming
Deployment descriptor reference
API reference
8/3/2019 Axia Actor Dev Guide
39/54
Advanced actor programmingPerformance considerations
Keep Serializable content as small as possible andimplement Externalizable rather than Serializable ActorStore content Event content Actor constructor arguments
Synchronization Do not use synchronized blocks in Actor code. Actor thread safety
is provided by the Actor Container and synchronization causesoverhead even when there is no contention.
Partitioned actor registration (HashFunction)
Each actor is single threaded. If the application cant be naturallypartitioned using event registrations, there is a way to register aHashFunction for a certain event type that populates events with ahash value that can be used to load balance events over multipleactors that register for the same criteria but different hash attributevalues.
8/3/2019 Axia Actor Dev Guide
40/54
Advanced actor programmingPerformance considerations
Event Channel Ports Child actors can be instructed to open an event channel by
passing an EventChannelPort in the constructor. This savesthe child actor an event that otherwise would be required topass the EventChannel reference back to the parent.
Linking Actors For Actor pairs/groups that have frequent communication
with each other, there could be a significant overheadcaused by network hops for published events. This can beavoided by linking the actors to hint to the Axia platform thatevents between these actors should be optimized, e.g. bycollocating the linked actors.
8/3/2019 Axia Actor Dev Guide
41/54
Advanced actor programmingUsing event channel ports
Event Channel Ports are created by an Actor and given to otherActors to subscribe to Forwarding a channel port as a constructor argument will cause a channel
handle to be returned from the create method. The channel port is used to open the event channel in the start or resume
method. The channel handle returned from the create method is used to publish
events to the new Actor.
Example:public class SampleActor implements Actor {private EventChannelSession session;public void start(ActorContext context) {session= context.getEventChannelFactory().open(
StartedEvent.class, new EventChannelHandler());EventChannelPort port = context.getEventChannelFactory().getPort(MyEvent.class)CreateActorResult result = context.getActorFactory().createActor(
SampleChildActor.class, ActorInstanceName, port,session.getChannel());
EventChannel channel = result. getEventChannels().get(port);
}public void stop(ActorContext context) {session.close();
}
}
* More details in notes
8/3/2019 Axia Actor Dev Guide
42/54
Advanced actor programmingPartitioned actor registrations
Avoiding single Actor bottleneck withHashFunction partitioned Actors Achieved by registering a HashFunction for the event class,
and duplicating the actor, but adding hash attribute to theirregistrations to avoid duplicate registration exceptions.
HashFunction should go in a separate bundle with Activatorregistering the HashFunction with the Event Broker. TheHashFunction bundle is deployed on all domains (bothprotocol adapter and application domains), as hash functionis applied on publisher side.
The Actor registrations must cover all possible valuesreturned by HashFunction or events may end up beingdropped.
* More details in notes
8/3/2019 Axia Actor Dev Guide
43/54
Advanced actor programmingCustom actor settings
Default settings Default exception handling is rollback for bootstrap actors and
shutdown for other actors.
Default event and timer queue sizes are 100 for bootstrap actorsand 10 for other actors.
Changing settings Settings can be specified per Actor class. This is achieved by
adding an actorSettings entry to actor.xml with the class namespecified in the implementationClass attribute.
Example:
8/3/2019 Axia Actor Dev Guide
44/54
Advanced actor programmingLinked actors
If two Actors have a chatty relationship,they can be linked to each other Hints to the platform that it should attempt optimizing
communication between the linked Actors, e.g. collocationon the same server to avoid network hops for Events.
Linked at create time, by using createLinkedActor method,link is always done between parent and child Actors.
Example:public class ParentActor implements Actor {public void start(ActorContext context) {context.getActorFactory().createLinkedActor(ChildActor.class);
}
}
8/3/2019 Axia Actor Dev Guide
45/54
Advanced actor programmingUsing instance factories
Instance factories can be used to keepseparation between interfaces andimplementation in Actor applications. Actors are created using the class which requires compile
time dependencies on implementation classes. Instance
factories provide a way for Actors to instantiate classeswithout requiring compile time or import dependencies onthe implementation class, that could be in a separate bundle.
Instance factories are registered by the application bundleowning the implementation class in its actor.xml. Seeexample XML in deployment descriptor reference section.
The implementation class must have a no-argumentconstructor. The consuming application bundle creates instances by
specifying the interface class to the InstanceFactoryRegistryfound in ActorFactory.
8/3/2019 Axia Actor Dev Guide
46/54
Shared
State
Advanced actor programmingShared actor state
Sharing state between Actors ActorStores are isolated to an Actor.
For Actors that need to share state between Actors, it isrecommended to keep the shared state in a separate Actor,e.g. a common parent Actor, and accessing this state by
publishing/receiving events to/from the shared Actorcontaining state information.
ParentActor
ChildActor-1 ChildActor-2 ChildActor-n
8/3/2019 Axia Actor Dev Guide
47/54
Advanced actor programmingProtocol Routers
Protocol routing actors When an Actor acts as a router or dispatching Actor for
inbound events, e.g. for receiving SIP invite and delegatingsession handling to another Actor, it should register aProtocolRouter rather than a normal inbound Event Handler.Under no circumstance shall an event be re-published once
received by an EventHandler. The ProtocolRouter is responsible for returning an
EventChannel pointing to the Actor that shall handle thesession.
The router may return an existing EventChannel or createnew Actor with an EventChannelPort to handle the event in a
new Actor. In the case of Actors consuming the SIP protocol, it is
especially important to use a ProtocolRouter, to avoidunnecessarily creating session state and timers in the routerActor.
* More details in notes
8/3/2019 Axia Actor Dev Guide
48/54
Topics
Concepts
Actor application artifacts
Actor runtime properties
Start programming actors
Advanced actor programming
Deployment descriptor reference
API reference
8/3/2019 Axia Actor Dev Guide
49/54
Deployment descriptor referenceBootstrap actor
Bootstrap Actor element content implementationClass Actor class to instantiate. Argument One or more constructor java.lang type
arguments. Both the number of arguments and specifiedtype must match the Actor class constructor signature.
Example XML:
Arg01
Example class:public class SampleBootActor implements Actor {public SampleBootActor(String arg0, Integer arg1) {
}
}
D l d i f
8/3/2019 Axia Actor Dev Guide
50/54
Deployment descriptor referenceEvent factory
Event Factory element content interfaceClass EventFactory service interface.
Supported EventFactory interfaces can be found by listinginterfaces extendingoracle.axia.api.eventbroker.EventFactory.
Example XML:
D l d i f
8/3/2019 Axia Actor Dev Guide
51/54
Deployment descriptor referenceActor settings
Actor settings element content implementationClass The Actor class. errorHandling ROLLBACK or SHUTDOWN. Specifies how to
handle exceptions thrown by Actor event transaction. DefaultROLLBACK for bootstrap Actors, and SHUTDOWN for otherActors.
maxEventCapacity Max number of pending events before eventsare rejected. Default 100 for bootstrap Actors, and 10 for otherActors.
maxTimerCapacity Max number of pending timers before timerevents are rejected. Default 100 for bootstrap Actors, and 10 forother Actors.
Example XML:
8/3/2019 Axia Actor Dev Guide
52/54
Deployment descriptor referenceInstance factory
Instance Factory element content interfaceClass The interface class. Used when creating
instances.
implementationClass The implementation classinstantiated when consumer requests a new instance of the
implemented interface.
Example XML:
T i
8/3/2019 Axia Actor Dev Guide
53/54
Topics
Concepts
Actor application artifacts
Start programming actors
Advanced actor programming
Deployment descriptor reference
API reference
API f
8/3/2019 Axia Actor Dev Guide
54/54
API reference
Actor API reference is described usingJavadoc.
Main packages used in applications are: oracle.axia.api.actor
oracle.axia.api.eventbroker
oracle.axia.api.event