From bdd0a41aed7edf21ec2a65cfa17a86af2ef8c48a Mon Sep 17 00:00:00 2001 From: dims Date: Tue, 17 Jun 2008 00:23:01 +0000 Subject: Move Tuscany from Incubator to top level. git-svn-id: http://svn.us.apache.org/repos/asf/tuscany@668359 13f79535-47bb-0310-9956-ffa450edef68 --- sandbox/jim/docs/assembly.html | 69 ++++++++++++++ sandbox/jim/docs/assembly.ppt | Bin 0 -> 19968 bytes sandbox/jim/docs/assembly/Slide1.png | Bin 0 -> 40286 bytes sandbox/jim/docs/exception_handling.html | 158 +++++++++++++++++++++++++++++++ sandbox/jim/docs/overview.ppt | Bin 0 -> 33280 bytes sandbox/jim/docs/overview/Slide1.png | Bin 0 -> 21875 bytes sandbox/jim/docs/overview/Slide2.png | Bin 0 -> 20819 bytes sandbox/jim/docs/runtime_overview.html | 86 +++++++++++++++++ sandbox/jim/docs/tuscany.runtime.001.jpg | Bin 0 -> 118685 bytes sandbox/jim/docs/tuscany.runtime.pdf | Bin 0 -> 61524 bytes 10 files changed, 313 insertions(+) create mode 100644 sandbox/jim/docs/assembly.html create mode 100644 sandbox/jim/docs/assembly.ppt create mode 100644 sandbox/jim/docs/assembly/Slide1.png create mode 100644 sandbox/jim/docs/exception_handling.html create mode 100644 sandbox/jim/docs/overview.ppt create mode 100644 sandbox/jim/docs/overview/Slide1.png create mode 100644 sandbox/jim/docs/overview/Slide2.png create mode 100644 sandbox/jim/docs/runtime_overview.html create mode 100644 sandbox/jim/docs/tuscany.runtime.001.jpg create mode 100644 sandbox/jim/docs/tuscany.runtime.pdf (limited to 'sandbox/jim/docs') diff --git a/sandbox/jim/docs/assembly.html b/sandbox/jim/docs/assembly.html new file mode 100644 index 0000000000..39f263939a --- /dev/null +++ b/sandbox/jim/docs/assembly.html @@ -0,0 +1,69 @@ + Tuscany Java Runtime Assembly

Assembly

Introduction

This document details how the Java Runtime performs assembly. Assembly is the process of + wiring networks of services based on external configuration. Assembly may occur both + locally (i.e. Between two services in a shared memory space) and remotely. Wires between + two services within the same aggregate context are local; wires whose target is an + external service or external URI are remote. Remote wires always follow pass-by-value + semantics. Local wires generally follow pass-by-reference except when the component + implementation contract declares otherwise.

Local Assembly

The Tuscany Java Runtime (TJR) attempts to precompute as much as possible of the assembly + model when a configuration is registered. This process is termed the build phase. During + this phase, the runtime walks the configuration (typically consisting of module + components, components, entry points, and external services) and calls all registered + implementations of o.t.core.builder.RuntimeConfigurationBuilder which in turn decorate + the configuration with implementations of o.t.core.builder.RuntimeConfiguration + (examples include the implementations in o.a.t.container.java.config and + o.a.t.container.java.builder). RuntimeConfigurations are factories for creating instance + contexts based on the corresponding configuration artifact. For example, an SCA Java + component will be decorated with a RuntimeConfiguration that can produce an instance + context which manages a POJO injected with the appropriate properties and references as + defined by the configuration.

The strategy for how a runtime configuration creates an instance context is specific to + the implementation type. For example, the SCA Java client implementation uses + o.a.t.core.injection.PojoObjectFactory to create POJOs. This in turns uses + implementations of o.a.t.core.Injector to inject properties and references during + instantiation (the injectors are created during the build phase by + o.a.t.container.java.builder.JavaComponentContextBuilder). Injectors are configured with + implementations of o.a.t.core.injection.ObjectFactory to create or return a property or + reference value. For example, reference values will have an injector that uses a factory + such as o.a.t.core.injection.ReferenceTargetFactory which is capable of creating a proxy + to the target service. In cases where a proxy is not needed, a factory may return the + actual target instance.

Remote Assembly - TBD

