Skip to Content.
Sympa Menu

notify-dpml - svn commit: r1484 - in development/main/central/site/src/docs/products/transit: . overview

notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

Chronological Thread  
  • From: niclas AT netcompartner.com
  • To: notify-dpml AT lists.ibiblio.org
  • Subject: svn commit: r1484 - in development/main/central/site/src/docs/products/transit: . overview
  • Date: Sun, 16 Jan 2005 09:24:01 +0100

Author: niclas
Date: Sun Jan 16 09:24:01 2005
New Revision: 1484

Modified:
development/main/central/site/src/docs/products/transit/index.xml

development/main/central/site/src/docs/products/transit/overview/artifact.xml

development/main/central/site/src/docs/products/transit/overview/classloading.xml
development/main/central/site/src/docs/products/transit/overview/index.xml

development/main/central/site/src/docs/products/transit/overview/plugins.xml
Log:
Touching up the Transit documentation.

Modified: development/main/central/site/src/docs/products/transit/index.xml
==============================================================================
--- development/main/central/site/src/docs/products/transit/index.xml
(original)
+++ development/main/central/site/src/docs/products/transit/index.xml Sun
Jan 16 09:24:01 2005
@@ -1,21 +1,21 @@
<?xml version="1.0" encoding="ISO-8859-1"?>

-<!--
+<!--
Copyright 2005 David Leangen
Copyright 2004 Stephen McConnell
Copyright 2004 Niclas Hedhman

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
+ You may obtain a copy of the License at
+
http://www.dpml.net/central/about/legal/
-
+
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied.
-
+
See the License for the specific language governing permissions and
limitations under the License.
-->
@@ -26,9 +26,9 @@
<author email="niclas AT hedhman.org">Niclas Hedhman</author>
<author email="david.leangen AT konova.com">David Leangen</author>
<title>DPML Transit</title>
- </properties>
+ </properties>

- <body verified="false">
+ <body verified="true">
<section name="Transit Resource Management System">


@@ -37,17 +37,17 @@
<ul>
<li><a href="overview/artifact.html">dynamically retrieving</a>
system and application resources</li>
<li><a href="overview/classloading.html">constructing</a>
classloaders</li>
- <li><a href="overview/management.html">managing</a> plugins</li>
+ <li><a href="overview/plugins.html">managing</a> plugins</li>
</ul>
</p>

<p>
- As a resource management system, Transit provides the foundation for
building
+ As a resource management system, Transit provides the foundation for
building
<a href="overview/index.html">repository-enabled applications</a>.
</p>

<img src="/images/transit/repositories.png"/>
-
+
<p>
Learn more about
<a href="overview/index.html">Transit features and benefits</a>.

Modified:
development/main/central/site/src/docs/products/transit/overview/artifact.xml
==============================================================================
---
development/main/central/site/src/docs/products/transit/overview/artifact.xml
(original)
+++
development/main/central/site/src/docs/products/transit/overview/artifact.xml
Sun Jan 16 09:24:01 2005
@@ -5,7 +5,7 @@
<author email="mcconnell AT dpml.net">Stephen McConnell</author>
<author email="dleangen AT dpml.net">David Leangen</author>
<title>DPML Transit</title>
- </properties>
+ </properties>

<body verified="false">
<section name="Dynamic Artifact Retrieval">
@@ -14,7 +14,7 @@
An <strong>artifact</strong> is simply a resource used by a Java
application. Basically, an artifact can be any type of file:
JAR, image, text...
- Based on its protocol specification, Transit provides for dynamic
+ Based on its protocol specification, Transit provides for dynamic
retrieval of such artifacts.
</p>

