notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

svn commit: r1842 - in development/laboratory/xsite/src/docs: magic/guide transit/MILESTONE/guide transit/MILESTONE/guide/plugins transit/MILESTONE/guide/plugins/cli transit/MILESTONE/guide/plugins/control transit/MILESTONE/guide/plugins/simple transit/MILESTONE/guide/resources transit/MILESTONE/overview transit/MILESTONE/setup

From: mcconnell AT netcompartner.com
To: notify-dpml AT lists.ibiblio.org
Subject: svn commit: r1842 - in development/laboratory/xsite/src/docs: magic/guide transit/MILESTONE/guide transit/MILESTONE/guide/plugins transit/MILESTONE/guide/plugins/cli transit/MILESTONE/guide/plugins/control transit/MILESTONE/guide/plugins/simple transit/MILESTONE/guide/resources transit/MILESTONE/overview transit/MILESTONE/setup
Date: Mon, 21 Feb 2005 07:08:17 +0100

Author: mcconnell
Date: Mon Feb 21 07:08:17 2005
New Revision: 1842

Added:
development/laboratory/xsite/src/docs/magic/guide/index.xml
development/laboratory/xsite/src/docs/magic/guide/navigation.xml
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/index.xml

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/navigation.xml
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins.xml
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/cli/

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/cli/index.xml

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/cli/navigation.xml

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/control/

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/control/index.xml

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/control/navigation.xml

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/index.xml

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/navigation.xml

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/simple/

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/simple/index.xml

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/simple/navigation.xml
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/resources/

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/resources/artifact.xml

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/resources/extension.xml

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/resources/index.xml

development/laboratory/xsite/src/docs/transit/MILESTONE/guide/resources/navigation.xml
Modified:

development/laboratory/xsite/src/docs/transit/MILESTONE/overview/classloading.xml

development/laboratory/xsite/src/docs/transit/MILESTONE/overview/plugins.xml
development/laboratory/xsite/src/docs/transit/MILESTONE/setup/index.xml
Log:
housekeeping

Added: development/laboratory/xsite/src/docs/magic/guide/index.xml
==============================================================================
--- (empty file)
+++ development/laboratory/xsite/src/docs/magic/guide/index.xml Mon Feb 21
07:08:17 2005
@@ -0,0 +1,40 @@
+<?xml version="1.0"?>
+
+
+
+<document>
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Guide</title>
+ </properties>
+
+ <body>
+ <section name="Magic Build System Guide">
+
+ <p>
+ COMMING SOON
+ </p>
+
+ </section>
+ </body>
+
+</document>
+
+
+
+

Added: development/laboratory/xsite/src/docs/magic/guide/navigation.xml
==============================================================================
--- (empty file)
+++ development/laboratory/xsite/src/docs/magic/guide/navigation.xml Mon
Feb 21 07:08:17 2005
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+
+<project>
+ <title>Metro</title>
+
+ <body>
+ <menu>
+ </menu>
+ </body>
+
+</project>

Added: development/laboratory/xsite/src/docs/transit/MILESTONE/guide/index.xml
==============================================================================
--- (empty file)
+++ development/laboratory/xsite/src/docs/transit/MILESTONE/guide/index.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Guide</title>
+ </properties>
+
+ <body>
+
+ <section name="Using Transit">
+
+ <p>
+ Transit: a sub-system that handles <a href="resources/index.html">
+ resource management</a>, classloader construction and
+ <a href="plugins/index.html">plugin</a> deployment based an an
underlying
+ protocol handler, local cache, and multiple mixed policy repositories.
+ A technical desctiption of Transit is provided under the
+ <a href="/products/transit/index.html">Transit Product</a>
+ pages.
+ </p>
+
+ <p>
+ Questions concerning guide content should be posted to the
+ <a href="/about/resources/lists.html">DPML Support mailing list</a>.
+ </p>
+
+ </section>
+ </body>
+</document>
+

Added:
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/navigation.xml
==============================================================================
--- (empty file)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/navigation.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+
+<project>
+
+ <title>DPML Guide</title>
+
+ <body>
+
+ <menu>
+ <item name="Resources" href="resources/index.html"/>
+ <item name="Plugins" href="plugins/index.html"/>
+ </menu>
+
+ </body>
+
+</project>

