Space: Apache Tuscany Docs 2.x (http://cwiki.apache.org/confluence/display/TUSCANYxDOCx2x) Page: SCA Java Runtime Overview (http://cwiki.apache.org/confluence/display/TUSCANYxDOCx2x/SCA+Java+Runtime+Overview)
Edited by Simon Laws: --------------------------------------------------------------------- h1. Software Organization h3. Source Code Locations If you take a Tuscany SCA Java source distribution or look in the Tuscany subversion repository (http://svn.apache.org/repos/asf/tuscany/java/sca/) you'll see the code layed out as follows: {code} BUILDING CHANGES LICENSE NOTICE README RELEASE_NOTES archetypes - Maven archetypes for creating Tuscany project templates distribution - the code that defines and build Tuscany distributions features - Maven projects that collect together Tuscany features itest - project integration tests modules - the source code for the runtime and the SCA extensions pom.xml samples - project samples shades - TBD {code} There is some related source code that's worth mentioning up front. Firstly the project Maven build relies on a set of Maven plugins that have been written specifically for Tuscany. They can also be found in the Tuscany subversion repository (http://svn.apache.org/repos/asf/tuscany/maven-plugins/trunk/) and are as follows: {code} maven-bundle-plugin - Creates Tuscany OSGi bundles based on the Tuscany modules and their dependencies also generates eclipse PDE projects for Tuscany modules maven-eclipse-compiler - Compiles using the Eclipse compiler and performs OSGi validation maven-java2wsdl-plugin - TBD maven-osgi-junit - Runs Junit tests in an OSGi environment maven-tuscany-plugin - TBD maven-wsdl2java-plugin - TBD {code} Secondly there are a set of tests that the OASIS SCA specifications define called otests. These test the Tuscany SCA runtime for compliance with the specifications. The tests themselves are stored in the OASIS subversion system (http://tools.oasis-open.org/version-control/browse/). Tuscany has a set of modules that retrieve these tests automatically and configure the Tuscany environment to run them (http://svn.apache.org/repos/asf/tuscany/otest/) as follows: {code} README build.xml - Ant utility script pom.xml sca-assembly - Generated automatically by svn externals when you check this directory out sca-java-caa - Generated automatically by svn externals when you check this directory out sca-java-ci - Generated automatically by svn externals when you check this directory out sca-policy - Generated automatically by svn externals when you check this directory out tuscany-java-caa-test-runner - Java Common Annotations and APIs test runner tuscany-java-ci-test-runner - Java Component Implementation test runner tuscany-policy-test-runner - Policy test runner tuscany-test-runner - Assembly test runner {code} h3. SCA Java Modules All of the functional code in Tuscany Java SCA can be found under the modules directory. There are a lot of sub-directories here but they basically fall into one of two categories, core function or extensions. We are using the term extension here in the sense that the SCA Assembly specification talks about and extension model You always have to have the core functions but most of the extensions are optional (we say most here because without some of the basic extensions the runtime won't do anything) Finding extension modules is easy. Modules that start with the following words are extensions. {code} binding databinding implementation interface policy {code} As you can see SCA extensions relate to the extensible parts of the SCA composite file. For example, if you want to use <binding.jms/> in you SCA composite files then you need to include the Tuscany modules for this extension in you installation. In this case that would mean the modules binding-jms and binding-jms-runtime. All of the other modules in the modules directory are core modules and are generally required to be present in you Tuscany runtime installation. The use of the word "generally" here sounds a bit vague. This is because the Tuscany runtime itself is based on an extensibility mechanism which means that many parts of the runtime (as well as the SCA extensions) are pluggable. In this way, for example, different hosting environments can be supported. Well talk about runtime extensibility further down this article but for the time being consider all core modules to be mandatory. h1. Runtime Building Blocks As you may have realized the Tuscany SCA Java runtime is just a Java program that, once started listens for incoming messages (via SCA component services) and, sometimes responds with outgoing messages (via SCA component references). !tuscany-runtime-context.png|align=center! The runtime then provides the context within which SCA composite applications run. If we crack open the Tuscany Runtime box we see the following structure. !tuscany-runtime-structure.png|align=center! We'll take a high level look at these different blocks in turn starting with Core. h2. Tuscany Core The Tuscany core is made up of several modules that provide basic runtime and extensibility support to the extensions that provide the real SCA functions. If you look in the modules directory of a Tuscany distribtuion (2.0-M4 at the time of writing - this list may change in subsequent releases) the modules that make up the Tuscany core are as follows: {code} assembly - The in-memory model of an OASIS SCA composite application (sometimes called an assembly) assembly-xml - The Tuscany processors that translate to and from XML and the in-memory model assembly-xsd - The schema used to validate the contents of various SCA files, e.g. the composite file builder - Process the in-memory model to build a complete SCA application representation common-java - General Java utilities common-xml - General XML utilities contribution - Read and process SCA contributions core - The core Tuscany SCA Java runtime functions core-databinding - The core databinding functions core-spi - The Java interfaces that extension developers use to create and register extensions databinding - Builds on the core databinding functions to provide features common to all databindings??? deployment - Loads the runtime and orchestrates the loading of SCA contributions extensibility - Reads META-INF/services files and manages Tuscany extensibility extensibility-equinox - Manages Tuscany extensibility in an OSGi environment host-http - Base interfaces for providing integration with a servlet container interface-java - Java interface model and instrospection interface-java-jaxws - Process JAX-WS annotations from a Java interface interface-wsdl - WSDL interface model launcher - Command line Tuscany runtime launcher monitor - Collects errors as they occur in the Tuscany runtime node-api - API for accessing an embedded Tuscany node (A node loads/runs contributions) node-impl - The JSE implementation for the node API node-impl-osgi - The OSGi implementation for the node API ???? node-launcher - The JSE based command line launcher for a Tuscany node node-launcher-equinox - The OSGi based command line launcher for a Tuscany node sca-api - The OASIS defined SCA API sca-client-impl - The Tuscany implementation of the OASIS defined SCA client xsd - The in-memory model of an XSD file, along with the processors to read it {code} We have already said that there are a set of extensions that, while in theory they are are optional, are in practice required to do anything useful. These are are follows: {code} binding-sca-runtime - The implementation for the local version of binding.sca binding-sca-axis2-runtime - The implementation for the remote version of binding.sca based on web services binding-ws - The in-memory model for binding.ws binding-ws-axis2 - TBD - should be called runtime binding-ws-axis2-policy - TBD binding-ws-wsdlgen - TBD databinding-axiom - The databinding for Axiom databinding-jaxb - The databinding for JAXB databinding-jaxb-axiom - TBD endpoint-tribes - The distributed endpoint registry based on tribes host-jetty - Allows Jetty to be started automatically to support HTTP based bindings host-webapp - Allows Tuscany to be embedded in a WAR implementation-java - The in-memory model for implementation.java implementation-java-runtime - The runtime artifacts for implementation.java {code} The rest of the modules are optional and can be omitted. In practice the easiest way to get started is to keep all of the modules. By default this is what you get when you install the binding distribution. In the future you're free to remove the extensions you don't use to reduce the size of the installation. The Tuscany project may even make releases in the future that package sets of extensions targeted at particular types of application. h2. Tuscany SPI The Tuscany SPI is generally used for building extensions. Extensions come in two flavours SCA extensions, like implementation and binding types, and Tuscany runtime extensions, like builders and binders. Both of these types of extension are discussed a little later in this article. The modules and module packages that describe the Tuscany SPI are as follows: {code} assembly org.apache.tuscany.sca.assembly org.apache.tuscany.sca.definitions org.apache.tuscany.sca.interfacedef org.apache.tuscany.sca.policy assembly-xsd sca-core-1.1.xsd sca-policy-1.1.xsd contribution org.apache.tuscany.sca.contribution org.apache.tuscany.sca.contribution.java org.apache.tuscany.sca.contribution.namespace org.apache.tuscany.sca.contribution.processor org.apache.tuscany.sca.contribution.resolver org.apache.tuscany.sca.contribution.scanner core org.apache.tuscany.sca.core.assembly org.apache.tuscany.sca.core.context org.apache.tuscany.sca.core.factory org.apache.tuscany.sca.core.invocation org.apache.tuscany.sca.core.scope core-databinding org.apache.tuscany.sca.core.databinding.processor core-spi (why not extension SPI?) org.apache.tuscany.sca.context org.apache.tuscany.sca.invocation org.apache.tuscany.sca.provider org.apache.tuscany.sca.runtime org.apache.tuscany.sca.work databinding org.apache.tuscany.sca.databinding org.apache.tuscany.sca.databinding.annotation org.apache.tuscany.sca.databinding.javabeans org.apache.tuscany.sca.databinding.util org.apache.tuscany.sca.databinding.xml deployment org.apache.tuscany.sca.deployment extensibility org.apache.tuscany.sca.core org.apache.tuscany.sca.extensibility monitor org.apache.tuscany.sca.monitor xsd org.apache.tuscany.sca.xsd {code} h2. Tuscany SCA API The Tuscany SCA API is used by SCA applications to access various information from the runtime. It's not mandatory to use the API but it can be useful in some circumstances. {code} launcher Tuscany API node-api Tuscany API node-launcher Tuscany API node-launcher-equinox Tuscany API sca-api OASIS API sca-client-impl OASIS API {code} h2. Tuscany Runtime Extensibility and Extensions As we've already mentioned the Tuscany core doesn't do much on it's own apart from providing basic features and support the plugging in of extensions which do the real work. Extensions come in two forms. Extension types defined by the OASIS SCA specifications and those that are particular to Tuscany. In the first category are the extension types defined by the OASIS Assembly specification: - interface - implementation - binding - import - export The Tuscany runtime defines it's own extension types which exploit the core runtimes extensibility features - policy - databinding - contribution - host The Tuscany extensibility framework is based on two simple ideas. Firstly that the Tuscany runtime provides extension points into which extension functions can be plugged. Secondly that the the Java META-INF/services mechanism provides a way for extension developers to register new extension functions with these extension points. The Tuscany extensibility framework exposes quite a few extension points, for example,(o.a.t.s = org.apache.tuscany) {code} o.a.t.s.core.FactoryExtensionPoint - Holds factories that create in-memory models o.a.t.s.core.UtilityExtensionPoint - A bucket for extensions that don't fit anywhere else o.a.t.s.core.ModuleActivatorExtensionPoint - A Tuscany extension module can defined an activator o.a.t.s.core.invocation.ProxyFactoryExtensionPoint - ??? o.a.t.s.provider.ProviderFactoryExtensionPoint - Created runtime providers o.a.t.s.contribution.processor.ValidationSchemaExtensionPoint - Holds schema for XML model validation o.a.t.s.contribution.processor.StAXAttributeProcessorExtensionPoint - ??? o.a.t.s.contribution.processor.StAXArtifactProcessorExtensionPoint - Holds processors are translate between XML and Java o.a.t.s.contribution.processor.URLArtifactProcessorExtensionPoint - Holds processors that read contribution artifacts o.a.t.s.contribution.resolver.ModelResolverExtensionPoint - Holds resolvers that locates model items in contributions o.a.t.s.assembly.builder.BuilderExtensionPoint - ??? Do we still need this? o.a.t.s.definitions.xml.DefinitionsExtensionPoint - Identifies definitions file in extension modules o.a.t.s.contribution.scanner.ContributionScannerExtensionPoint - Holds scanners that process different contributions formats o.a.t.s.databinding.DataBindingExtensionPoint - Holds databindings o.a.t.s.databinding.jaxb.XMLAdapterExtensionPoint - ??? o.a.t.s.context.ContextFactoryExtensionPoint - ??? o.a.t.s.databinding.TransformerExtensionPoint - ??? o.a.t.s.runtime.RuntimeWireProcessorExtensionPoint - Holds processors that process endpoint and endpoint reference interceptor chains o.a.t.s.implementation.java.introspect.JavaClassVisitor - Holds visitors used to introspect Java classes o.a.t.s.context.PropertyValueFactory - ??? {code} Extension points are usually used in groups. You have to populate the right extension points when implementing say an implementation or a binding extensions. The best way to get a grip on how this works is to look at existing extensions and see what they do. As an example, if you look at how the implementation.java extension registers an extension to read the <implemenation.java/> element from a composite file and turn it into an in-memory Java model you will see the following file: modules/implementation-java/src/main/resources/META-INF/services/o.a.t.s.contribution.processor.StAXArtifactProcessor Which contains a single line as follows: org.apache.tuscany.sca.implementation.java.xml.JavaImplementationProcessor;qname=http://docs.oasis-open.org/ns/opencsa/sca/200903#implementation.java,model=org.apache.tuscany.sca.implementation.java.JavaImplementation This tells the Tuscany runtime to register and extension in the StAXArtifactProcessorExtensionPoint with the follwing properties: - org.apache.tuscany.sca.implementation.java.xml.JavaImplementationProcessor -- The name of the process that turns the XML <implementation.java> element into a Java model - qname=http://docs.oasis-open.org/ns/opencsa/sca/200903#implementation.java -- The QName of the <implementation.java/> element to look for in incoming composite files - model=org.apache.tuscany.sca.implementation.java.JavaImplementation -- The name of the Java model interface that will be used to represent the XML element in-memory. The full set of extension points required to represent the implementation.java extension is spread across the implemenation-java and implementation-java-runtime modules as follows: implementation-java - resources/META-INF/services/ -- o.a.t.s.contribution.processor.StAXArtifactProcessor - Converts <implementation.java/> to/from JavaImplementation model -- o.a.t.s.implementation.java.JavaImplementationFactory - Creates JavaImplementation model objects -- o.a.t.s.implementation.java.introspect.JavaClassVisitor - Registers visitors used to introspect Java classes implementation-java-runtime - resources/META-INF/services/ -- o.a.t.s.context.PropertyValueFactory - ??? -- o.a.t.s.definitions.xml.Definitions - Registers a definitions.xml file for implementation.java -- o.a.t.s.provider.ImplementationProviderFactory - Creates a runtime provider for implementation.java -- o.a.t.s.runtime.RuntimeWireProcessor - Registers a processor for endpoint and endpoint reference interceptor chains All of these extension point entries come together at runtime to allow Tuscany to process implementation.java elements that appear in composite files. TODO - more detail? Most extension are packaged in a least two modules. For example the implementation.java extension is provided in the following modules: {code} modules/implementation-java - the implementation.java model classes and XML processor modules/implementation-java-runtime - the runtime artifacts such as the runtime providers {code} You will currently see extension that don't match this pattern. Often this is because the extension has been moved into 2.x from 1.x but has not been tidied up yet. TODO - What more on modularization? h2. Runtime hosting and containers, OSGi, JSE, Webapps etc. The Tuscany runtime will work in the JSE environment and when deployed to an OSGi runtime like Felix or Equinox. Since 1.x we have been through an exercise of refactoring all of the runtime modules into OSGi bundles and providing consistent OSGi manifest files. See (http://cwiki.apache.org/confluence/display/TUSCANYxDOCx2x/OSGi+Enablement+for+Tuscany+Runtime) for more details on how we OSGi-igfied the Tuscany runtime. A launcher is provided to each environment. For JSE use the following class from modules/node-launcher: {code} org.apache.tuscany.sca.node.launcher.NodeLauncher {code} For in OSGi in the Equinoz framework use the following class from modules/node-launcher-equinox: {code} org.apache.tuscany.sca.node.equinox.launcher.NodeLauncher {code} In both cases you use the launcher to create a node instance as follows: {code} Node node = launcher.createNode(new Contribution("contrib1", "./contrib1.jar"), new Contribution("contrib2", "./contrib2.jar")); node.start(); {code} When you use the JSE launcher the runtime starts and creates a classpath to load the Tuscany runtime. It uses the following algorithm (coded in the NodeLauncherUtil.runtimeClassloader method) to create the classpath: - Check to see if the runtime has been added to the current classpath already. If it has don't do anything more - Determine where the launcher class was loaded from and load all the Tuscany classes from that location - Look for an environment variable called TUSCANY_HOME which should point to a distribution. Load jars from there and from lib and modules sub directories - Look for an environment variable called TUSCANY_PATCH which contains a list of Jars to load? When you use the OSGI launcher the algorithm is similar but of course this time the Tuscany bundles are loaded into the OSGi framework. The node launcher starts up the Equinox framework and then goes looking for bundles to load using the following algorithm: - TBD There is no single classpath that gives access to the Tuscany runtime. TODO what features of the OSGi integration do we need to cover in this overview? (In the OSGi runtime special processing is applied to collect together all the META-INF/services information so that it is all accessible without having to delve inside each bundle. See the runtime enviroments section for more information) You can of course use the launchers from the command line in various guises. {code} TBD {code} TODO - what other ways are we actually going to support for starting the runtime? h1. SCA Domain and Nodes The design for the 2.x SCA domain is based on a registry that is accessible from all nodes that are running composites in the domain. There is also the intention to add a management mechanism to allow for central control of the nodes. This is not in place yet. !tuscany-domain-overview.png|align=center! It is out intention to bring the Domain Manager function over from the 1.x code base to provide a central place for adding contributions and assigning them to nodes. This time though it won't be mandatory to run a Domain Manager to have nodes run a distributed SCA application. If you are happy to configure nodes directly and start them individually you are able to do that. The registry hold information that is common across the domain including: - available endpoints (the result of specifying a binding on a component services) - policy model - extension type model The following diagram shows an example of domain data populating the registry and two nodes, in separate JVMs, running separate composites from the SCA application !tuscany-domain-registry.png|align=center! Deployment and contributions h1. Runtime Lifecycle h2. Create See previous hosting section h2. Read Read composites using processors TODO - more info h2. Resolve Resolve composite artifacts using processors TODO - more info h2. Build !tuscany-builders.png|align=center! |tuscany-endpoint-structure.png|align=center! !tuscany-endpoint-callback.png|align=center! !tuscany-endpoint-build.png|align=center! h2. Activate TODO h2. Start TODO h2. Message Processing !tuscany-reference-interceptors.png|align=center! !tuscany-service-interceptors.png|align=center! !tuscany-interface-contracts.png|align=center! !tuscany-reference-databinding.png|align=center! !tuscany-service-databinding.png|align=center! h2. Stop Change your notification preferences: http://cwiki.apache.org/confluence/users/viewnotifications.action
