summaryrefslogtreecommitdiffstats
path: root/sandbox/jim/docs
diff options
context:
space:
mode:
authordims <dims@13f79535-47bb-0310-9956-ffa450edef68>2008-06-17 00:23:01 +0000
committerdims <dims@13f79535-47bb-0310-9956-ffa450edef68>2008-06-17 00:23:01 +0000
commitbdd0a41aed7edf21ec2a65cfa17a86af2ef8c48a (patch)
tree38a92061c0793434c4be189f1d70c3458b6bc41d /sandbox/jim/docs
Move Tuscany from Incubator to top level.
git-svn-id: http://svn.us.apache.org/repos/asf/tuscany@668359 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'sandbox/jim/docs')
-rw-r--r--sandbox/jim/docs/assembly.html69
-rw-r--r--sandbox/jim/docs/assembly.pptbin0 -> 19968 bytes
-rw-r--r--sandbox/jim/docs/assembly/Slide1.pngbin0 -> 40286 bytes
-rw-r--r--sandbox/jim/docs/exception_handling.html158
-rw-r--r--sandbox/jim/docs/overview.pptbin0 -> 33280 bytes
-rw-r--r--sandbox/jim/docs/overview/Slide1.pngbin0 -> 21875 bytes
-rw-r--r--sandbox/jim/docs/overview/Slide2.pngbin0 -> 20819 bytes
-rw-r--r--sandbox/jim/docs/runtime_overview.html86
-rw-r--r--sandbox/jim/docs/tuscany.runtime.001.jpgbin0 -> 118685 bytes
-rw-r--r--sandbox/jim/docs/tuscany.runtime.pdfbin0 -> 61524 bytes
10 files changed, 313 insertions, 0 deletions
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 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> <title>Tuscany Java Runtime Assembly</title> </head> <body> <h1>Assembly</h1> <h2>Introduction</h2> <p>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.</p> <h2>Local Assembly</h2> <p>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.</p> <p>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.</p>
+ <h2>Remote Assembly - TBD</h2> <h2>Runtime Assembly</h2> <p>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:</p>
+ <ul>
+ <li><i>Autowiring.</i> 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:<p/>
+ <img src="assembly/Slide1.png" alt="autowire"/>
+ <p>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.</p>
+ </li>
+ <li><i>ParentContext.</i> System components can also contain references to their parent
+ aggregate context. This is done through the "ParentContext" metadata (e.g.
+ <code>@ParentContext</code></li>
+ </ul>
+ <h3>Hierarchical Runtime Assembly</h3> <p>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.</p>
+ </body>
+</html>
diff --git a/sandbox/jim/docs/assembly.ppt b/sandbox/jim/docs/assembly.ppt
new file mode 100644
index 0000000000..3ffee9545c
--- /dev/null
+++ b/sandbox/jim/docs/assembly.ppt
Binary files differ
diff --git a/sandbox/jim/docs/assembly/Slide1.png b/sandbox/jim/docs/assembly/Slide1.png
new file mode 100644
index 0000000000..03a2adf539
--- /dev/null
+++ b/sandbox/jim/docs/assembly/Slide1.png
Binary files 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 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> <title>Exception Handling Guidelines for The Java Runtime</title> </head> <body> <h1>Java Runtime Exception Policy</h1> <p> 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: </p> <ul>
+ <li>Code Exception: Code can work around the discovered problem</li>
+ <li>User Exception: Problem to be remedied by a human (e.g. Administrator)</li>
+ <li>Assertion Exception: Problem remedied by human fixing a bug in the code</li>
+ </ul>
+ <h2>Code Exceptions</h2>
+ <p> 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.</p>
+ <h3>Implications</h3>
+ <p>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).</p>
+ <p>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". </p>
+ <h2>User Exceptions</h2>
+ <p> 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.</p>
+ <p>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.</p>
+ <p> 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: </p>
+ <ul>
+ <li>It's the fault of the client code that is sending the incoming message (e.g. SOAP
+ faults).</li>
+ <li>It's the fault of the code or configuration that is handling the message. </li>
+ </ul>
+ <p> 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. </p>
+ <p> 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. </p>
+ <h2>Assertion Exceptions</h2>
+ <p> 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. </p>
+
+
+ <h2>Guidelines</h2>
+ <p> The following are a set of guidelines based on the above exception philosophy: </p>
+ <h4>1. Checked vs. unchecked exceptions</h4>
+ <p> 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. </p>
+ <h4>2. Assertion exceptions should use the standard JDK assert facilities</h4>
+ <h4>3. Any exception thrown to user code must extend the appropriate Exception as defined
+ by the specification. This will typically be a runtime Exception.</h4>
+ <h4>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.
+ <h4>4. When possible, create clear package exception hierarchies</h4>
+ <p> 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). </p>
+ <h4> 5. Preserve all stack trace information and the original exception</h4>
+ <p> 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.</p>
+ <h4>6. Only include local information pertinent to the failure</h4>
+ <p> 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. </p>
+ <h4>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.</h4>
+ <p> 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: </p>
+ <ul>
+ <li> A component property is configured with an invalid integer type</li>
+ <li> The property value parsing code attempts to load an integer value using parseInt(),
+ resulting in a NumberFormatException</li>
+ <li> NumberFormatException is wrapped in an InvalidParameterException (IPE) containing
+ the name of the property.</li>
+ <li> IPE extends a more general ConfigException, which has setters for adding additional
+ context information such as component and module names</li>
+ <li> As the IPE is thrown up the stack, the component and module parsers provide
+ additional context information.</li>
+ <li> The configuration loader then wraps the IPE in a ConfigLoadExeption and provides
+ the source from which the configuration is being loaded.</li>
+ <li> The UI being used to load the configuration reports the error to the user and
+ displays the appropriate contextual information</li>
+ </ul>
+ <h4>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 ]"</h4>
+ <h4>9. Do not override the behaviour of Throwable.toString() and Throwable.printStackTrace()</h4>
+ <h4>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.</h4>
+ <h4>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.</h4>
+ </body>
+</html>
diff --git a/sandbox/jim/docs/overview.ppt b/sandbox/jim/docs/overview.ppt
new file mode 100644
index 0000000000..839fe71a8e
--- /dev/null
+++ b/sandbox/jim/docs/overview.ppt
Binary files differ
diff --git a/sandbox/jim/docs/overview/Slide1.png b/sandbox/jim/docs/overview/Slide1.png
new file mode 100644
index 0000000000..cfaf8e54fd
--- /dev/null
+++ b/sandbox/jim/docs/overview/Slide1.png
Binary files differ
diff --git a/sandbox/jim/docs/overview/Slide2.png b/sandbox/jim/docs/overview/Slide2.png
new file mode 100644
index 0000000000..6b4d1ab449
--- /dev/null
+++ b/sandbox/jim/docs/overview/Slide2.png
Binary files 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 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> <title>Tuscany Java Runtime Overview</title> </head> <body> <h1>Tuscany Java Runtime Overview</h1> <h2>Introduction</h2> <p>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 <i>o.a.t.core.context.Context</i>. which, at a minimium,
+ control their lifecycle state . The most prevalent type of context is
+ <i>o.a.t.core.InstanceContext</i>, which manages instances of a runtime artifact.
+ There are several types of instance context: </p>
+ <ul>
+ <li><i>SimpleComponentContext:</i> 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.</li>
+ <li><i>AggregateContext:</i> Manages a context which contains child contexts such as an SCA module component. Aggregates may contain SimpleComponentContexts, EntryPointContexts and ExternalServiceContexts.</li> <li><i>EntryPointContext:</i> Manages the public access point of a service offered by a
+ component or external service in a an aggregate context over a transport binding.</li>
+ <li><i>ExternalServiceContext:</i> Manages a local representation of a service external
+ to an aggregate context.</li>
+ <li><i>ScopeContext:</i> 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.</li>
+ <li>
+ <i>RuntimeContext:</i>Manages a runtime instance. A runtime context is an aggregate
+ context that contains a root aggregate context and a system aggregate context.</li>
+ </ul>
+ <p>The relationship between contexts is described in the following diagram:</p>
+ <img alt="context.uml" src="overview/Slide1.png"/>
+ <h2>Configuration</h2>
+ <p>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.</p>
+ <h2>The Runtime Bootstrap</h2>
+ <p>Contexts are assembled in hierarchical fashion, starting with the RuntimeContext:</p>
+ <img alt="context.uml" src="overview/Slide2.png"/>
+ <p>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:</p>
+ <ol>
+ <li>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.</li>
+ <li>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.</li>
+ <li>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.</li>
+ <li>Bring the runtime online.</li>
+ </ol>
+ <p>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.</p>
+ <h2>Registering and Building Configuration</h2> <p>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).</p>
+ <h3>Runtime Configuration</h3>
+ <p>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. </p>
+ </body>
+</html>
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
--- /dev/null
+++ b/sandbox/jim/docs/tuscany.runtime.001.jpg
Binary files differ
diff --git a/sandbox/jim/docs/tuscany.runtime.pdf b/sandbox/jim/docs/tuscany.runtime.pdf
new file mode 100644
index 0000000000..399f78a9b1
--- /dev/null
+++ b/sandbox/jim/docs/tuscany.runtime.pdf
Binary files differ