notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

r1581 - in trunk/central: . site site/src/docs/metro/directives site/src/docs/transit site/src/docs/transit/config site/src/docs/transit/tutorials

From: mcconnell at BerliOS <mcconnell AT mail.berlios.de>
To: notify-dpml AT lists.ibiblio.org
Subject: r1581 - in trunk/central: . site site/src/docs/metro/directives site/src/docs/transit site/src/docs/transit/config site/src/docs/transit/tutorials
Date: Mon, 17 Jul 2006 16:08:08 +0200

Author: mcconnell
Date: 2006-07-17 16:08:06 +0200 (Mon, 17 Jul 2006)
New Revision: 1581

Added:
trunk/central/site/src/docs/transit/tutorials/
trunk/central/site/src/docs/transit/tutorials/artifacts.xml
trunk/central/site/src/docs/transit/tutorials/index.xml
trunk/central/site/src/docs/transit/tutorials/navigation.xml
trunk/central/site/src/docs/transit/tutorials/overview.xml
trunk/central/site/src/docs/transit/tutorials/plugins.xml
trunk/central/site/src/docs/transit/tutorials/repositories.xml
trunk/central/tutorials/
Modified:
trunk/central/site/build.xml
trunk/central/site/src/docs/metro/directives/index.xml
trunk/central/site/src/docs/transit/config/index.xml
trunk/central/site/src/docs/transit/navigation.xml
Log:
add transit tutorial

Modified: trunk/central/site/build.xml
===================================================================
--- trunk/central/site/build.xml 2006-07-17 08:34:26 UTC (rev 1580)
+++ trunk/central/site/build.xml 2006-07-17 14:08:06 UTC (rev 1581)
@@ -6,9 +6,56 @@

<transit:import uri="local:template:dpml/tools/standard"/>

- <target name="build" depends="standard.build">
+ <target name="build" depends="standard.build,docs,javadoc"/>
+
+ <target name="docs" depends="prepare">
<x:docs dest="${dpml.data}/docs"/>
</target>
-
+
+ <target name="javadoc" depends="prepare">
+ <x:javadoc title="DPML Component Management Platform" access="protected"
ref="dpml">
+ <link href="http://java.sun.com/j2se/1.4/docs/api"/>
+ <link href="http://api.dpml.net/javax/servlet/2.5"/>
+ <link href="http://api.dpml.net/jetty/20060213"/>
+ <group title="Library">
+ <package name="net.dpml.library"/>
+ <package name="net.dpml.library.*"/>
+ </group>
+ <group title="Depot">
+ <package name="net.dpml.depot"/>
+ <package name="net.dpml.depot.*"/>
+ <package name="net.dpml.tools"/>
+ <package name="net.dpml.tools.*"/>
+ </group>
+ <group title="Transit">
+ <package name="net.dpml.lang"/>
+ <package name="net.dpml.transit"/>
+ <package name="net.dpml.transit.*"/>
+ <package name="net.dpml.util"/>
+ </group>
+ <group title="Metro">
+ <package name="net.dpml.component"/>
+ <package name="net.dpml.metro"/>
+ <package name="net.dpml.metro.*"/>
+ <package name="net.dpml.state"/>
+ </group>
+ <group title="Station">
+ <package name="net.dpml.station"/>
+ <package name="net.dpml.station.*"/>
+ </group>
+ <group title="Planet">
+ <package name="net.dpml.http"/>
+ <package name="net.dpml.http.*"/>
+ </group>
+ <group title="Util">
+ <package name="net.dpml.cli"/>
+ <package name="net.dpml.cli.*"/>
+ <package name="net.dpml.i18n"/>
+ <package name="net.dpml.i18n.*"/>
+ <package name="net.dpml.logging"/>
+ <package name="net.dpml.logging.*"/>
+ </group>
+ </x:javadoc>
+ </target>
</project>