Added:
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins.xml
==============================================================================
--- (empty file)
+++ development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+
+<document>
+ <properties>
+ <author email="niclas AT hedhman.org">Niclas Hedhman</author>
+ <title>DPML Guide</title>
+ </properties>
+
+ <body>
+ <section name="Plugin Management">
+ <p>
+ The Transit Repository is a higher level system built on top of the
+ Transit artifact protocol handler. It allows you to load plugins from
+ central/remote locations and it will resolve its class dependencies
and
+ establish the classloader hierarchy for you.
+ </p>
+ <subsection name="Loading a Plugin">
+ <p>
+ The basic operation of loading a plugin is as follows;
+ </p>
+<source>
+ Repository repository = new StandardLoader();
+ ClassLoader parent = getClass().getClassLoader();
+ URI uri = new URI( "artifact:plugin:dpml/examples/hello/hello-world#1.0.0"
);
+ Object[] args = new Object[] { "Hello, World!" };
+ Object plugin = repository.getPlugin( parent, uri, args );
+</source>
+ <p>
+ Transit Repository will only instantiate the plugin, and not call
+ any other methods. The <code>args</code> in the snippet above will
be
+ passed to one of the constructors of the plugin. It will loop
through
+ each of the found constructors, and choose the one where each
supplied
+ argument is assignable.
+ </p>
+ </subsection>
+ <subsection name="Investigating a Plugin" >
+ </subsection>
+ <subsection name="Creating the Plugin descriptor with Magic.">
+ </subsection>
+ <subsection name="Creating the Plugin descriptor with Ant." >
+ </subsection>
+ </section>
+ </body>
+</document>
+
+

Added:
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/cli/index.xml
==============================================================================
--- (empty file)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/cli/index.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+
+<document>
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Guide</title>
+ </properties>
+
+ <body>
+ <section name="Enhancing the Simple Plugin">
+
+ <p>
+ This tutorial introduces some implementation changes to the Simple
Plugin
+ example. In particular we have included some functionality from the
+ commons-cli to handle the incomming arguments. This change impacts
our
+ implementation dependencies which are automatically reflected in the
+ plugin descriptor. During execution our controlling application is
+ using Transit to take care of the classloader management and
everything
+ proceeds witout any modification to the controlling system.
+ </p>
+
+ <subsection name="Enhanced Plugin Source">
+ <p>
+ The example plugin java source including CLI handling:
+ </p>
+<source><![CDATA[
+package tutorial.plugin;
+
+import org.apache.commons.cli.CommandLine;
+import org.apache.commons.cli.CommandLineParser;
+import org.apache.commons.cli.GnuParser;
+import org.apache.commons.cli.Option;
+import org.apache.commons.cli.OptionBuilder;
+import org.apache.commons.cli.Options;
+import org.apache.commons.cli.ParseException;
+
+
+/**
+ * A simple plugin enhanced to include cli handling.
+ *
+ * @author <a href="mailto:dev@dpmlnet";>Stephen J. McConnell</a>
+ */
+public class SimplePlugin
+{
+ //
------------------------------------------------------------------------
+ // static
+ //
------------------------------------------------------------------------
+
+ private static Options buildOptions()
+ {
+ Options options = new Options();
+ OptionBuilder.hasArg();
+ OptionBuilder.withArgName( "message-test" );
+ OptionBuilder.withDescription( "prints a message" );
+ Option option = OptionBuilder.create( "message" );
+ options.addOption( option );
+ return options;
+ }
+
+ //
------------------------------------------------------------------------
+ // constructors
+ //
------------------------------------------------------------------------
+
+ /**
+ * Creation of a new SimplePlugin instance.
+ *
+ * @param args the commandline arguments
+ */
+ public SimplePlugin( String[] args ) throws ParseException
+ {
+ Options options = buildOptions();
+ CommandLineParser parser = new GnuParser();
+ CommandLine line = parser.parse( options, args );
+
+ if( line.hasOption( "message" ) )
+ {
+ String message = line.getOptionValue( "message" );
+ System.out.println( message );
+ }
+ else
+ {
+ System.out.println( "Nothing to say." );
+ }
+ }
+}
+]]></source>
+
+ </subsection>
+
+ <subsection name="Plugin meta data">
+
+ <p>
+ If we look at the plugin meta data we see that the list of
+ implementation now includes the commons-cli package.
+ </p>
+
+<source>
+#
+# Implementation dependencies.
+#
+dpml.artifact.dependency.0 =
artifact:jar:dpml/transit/dpml-transit-main#SNAPSHOT
+dpml.artifact.dependency.1 = artifact:jar:commons-cli/commons-cli#1.0
+dpml.artifact.dependency.2 =
artifact:jar:dpml/tutorial/dpml-transit-tutorial-plugin-cli
+
+</source>
+
+ </subsection>
+
+ <subsection name="Executing the Plugin">
+
+ <p>
+ In the following example the command line arguments that are not
handled
+ by the Transit CLI handler are passed on to the plugin it is
loading. In particular
+ we are declaring a message using the -message option that we added
to the our plugin.
+ </p>
+
+ <pre>$ transit -load
artifact:plugin:dpml/tutorial/dpml-transit-tutorial-plugin-cli -message
Hello</pre>
+
+ <p>
+ The result of running the plugin is show below:
+ </p>
+
+ <pre>Hello</pre>
+
+ </subsection>
+
+ <subsection name="Next Step">
+
+ <p>
+ In the <a href="../control/index.html">next tutorial</a> we take
control
+ over plugin deployment.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
+
+