Runtime Assembly

Runtime assembly is the process of wiring components which offer special services in the + runtime. Runtime assembly is done in a manner similar to the standard assembly described + above, except that system components have their own implementation type (cf. + o.a.t.core.system). The system implementation type supports all SCA Java Client and + Implementation model constructs (properties and references), metadata, and stateless and + module scope lifecycles (request and session scopes are not currently supported but they + could be added if needed). In addition, the system implementation type also supports the + following capabilities:

Autowiring. Autowiring provides the ability to resolve reference targets + based on interface type. This is used to resolve targets where the actual target + component is not important (or should remain unknown) as long as it provides the + required service, for example, a transaction manager or monitor factory. Autowire + targets must be configured in a system module component external to the source + component (otherwise one would use "regular" wiring). An autowire target must be + published as an entry point using the special "system" binding. Further, autowire + entry points are only visible to the parent aggregate context and its children. To + make an autowire entry point visible more than one level up in an aggregate + hierarchy, it must be republished as an entry point by the parent aggregate context. + The following demonstrates how autowiring occurs:
+ +
To understand autowiring in more detail, review + o.a.t.core.system.SystemAggregateContextImpl, + o.a.t.core.context.AggregateContextImp, and + o.a.t.core.system.builder.SystemComponentContextBuilder.
+
ParentContext. System components can also contain references to their parent + aggregate context. This is done through the "ParentContext" metadata (e.g. + @ParentContext

Hierarchical Runtime Assembly

The TJR essentially assembles itself from a series of "system" components in a recursive + fashion. Aggregate contexts are created from Module Components which in turn contain + children that are assembled (other aggregates, simple components, entry points, and + external services). Aggregate contexts may also be autowired (e.g. + o.a.t.core.context.AggregateComponentContextImpl). Child aggregate contexts are managed + by a special scope context, o.a.t.core.context.scope.AggregateScopeContext. This allows + the runtime to assemble itself using a relatively lightweight builder infrastructure to + an arbitrarily deep nesting. For further details see o.a.t.core.system.builder and + o.a.t.core.system.config.

+ + diff --git a/sandbox/jim/docs/assembly.ppt b/sandbox/jim/docs/assembly.ppt new file mode 100644 index 0000000000..3ffee9545c Binary files /dev/null and b/sandbox/jim/docs/assembly.ppt differ diff --git a/sandbox/jim/docs/assembly/Slide1.png b/sandbox/jim/docs/assembly/Slide1.png new file mode 100644 index 0000000000..03a2adf539 Binary files /dev/null and b/sandbox/jim/docs/assembly/Slide1.png differ diff --git a/sandbox/jim/docs/exception_handling.html b/sandbox/jim/docs/exception_handling.html new file mode 100644 index 0000000000..84b075baf0 --- /dev/null +++ b/sandbox/jim/docs/exception_handling.html @@ -0,0 +1,158 @@ + Exception Handling Guidelines for The Java Runtime

Java Runtime Exception Policy

The key tenet of this exception policy is that exceptions should be designed with an eye + toward what the catch clause would likely do with the exception. The three main cases + are:

Code Exception: Code can work around the discovered problem
User Exception: Problem to be remedied by a human (e.g. Administrator)
Assertion Exception: Problem remedied by human fixing a bug in the code

Code Exceptions

These are exceptions where it is expected that some calling code may be able to + completely handle the exception, without involvement of any user. In other words, the + exception is of an alternate way of returning a value. There is a reasonable chance that + calling code (maybe a couple levels up) will be able to catch the exception and either + try again or try some other approach to accomplishing its job. Note that there may be no + way of knowing whether the caller will be able to figure out a different approach to + handling the situation. This is especially true in reusable utility code. In these + cases, the exceptions should be considered to be code exceptions. The code that handles + the exception might just turn it into a different kind of exception.

Implications

In general, code exceptions should be checked exceptions. They should be named based on + what happened, rather than based on who is throwing the exception. If the exception is + well named, it should be possible for the exception to be present on signatures at + several levels of a call stack and still make sense (e.g. ServiceUnavailableException).

There are some cases where code exceptions should not be checked exceptions. If code + cannot reasonably be expected to recover from an exception, it should be unchecked, + Also, iIf a large fraction of the methods in the code would need to declare the + exception, then its declaration doesn't add much value and so it should be a + RuntimeException so it doesn't need to be declared. One example of this kind of + exception might be a RetryException. This exception might occur on some kind of resource + conflict where retrying the transaction is likely to solve it. Since it is solved + without human involvement it is still a "code exception".

User Exceptions

These are exceptions that signal a problem that will be handled by a person, so the most + important component of the exception is the message, rather than the type of the + exception. Unfortunately, the code that throws the original exception often will not + have enough information to give a meaningful message to the user that has all the + necessary context. The typical "user" in this situation is an administrator, where a + stack traceback wouldn't be very helpful. Because of this, it is important that code be + littered with try/catch blocks that do no more than add context to the exception message + and then rethrow.

In a previous project this was done by having a base UserException class that had an + array of messages, rather than just one message. For example, code that parses an SCA + subsystem file might have a rethrow that just adds "While parsing the xyz subsystem + file". That is a message that could not be generated by the code that discovered the + problem (say an XML parsing problem), so a combination of the original message (e.g. + "Missing end tag") and the higher level message ("while parsing the xyz subsystem file") + are both necessary for know what happened. Naturally it can be any number of levels + deep.

The handling code for a user exception will somehow notify a user of the message and + then possibly go on. There should be different kinds of exceptions when there need to be + different ways of handling of the message or different ways to continue. Different ways + to report the error: In a server, user exceptions can often be divided according to + fault:

It's the fault of the client code that is sending the incoming message (e.g. SOAP + faults).
It's the fault of the code or configuration that is handling the message.

If the problem is the fault of the client code, then the message needs to be reported + back to the client code in a format appropriate for the client. If the problem is the + fault of the server code or configuration, then only a vague "I've got a problem here" + message should be sent to the client and the real exception message should be logged + and/or sent to an administrator. Because of the two different ways of handling the + problem, there should be different exception types. For example, ClientException could + be used for exceptions that signal problems that are the client's fault.

The remaining user exceptions are typically problems with configuration or the + environment. Some of them will be severe enough that the entire application needs to be + brought down, while others could be handled by just logging the problem and going on. + This difference implies that there needs to be a different exception type. Advanced + Scenario: In the case of session-scoped services, the problem is likely to require that + the instance of the service be put into an error state (like paused). This is because + subsequent messages for the service have been sent on the assumption that the previous + message actually gets processed. If some configuration error prevents a session-scoped + service from handling a single message, all future (async) messages for that service + instance should be queued up so they can be processed once the problem has been solved.

Assertion Exceptions

Assertion exceptions are exceptions that result from a bug in Tuscany and as such are + also intended to be solved by humans, but in this case the humans are us --are the + developers of the SCA runtime. In these cases the message isn't nearly as important, + since the stack traceback provides valuable context. If an assertion exception occurs + little can be known about the state of the server. If we wanted to be safe we would say + that assertion exceptions always bring down the entire server. However, we could play it + a little looser and say that assertion exceptions only bring down the application in + which they are discovered.

+ + +

Guidelines

The following are a set of guidelines based on the above exception philosophy:

1. Checked vs. unchecked exceptions

Unchecked exceptions should be used when an error condition is not recoverable. Checked + exceptions thrown by third party libraries that are not recoverable should be wrapped in + unchecked exceptions rather than being propagated up the call stack. For example, an + IOException raised when reading a file might be wrapped in an unchecked LoadException + containing the name of the file. + Unchecked must always be Javadoced and declared in the throws clause of a method.

2. Assertion exceptions should use the standard JDK assert facilities

3. Any exception thrown to user code must extend the appropriate Exception as defined + by the specification. This will typically be a runtime Exception.

4. No other Exceptions should be thrown to user code. Each user API method should + catch any internal exceptions and wrap them in the applicable Exception defined + by the specification. Internal exceptions must ultimately extend either TuscanyException + or TuscanyRuntimeException. +

4. When possible, create clear package exception hierarchies

In most cases, packages should have a clear exception hierarchy with abstract root + checked and unchecked exceptions which more specific concrete exceptions extend. + Declaring the root package exceptions abstract avoids code throwing exceptions which are + too general. Creating an exception hierarchy allows client code using a particular + package to choose the level of exception handling granularity (which in turn simplifies + the client code by avoiding unwieldy try..catch clauses).

5. Preserve all stack trace information and the original exception

Exceptions must always preserve the stack trace and original exception except under + special circumstances. When wrapping exceptions to propagate, never modify the stack + trace and always include the caught exception as the cause.

6. Only include local information pertinent to the failure

For I18N, contextual information stored in the Exception should not be localized. It + should comprise only data pertaining to the cause, such as the name of the artifact as + above, or a key that can be used by the top level exception handler. This is needed + because the locale used to render the exception may be completely different from the + locale used by the code raising the exception. For example, an exception may be thrown + on a system whose default locale is German, logged to the system log in English but + displayed to the end user in French, Japanese, whatever their native language is.

7. For exceptions that require contextual information from various code layers, either + wrap exceptions or create exceptions that can accept additional context as they are + propagated up the call stack.

If a failure requires information from multiple levels, e.g. “there was an error setting + property X on component Y in module Z” do one of the following. If the initial exception + should be wrapped as it is propagated (e.g. the exception occurs at a library boundary), + add additional context information in the wrapping exception(s). If the initial + exception can be propagated, include methods for adding additional context information + as the exception is rethrown up the stack. For example, the previous failure scenario + could result in the following exception handling strategy:

A component property is configured with an invalid integer type
The property value parsing code attempts to load an integer value using parseInt(), + resulting in a NumberFormatException
NumberFormatException is wrapped in an InvalidParameterException (IPE) containing + the name of the property.
IPE extends a more general ConfigException, which has setters for adding additional + context information such as component and module names
As the IPE is thrown up the stack, the component and module parsers provide + additional context information.
The configuration loader then wraps the IPE in a ConfigLoadExeption and provides + the source from which the configuration is being loaded.
The UI being used to load the configuration reports the error to the user and + displays the appropriate contextual information

8. getMessage() must return unformatted context info. If the Exception contains multiple + context fields they should be surrounded in square brackets and separated by commas, + e.g. "[ property X, component Y, module Z ]"

9. Do not override the behaviour of Throwable.toString() and Throwable.printStackTrace()

10. The java.lang.Exception base class is Serializable so all subclasses must provide + a serial UID. Any context fields must be Serializable and should be defined in the + base java namespace for JDK1.4.

11. Exceptions that wrap other Exceptions should ensure that any wrapped Exception can + be deserialized in a client environment. This may require providing a custom + writeObject method to extract any context information from the wrapped Exception + during serialization; at a minimum the message should be preserved.

+ + diff --git a/sandbox/jim/docs/overview.ppt b/sandbox/jim/docs/overview.ppt new file mode 100644 index 0000000000..839fe71a8e Binary files /dev/null and b/sandbox/jim/docs/overview.ppt differ diff --git a/sandbox/jim/docs/overview/Slide1.png b/sandbox/jim/docs/overview/Slide1.png new file mode 100644 index 0000000000..cfaf8e54fd Binary files /dev/null and b/sandbox/jim/docs/overview/Slide1.png differ diff --git a/sandbox/jim/docs/overview/Slide2.png b/sandbox/jim/docs/overview/Slide2.png new file mode 100644 index 0000000000..6b4d1ab449 Binary files /dev/null and b/sandbox/jim/docs/overview/Slide2.png differ diff --git a/sandbox/jim/docs/runtime_overview.html b/sandbox/jim/docs/runtime_overview.html new file mode 100644 index 0000000000..5d9af90eb1 --- /dev/null +++ b/sandbox/jim/docs/runtime_overview.html @@ -0,0 +1,86 @@ + Tuscany Java Runtime Overview

Tuscany Java Runtime Overview

Introduction

This document is intended to provide a high level view of the Tuscany Java Runtime. At + the most general level, the Tuscany Java Runtime is organized into a series of artifacts + which can be loosely defined as units of management. Runtime artifacts can vary from the + bootrap container, component containers to application components. Runtime artifacts are + managed by implementations of o.a.t.core.context.Context. which, at a minimium, + control their lifecycle state . The most prevalent type of context is + o.a.t.core.InstanceContext, which manages instances of a runtime artifact. + There are several types of instance context:

SimpleComponentContext: Manages implementation instances of a leaf + appplication component such as an SCA component, i.e. a component that has no + children. There is generally a 1:1 relationship between a simple context and a + component implementation instance.
AggregateContext: Manages a context which contains child contexts such as an SCA module component. Aggregates may contain SimpleComponentContexts, EntryPointContexts and ExternalServiceContexts.
EntryPointContext: Manages the public access point of a service offered by a + component or external service in a an aggregate context over a transport binding.
ExternalServiceContext: Manages a local representation of a service external + to an aggregate context.
ScopeContext: Manages a scope which defines the lifecycle and visibility of + component instances. SimpleComponentContexts, EntryPointContexts, External Services, + and AggregateComponentContexts are associated with a scope context. Further, + aggregate contexts contain scope contexts to manage the visibility of their + children.
+ RuntimeContext:Manages a runtime instance. A runtime context is an aggregate + context that contains a root aggregate context and a system aggregate context.

The relationship between contexts is described in the following diagram:

Configuration

Runtime artifacts are defined by configuration artifact. The set of configuration + artifacts and their inter-relations are described by a Logical Configuration Model (LCM) + located in o.a.t.model.assembly. The LCM is an in-memory representation of configuration + information derviced from some external source (e.g. XML, programmatically, etc.). The + runtime uses an LCM to generate the appropriate context objects. For example, a + SimpleComponentContext is generated from a Component, an AggregateContext from a + ModuleComponent, etc. This is done through a multistep configuration process described + further on.

The Runtime Bootstrap

Contexts are assembled in hierarchical fashion, starting with the RuntimeContext:

A host environment is responsible for bootstrapping the runtime, providing "core" + capabilities such as classloader semantics, and loading configuration artifacts. For + example, a host runtime will typically boostrap the runtime according to the following + steps:

Instantiate a runtime context (the default implementation is + o.a.t.core.system.context.RuntimeContextImpl) with a collection of boostrap runtime + configuration builders (.cf the description of configuration processing), and an + implementation of o.a.t.common.monitor.MonitorFactory for logging. This context + serves as the runtime bootstrap.
Load system module components and register them with the runtime context. System + module components contain system components that provide core runtime functionality + such as support for the SCA Java Client and Implementation model, transport + bindings, configuration builders, and data binding.
Recursively load susbsystems, module components and other artifacts, registering + them with the runtime context as parts of an LCM. The runtime context will modify or + complete the LCM during this registration phase. Note that additional components and + other artifacts may be registered dynamically after the runtime has been brought + online.
Bring the runtime online.

This design allows the Tuscany runtime to be hosted on a variety of technology platforms + such as J2SE, a Servlet engine, a J2EE container, or an OSGi container.

Registering and Building Configuration

A configuration is registered with its parent context which is always an + AggregateContext. For example, a SimpleComponent is registered with its parrent + AggregateContext. Similarly, an AggregateContext is registered with its parent context + which will be another AggregateContext. All registered aggregates form a hierarchy + descending either from the root or system aggregate contexts (whose parent is the + runtime context). When a component configuration is registered with its parent context, + the configuration is passed up the hierarchy for completion. At this point, a second + pass termed the build phase is made over the configuration and it is decorated with + factories that create Context instances (the specifics of this process are detailed in a + separate document; in brief, however, a pass is made over the configuration by + implementations of o.a.t.core.builder.RuntimeConfigurationBuilder, which are configured + system components).

Runtime Configuration

The core Tuscany runtime is also built in the same manner as described above. In this + case, the host environment registers system components with the system context (or one + of its children). These system component configurations are processed and decorated by a + series of bootstrap builders (c.f. o.a.t.core.system.builder). The system context is + then started and appropriate child contexts are created from the decorated model. These + contexts manage implementation instances which provide core runtime functionality. + System entry points may be wired to external services in other modules, thereby + providing a way to access system capabilities from other components.

+ + diff --git a/sandbox/jim/docs/tuscany.runtime.001.jpg b/sandbox/jim/docs/tuscany.runtime.001.jpg new file mode 100644 index 0000000000..bd2c8e34d7 Binary files /dev/null and b/sandbox/jim/docs/tuscany.runtime.001.jpg differ diff --git a/sandbox/jim/docs/tuscany.runtime.pdf b/sandbox/jim/docs/tuscany.runtime.pdf new file mode 100644 index 0000000000..399f78a9b1 Binary files /dev/null and b/sandbox/jim/docs/tuscany.runtime.pdf differ -- cgit v1.2.3