Modified: trunk/central/site/src/docs/metro/directives/index.xml
===================================================================
--- trunk/central/site/src/docs/metro/directives/index.xml 2006-07-17
08:34:26 UTC (rev 1580)
+++ trunk/central/site/src/docs/metro/directives/index.xml 2006-07-17
14:08:06 UTC (rev 1581)
@@ -25,21 +25,22 @@
The following example demonstrates the definition of a part
using a component directive as the part deployment strategy.

-<source><![CDATA[<?xml version="1.0"?>
+<source><?xml version="1.0"?>

-<part xmlns="link:xsd:dpml/lang/dpml-part#1.0">
+<part xmlns="link:xsd:dpml/lang/dpml-part#1.0">

- <info/>
+ <info/>

- <component xmlns="link:xsd:dpml/lang/dpml-component#1.0"
type="org.acme.Widget"/>
+ <component
xmlns="link:xsd:dpml/lang/dpml-component#1.0"
+ type="org.acme.Widget"/>

- <classpath>
- <private>
- <uri>artifact:jar:acme/widget/acme-widget#1.2.3</uri>
- </private>
- </classpath>
+ <classpath>
+ <private>
+ <uri>artifact:jar:acme/widget/acme-widget#1.2.3</uri>
+ </private>
+ </classpath>

-</part>]]></source>
+</part></source>

</subsection>

Modified: trunk/central/site/src/docs/transit/config/index.xml
===================================================================
--- trunk/central/site/src/docs/transit/config/index.xml 2006-07-17
08:34:26 UTC (rev 1580)
+++ trunk/central/site/src/docs/transit/config/index.xml 2006-07-17
14:08:06 UTC (rev 1581)
@@ -79,8 +79,8 @@
<td>The proxy setting configuration.</td>
</tr>
<tr>
- <td><tt><a href="hosts.html">hosts</a></tt></td>
- <td>A colection of remote host definitions.</td>
+ <td><tt><a href="hosts/index.html">hosts</a></tt></td>
+ <td>A collection of remote host definitions.</td>
</tr>
</table>

Modified: trunk/central/site/src/docs/transit/navigation.xml
===================================================================
--- trunk/central/site/src/docs/transit/navigation.xml 2006-07-17 08:34:26
UTC (rev 1580)
+++ trunk/central/site/src/docs/transit/navigation.xml 2006-07-17 14:08:06
UTC (rev 1581)
@@ -26,6 +26,7 @@

<menu>
<item name="Overview" href="concepts/index.html"/>
+ <item name="Tutorials" href="tutorials/index.html"/>
<item name="System Properties" href="properties.html"/>
<item name="Cache Configuration" href="config/index.html"/>
<item name="Part Directive" href="parts/index.html"/>

