--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"\r
+ "http://www.w3.org/TR/REC-html40/loose.dtd">\r
+<html>\r
+<head>\r
+ <meta http-equiv="Content-Type" content="text/html">\r
+ <title>Jigsaw 2.0 Internal design</title>\r
+ <link rel="stylesheet" type="text/css" href="../style/doc.css">\r
+</head>\r
+\r
+<body text="#000000" bgcolor="#FFFFFF" link="#0000EE" vlink="#551A8B"\r
+alink="#FF0000">\r
+\r
+<div class="icons-w3c">\r
+<a href="../../../"><img src="/Icons/w3c_home" border="0" alt="W3C logo"\r
+height="48" width="72">\r
+</a></div>\r
+\r
+<div class="icons-jigsaw">\r
+<a href="../../"><img src="/Icons/jigsaw" border="0" alt="Jigsaw" height="49"\r
+width="212">\r
+</a></div>\r
+\r
+<div class="title">\r
+<h1 class="title">Jigsaw<br>\r
+<span class="subtitle">Internal design of Jigsaw 2.0</span></h1>\r
+<hr noshade="noshade" width="70%" align="left">\r
+\r
+<a href="../../Overview.html">Jigsaw Home</a> / <a\r
+href="../Overview.html">Documentation Overview</a></div>\r
+\r
+<div class="body">\r
+<p>In <b>Jigsaw</b> each served URI is bound to an object generating content. This object is mapped to a <a\r
+href="../Reference/org.w3c.tools.resources.FramedResource.html">FramedResource</a>\r
+(<a\r
+href="../Reference/org.w3c.tools.resources.FileResource.html">FileResource</a>,\r
+<a\r
+href="../Reference/org.w3c.tools.resources.DirectoryResource.html">DirectoryResource</a>...)\r
+which in turn is associated with a <a\r
+href="../Reference/org.w3c.tools.resources.ProtocolFrame.html">ProtocolFrame</a>\r
+(usually the <a\r
+href="../Reference/org.w3c.jigsaw.frames.HTTPFrame.html">HTTPFrame</a> or any\r
+subclass) instance, which in turn is created manually (with JigAdmin <a\r
+href="../User/AdminTools.html">1.0</a> or <a\r
+href="../User/JigAdmin/Overview.html">2.0</a>) or automatically by an <a\r
+href="../User/indexers.html">indexer</a>.</p>\r
+\r
+<p>This document has the following sections:</p>\r
+\r
+<p></p>\r
+<ul>\r
+ <li><a href="#whatr">What is a Resource?</a></li>\r
+ <li><a href="#whatf">What is a Frame?</a></li>\r
+ <li><a href="#whatfi">What is a Filter?</a></li>\r
+ <li><a href="#indexer">What is an Indexer?</a></li>\r
+ <li><a href="#resource">The new Resource</a></li>\r
+ <li><a href="#manager">The new ResourceStoreManager</a></li>\r
+ <li><a href="#lookup-algo">The lookup and perform algorithm</a></li>\r
+</ul>\r
+\r
+<h1><a name="whatr"></a>What is a Resource?</h1>\r
+The Resources are the objects exported by <b>Jigsaw</b> to the outside world. Resources can generate raw data stream, like text files or image files, or they can be active objects, generating data stream on the fly, depending on different contexts, like servlets, cgi scripts, filtered resources.\r
+\r
+<p>Inside <b>Jigsaw</b>, a resource is a full Java object, containing only information that the raw Resource (a file, a directory...) can provide (eg, for a file, the size, last modification date...)</p>\r
+\r
+<p>To be available on the server, a resource <b>MUST</b> be associated with a ProtocolFrame implementing the protocol available on that particular server. An instance of Jigsaw (ie: the java process) can support multiple servers, each server having the possibility of implementing different protocols and may or may not share the same set of resources.\r
+\r
+<p>The list of all <a href="../Reference/resources.html">Resources</a> is\r
+available.</p>\r
+\r
+<h1><a name="whatf"></a>What is a Frame?</h1>\r
+Since Jigsaw-2.0, the Resources are very basic and contains only the intrinsic\r
+knowledge of this resource. For file, you have the size, last modification\r
+date... The 2.0 Resources have protocol frames. Those frames are handling the\r
+different protocols used to fetch this particular resource.\r
+\r
+<p>A Frame is a full Java Object, containing all the information needed to\r
+serve this Resource using a specific Protocol (eg, HTTPFrame for\r
+<b>HTTP</b>).</p>\r
+\r
+<p>The list of all <a href="../Reference/frames.html">Frames</a> is\r
+available.</p>\r
+\r
+<center>\r
+<img src="resframe.gif" alt="Resources and frames" height="300" width="498">\r
+</center>\r
+\r
+<h1><a name="whatfi"></a>What is a Filter?</h1>\r
+The filters alters the resources, by requesting authentification for example.\r
+The filters are attached to the resource. In the 2.0 version the filters are\r
+atteched to the protocol frame of the resource rather than to the resource\r
+itself because many filtering scheme depends on the protocol used, the\r
+authentification in HTTP is very specific to HTTP and can't be used in other\r
+protocols. The filters are called before and after serving the resource. You\r
+may have filters that are called only before the resource is served, like an\r
+authentification filter, or after, like a "find and replace" filter.\r
+\r
+<p>A Filter is a full Java Object, associated to a Frame, that can modify the\r
+Request and/or the Reply. For example the Authentication is handled by a\r
+special filter, the <a\r
+href="../Reference/org.w3c.jigsaw.auth.GenericAuthFilter.html">GenericAuthFilter</a>\r
+(Note, as this filter is protocol dependant, it is placed on the protocol\r
+frame).</p>\r
+\r
+<p>The list of all <a\r
+href="../Reference/frames.html#Filter+frames">Filters</a> is available.</p>\r
+\r
+<h1><a name="indexer"></a>What is an Indexer ?</h1>\r
+There are two ways of configuring the resources, by adding directly a specific\r
+resource at a specific place, or by letting the indexers create the resource\r
+in the server hierarchy. Of course the manual tune can be used along with the\r
+indexers. That is the most common way to configure <b>Jigsaw</b>. <a\r
+name="indexers"></a>\r
+\r
+<p>An indexers, placed on a Container, will be in charge of creating its sons\r
+resources. It will create Resource of a special kind depending, for example,\r
+on the extension of the filename ("html" for an html page, "png" for a PNG\r
+image file....). Or place a specific indexer for cgi on a directory named\r
+"cgi-bin". In Jigsaw-2.0, the indexer is not only in charge of creating the\r
+resource, it has also to put the right protocol frames (and other frames if\r
+necessary) on the created resource.</p>\r
+\r
+<p>An indexer have two main part:</p>\r
+<ol>\r
+ <li>The Directories.</li>\r
+ <li>The Extensions.</li>\r
+</ol>\r
+In the Directories, you have to specify how to index directories with a\r
+specific name. The default name is "*default*", in the default indexer the\r
+resource created is a DirectoryResource. In the 2.0 version, it creates a\r
+DirectoryResource with a default HTTPFrame.\r
+\r
+<p>In the extensions, you have to specify how to index files or leaf\r
+Resources. The default extension are mapped to FileResource, html, gif, png,\r
+txt... In the 2.0 version, an HTTPFrame is added to the Resource.</p>\r
+\r
+<p>A tutorial about the <a href="../User/indexers.html">setup of indexers\r
+</a>is available, it helps understanding how it works.</p>\r
+\r
+<h1><a name="resource"></a>The new Resource</h1>\r
+In the previous version of <b>Jigsaw</b> (1.0), the inheritance tree of\r
+Resources was:\r
+\r
+<center>\r
+<img src="olddesign.gif" alt="Sketches of the old design">\r
+</center>\r
+\r
+<p>All the basic Resources, such as FileResource and DirectoryResource, were\r
+heavily linked to HTTP as all the resources served were extensions protocols\r
+that are not HTTP-related, we propose this new version of the Resource:</p>\r
+\r
+<center>\r
+<img src="resource.gif" alt="basic resource with frames">\r
+</center>\r
+\r
+<p>Where (1) and (2) are ResourceFrames. A Resource is now a very basic thing,\r
+containing only information that the raw Resource can provide (e.g., for a\r
+file, the size, last modification date, creation date if available, etc.),\r
+then, attached to that Resource, we find the ResourceFrames that extend\r
+Resource (they are handled the same way) and contain information about the\r
+Resource they are attached to.</p>\r
+\r
+<p>To serve a resource using a protocol -- for instance, HTTP -- the Resource\r
+will have a protocol ResourceFrame, HTTPFrame, that contains all the\r
+information needed to serve this Resource using HTTP. This frame is like the\r
+old version of HTTPResource, but it contains more information than the\r
+previous version.</p>\r
+\r
+<p>The filters are now divided in two categories: the filters on the Resource\r
+and the filters on the protocol Frames. The usual filtering scheme used in the\r
+previous version of <b>Jigsaw</b> is still valid. The main difference is that\r
+filters are no longer attached to the Resource itself but to its protocol\r
+frame. ResourceFrames can also have frames.</p>\r
+\r
+<p>Other kind of frames can be attached, like RDF frame for metadata, PICS\r
+frame to rate this resource, etc...</p>\r
+\r
+<p>The new inheritance tree is:</p>\r
+\r
+<center>\r
+<img src="design.gif" border="0" usemap="#map" alt="new design (inheritance)\r
+sketches">\r
+</center>\r
+<map name="map">\r
+ <area shape="rect" coords="202,26,316,61" href="samples/Resource.html"\r
+ alt="basic resource">\r
+ <area shape="rect" coords="169,80,346,116"\r
+ href="samples/FramedResource.html" alt="framed resource">\r
+ <area shape="rect" coords="486,140,660,175"\r
+ href="samples/ResourceFrame.html" alt="resource frame">\r
+ <area shape="rect" coords="15,140,221,176"\r
+ href="samples/AbstractContainer.html" alt="abstract container">\r
+ <area shape="rect" coords="261,140,431,176" href="samples/FileResource.html"\r
+ alt="file resource">\r
+ <area shape="rect" coords="85,205,291,241"\r
+ href="samples/ContainerResource.html" alt="container resource">\r
+ <area shape="rect" coords="520,260,671,296"\r
+ href="samples/ProtocolFrame.html" alt="protocol frame">\r
+ <area shape="rect" coords="19,265,226,301"\r
+ href="samples/ExternalContainer.html" alt="external container">\r
+ <area shape="rect" coords="325,320,511,357"\r
+ href="samples/ResourceFilter.html" alt="resource filter">\r
+ <area shape="rect" coords="84,325,289,362"\r
+ href="samples/DirectoryResource.html" alt="directory resource">\r
+ <area shape="rect" coords="535,360,661,396" href="samples/HTTPFrame.html"\r
+ alt="http frame">\r
+</map>\r
+\r
+<p></p>\r
+\r
+<p>more complex, but more flexible than the previous version.</p>\r
+\r
+<h1><a name="manager"></a>The new ResourceStoreManager</h1>\r
+In order to share all the Resources amongst different servers efficiently, we\r
+created a new central ResourceStoreManager. In the previous version the\r
+Resources were handled by other Resources. For example, the FileResource was\r
+handled by its DirectoryResource. This induced a number of bugs and was not\r
+very well-adapted to the new way of sharing Resources. There is now only one\r
+manager for the server handler so that each server will talk to this sole\r
+manager.\r
+\r
+<center>\r
+<img src="rsm.gif" alt="resource manager drawing">\r
+</center>\r
+\r
+<p>This RSM contains a hashtable associating a key (unique indentifier of a\r
+ResourceContainer) and a StoreEntry. The StoreEntry contains the store of the\r
+resource sons and a hashtable associating the identifier of the sons of the\r
+resource and the ResourceReference of those resources.</p>\r
+\r
+<p>The ResourceReference is used like this:</p>\r
+<pre> ResourceReference rr;\r
+ ....\r
+ try {\r
+ Resource res = rr.lock();\r
+ ....\r
+ } catch (InvalidResourceException ex) {\r
+ /* InvalidResource means that the resource has been deleted */\r
+ ....\r
+ } finally {\r
+ rr.unlock();\r
+ }\r
+ ...</pre>\r
+If the resource has been garbage-collected, the rr.lock() will load it again,\r
+and during the lock, it is guaranteed that the resource won't be deleted,\r
+unloaded or modified by someone else. This allows safe concurrent modification\r
+access to this resource.\r
+\r
+<p>Now the container is no longer responsible for the management of its son;\r
+it only has a key to the StoreEntry, which contains its sons. To get its own\r
+store, the resource has to ask its parent for the StoreEntry that contains\r
+it.</p>\r
+\r
+<h1><a name="lookup-algo"></a>The lookup and perform algorithm</h1>\r
+This part describe the lookup and the perform algorithm used by <b>Jigsaw</b>.\r
+\r
+<p>The following picture show a <b>Jigsaw</b> resources tree (relative to the\r
+URL <tt>/archives/index.html</tt>), where <tt>root</tt> and <tt>archives</tt>\r
+are <a href="samples/DirectoryResource.html">DirectoryResource</a>\r
+(<tt>root</tt> is the root resource) and <tt>index.html</tt> is a <a\r
+href="samples/FileResource.html">FileResource</a>. <tt>F1</tt>, <tt>F2</tt>\r
+and <tt>F3</tt> are filters (<a\r
+href="samples/ResourceFilter.html">ResourceFilter</a> subclass instance).</p>\r
+\r
+<center>\r
+<img src="perform.gif" hspace="10" vspace="10" height="354" width="445"\r
+alt="graphical description of request handling">\r
+</center>\r
+\r
+<p>In the following description, <b>Jigsaw</b> receive an HTTP GET request for\r
+<tt>/archives/index.html</tt>. To handle the incomming request, <b>Jigsaw</b>\r
+will go through the following steps:</p>\r
+<ol>\r
+ <li><a href="#lookup">Lookup for /archives/index.html</a></li>\r
+ <li><a href="#ingoing">Call the ingoingFilter method of filters</a></li>\r
+ <li><a href="#perform">Perform the request</a></li>\r
+ <li><a href="#outgoing">Call the outgoingFilter method of filters</a></li>\r
+ <li><a href="#reply">Emit the reply</a></li>\r
+</ol>\r
+<a name="lookup"></a><b>1</b>) Lookup for <tt>/archives/index.html</tt>. The\r
+<a\r
+href="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/tools/resources/LookupState.html">LookupState</a>\r
+(ls) keeps the state info, and the <a\r
+href="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/tools/resources/LookupResult.html">LookupResult</a>\r
+(lr) is the result of the lookup algorithm.\r
+\r
+<div class="box">\r
+<pre><tt>root</tt> <b>lookup</b>(ls,lr)\r
+ -> <tt>HTTPFrame1</tt> <b>lookup</b>(ls,lr)\r
+ -> <tt>F1</tt> <b>lookup</b>(ls,lr)\r
+ -> <tt>HTTPFrame1</tt> <b>lookupDirectory</b>(ls,lr)\r
+ -> <tt>archives</tt> <b>lookup</b>(ls,lr)\r
+ -> <tt>HTTPFrame2</tt> <b>lookup</b>(ls,lr)\r
+ -> <tt>F2</tt> <b>lookup</b>(ls,lr)\r
+ -> <tt>HTTPFrame2</tt> <b>lookupDirectory</b>(ls,lr)\r
+ -> <tt>index.html</tt> <b>lookup</b>(ls,lr)\r
+ -> <tt>HTTPFrame3</tt> <b>lookup</b>(ls,lr)\r
+ -> <tt>F3</tt> <b>lookup</b>(ls,lr)\r
+ -> <tt>HTTPFrame3</tt> <b>lookupFile</b>(ls,lr) => index.html</pre>\r
+</div>\r
+\r
+<center>\r
+<img src="algo-lookup.gif" hspace="10" vspace="10" height="406" width="513"\r
+alt="the lookup algorithm">\r
+</center>\r
+\r
+<p><a name="ingoing"></a><b>2</b>) Call the ingoingFilter method of filters.\r
+<a\r
+href="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/jigsaw/http/Request.html">Request</a>\r
+is the incomming request.</p>\r
+\r
+<div class="box">\r
+<pre><tt>F1</tt> <b>ingoingFilter</b>(Request)\r
+<tt>F2</tt> <b>ingoingFilter</b>(Request)\r
+<tt>F3 </tt><b>ingoingFilter</b>(Request)</pre>\r
+</div>\r
+Note that if any filter answer with a non-null Reply, the process is stopped\r
+and the Reply is sent back to the client directly (like in the\r
+GenericAuthFilter)\r
+\r
+<p><a name="perform"></a><b>3</b>) Perform the request (GET) on the resource\r
+found at lookup time.</p>\r
+\r
+<div class="box">\r
+<pre><tt>index.html</tt> <b>perform</b>(Request)\r
+ -> <tt>HTTPFrame3</tt> <b>perform</b>(Request)\r
+ -> <tt>HTTPFrame3</tt> <b>get</b>(Request)\r
+ -> <tt>HTTPFrame3</tt> <b>getFileResource</b>(Request) => Reply</pre>\r
+</div>\r
+<a name="outgoing"></a><b>4</b>) Call the outgoingFilter method of filters.\r
+Request is the incomming request, <a\r
+href="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/jigsaw/http/Reply.html">Reply</a>\r
+is the reply created by <tt>HTTPFrame3</tt>.\r
+\r
+<div class="box">\r
+<pre><tt>F3</tt> <b>outgoingFilter</b>(Request, Reply)\r
+<tt>F2</tt> <b>outgoingFilter</b>(Request, Reply)\r
+<tt>F1</tt> <b>outgoingFilter</b>(Request, Reply)</pre>\r
+</div>\r
+\r
+<center>\r
+<img src="algo-perform.gif" hspace="10" vspace="10" height="370" width="566"\r
+alt="the perform algorithm, with filters and such">\r
+</center>\r
+\r
+<p><a name="reply"></a><b>5</b>) Emit the reply created by\r
+<tt>HTTPFrame3</tt>.</p>\r
+</div>\r
+<!-- body -->\r
+\r
+<div class="footer">\r
+<p></p>\r
+<hr noshade="noshade" width="100%">\r
+\r
+<a href="mailto:jigsaw@w3.org">Jigsaw Team</a> <br>\r
+<span class="mini">$Id: design.html,v 1.28 1999/07/30 13:42:40 bmahe Exp\r
+$ </span>\r
+\r
+<p class="policyfooter"><font size="-1"><a\r
+href="/Consortium/Legal/ipr-notice.html#Copyright">Copyright</a> © 1999 <a\r
+href="http://www.w3.org">W3C</a> (<a href="http://www.lcs.mit.edu">MIT</a>, <a\r
+href="http://www.inria.fr/">INRIA</a>, <a\r
+href="http://www.keio.ac.jp/">Keio</a> ), All Rights Reserved. W3C <a\r
+href="/Consortium/Legal/ipr-notice.html#Legal Disclaimer">liability, </a><a\r
+href="/Consortium/Legal/ipr-notice.html#W3C Trademarks">trademark </a>, <a\r
+href="/Consortium/Legal/copyright-documents.html">document use </a>and <a\r
+href="/Consortium/Legal/copyright-software.html">software licensing </a>rules\r
+apply. Your interactions with this site are in accordance with our <a\r
+href="/Consortium/Legal/privacy-statement.html#Public">public </a>and <a\r
+href="/Consortium/Legal/privacy-statement.html#Members">Member </a>privacy\r
+statements.</font></p>\r
+</div>\r
+</body>\r
+</html>\r
projects / Benchmarks_CSolver.git / blobdiff