Introduction

This document provides a high-level overview of the Tuscany Java Runtime architecture.

Project Structure

The runtime is organized into separate projects to facilitate a clean separation between functional units as well as reuse across a variety of host environments. The main functional units are:

o.a.t.runtime.common

Basic utility code used throughout the runtime such as the logging monitor framework, io, discovery, and resource loading

o.a.t.runtime.model

Contains interfaces defining a representation of SCA SCDL used by the runtime - the logical model - to create runtime artifacts and an SDO implementation that generates it from XML. This project also contains XSD type definitions used to describe various runtime artifacts such as services.

o.a.t.runtime.core

The core runtime code. Contains configuration builders used to generate runtime artifacts - the runtime model - from the logical model, messaging and invocation infrastructure, the runtime artifacts (o.a.t.runtime.core.context), injection container, and proxy framework.

o.a.t.runtime.container.java

Code that implements functionality specific to the Java SCA Client and Implementation model, logical model extensions, builders, handlers and general POJO management.

The following is a pictorial representation of the project dependencies:
architecture dependencies

Basic Concepts

Runtime

A running instance of an SCA container

Host Platform

An environment which the SCA runtime is deployed to, such as (but not limited to) Tomcat or a J2EE application server.

Runtime Artifacts

The core runtime includes the following key functional units:

The Logical Configuration Model
The Runtime Configuration Model
Instance Contexts
Messaging and Invocation Handling

The Logical Configuration Model

o.a.t.model, o.a.t.runtime.container.java.assembly

The LCM is an in-memory representation of a set of one or more configuration sources and is designed for easy manipulation of configuration information. The LCM is derived from SCA SCDL and analogous to an Abstract Syntax Tree. Tuscany currently supports generating the LCM from XML using SDO but other data binding technologies may be substituted. The logical model may be represented as:

The Runtime Configuration Model

o.a.t.model,o.a.t.runtime.core.builder, o.a.t.runtime.container.java.builder, o.a.t.runtime.container.java.injection

The RCM is a set of in-memory artifacts used by the runtime to “execute” SCA code. The RCM is derived from the logical model but does not have to be “round-trippable.” Rather, it is designed and optimized for runtime processing work. The RCM is analogous to compiled output.

Instance Context

o.a.t.runtime.core.context, o.a.t.runtime.container.java.context

The RCM produces instance contexts, which are responsible for managing runtime resources such as component implementation instances. The following is a simplified instance context inheritance hierarchy:

TuscanyModuleComponentContext implementations are responsible for providing module component functionality as specified by SCA, including assembly and management of SCA application component lifecycle. SimpleComponentContext implementations are responsible for managing component implementation instances for a particular type. For example, JavaComponentContext manages SCA POJO implementation types. Other SimpleComponentContext implementations may exist for other component types such as BPEL or XSLT. As detailed below, a TuscanyModuleComponentContextImpl (the implementation which supports SCA POJOs) indirectly contains SimpleComponentContexts.

Scope Containers

o.a.t.runtime.core.context, o.a.t.runtime.core.context.scope

TuscanyModuleComponentContextImpl contains scope containers which are responsible for managing component instance visibility and lifecycle. That is, they implement scoping functionality defined by SCA. Generally, scope containers have collections of instance contexts associated with a scope key (an exception is the stateless scope). Instance contexts in turn contain one or more component implementation instances (the common case is a 1:1 relation). Concretely, an HTTP session scope container would have a collection of instance contexts associated with session keys. Therefore, for every session-scoped component, an instance context would exist (assuming the component was accessed). If the implementation type was SCA Java, the instance context would contain the actual POJO component implementation instance.
scope containers
This relationship between the LCM, instance contexts, and scopes is depicted in the following diagram:

Messaging and Invocation Handling

o.a.t.runtime.core.invocation, o.a.t.runtime.core.message, o.a.t.runtime.core.pipeline, o.a.t.runtime.container.java.handler, o.a.t.runtime.container.java.injection

Complete

The Recursive Runtime Design

Assembly in the Large

Assembly in the Small

Dispatching

Creating a new implementation instance

The following sequence diagram shows how new component implementation instances are created and configured (injected) with property and reference values using the default TuscanyModuleComponentContextImpl:

Module event dispatching

Scope containers rely on a module context eventing mechanism to be notified of lifecycle changes in the runtime, for example, when a request processing starts/stops, a session starts/stops, or the module starts/stops. Scope containers have a reference to an EventContext, which returns an id associated with the current thread for a given scope type. This enables lazy id creation (e.g. lazy creation of HTTP session ids and contexts). The following sequence diagram traces how module eventing works for request and session lifecycles:
dispatching