Added:
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/cli/navigation.xml
==============================================================================
--- (empty file)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/cli/navigation.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+
+<project>
+
+ <title>DPML Guide</title>
+
+ <body>
+
+ <menu>
+ </menu>
+
+ </body>
+
+</project>

Added:
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/control/index.xml
==============================================================================
--- (empty file)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/control/index.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,114 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+
+<document>
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Guide</title>
+ </properties>
+
+ <body>
+ <section name="Taking Control over Plugin Deployment">
+
+ <p>
+ In this tutorial we create a tiny plugin that takes control over the
+ creation and deployment of our simple cli-enhanced plugin.
+ </p>
+
+ <subsection name="Controller Source">
+ <p>
+ The following source code demonstrates has an application
+ can easily take control over plugin deployment.
+ </p>
+<source><![CDATA[
+package tutorial.plugin.controller;
+
+import java.net.URI;
+import java.net.URL;
+
+import net.dpml.transit.repository.Repository;
+import net.dpml.transit.repository.StandardLoader;
+
+/**
+ * A simple plugin enhanced to include cli handling.
+ *
+ * @author <a href="mailto:mcconnell AT dpml.net";>DPML Development</a>
+ */
+public class ControllerPlugin
+{
+ //
------------------------------------------------------------------------
+ // constructors
+ //
------------------------------------------------------------------------
+
+ /**
+ * A plugin deployed by the transit tool that controls the
+ * establishment of another plugin.
+ *
+ * @param args the commandline arguments
+ */
+ public ControllerPlugin( String[] args ) throws Exception
+ {
+ String spec =
"artifact:plugin:dpml/tutorial/dpml-transit-tutorial-plugin-cli";
+ URI uri = new URI( spec );
+ Repository repository = new StandardLoader();
+ ClassLoader classloader = getClass().getClassLoader();
+ Object[] params = new Object[]{ args };
+ Object plugin = repository.getPlugin( classloader, uri, params );
+
+ // ...
+
+ }
+
+}
+]]></source>
+
+ <p>
+ Execution of the above example is shown below.
+ </p>
+
+<pre>$ transit -load
artifact:plugin:dpml/tutorial/dpml-transit-tutorial-plugin-controller
-message "Good Morning!"</pre>
+
+ <p>
+ Output of the above is:
+ </p>
+
+<pre>Good Morning!</pre>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ The Transit Repository class provides support for the creation of
+ classloaders and for class instantiation. Different controllers
can
+ apply specialized lifecycle processing. For example the Transit ant
+ plugin task handles deployment of build listeners and antlib
whereas
+ more complex systems such as Metro use Transit to handle the
establish
+ of the underlying logging sub-system, system context, composition
model
+ and multiple runtime sub-systems.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
+
+

Added:
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/control/navigation.xml
==============================================================================
--- (empty file)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/control/navigation.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+
+<project>
+
+ <title>DPML Guide</title>
+
+ <body>
+
+ <menu>
+ </menu>
+
+ </body>
+
+</project>

