commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nia...@apache.org
Subject svn commit: r657225 - /commons/sandbox/jnet/trunk/src/site/xdoc/index.xml
Date Fri, 16 May 2008 21:42:36 GMT
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>



Mime
View raw message