Added: trunk/central/site/src/docs/transit/tutorials/artifacts.xml
===================================================================
--- trunk/central/site/src/docs/transit/tutorials/artifacts.xml 2006-07-17
08:34:26 UTC (rev 1580)
+++ trunk/central/site/src/docs/transit/tutorials/artifacts.xml 2006-07-17
14:08:06 UTC (rev 1581)
@@ -0,0 +1,153 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Resource Management</title>
+ </properties>
+
+ <body>
+
+ <section name="Transit Artifacts">
+
+ <subsection name="Tutorial Objective">
+
+ 
+ The aim of this tutorial is to establish a good understanding
+ of the term "artifact", the structure of an artifact URI, an the
+ role of the Transit system concerning resource retrieval, hosts,
+ and resource caching.
+ 
+
+ </subsection>
+
+ <subsection name="Definition of an Artifact">
+
+ 
+ An artifact is any streamable resource locatable using the
<code>artifact</code>
+ URL protocol. Examples of resources include - jar files, property
files, XML
+ files, files containing meta data, serialized objects, images, etc.
Resources
+ can be viewed as artifacts if they can be located using the
<code>artifact</code>
+ protocol. The protocol structure is as follows:
+ 
+
+ <code>artifact:[type]:[group]/[name]#[version]</code>
+
+ 
+ To locate a resource Transit maps the <code>[type], [group],
+ [name],</code> and <code>[version]</code> fields of the artifact URI
to a URL
+ using a layout assigned to a particular host defintion. The most
common layout
+ strategy (refered to as the classic layout) maps the artifact
specifications
+ according to the following rule:
+ 
+
+ <code>[host-address]/[group]/[type]s/[name]-[version].[type]</code>
+
+ 
+ The eclipse layout maps artifacts in accordance with the following
scheme:
+ 
+
+ <code>[host-address]/[group]-[version]/[name].[type]</code>
+
+ 
+ In addition to the above you can create and declare a custom layout
handler
+ via the Transit Management API via
<code>net.dpml.transit.model.LayoutRegistryModel</code>.
+ 
+
+ </subsection>
+
+ <subsection name="Using Artifacts">
+
+ 
+ The following testcase demonstrates the use of an artifact to
retrieve a property
+ file from a remote location and supply it as an input stream to a
Properties object.
+ The initial <code>setUp()</code> method handles the declaration of
the Artifact protocol handler
+ to the JVM. This is Transit's hook into the JVM's URL Hander object
model. Within the
+ <code>testPropertyLoading()</code> we construct a new URL using an
artifact specification
+ that declares a resource type of "properties", a group named
"dpml/test", the name
+ "example-property-file" and a version equal to "2.2". We then pass
the URLs resource
+ stream to a new Property instance and print out the value of a
property declared in the
+ properties resource.
+ 
+
+ Source:
<tt>trunk/validation/resources/src/test/net/osm/tutorial/TransitTestCase.java</tt>
+ <source>
+public class TransitTestCase extends TestCase
+{
+ protected void setUp() throws Exception
+ {
+ System.setProperty( "java.protocol.handler.pkgs", "net.dpml.transit"
);
+ }
+
+ public void testPropertyLoading() throws Exception
+ {
+ URL url = new URL(
"artifact:properties:dpml/test/example-property-file#2.2" );
+ InputStream input = url.openStream();
+ Properties properties = new Properties();
+ properties.load( input );
+ String message = properties.getProperty( "tutorial.message" );
+ System.out.println( message );
+ }
+}</source>
+ 
+ Testcase output:
+ 
+<pre> [x:junit] Executing forked test.
+ [x:junit] Running net.osm.tutorial.TransitTestCase
+ [x:junit] Welcome to the world of Transit!
+ [x:junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.344
sec</pre>
+
+
+ </subsection>
+
+
+ <subsection name="Behind the Scenes">
+
+ 
+ When the new URL constructor is invoked the JVM checks available
URLStreamHandlers
+ using a number of mechanisms - one of which is to check the value of
the
+ "java.protocol.handler.pkgs" system property. The JVM will look for
a protocol
+ handler named "net.dpml.transit" + [protocol].Handler. The
Transit's artifact
+ Handler class is primarily responsible for the establishment of a
ArtifactURLConnection.
+ The ArtifactURLConnection holds a reference to the Transit system.
When the openStream
+ operation is invoked the Artifact URL connection will use a cache
handler to resolve
+ the URL to a local cached resource. The cache handler will check
prioritized hosts for
+ the resource (converting the artifact to the appropriate URL for the
host as it evaluates
+ potential multiple candidates). When a host is located a network
service downloads the
+ resource to the local cache (itself equivalent to a local files
based repository). The
+ openStream() request is then delegated to the local resource.
+ 
+
+ </subsection>
+
+ <subsection name="Key Benefits">
+
+ <ul>
+ <li>Removal of "location" concerns from the codebase.</li>
+ <li>Notion of transport protocol is abstracted out.</li>
+ <li>Potential redundancy when a resource exists on multiple
hosts.</li>
+ <li>Configuration concerns are separted from usage.</li>
+ <li>Artifact structure encorages consistent naming patterns and
resource versioning.</li>
+ <li>Functionlity is encapsulated with the URL and URLConnection
object model.</li>
+ </ul>
+
+ </subsection>
+
+ <subsection name="Next Topic - Plugins">
+
+ 
+ This page has presented a more in-depth look at the
<tt>artifact</tt> protocol.
+ The <a href="plugins.html">next tutorial</a> introduced a simple
datatype called a
+ <tt>part</tt> that describes an object instantiation strategy with a
classloader
+ chain definition. This datatype is commonly referred to as a
<tt>plugin</tt> and
+ demonstrates the usage of one artifact to describe the usage of many
artifacts.
+ 
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: trunk/central/site/src/docs/transit/tutorials/index.xml
===================================================================
--- trunk/central/site/src/docs/transit/tutorials/index.xml 2006-07-17
08:34:26 UTC (rev 1580)
+++ trunk/central/site/src/docs/transit/tutorials/index.xml 2006-07-17
14:08:06 UTC (rev 1581)
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Resource Management</title>
+ </properties>
+
+ <body>
+
+ <section name="Resource Management Tutorial">
+
+ 
+ A common requirement across a broad-spectrum of software projects is
+ the management of resources such as configuration data, property
files,
+ meta information, classpath descriptions, etc. These resources can
form
+ a central part of well-functioning application and are frequently
handled
+ as identifiable and versioned artifacts.
+ This tutorial will take you through the usage of a product named
Transit that
+ handles retrieval of versioned resources using the standard Java URL
protocol
+ handler.
+ 
+
+ <subsection name="Tutorial Index">
+
+ <table>
+ <tr>
+ <td width="15%"><a href="overview.html">Introduction</a></td>
+ <td>
+ Overview of the Transit system and it's role in resource
management.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="artifacts.html">Artifacts</a></td>
+ <td>
+ Artifacts creation and usage.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="plugins.html">Plugins</a></td>
+ <td>
+ Classloader construction using plugins and the Transit
services.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="repositories.html">Repositories</a></td>
+ <td>
+ Creating your own repository.
+ </td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ </section>
+ </body>
+</document>
+

Added: trunk/central/site/src/docs/transit/tutorials/navigation.xml
===================================================================
--- trunk/central/site/src/docs/transit/tutorials/navigation.xml
2006-07-17 08:34:26 UTC (rev 1580)
+++ trunk/central/site/src/docs/transit/tutorials/navigation.xml
2006-07-17 14:08:06 UTC (rev 1581)
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+
+<project>
+
+ <title>OSM Guide</title>
+
+ <body>
+
+ <menu>
+ <item name="Introduction" href="overview.html"/>
+ <item name="Artifacts" href="artifacts.html"/>
+ <item name="Plugins" href="plugins.html"/>
+ <item name="Repositories" href="repositories.html"/>
+ </menu>
+
+ </body>
+
+</project>

Added: trunk/central/site/src/docs/transit/tutorials/overview.xml
===================================================================
--- trunk/central/site/src/docs/transit/tutorials/overview.xml 2006-07-17
08:34:26 UTC (rev 1580)
+++ trunk/central/site/src/docs/transit/tutorials/overview.xml 2006-07-17
14:08:06 UTC (rev 1581)
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Resource Management</title>
+ </properties>
+
+ <body>
+
+ <section name="Resource Management Overview">
+
+ <subsection name="Introduction to Transit Resource Managmeent">
+
+ A typical Transit URL is show below:
+
+ <code>artifact:jar:dpml/metro/dpml-metro-composition#3000</code>
+
+ 
+ The above URL is referencing a 'jar' resource within the group
'dpml/metro', named
+ 'dpml-metro-composition', and version '3000'. This information is
sufficient for
+ Transit to retrieve the resource from one of resurce hosts it is
associated with and
+ locally cache the resource.
+ 
+
+ In effect ...
+<pre>
+ |-----------------------------------|
+ | artifact:thing:mygroup/myname#123 | is a URI
+ |-----------------------------------|
+ |
+ | is handled by
+ |
+ |-----------------------------------| n 1 |-----------| 1 n
|----------------|
+ | net.dpml.transit.artifact.Handler | <>---- | Transit |
<>----| ResourceHost |
+ |-----------------------------------| |-----------|
|----------------|
+</pre>
+
+ 
+ Using URIs you can reference and work with resources in a more
abstract manner as your
+ dealing with a URI as opposed to a URL. A URI "identifies" a resource
whereas a URL
+ "locates" a resource. Transit maps URIs to URLs when interogating
+ resource host that are declared within the Tranist configuration. As
Transit
+ supports multiple hosts and multiple protocols you in effect remove
resource
+ location concerns from you code.
+ 
+
+ 
+ Here is an example of URI and URL construction:
+ 
+
+ <source>String path =
"artifact:jar:dpml/metro/dpml-metro-composition#3000";
+URI uri = new URI( path );
+URL url = uri.toURL();</source>
+
+ 
+ To use Transit in your application you will need to ensure that the
following two
+ conditions are met:
+ 
+
+ <ol>
+ <li>the system property <code>java.protocol.handler.pkgs</code> is
declared
+ with a value including <code>net.dpml.transit</code>. For
example: <code>
+ System.setProperty( "java.protocol.handler.pkgs", "net.dpml.transit"
);</code> </li>
+ <li>the <code>dpml-transit-main.jar</code> is included within the
system classloader</li>
+ </ol>
+
+ 
+ If you plan on using Transit in a production scenario you will want to
take a close
+ look at the information concerning the <a href="../config/index.html">
+ setup and configuration of Transit</a>.
+ 
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ 
+ This overview has presented Tranist in terms of its role as an
abstract protocol handler
+ and the mechanisms used to map transit uris to urls. The next
tutorial goes into
+ more detail concerning the <a href="artifacts.html">usage of the
<tt>artifact:</tt>
+ protocol</a> when handling simple resources such as property files,
xml data files,
+ etc.
+ 
+
+ </subsection>
+
+ </section>
+ </body>
+</document>
+

Added: trunk/central/site/src/docs/transit/tutorials/plugins.xml
===================================================================
--- trunk/central/site/src/docs/transit/tutorials/plugins.xml 2006-07-17
08:34:26 UTC (rev 1580)
+++ trunk/central/site/src/docs/transit/tutorials/plugins.xml 2006-07-17
14:08:06 UTC (rev 1581)
@@ -0,0 +1,204 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Resource Management</title>
+ </properties>
+
+ <body>
+
+ <section name="Transit Part Management">
+
+ <subsection name="Tutorial Objective">
+
+ 
+ The aim of this tutorial is to establish a good understanding
+ of the term "part" and how part management can help you
+ to build flexible and adaptive runtime system by leaveraging
+ Transit's cassloader construction services.
+ 
+
+ </subsection>
+
+ <subsection name="Definition of a Part">
+
+ 
+ A <code>part</code> is an resource type that is used to describe
+ a classloader chain. The part resource is an XML file that
+ declares the contents of an PUBLIC classloader, PROTECTED
classloader,
+ and an PRIVATE implementation classloader. Each classloader
definition is
+ expressed as a series of jar artifact uris. Transit provides
+ support for the construction of classloader chains based on the
+ information contained within the part definition. A chain is
+ constructed by creating an PUBLIC classloader as child of a supplied
+ parent classloader, a PROTECTED classloader as a child of the PUBLIC
classloader,
+ and a PRIVATE implementation classloader as a child of the PROTECTED
classloader.
+ 
+
+ 
+ In additon to classloader chain information, a part resource can
+ include the declaration of a deployment strategy. The Transit
system provides support
+ for 'plugin' strategies that enable declaration of a main class or
resource. The
+ combination of classloader chain with a deployment strategy combines
+ to provide a framework for plugable sub-systems deployment.
+ 
+
+ </subsection>
+
+ <subsection name="A sample part resource">
+
+ 
+ The following file is an example of a part resource. The
+ example is a development version of the part resource used to mount
the
+ runtime controller that executes within the Metro component
management
+ platform.
+ 
+
+ <source><![CDATA[<?xml version="1.0"?>
+<part xmlns="link:xsd:dpml/lang/dpml-part#1.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";>
+
+ <info title="Metro Container Runtime">
+ <description>DPML Component management platform runtime
container.</description>
+ </info>
+
+ <strategy xsi:type="plugin"
class="net.dpml.metro.runtime.CompositionController">
+ <param class="net.dpml.component.InitialContext"/>
+ </strategy>
+
+ <classpath>
+ <public>
+ <uri>artifact:jar:dpml/util/dpml-logging-api#1.0.0-RC8</uri>
+ </public>
+ <protected>
+ <uri>artifact:jar:dpml/metro/dpml-state-api#1.0.0-RC8</uri>
+ <uri>artifact:jar:dpml/metro/dpml-job-api#1.0.0-RC8</uri>
+ <uri>artifact:jar:dpml/transit/dpml-transit-main#1.0.0-RC8</uri>
+ <uri>artifact:jar:dpml/metro/dpml-metro-component#1.0.0-RC8</uri>
+ <uri>artifact:jar:dpml/metro/dpml-metro-model#1.0.0-RC8</uri>
+ </protected>
+ <private>
+ <uri>artifact:jar:dpml/metro/dpml-job-impl#1.0.0-RC8</uri>
+ <uri>artifact:jar:dpml/metro/dpml-state-impl#1.0.0-RC8</uri>
+ <uri>artifact:jar:dpml/metro/dpml-metro-runtime#1.0.0-RC8</uri>
+ </private>
+ </classpath>
+
+</part>
+]]></source>
+
+ </subsection>
+
+ <subsection name="Part Creation">
+
+ 
+ In practice the creation and maintenance of plugin information is
highly
+ error prone due to overall complexity of dependency management. This
was one
+ of the driving factors in the development of the Depot build system.
Depot
+ was developed from the ground up to provided full transitive
+ dependency management across build, runtime and test scopes. Using
the
+ Depot project model the job of creating a plugin definition is
reduced down
+ to type production declaration within a project definition.
+ 
+
+<pre>
+ <project name="dpml-metro-runtime" basedir="runtime">
+ <info title="Metro Container Runtime">
+ <description>
+ DPML Component management platform runtime container.
+ </description>
+ </info>
+ <types>
+ <type id="jar"/>
+ <part:plugin alias="true"
class="net.dpml.metro.runtime.CompositionController"/>
+ </types>
+ <dependencies>
+ <include ref="dpml/util/dpml-logging-api" tag="public"/>
+ <include key="dpml-metro-component" tag="protected"/>
+ <include key="dpml-metro-model" tag="protected"/>
+ <include ref="dpml/util/dpml-job-impl"/>
+ <include key="dpml-state-impl"/>
+ </dependencies>
+ <dependencies scope="test">
+ <include ref="ant/ant-junit"/>
+ </dependencies>
+ </project>
+</pre>
+
+ 
+ Observations concerning the above project definition with respect to
+ part datastructure creation:
+ 
+
+ <ul>
+ <li>The <tt>info</tt> element is mapped directory to a part info
declaration.</li>
+ <li>The <tt>part</tt> type element is mapped to a part deployment
<tt>strategy</tt>
+ definition.</li>
+ <li>All runtime dependencies are fully expanded relative to
respective runtime scope</li>
+ </ul>
+
+ </subsection>
+
+ <subsection name="Plugin Loading">
+
+ 
+ Transit provides a number of plugin related services including
loading of
+ plugin descriptor, creation of a plugin classloader chain, plugin
class
+ establishment, plugin instance establishment, and generic object
+ instantiation utility function. Collectively these methods make the
+ process of sub-systems creation a painless development process.
+ 
+
+ 
+ The following example demonstrates the creation of a plugin
sub-system
+ using Transit.
+ 
+
+ <source>
+ URI uri = new URI( "@METRO-RUNTIME-URI@" );
+ Part part = Part.load( uri );
+ Logger logger = getLogger();
+ m_handler = (ContentHandler) part.instantiate( new Object[]{ logger } );
+ </source>
+
+ 
+ The above code is typical in that it covers the following functions:
+ 
+
+ <ol>
+ <li>Establish the classloader that will serve as the anchor for
the classloader chain.</li>
+ <li>Create an artifact URI referencing a "plugin" resource.</li>
+ <li>Construct any objects that should be supplied as constructor
arguments.</li>
+ <li>Load the part definition.</li>
+ <li>Request part instantiation using supplied constructor
arguments.</li>
+ </ol>
+
+ 
+ Within production applications you would typically see a reasonable
amount of error
+ handling code wrapping the above code framgment. The error handling
code would typically
+ handle validation of the plugin either prior to instantiation or
part of a try catch block,
+ type checking, etc.
+ 
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ 
+ In the examples presented above we have demonstrated the usage of
Depot's project
+ definition as the source of information about project runtime
dependencies and
+ deployment information from which a part definition is created and
used at runtime
+ within an application. The next tutorial focussed on the <a
href="repositories.html">
+ underlying resource repositories</a> from which artifact uris are
resolved in terms of
+ physical resources.
+ 
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: trunk/central/site/src/docs/transit/tutorials/repositories.xml
===================================================================
--- trunk/central/site/src/docs/transit/tutorials/repositories.xml
2006-07-17 08:34:26 UTC (rev 1580)
+++ trunk/central/site/src/docs/transit/tutorials/repositories.xml
2006-07-17 14:08:06 UTC (rev 1581)
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Resource Management</title>
+ </properties>
+
+ <body>
+
+ <section name="Transit Repository Tutorial">
+
+ <subsection name="Tutorial Objectives">
+
+ 
+ The objective of this tutorial is to introduce the concept of a
resource
+ respository, to describe the role of local and remote repositories
in the
+ Transit system, and to show examples of definition and setup of a
private
+ repository.
+ 
+
+ </subsection>
+
+ <subsection name="What is a Repository?">
+
+ 
+ A repository is a resource server. Examples of repositories include
+ the HTTP based DPML Repository accessible under
+ <a
href="http://repository.dpml.net/classic/";>http://repository.dpml.net/classic</a>.
+ Techically this is simply a web server with content structured in
terms of groups
+ and resources named using a particular convention. The mapping
between an artifact
+ uri and a repository is handled by a Layout object that is declared
as part of a
+ resource host definition. A layout implementation translates the
artifact uri to
+ to a url relative to the target host structure. Using this model
Transit can provide
+ suport for varying repository access and transport strategies.
+ 
+
+ </subsection>
+
+ <subsection name="Creating a repository">
+
+ 
+ Transit's default ResourceHost implementation provides out of the
box support
+ for file, http and ftp based respository access. The simplest way
to create a new
+ repository is to setup a file based repository. This simply
involves the the creation
+ of the repository root directory, adding a group directory under the
root, adding
+ a directory named after the content type under the group directory,
then adding
+ your resources into the type directories using the naming convention
[name]-[version].[type]
+ or [name].[type] in the case of artifacts without a version. You
host defintion
+ simply references the root directory using the file: protocol as the
repository base
+ directory. Note - the above description is based on the 'classic'
layout strategy
+ used across the majority of know repositories and internally within
Transit's local
+ cache.
+ 
+
+ 
+ A more typical scenario is the establishment of a company wide
repository within a
+ local intranet. For this you need to setup a server (e.g. HTTP)
with a file based
+ resource handler then configure Transit by declaring a new remote
host and defintining
+ the host base url as the http server.
+ 
+
+ 
+ The following commandline operations demonstrate the setup of a new
local repository
+ using a file protocol referencing a root repository directory of
<tt>${dpml.data}/demo</tt>.
+ Symbolic expressions used within the host defintion may include any
system property and
+ core Transit location references (such as <tt>${dpml.home}</tt>).
+ 
+
+<pre>
+$ transit add host demo -url file:${dpml.data}/demo -priority 60
+</pre>
+
+ 
+ Once created the new repository can be listed using the following
command:
+ 
+
+<pre>
+$ transit info
+</pre>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

r1581 - in trunk/central: . site site/src/docs/metro/directives site/src/docs/transit site/src/docs/transit/config site/src/docs/transit/tutorials, mcconnell at BerliOS, 07/17/2006