Added:
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/index.xml
==============================================================================
--- (empty file)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/index.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+
+<document>
+ <properties>
+ <author email="niclas AT hedhman.org">Niclas Hedhman</author>
+ <title>DPML Guide</title>
+ </properties>
+
+ <body>
+ <section name="Plugin Management">
+ <p>
+ The Transit Repository is a higher level system built on top of the
+ Transit artifact protocol handler. It allows you to load plugins from
+ central/remote locations and it will resolve its class dependencies
and
+ establish the classloader hierarchy for you.
+ </p>
+
+ <subsection name="Loading a Plugin">
+ <p>
+ The basic operation of loading a plugin is as follows;
+ </p>
+<source>
+ Repository repository = new StandardLoader();
+ ClassLoader parent = getClass().getClassLoader();
+ URI uri = new URI( "artifact:plugin:dpml/examples/hello/hello-world#1.0.0"
);
+ Object[] args = new Object[] { "Hello, World!" };
+ Object plugin = repository.getPlugin( parent, uri, args );
+</source>
+ <p>
+ Transit Repository will only instantiate the plugin, and not call
+ any other methods. The <code>args</code> in the snippet above will
be
+ passed to one of the constructors of the plugin.
+ </p>
+ <p>
+ In the above example, we do not have Jar dependencies, but if we
did
+ those would be resolved and downloaded on demand as well as the
+ hello-world plugin.
+ </p>
+ <p>
+ Can you now imagine how easy it is to provide plugin capabilities,
+ hot-swap of subsystem, automatic upgrades and many other advanced
+ features for both the server as well the desktop applications?
+ </p>
+
+ </subsection>
+
+ </section>
+
+
+ </body>
+</document>
+
+

Added:
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/navigation.xml
==============================================================================
--- (empty file)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/navigation.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+
+<project>
+
+ <title>DPML Guide</title>
+
+ <body>
+
+ <menu>
+ <item name="Simple Plugin" href="simple/index.html"/>
+ <item name="Enhanced Plugin" href="cli/index.html"/>
+ <item name="Taking Control" href="control/index.html"/>
+ </menu>
+
+ </body>
+
+</project>

