Page History

{panel:title=Apache Tuscany SCA Java Kernel Architecture Guide |borderStyle=solid|borderColor=#6699ff|titleBGColor=#D5EFFF|bgColor=#ffffff}
*This page is work in progress. Thanks for your contribution* :-)
* [Overview|#Overview]
** [Core|#Core Definition]
** [Extension|#Extension Definition]
** [Runtime|#Runtime Definition]
* [Internal High Level View|#Internal High Level View]
* [Bootstrap|#Bootstrap]
* [Metadata|#Metadata]
* [Contribution|#Contribution]
* [Binding Extension|#Binding Extension]
* [Component Implementation Extension|#Component Implementation Extension]
* [Data Binding Extension|#Data Binding Extension]
* [Spring Integration|#Spring Integration]
\**{Spring as component implementation\|#Spring as component implementation\]
\*\*[Spring as IOC container|#Spring as IOC container]

\\
 
{panel}{section}{section}

h3. {anchor:Overview} {color:#0099cc}Overview{color}

The SCA Java runtime is composed of core and extensions. The core is essentially a multi-VM wiring engine that connects components together using the principles of [Dependency Injection|http://en.wikipedia.org/wiki/Dependency_injection], or [Inversion of Control|http://en.wikipedia.org/wiki/Inversion_of_control].

h4. Core

The Core is designed to be simple and limited in its capabilities. It wires functional units together and provides SPIs that extensions can interact with. Capabilities such as service discovery, reliability, support for transport protocols, etc. are provided through extensions.

h4. Extension

Extensions enhance SCA runtime functionality. Extension types are not fixed and core is designed to be as flexible as possible by providing an open-ended extension model. However, there are a number of known extension types defined including:
* *Component implementation types*, e.g. Spring, Groovy, and JavaScript
* *Binding types*, e.g. Axis, CXF, AMQP, ActiveMQ, JXTA
* *DataBinding types*, e.g. JAXB, SDO, XmlBeans
* *Interface Binding types*, e.g. WSDL, Java

Details of how to implement an extension can be can be found in the [Extensions Guide| Java SCA Extension Guide].

h4. Runtime

The core is designed to be embedded in, or provisioned to, a number of different host environments. For example, the core may be provisioned to an OSGi container, a standalone runtime, a servlet engine, or J2EE application server. Runtime capabilities may vary based on the host environment.

{HTMLcomment:hidden}{children:sort=creation}{HTMLcomment}

h3. {anchor:Modules}{color:#0099cc}Module Structure{color}

\[Note: Do we want to link to [Kernel-Structure|Java SCA Modulization Design Discussions]\]?

As illustrated below, the Tuscany runtime consists of the following key modules/packages:
# SCA Spec API: The APIs defined by the SCA Java Client and Implementation Spec
# API: Tuscany APIs which extend the SCA spec APIs
# Core: The runtime implementation
# SPI: SPI and base classes to extend the Tuscany runtime. It defines all the contract that Core interacts with Container/Binding/Databinding extensions.
# Extensions:
## Container
## Binding
## Databinding
# Host API: The interface between hosting environments and the Tuscany runtime
# Host Platforms: The environments that host the Tuscany runtime

!tuscany_layers.jpg!

h3. {anchor:Internals High Level View}{color:#0099cc}Internals High Level View{color}

\[Note: Do we want to link to [Kernel-Structure|Java SCA Modulization Design Discussions]\]?

h3. {anchor:Kernel Bootstrap}{color:#0099cc}Bootsrap{color}

Bootstrap process is controlled by Host environment. The default process is implemented in DefaultBootstrapper.

!bootstrap.jpg!


h3. {anchor:Metadata}{color:#0099cc}Metadata{color}

* Component
** Basic unit of executable code
** Offer services and have references
* Service
** A contract for component clients consisting of 0..n operations
** Services may be local or remote
* Reference
** A dependency on a service
** Component references are wired to services by the runtime

h3. {anchor:Contribution}{color:#0099cc}Contribution{color}

h3. {anchor:Binding Extension}{color:#0099cc}Binding Extension{color}

h3. {anchor:Component Implementation Extension}{color:#0099cc}Component Implementation Extension{color}

h3. {anchor:Data Binding Extension}{color:#0099cc}Data Binding Extension{color}

h3. {anchor:Spring Integration}{color:#0099cc}Spring Integration{color}


h3. {anchor:Wiring}{color:#0099cc}Wiring{color}

To understand how wiring works, we need to detail how Components function in the system. Let's start with Atomic Components and then discuss Composite Components.

h4. Atomic Component

AtomicComponent is the most basic component form. It corresponds to the spec concept which offers services, has references and properties
* Implementation types e.g. Java, XSLT, etc.
* Are wired
* Have properties

Atomic Components have implementation instances. Instances are associated with a scope: e.g. request, conversation, composite. A SCDL entry is used to define a Component. [Haleh: Define scope]

Atomic components use a ScopeContainer to manage implementation instances:
* Composite, HTTP Session, Request, Stateless
* ScopeContainers track implementation instances by scope id and the AtomicComponent instance identity
* Instances are stored in an InstanceWrapper which is specific to the component implementation type (e.g. PojoInstanceWrapper.java)

h4. Component Wiring

Component references are connected to services through wires
* Two sides
** InboundWire - handles the source side of a wire, including policy
** OutboundWire - handles the target side of a wire, including policy
* The runtime connects inbound and outbound wires, performing optimizations if possible
** Inbound and outbound wires may be associated with different service contracts
** Different implementation types
** "Standard" wires contain invocation chains that have Interceptors that perform some form of mediation (e.g. policy)
** Other wire types exist that, for example, do not perform mediations

h4. Invocation Chains

A wire has an InvocationChain per service operation. An InvocationChain may have interceptors - "around-style" mediation. Component implementation instances access a wire through a WireInvocationHandler associated with a reference.
* WireInvocationHandlers may (or may not depending on the component type) be fronted by a proxy
* WireInvocationHandlers dispatch an invocation to the correct chain
A wire has a TargetInvoker that is created from the target side AtomicComponent or Reference and is stored on the source wire invocation handler. The TargetInvoker is resposnible for dispatching the request to the target instance when the message hits the end of the target invocation chain.

h4. Invocation Overview

* An invocation is dispatched to the WireInvocationHandler
* The WireInvocationHandler looks up the correct InvocationChain
* It then creates a message, sets the payload, sets the TargetInvoker, and passes the message down the chain
* When the message reaches the end of the chain, the TargetInvoker is called, which in turn is responsible for dispatching to the target
* Having the TargetInvoker stored on the outbound side allows it to cache the target instance when the wire source has a scope of equal or lesser value than the target (e.g. request-->composite

The runtime provides components with InboundWires and OutboundWires. InvocationChains are held in component wires and are therefore stateless which allows for dynamic behavior such as introduction of new interceptors or re-wiring.

h3. {anchor:Kernel Bootstrap}{color:#0099cc}Bootsrap{color}

Bootstrap process is controlled by Host environment. The default process is implemented in DefaultBootstrapper.

!bootstrap.jpg!

h3. {anchor:Kernel Composite Hierarchy}{color:#0099cc}Composite Hierarchy{color}

!tuscany_composite_hierarchy.jpg|thumbnail!

h3. The sequence diagram for the bootstrapping

!bootstrap_seq.jpg|thumbnail!

h3. {anchor:Java SCA Deployment}{color:#0099cc}Deployment{color}

The runtime processes service assemblies serialized using SCA XML vocabulary, SCDL, but can take other forms.
* The load phase processes SCDL and creates an in-memory model
* The build phase evaluates the model and produces corresponding runtime artifacts (e.g. components, services, references)
* The connect phase wires references to services

h3. {anchor:Java SCA Loaders}{color:#0099cc}Loader{color}

SCA service assemblies are deployed to the SCA domain in the format of SCDL files. Tuscany runtime uses loader to load the SCDLs into model objects which are a set of java beans to hold the metadata.

There are two types of loaders:
* StAXElementLoader: Load the XML element from the StAX events
* ComponentTypeLoader: Load the Component Type for an implementation either by introspection or paring a side file

h3. {anchor:Java SCA model}{color:#0099cc}Model{color}


!assembly.jpg!


h3. Loading Component Type

Loads the component type definition for a specific implementation
* How it does this is implementation-specific
* May load XML sidefile (location set by implementation)
* May introspect an implementation artifact (e.g. Java annotations)
* ... or anything else

Composite ComponentType Loader
* Load SCDL from supplied URL
* Extract and load SCDL from composite package

POJO ComponentType Loader
* Introspect Java annotations
* Uses a pluggable "annotation processing" framework to introspect Java classes

h3. Class diagram for the runtime artifacts

!runtime-model.jpg!