Author: niallp
Date: Fri May 16 14:42:36 2008
New Revision: 657225
URL: http://svn.apache.org/viewvc?rev=657225&view=rev
Log:
Add an overview of JNet - if its a load of rubbish, hopefully someone will
correct it
Modified:
commons/sandbox/jnet/trunk/src/site/xdoc/index.xml
Modified: commons/sandbox/jnet/trunk/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/commons/sandbox/jnet/trunk/src/site/xdoc/index.xml?rev=657225&r1=657224&r2=657225&view=diff
==============================================================================
--- commons/sandbox/jnet/trunk/src/site/xdoc/index.xml (original)
+++ commons/sandbox/jnet/trunk/src/site/xdoc/index.xml Fri May 16 14:42:36 2008
@@ -24,11 +24,75 @@
<body>
- <section name="Introduction">
+ <section name="Background">
<p>
- JNet allows dynamically register url stream handlers through the
java.net API.
+ Java's <a
href="http://java.sun.com/j2se/1.3/docs/api/java/net/URL.html";>URL</a>
implementation provides the facility to
+ set a <a
href="http://java.sun.com/j2se/1.3/docs/api/java/net/URLStreamHandlerFactory.html";>URLStreamHandlerFactory</a>:
</p>
+ <source>
+ URLStreamHandlerFactory myFactory = new MyCustomStreamHandlerFactory();
+ URL.setURLStreamHandlerFactory(myFactory);
+ </source>
+ <p>
+ However the <code>setURLStreamHandlerFactory</code> method can only be
called once for a <i>Java Virtual Machine</i>.
+ While this may be adequate for <i>standalone</i> applications this can
be a problem where multiple applications run
+ within the same JVM, such as in a web application environment.
+ </p>
+ </section>
+
+
+ <section name="Overview">
+
+ <p>
+ JNet uses a technique to circumvent this restriction and allow URL
stream handler factories to be registered based on
+ the <i>current execution context</i>, so it's possible to have
different handlers for different applications running in
+ the same JVM. It also provides the facility to overcome the limitation
of only being able to call the
+ <code>URL.setURLStreamHandlerFactory()</code> once.
+ </p>
+
+ <subsection name="Installer">
+ <p>
+ <a
href="apidocs/org/apache/commons/jnet/Installer.html">Installer</a> provides
the facility to set the
+ <code>URLStreamHandlerFactory</code>, even if already set by another
application.
+ </p>
+ <source>
+ URLStreamHandlerFactory myFactory = new
MyCustomStreamHandlerFactory();
+ Installer.setURLStreamHandlerFactory(myFactory);
+ </source>
+ <p>
+ If a <code>URLStreamHandlerFactory</code> has alreay been set
<i>AND</i> the new factory is a
+ <a
href="apidocs/org/apache/commons/jnet/ParentAwareURLStreamHandlerFactory.html">ParentAwareURLStreamHandlerFactory</a>,
+ then the old factory is set as the <i>parent</i>
<code>URLStreamHandlerFactory</code>.
+ </p>
+ </subsection>
+
+ <subsection name="Dynamic URLStreamHandlerFactory">
+ <p>
+ <a
href="apidocs/org/apache/commons/jnet/DynamicURLStreamHandlerFactory.html">DynamicURLStreamHandlerFactory</a>
+ provides the facility for different applications to use different
<code>URLStreamHandlerFactory</code>
+ implementations by storing delegate
<code>URLStreamHandlerFactory</code> implementations in a
+ <a
href="http://java.sun.com/j2se/1.3/docs/api/java/lang/ThreadLocal.html";>thread
local</a> variable.
+ </p>
+ <p>
+ This allows the URL handler factory to be changed dynamically at
runtime through the
+ <a
href="apidocs/org/apache/commons/jnet/DynamicURLStreamHandlerFactory.html#push(java.net.URLStreamHandlerFactory)">push(URLStreamHandlerFactory)</a>
+ and <a
href="apidocs/org/apache/commons/jnet/DynamicURLStreamHandlerFactory.html#pop()">pop()</a>
+ methods.
+ </p>
+ <source>
+ // At startup, set the DynamicURLStreamHandlerFactory
+ URLStreamHandlerFactory dynamicFactory = new
DynamicURLStreamHandlerFactory();
+ Installer.setURLStreamHandlerFactory(dynamicFactory);
+ ....
+
+ // Set a custom URLStreamHandlerFactory for the current context
+ URLStreamHandlerFactory myFactory = new
MyCustomStreamHandlerFactory();
+ DynamicURLStreamHandlerFactory.push(myFactory);
+ ...
+ </source>
+ </subsection>
</section>
+
</body>
</document>