Added:
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/simple/index.xml
==============================================================================
--- (empty file)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/simple/index.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,170 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+
+<document>
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Guide</title>
+ </properties>
+
+ <body>
+ <section name="Simple Plugin">
+
+ <p>
+ This tutorial runs through the creation of a very simple plugin. It
+ demonstrates the creation of the plugin class and shows how the
plugin
+ can be loaded within an application or via the Transit command line
+ utility.
+ </p>
+
+ <subsection name="Plugin Source">
+ <p>
+ An example plugin java source:
+ </p>
+<source><![CDATA[
+package tutorial.plugin;
+
+/**
+ * A really simple plugin that just prints an array of messages to
+ * System.out.
+ */
+public class SimplePlugin
+{
+ public SimplePlugin( String[] messages )
+ {
+ for( int i=0; i<messages.length; i++ )
+ {
+ System.out.println( messages[i] );
+ }
+ }
+}
+]]></source>
+
+ </subsection>
+
+ <subsection name="Generating the Plugin meta data">
+
+ <p>
+ A plugin is described using a <code>.plugin</code> file that
contains
+ information such as the name of the class and a list jar files
needed
+ to construct a classloader for plugin deployment. The following
ant
+ build file demonstrates the use of the
<code><x:export></code>
+ task which is used to generate plugin meta data automatically
based on
+ the dependencies declared under the Magic build system.
+ </p>
+ <p>
+ Example build.xml:
+ </p>
+
+<source><![CDATA[<project name="dpml-transit-tutorial-plugin-simple"
default="install" basedir="."
+ xmlns:transit="antlib:net.dpml.transit"
xmlns:x="plugin:dpml/magic/dpml-magic-core" >
+
+
+ <transit:import uri="artifact:template:dpml/magic/standard"/>
+
+ <target name="package" depends="standard.package">
+ <x:export class="tutorial.plugin.SimplePlugin"/>
+ </target>
+
+</project>]]></source>
+
+ </subsection>
+
+ <subsection name="Plugin meta data">
+
+ <p>
+ After executing the build (using ant) the following plugin
descriptor
+ is created under the ${basedir}/target/deliverables/plugins
directory. It
+ contains the name of the plugin class and the names of the jar
files
+ needed to construct the plugin. The plugin data file is itself
registered
+ in your local cache directory and can be referenced using the
Transit
+ artifact protocol.
+ </p>
+
+<source>
+#
+# Specification classifier.
+#
+dpml.plugin.meta.namespace = net.dpml
+dpml.plugin.meta.version = 1.0
+
+#
+# Artifact descriptor.
+#
+dpml.artifact.group = dpml/tutorial
+dpml.artifact.name = dpml-transit-tutorial-plugin-simple
+dpml.artifact.version = null
+dpml.artifact.signature = 20041204.082137
+
+#
+# Type.
+#
+dpml.plugin.class = tutorial.plugin.SimplePlugin
+
+#
+# Implementation dependencies.
+#
+dpml.artifact.dependency.0 =
artifact:jar:dpml/transit/dpml-transit-main#SNAPSHOT
+dpml.artifact.dependency.1 =
artifact:jar:dpml/tutorial/dpml-transit-tutorial-plugin-simple
+
+#
+# EOF.
+#
+</source>
+
+ </subsection>
+
+ <subsection name="Executing the Plugin">
+
+ <p>
+ The establishment of a plugin is the reposibility of the Transit
+ repository. Actual deployment of the plugin is the responsibility
+ of a managing application. In the following example we will use
+ the Transit CLI utility to run the plugin.
+ </p>
+
+ <pre>$ transit -load
artifact:plugin:dpml/tutorial/dpml-transit-tutorial-plugin-simple Hello.</pre>
+
+ <p>
+ The above command simply instructs Transit to load the plugin
described by
+ plugin referenced under the -load option and passes any command
line arguments
+ on to the plugin. The result of running the plugin is show below:
+ </p>
+
+ <pre>Hello.</pre>
+
+ </subsection>
+
+ <subsection name="Next Step">
+
+ <p>
+ In the <a href="../cli/index.html">next tutorial</a> we do some
implemetation
+ changes involving the addition of cli handling using the
commons-cli package and
+ look at the impact on our plugin metadata.
+ </p>
+
+ </subsection>
+
+
+ </section>
+
+ </body>
+</document>
+
+

Added:
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/simple/navigation.xml
==============================================================================
--- (empty file)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/plugins/simple/navigation.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+
+<project>
+
+ <title>DPML Guide</title>
+
+ <body>
+
+ <menu>
+ </menu>
+
+ </body>
+
+</project>