@@ -22,12 +22,12 @@
<p>
Each artifact has a unique identifier conforming to the Transit
<a href="../technical/protocol/index.html">protocol
specification</a>.
- Using an extension to the xxxxxxx class in the Java API, Transit
+ Using an extension to the java.net.URL class in the Java API,
Transit
accesses an artifact through an <strong>artifact URI</strong>.
The artifact URI thus serves the dual purpose of identifying the
artifact and providing a means for Transit to retrieve the file.
</p>
-
+
<p>
The artifact URI describes the:
<ul>
@@ -37,41 +37,56 @@
<li>version</li>
</ul>
</p>
-
+
<p>
- Typically, an artifact is a JAR file, a <a href="">meta</a> file,
- or a <a href="">block</a> descriptor file.
+ Typically, an artifact is a JAR file, a
+ <a invalid="true" href="">meta</a> file,
+ or a <a
href="../../metro/composition/directives/container/index.html">
+ block</a> descriptor file.
However, there is no limitation to the type of resource that an
artifact
- can be. Essentially, you can use the Transit system to manage
virtually
+ can be. Essentially, you can use the Transit system to manage
virtually
any type of resource.
</p>
-
- <p>
- The group is an arbitrary grouping of resources that is decided by
- the developer. [[need a better way of saying this]]
- </p>
-
+
<p>
- [[Need some explanation of version]]
+ The purpose of the group is to avoid naming conflicts in the
artifact
+ name space. The top level group should be a distinguishable and
well
+ accepted name of the organisation, and any sub groups to be decided
+ by the organisation itself to further avoid name clashes.
+ It is recommended that the bottom level group is the release
level, i.e.
+ all resources within the 'release' shares the same version and are
+ meant to be working in a group within that version, and not mixed
+ between versions.
</p>
-
+
<p>
- [[Point to best practices for naming and managing projects]]
+ Transit promotes strong version management. The underlying problem
is
+ that many parts of the system are dependent on particular versions
of
+ another part or resource, and can not be freely mixed. To ensure
+ that all dependencies are resolved against the proper versions, it
is
+ paramount that a version management system is in place, and
policies
+ are established. From Transit's point of view, the version is an
+ opaque identifier without any in-built semantic meaning.
</p>
-
+
<p>
- These identifiers dissassociate the definition of an application
- from the source of the resources needed to build and deploy the
- application.
-
- [[Not sure what you're trying to say here...]]
+ These identifiers disassociate the definition of an application
+ from the source of the resources needed to build and deploy the
+ application. Meaning, it is only in the interest of the user of
+ the resources, be it built tools or running applications, that the
+ <strong>correct</strong> resources are provided, and not from which
+ server these were downloaded. The task of resolving the location
+ is transferred from each application to Transit itself, which is
+ configured to know about which servers are available in its running
+ environment.
</p>

</subsection>
-
+
<subsection name="Artifact Retrieval">
+
</subsection>
-
+
</section>
</body>
</document>

Modified:
development/main/central/site/src/docs/products/transit/overview/classloading.xml
==============================================================================
---
development/main/central/site/src/docs/products/transit/overview/classloading.xml
(original)
+++
development/main/central/site/src/docs/products/transit/overview/classloading.xml
Sun Jan 16 09:24:01 2005
@@ -1,21 +1,21 @@
<?xml version="1.0" encoding="ISO-8859-1"?>

-<!--
+<!--
Copyright 2005 David Leangen
Copyright 2004 Stephen McConnell
Copyright 2004 Niclas Hedhman

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
+ You may obtain a copy of the License at
+
http://www.dpml.net/central/about/legal/
-
+
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied.
-
+
See the License for the specific language governing permissions and
limitations under the License.
-->
@@ -26,17 +26,18 @@
<author email="niclas AT hedhman.org">Niclas Hedhman</author>
<author email="david.leangen AT konova.com">David Leangen</author>
<title>DPML Transit</title>
- </properties>
+ </properties>

<body verified="false">
<section name="Classloader Construction">

<p>
- Layered above the Transit artifact handler is a system that provides
- support for the creation of classloaders. Classloaders are described
- under a 'meta' file which is basically a list of artifact uris. The
- meta file is itself normally referenced as an artifact which means
- that the list is itself versioned, named, associated with a group,
and
+ Layered above the Transit artifact protocol handler is a system that
+ provides support for the creation of classloaders. Classloaders are
+ described under a 'meta' file which is basically a list of dependent
+ artifact uris and their location in the classloader hierarchy. The
+ meta file is itself normally referenced as an artifact which means
+ that the list is itself versioned, named, associated with a group,
and
dynamically resolvable.
</p>

@@ -45,23 +46,23 @@
<code>@METRO-PLUGIN-URI@</code>

<p>
- The meta file declares api, spi and implementation jar files in
- the form of artifact uris. Transit uses this infomation to
+ The meta file declares api, spi and implementation jar files in
+ the form of artifact uris. Transit uses this infomation to
construct a classloader chain.
</p>

<img src="/images/transit/chain.png"/>

<p>
- Meta files use a simple property file format to declare features of
+ Meta 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
+ 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.
</p>

<p>
- The following code fragment demonstrates the relativly simple
process of
+ The following code fragment demonstrates the relativly simple
process of
creating a new classloader using Transit.
</p>


Modified:
development/main/central/site/src/docs/products/transit/overview/index.xml
==============================================================================
---
development/main/central/site/src/docs/products/transit/overview/index.xml
(original)
+++
development/main/central/site/src/docs/products/transit/overview/index.xml
Sun Jan 16 09:24:01 2005
@@ -1,21 +1,21 @@
<?xml version="1.0" encoding="ISO-8859-1"?>

-<!--
+<!--
Copyright 2005 David Leangen
Copyright 2004 Stephen McConnell
Copyright 2004 Niclas Hedhman

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
+ You may obtain a copy of the License at
+
http://www.dpml.net/central/about/legal/
-
+
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied.
-
+
See the License for the specific language governing permissions and
limitations under the License.
-->
@@ -26,7 +26,7 @@
<author email="niclas AT hedhman.org">Niclas Hedhman</author>
<author email="david.leangen AT konova.com">David Leangen</author>
<title>DPML Transit</title>
- </properties>
+ </properties>

<body verified="false">

@@ -34,26 +34,32 @@

<p>
One of the more difficult tasks when building Java applications
- is managing <a href="">classloaders</a>. Oftentimes, when combining
- various projects together into an enterprise application, because
- of Java's classloading mechanism, the application is not able to
- load the right classes at the right time, causing the application
- to fail. Although a fundamental issue, classloading has remained
+ is managing <a href="">classloaders</a>. Often, when combining
+ various projects together into an enterprise application, the
+ application is not able to load the right classes at the right time,
+ causing the application to fail in mysterious and sometimes subtle
+ ways.
+ Although a fundamental issue, classloading has remained
a rather obscure topic. Not surprisingly, many Java projects fail
to manage classloaders effectively.
</p>
-
+
<p>
Transit provides a solution to this problem.
</p>

<p>
- At core of Transit is a URL protocol handler.
- Based on the protocol handler, Transit is able to manage classloaders
- effectively. This allows an application to provide more advanced
services
- such as a plugin framework.
+ At the core of Transit is a URL protocol handler, a classloader meta
+ information descriptor and plugin loader.
+ Based on these, Transit is able to manage classloaders, not only
+ effectively and nearly invisible to the casual user, but in a
location
+ independent way. That means, applications don't need to be concerned
over
+ where the jars and other resources are located, whether on the local
file
+ system, on LAN servers or somewhere on the Internet.
+ This allows an application to provide extendability, hot-redeploy
+ and more advanced services.
</p>
-
+
<p>
In other words, Transit helps to realize the full potential of a
Java application.

Modified:
development/main/central/site/src/docs/products/transit/overview/plugins.xml
==============================================================================
---
development/main/central/site/src/docs/products/transit/overview/plugins.xml
(original)
+++
development/main/central/site/src/docs/products/transit/overview/plugins.xml
Sun Jan 16 09:24:01 2005
@@ -5,47 +5,148 @@
<author email="mcconnell AT dpml.net">Stephen McConnell</author>
<contributor email="dleangen AT dpml.net">David Leangen</contributor>
<title>DPML Transit</title>
- </properties>
+ </properties>

<body verified="false">
<section name="Plugin Management">
-
+
<p>
In addition to the structural classloader information - the meta file
- may contain the declaration of a main class or and antlib resource
and
- namespace. The antlib information is a special case used within the
- Magic build system to support dynamic task loading. The main class
+ may contain the declaration of a main class or an antlib resource and
+ namespace. The antlib information is a special case used within the
+ Magic build system to support dynamic task loading. The main class
declaration is the entry point for classic plugin class loading
relative
to the established classloader.
</p>

<p>
- The Transit repository service provides support for class creation
and
+ The Transit repository service provides support for class creation
and
object instantiation. Class creation is typically used by
applications
- that handle a particular semantics concerning a plugin model whereas
- the Tranit object instantiation provides a simple but flexible model
- suitable for control over selectable sub-system strategies (e.g. the
+ that handle a particular semantics concerning a plugin model whereas
+ the Tranit object instantiation provides a simple but flexible model
+ suitable for control over selectable sub-system strategies (e.g. the
loading of a logging system or application runtime).
</p>

<p>
- The following code fragment demonstrates the creation of a plugin
instance
+ The following code fragments demonstrates the creation of a plugin
instance
using Transit's standard plugin loader.
</p>
-
+ <p>
+ We create a API project called hello-api, which contains this
advanced
+ interface.
+ </p>
+<source>
+/** API of the Hello service.
+ */
+public interface Hello
+{
+ void announce();
+}
+</source>
+ <p>
+ And then we need an implementation of the API, and we call that
+ hello-impl.
+ </p>
+<source>
+/** Implementation of the Hello API.
+ */
+public class HelloImpl
+ implements Hello
+{
+ private String m_Message;
+
+ public Hello( String message )
+ {
+ m_Message = message;
+ }
+
+ public void announce()
+ {
+ System.out.println( m_Message );
+ }
+}
+</source>
+ <p>
+ so we need to do the following from the class that loads the
plugin;
+ </p>
<source>
Repository repository = new StandardLoader();
ClassLoader parent = getClass().getClassLoader();
- URI uri = new URI( "artifact:meta:dpml/examples/hello/hello-world#1.0.0" );
+ URI uri = new URI( "artifact:meta:mycompany/thisproject/hello-impl#1.4.1"
);
Object[] args = new Object[] { "Hello, World!" };
Object plugin = repository.getPlugin( parent, uri, args );
+ if( plugin instanceof Hello )
+ {
+ m_hello = (Hello) plugin;
+ }
+ else
+ {
+ throw Exception( "Loaded plugin is not of the right type." );
+ }
+ :
+ :
+ :
+ m_hello.announce();
</source>
+ <p>
+ For this to work, you will also need to create the meta information
+ descriptor. The easiest way is to use the DPML Magic build system,
+ but it can also be done manually or with other tools. The above
+ would need a simple descriptor like this;
+ </p>
+<source>

+#
+# Meta classifier.
+#
+meta.domain = net.dpml
+meta.version = 1.0
+
+#
+# Artifact descriptor.
+#
+dpml.artifact.group = mycompany/thisproject
+dpml.artifact.name = hello-impl
+dpml.artifact.version = 1.4.1
+dpml.artifact.signature = 20050116.140842
+
+#
+# Type.
+#
+dpml.plugin.class = com.mycompany.thisproject.HelloImpl
+
+#
+# API dependency.
+#
+dpml.artifact.dependency.api.0 =
artifact:jar:mycompany/thisproject/hello-api#1.4.1
+
+#
+# SPI dependencies.
+#
+# No SPI dependencies
+# dpml.artifact.dependency.spi.0 =
+
+#
+# Implementation dependencies.
+#
+# No impl dependencies
+# dpml.artifact.dependency.0 =
+</source>
+ <p>
+ Now, the beauty of Transit is that IF the hello-api artifact is
present
+ in the parent classloader (or higher), the API classloader will NOT
+ receive an additional instance of the Jar. This means that, if
+ the plugin user have the hello-api already loaded it is not added
to the
+ API classloader, and the correct classloader management is ensured.
+ Furthermore, if any of the Classloaders in the chain
+ becomes empty, i.e. no new URLs not present in the parent
structure,
+ then the Classloader in question is not created.
+ </p>
<p>
- Example of plugin loading and general plugin handling is provided
+ Example of plugin loading and general plugin handling is provided
under the <a href="/guide/transit/plugins/index.html">Transit
Guide</a>.
</p>
-
</section>
</body>
</document>



  • svn commit: r1484 - in development/main/central/site/src/docs/products/transit: . overview, niclas, 01/16/2005

Archive powered by MHonArc 2.6.24.

Top of Page