Added:
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/resources/artifact.xml
==============================================================================
--- (empty file)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/resources/artifact.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Guide</title>
+ </properties>
+
+ <body>
+ <section name="Using the transit protocol Handler">
+
+ <p>
+ The following testcase demonstrates the use of a transit protocol
+ handler when constructing a new URL. The advantages of this approach
+ is that your application is not dependent on any jvm configuration
+ prerequisited. However, you code is dependent on a reference to the
+ Transit Handler class.
+ </p>
+
+ <p>
+ <i>Example:</i>
+ </p>
+<source>String spec = "artifact:spec:tutorial/example-property-file";
+URL url = new URL( null, spec, new net.dpml.transit.artifact.Handler() );
+</source>
+
+ <subsection name="Testcase Examples">
+
+<source>
+package tutorial.artifact;
+
+import java.io.File;
+import java.io.InputStream;
+import java.util.Properties;
+import java.net.URL;
+
+import net.dpml.transit.artifact.Handler;
+
+import junit.framework.TestCase;
+
+/**
+ * Example of loading a property file using the artifact protocol and
explicit
+ * handler declaration.
+ *
+ * @author <a href="mailto:dev-dpml AT lists.ibiblio.org";>The Digital Product
Meta Library</a>
+ */
+public class ExampleTestCase extends TestCase
+{
+ protected void setUp() throws Exception
+ {
+ File basedir = new File( System.getProperty( "project.dir" ) );
+ File authority = new File( basedir, "dpml.transit.authority" );
+ System.setProperty( "dpml.transit.authority.file",
authority.getAbsolutePath() );
+ }
+
+ public void testPropertyLoading() throws Exception
+ {
+ Properties properties = new Properties();
+ URL url = new URL( null,
"artifact:spec:tutorial/example-property-file", new Handler() );
+ InputStream input = url.openStream();
+ properties.load( input );
+ String message = properties.getProperty( "tutorial.message" );
+ System.out.println( message );
+ }
+}
+</source>
+
+ <p>
+ Output from the above testcase is shown below:
+ </p>
+<pre>
+test:
+ [x:junit] executing in local jvm
+ [x:junit] Running tutorial.artifact.ExampleTestCase
+ [x:junit] Hello!
+ [x:junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.188 sec
+</pre>
+ </subsection>
+
+ </section>
+ </body>
+</document>
+

Added:
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/resources/extension.xml
==============================================================================
--- (empty file)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/resources/extension.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Guide</title>
+ </properties>
+
+ <body>
+
+ <section name="Setting Transit as a system-wide protocol handler">
+
+ <p>
+ After Transit has been properly installed on a host, a
+ Transit-agnostic application that retrieves resources by the
+ <code>java.net.URL</code> can be Transit enabled just by including
+ the Transit jar file in the system or extension classloader and
setting
+ a system property. Then Jar files can be referenced with the
artifact:
+ protocol, just like png, jpg or xml files. Even the URLClassLoader
+ will automatically utilize the artifact: protocol.
+ </p>
+
+ <p>
+ The following testcase demonstrates the declaration of Transit
+ as a jvm-wide protocol handler. The advantages of this approach
+ is that client code does not need to reference transit classes.
+ </p>
+
+ <p>
+ <i>Example:</i>
+ </p>
+<source>URL url = new URL( "artifact:spec:tutorial/example-property-file" );
+</source>
+
+ <subsection name="Testcase Example">
+
+ <p>
+ The setup of the Transit handler as part of the JVM is described in
+ the following example.
+ </p>
+
+<source>package tutorial.extension;
+
+import java.io.InputStream;
+import java.util.Properties;
+import java.net.URL;
+
+import junit.framework.TestCase;
+
+/**
+ * Example of loading a property file using the artifact protocol with
+ * the protocol handler setup as part of the jvm.
+ *
+ * @author <a href="mailto:dev-dpml AT lists.ibiblio.org";>The Digital Product
Meta Library</a>
+ */
+public class ExampleTestCase extends TestCase
+{
+ protected void setUp() throws Exception
+ {
+ System.setProperty( "java.protocol.handler.pkgs", "net.dpml.transit"
);
+ System.setProperty( "dpml.transit.authority.file",
"target/test/dpml.transit.authority" );
+ }
+
+ public void testPropertyLoading() throws Exception
+ {
+ Properties properties = new Properties();
+ URL url = new URL( "artifact:spec:tutorial/example-property-file" );
+ InputStream input = url.openStream();
+ properties.load( input );
+ String message = properties.getProperty( "tutorial.message" );
+ System.out.println( message );
+ }
+}
+</source>
+
+ <p>
+ Output from the above testcase is shown below:
+ </p>
+<pre>
+test:
+ [x:junit] Executing forked test.
+ [x:junit] Running tutorial.extension.ExampleTestCase
+ [x:junit] Hello!
+ [x:junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.125 sec
+</pre>
+
+ </subsection>
+
+ <subsection name="Installing Transit as a system wide protocol
handler.">
+
+ <p>
+ <i>Please note that this information is only relevant when using
Transit
+ outside of Metro or Magic.</i>
+ </p>
+
+ <p>
+ To install transit as a system wide protocol handler you need to
do two things;
+ </p>
+ <ol>
+ <li>
+ Put the dpml-transit-main.jar in the system or extension
classpath.
+ </li>
+ <li>
+ Set the system property
<strong>"java.protocol.handler.pkgs"</strong>
+ to <strong>"net.dpml.transit"</strong> in the application's
launcher,
+ i.e.
+<source> java -Djava.protocol.handler.pkgs=net.dpml.transit ... </source>
+ </li>
+ </ol>
+ <p>
+ You should probably also take a look at settings of the
authorative
+ host and its associated resource hosts, by default installed at
+ ${dpml.home}/transit/authority
+ </p>
+ <p>
+ If you have a large number of hosts that needs the same resource
host
+ configuration, you move the ${dpml.home}/transit/authority
+ content to a LAN based server, and change the property found in the
+ ${dpml.home}/transit/dpml.transit.authority file to point
+ to that location. You will also need to create a file named
+ <strong><i>index.lst</i></strong> on that server, which lists all
the
+ resource host files at that location.
+ </p>
+ </subsection>
+
+ <subsection name="Troubleshooting" >
+ <p>
+ Unfortunately there are a few things that can go wrong, and as we
gain
+ more experience we will add them as they appear here.
+ </p>
+ <table>
+ <tr>
+ <th>Problem</th>
+ <th>Solution</th>
+ </tr>
+ <tr>
+ <td>I get "Artifact AUTHORITY can not be established."</td>
+ <td>
+ The Authorative Host could not be established, for one of many
+ reasons. First of all check that the environment variable
+ DPML_HOME (if present) points to a valid Transit installation.
+ Then make sure that if the system property "dpml.home" is
present,
+ that it points to a proper Transit installation. Then make
sure
+ that you have a file named
+ ${dpml.home}/transit/dpml.transit.authority, and that it
contains
+ a property named "dpml.transit.authority" which either points
to
+ a URL or a file (no protocol defined), and if it is file based
+ that the location is relative to ${dpml.home}/transit. Finally,
+ the location specified must be a directory, and that directory
+ must contain one or more resource host definitions, plus it
must
+ contain a transit configruation and a cache configuration file.
+ </td>
+ </tr>
+ <tr>
+ <td>I get "Unknown protocol: artifact" when I instantiate a
URL.</td>
+ <td>
+ This means that the java.net package doesn't manage to locate
the
+ Transit protocol handler. One of two possible reasons. Either
you
+ have not managed to properly set up the system property
+ "java.protocol.handler.pkgs" to "net.dpml.transit", OR the
+ dpml-transit-main.jar file is not in the <strong>system
classpath
+ </strong> or higher up in the classloader chain. Due to a bug
in
+ the protocol handler code in the JVM, the classloader of the
+ calling class is not used as intended, and the JVM will
fallback
+ to use ClassLoader.getSystemClassLoader() to locate the
protocol
+ handler. If this is not possible in your application, you can
+ also enforce the proper handler for the URL using the
+ <code>new URL( null, spec, new Handler() )</code> format
described
+ above.
+ </td>
+ </tr>
+ </table>
+ </subsection>
+
+
+
+ </section>
+
+ </body>
+</document>
+

Added:
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/resources/index.xml
==============================================================================
--- (empty file)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/resources/index.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT dpml.net">Stephen McConnell</author>
+ <title>DPML Guide</title>
+ </properties>
+
+ <body>
+ <section name="Resource Management">
+
+ <subsection name="Transit repository basics." >
+ <p>
+ Transit is a light-weight solution to a common problems. Transit
allows
+ almost any existing application to access centrally located
resources,
+ without having the application knowing the location of these
resources,
+ yet have the resources cached locally for performance reasons.
+ </p>
+ <p>
+ There are a number of public central repositories on the Internet
today, most
+ notably
+ <a
href="http://repository.dpml.net/classic";>http://repository.dpml.net/classic</a>,

+ <a
href="http://www.ibiblio.org/maven";>http://www.ibiblio.org/maven</a> and
+ <a
href="http://www.apache.org/dist/java-repository";>http://www.apache.org/dist/java-repository</a>.
+ But it is very easy to set up and configure your own central
repository.
+ </p>
+ </subsection>
+
+ <subsection name="Transit Tutorials">
+
+ <p>
+ The following tutorials present alternative approaches to
+ the use of trasit artifact urls.
+ </p>
+
+ <table>
+ <tr><th>Topic</th><th>Summary</th></tr>
+ <tr>
+ <td><a href="artifact.html">Creating a Artifact URL</a></td>
+ <td>
+ Tutorial describes the creation and use of an Artifact URL
+ using a supplied protocol Handler.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="extension.html">Using a system wide protocol
handler.</a></td>
+ <td>
+ Tutorial covering the declaration of the transit protocol
handler
+ to the JVM and the subsequent use of the handler independently
of
+ the Transit API.
+ </td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ </section>
+ </body>
+</document>
+

Added:
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/resources/navigation.xml
==============================================================================
--- (empty file)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/guide/resources/navigation.xml
Mon Feb 21 07:08:17 2005
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+
+<project>
+
+ <title>DPML Guide</title>
+
+ <body>
+
+ <menu>
+ <item name="Transit Handler" href="artifact.html"/>
+ <item name="System Extension" href="extension.html"/>
+ </menu>
+
+ </body>
+
+</project>

Modified:
development/laboratory/xsite/src/docs/transit/MILESTONE/overview/classloading.xml
==============================================================================
---
development/laboratory/xsite/src/docs/transit/MILESTONE/overview/classloading.xml
(original)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/overview/classloading.xml
Mon Feb 21 07:08:17 2005
@@ -51,14 +51,14 @@
construct a classloader chain.
</p>

- <img src="/images/transit/@TRANSIT-BUILD-ID@/chain.png"/>
+ <img src="/images/transit/chain.png"/>

<p>
Plugin files use a simple property file format to declare features of
of the classloader, including information used when resolving
plugins.
This information is normally created automatically using the
- <a href="/products/magic/tasks/export.html">Export Task</a> from the
- <a href="/products/magic/index.html">Magic</a> build system.
+ <a href="/magic/tasks/export.html">Export Task</a> from the
+ <a href="/magic/index.html">Magic</a> build system.
</p>

<p>

Modified:
development/laboratory/xsite/src/docs/transit/MILESTONE/overview/plugins.xml
==============================================================================
---
development/laboratory/xsite/src/docs/transit/MILESTONE/overview/plugins.xml
(original)
+++
development/laboratory/xsite/src/docs/transit/MILESTONE/overview/plugins.xml
Mon Feb 21 07:08:17 2005
@@ -150,7 +150,7 @@
</p>
<p>
Examples of plugin loading and general plugin handling is provided
- under the <a
href="/guide/transit/@TRANSIT-BUILD-ID@/plugins/index.html">Transit Guide</a>.
+ under the <a href="../guide/plugins/index.html">Transit Guide</a>.
</p>
</section>
</body>

Modified:
development/laboratory/xsite/src/docs/transit/MILESTONE/setup/index.xml
==============================================================================
--- development/laboratory/xsite/src/docs/transit/MILESTONE/setup/index.xml
(original)
+++ development/laboratory/xsite/src/docs/transit/MILESTONE/setup/index.xml
Mon Feb 21 07:08:17 2005
@@ -42,7 +42,7 @@
<td>Windows Binary (zip distribution)</td>
<td>
<a
href="http://store.dpml.net/milestones/transit/@TRANSIT-BUILD-ID@/dpml-transit-win32-@TRANSIT-BUILD-ID@.zip";>
- dpml-home-@TRANSIT-BUILD-ID@.zip</a>
+ dpml-transit-win32-@TRANSIT-BUILD-ID@.zip</a>
</td>
<td>
<a
href="http://store.dpml.net/milestones/transit/@TRANSIT-BUILD-ID@/dpml-transit-win32-@TRANSIT-BUILD-ID@.zip.md5";>MD5</a>
@@ -55,7 +55,7 @@
<td>Linux Binary (tar.gz distribution)</td>
<td>
<a
href="http://store.dpml.net/milestones/transit/@TRANSIT-BUILD-ID@/dpml-transit-linux-@TRANSIT-BUILD-ID@.tar.gz";>
- dpml-home-@TRANSIT-BUILD-ID@.zip</a>
+ dpml-transit-linux-@TRANSIT-BUILD-ID@.zip</a>
</td>
<td>
<a
href="http://store.dpml.net/milestones/transit/@TRANSIT-BUILD-ID@/dpml-transit-linux-@TRANSIT-BUILD-ID@.tar.gz.md5";>MD5</a>

svn commit: r1842 - in development/laboratory/xsite/src/docs: magic/guide transit/MILESTONE/guide transit/MILESTONE/guide/plugins transit/MILESTONE/guide/plugins/cli transit/MILESTONE/guide/plugins/control transit/MILESTONE/guide/plugins/simple transit/MILESTONE/guide/resources transit/MILESTONE/overview transit/MILESTONE/setup, mcconnell, 02/21/2005