--- /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
+ <link rel="stylesheet" type="text/css" href="../style/doc.css">\r
+ <TITLE>Jigsaw architecture</TITLE>\r
+<!-- Created by GNNpress -->\r
+<!-- Changed by: Anselm Baird-Smith, 4-Feb-1997 -->\r
+</HEAD>\r
+<BODY>\r
+ <div class="icons-w3c">\r
+ <a href="../../../">\r
+ <img src="/Icons/w3c_home" \r
+ border="0" \r
+ alt="W3C logo"\r
+ height="48" \r
+ width="72">\r
+ </a>\r
+ </div>\r
+ <div class="icons-jigsaw">\r
+ <a href="../../">\r
+ <img src="/Icons/jigsaw" \r
+ border="0"\r
+ alt="Jigsaw"\r
+ height="49"\r
+ width="212">\r
+ </a>\r
+ </div>\r
+\r
+ <div class="title">\r
+ <h1 class="title">\r
+ Jigsaw<br>\r
+ <span class="subtitle">Basic concepts</span>\r
+ </h1>\r
+ <hr NOSHADE width="70%" align="left">\r
+ <a href="../../Overview.html">Jigsaw Home</a> /\r
+ <a href="../Overview.html">Documentation Overview</a>\r
+ </div>\r
+ <div class="body">\r
+<P>\r
+<div class="box">\r
+<IMG SRC="/Icons/32x32/caution.gif" ALT="WARN !" BORDER=0 HEIGHT=32 WIDTH=32> \r
+This page has not been updated since release 1.0alpha3. Even though the \r
+ideas haven't changed that much, some class have been renamed as\r
+part of an API cleanup (check the <A HREF="../../RelNotes.html">Release\r
+Notes</A>). A new architecture overview is under construction <A HREF="../Programmer/design.html">here</A>.\r
+</div>\r
+<H1>\r
+Jigsaw Architecture</H1>\r
+<B>Jigsaw</B> is made of two distinct modules, linked through a set of\r
+interfaces:\r
+<UL>\r
+<LI>\r
+The <A HREF="#protocol-module">daemon module</A> deals with the HTTP protocol:\r
+it handles new incomming connections, create new client objects, decode\r
+requests, and send replies.</LI>\r
+\r
+<LI>\r
+The <A HREF="#resource-module">resource module</A> is some representation\r
+of your information space. It is responsible for generating reply objects\r
+out of the incoming request objects.</LI>\r
+</UL>\r
+As these two modules are linked through a set of Java interface specifications,\r
+you can replace each of them independantly of the other, provided they\r
+implement adequatly the interfaces.\r
+<H2>\r
+<A NAME="protocol-module"></A>The daemon module</H2>\r
+As a server administrator, you probably won't have to deal much with this\r
+part of <B>Jigsaw</B>, although it might be a good idea to read this section\r
+(or at least the one on terminology), just to get a filling of what's happening\r
+behind the scene. This section will goes through a bit of <A HREF="#protocol-terminology">terminology</A>,\r
+it will then step through the <A HREF="#protocol-life-time-of-a-connection">life-time\r
+of a connection</A>, and introduce the resource module.\r
+<H3>\r
+<A NAME="protocol-terminology"></A>Terminology</H3>\r
+The protocol module deals with a number of objects. To get you into this\r
+world, we will start by describing the most important.\r
+<DL>\r
+<DT>\r
+<A HREF="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/jigsaw/http/httpd.html">httpd</A></DT>\r
+\r
+<DD>\r
+This is the object whose <TT><A HREF="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/jigsaw/http/httpd.html#main">main</A></TT>\r
+method will actually run the server. It has two purposes: the first one\r
+is to run the <I>accepting thread</I>, i.e. the thread that will loop waiting\r
+for new incomming connections to come by. The second purpose of this object\r
+is to manage the set of other objects, responsible for handling part of\r
+the server behavior. Among them, there is the <A HREF="#logger">logger</A>\r
+(responsible for loggin requests), the <A HREF="#realm-manager">authentication\r
+realm manager</A> (responsible for the list of authentication realms defined\r
+attached to the server), the <A HREF="#client-pool">client pool</A> (responsible\r
+for handling accepted connections), the <A HREF="#root-resource">root resource</A>\r
+of the server, and last but not least, the <A HREF="#resource-store-manager">resource\r
+store manager</A>. We will describe all these objects more precisely in\r
+the comming sections.</DD>\r
+\r
+<DT>\r
+<A NAME="logger" HREF="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/jigsaw/http/Logger.html"></A><A HREF="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/jigsaw/http/Logger.html" NAME="logger">logger</A></DT>\r
+\r
+<DD>\r
+Each time a request processing terminates (be it with success or not),\r
+the server will call back the logger so that it can keep track of all handled\r
+requests. The current version of <B>Jigsaw</B> comes with a simple logger,\r
+compliant with the <A HREF="http://www.w3.org/pub/WWW/Daemon/User/Config/Logging.html#common-logfile-format">Common\r
+Log file format</A> (ie it will emit a one line record for each processed\r
+request).</DD>\r
+\r
+<DT>\r
+<A NAME="realm-manager" HREF="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/jigsaw/auth/RealmsCatalog.html"></A><A HREF="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/jigsaw/auth/RealmsCatalog.html" NAME="realm-manager">realm\r
+manager</A></DT>\r
+\r
+<DD>\r
+The realm manager keeps track of all the authentication realms defined\r
+by the server. Each created authentication realm is assigned a symbolic\r
+name, that the web admin will use to refer to it when configuring the server.\r
+This name will also be used as the HTTP <I>realm name</I>, so it should\r
+be uniq within the server scope. The sample implementation of this object\r
+manages a persistent catalog of realms, that can be edited through a special\r
+tool called JigAdmin (see <A HREF="configuration.html"><B>Jigsaw</B> configuration\r
+manual</A>).</DD>\r
+\r
+<DT>\r
+<A NAME="client-pool" HREF="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/jigsaw/http/ClientPool.html"></A><A HREF="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/jigsaw/http/ClientPool.html" NAME="client-pool">client\r
+pool</A></DT>\r
+\r
+<DD>\r
+The client pool object is responsible for handling new incomming connections.\r
+It should make its best effort to guess what protocol the other end wants\r
+to speak on this connection, and create an appropriate client object, to\r
+handle it. The current sample implementation will always assume that new\r
+connections are for speaking the HTTP/1.0 protocol (with the addition of\r
+persistent connections). The other role of the client pool is to optimize\r
+as much as possible thread creations. Thread creation can be a costly process,\r
+wo its worth trying to avoid it as much as possible. The sample implementation\r
+will maintain a ready-to-run set of client objects, so that it won't re-create\r
+them from scratch upon each new connections.</DD>\r
+\r
+<DT>\r
+<A NAME="root-resource" HREF="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/jigsaw/resources/ContainerResource.html"></A><A HREF="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/jigsaw/resources/ContainerResource.html" NAME="root-resource">root\r
+resource</A></DT>\r
+\r
+<DD>\r
+The root resource is <I>the</I> object that will link the protocol module\r
+to the <A HREF="#resource-module">resource module</A>. This object should\r
+implement the appropriate interface (right now, it should be an instance\r
+of the <A HREF="../../User/api/w3c.jigsaw.resources.ContainerResource.html">ContainerResource</A>,\r
+but this is likely to change in the very near future).</DD>\r
+\r
+<DT>\r
+<A NAME="resource-store-manager" HREF="../../User/api/w3c.jigsaw.resources.ResourceStoreManager.html"></A><A HREF="http://jigsaw.w3.org/Doc/Programmer/api/org/w3c/tools/resources/store.ResourceStoreManager.html" NAME="resource-store-manager">resource\r
+store manager</A></DT>\r
+\r
+<DD>\r
+As you will see in the next section, <B>Jigsaw</B> serves each file or\r
+directory by wrapping it into some <A HREF="../../User/api/w3c.jigsaw.resources.Resource.html">Resource</A>\r
+instance. As their number might become fearly large, the server will keep\r
+track of the one that haven't been accessed for a while, and unload them\r
+from memory. The resource store manager is responsible for this piece of\r
+the server behavior: it keeps track of all the loaded resources, and unload\r
+them when it thinks appropriate.</DD>\r
+</DL>\r
+Given these definitions, we can now explain how the server handles new\r
+incomming connections.\r
+<H3>\r
+<A NAME="protocol-life-time-of-a-connection"></A>Life-time of a connection</H3>\r
+The life time of a connection can be divided into the following steps:\r
+<OL>\r
+<LI>\r
+The accepting thread is notified of it.</LI>\r
+\r
+<LI>\r
+It gets handled by the client pool object</LI>\r
+\r
+<LI>\r
+A thread starts waiting for incoming requests</LI>\r
+\r
+<LI>\r
+The request is handed out to the resource module, for actual processing</LI>\r
+\r
+<LI>\r
+The resource module generated reply is emited</LI>\r
+\r
+<LI>\r
+The server logger is called back to log the request</LI>\r
+</OL>\r
+The first stage in processing a new connection, is to hand it out as quickly\r
+as possible to the client pool (so that the accepting thread can return\r
+as fast as possible to the <TT>accept</TT> system call). The client pool\r
+then look for an idle <A HREF="../../User/api/w3c.jigsaw.http.Client.html">Client</A>\r
+object, if one is found, it is <TT><A HREF="../../User/api/w3c.jigsaw.http.Client.html#bind">bind</A></TT>\r
+to the accepted connection, which makes it run its main loop. If no client\r
+is available, if we have reached the <A HREF="../../User/Reference/w3c.jigsaw.http.socket.SocketConnectionProp.html#w3c.jigsaw.http.socket.SocketClientFactory.maxClients">maximum\r
+allowed number of connections</A> the new connection gets rejected\r
+(by closing it), otherwise a fresh client is created and bound to the connection.\r
+\r
+<P>By the end of stage 2, the client pool has either rejected the connection,\r
+got a new client to handle it, or created a fresh client for this connection.\r
+At stage 3, the client object is bound to the connection, and awaken to\r
+actually process it. The client thread enters the client main loop.\r
+\r
+<P>The client main loop starts by getting any available request. When such\r
+a request has been read from the network, it is handed out to the <A HREF="#resource-module">resource\r
+module</A>. This latest module is responsible for generating an appropriate\r
+<A HREF="../../User/api/w3c.jigsaw.http.Reply.html">Reply</A> object, which\r
+is then emited (stage 5) by the client thread, back to the browser. Finally\r
+the server logger is invoked with the request, its reply and the number\r
+of bytes sent back to the browser.\r
+\r
+<P>At the end of this request processing, the client object tests to see\r
+if it can keep the connection alive. If so, it loops back to stage 2, otherwise,\r
+the client notify the client pool that it has become idle. The client pool,\r
+in turn, decides if this client object should be spared for future use\r
+or not.\r
+<H2>\r
+<A NAME="resource-module"></A>The Resource module</H2>\r
+The resource module is the one that manages the information space. In <B>Jigsaw</B>\r
+each exported object is mapped to an <A HREF="../../User/api/w3c.jigsaw.resources.HTTPResource.html">HTTPResource</A>\r
+instance, which is created at configuration time, either manually or by\r
+the <A HREF="../../User/Introduction/indexer.html">resource factory</A>.\r
+We will describe here <A HREF="#resources">what are resources</A> and then\r
+sketch the way <B>Jigsaw</B> <A HREF="#looking-up">looks up</A> the specific\r
+target resource of a request. We finally present the <A HREF="#filters"><I>filter</I>\r
+concept</A>.\r
+<H3>\r
+<A NAME="resources"></A>Resources</H3>\r
+Resources are full Java objects, defined by two characteristics:\r
+<UL>\r
+<LI>\r
+Their Java class define their <I>behavior</I> (how they implement the HTTP\r
+methods)</LI>\r
+\r
+<LI>\r
+Their <I>state</I> is described through a set of attributes</LI>\r
+</UL>\r
+The <A HREF="../../User/api/w3c.jigsaw.resources.AttributeRegistry.html">AttributeRegistry</A>\r
+keeps track of all the attributes of each classes. As instance variables,\r
+attributes are inherited along the normal sub-class relationship. Each\r
+resource attribute is described by some instance of the <A HREF="../../User/api/w3c.jigsaw.resources.Attribute.html">Attribute</A>\r
+class (or some of its sub-class). This description is made of\r
+<UL>\r
+<LI>\r
+the name of the attribute,</LI>\r
+\r
+<LI>\r
+some flags indicating if the attribute is mandatory, editable, computed\r
+or whatever</LI>\r
+\r
+<LI>\r
+the methods to pickle (dump) and unpickle (restore) this attribute values</LI>\r
+\r
+<LI>\r
+a method to check if some Object instance can be used as a value for this\r
+attribute.</LI>\r
+</UL>\r
+Given this description, <B>Jigsaw</B> is able to make resources persistent,\r
+just by dumping their class-name, and all their attribute values. Unpickling\r
+(i.e. restoring) a resource is just creating an empty instance of its class,\r
+and filling its attributes with their saved values.\r
+\r
+<P><A HREF="../../User/api/w3c.jigsaw.resources.Resource.html">Resource</A>\r
+instances are the basic resources. The <A HREF="../../User/api/w3c.jigsaw.resources.HTTPResource.html">HTTPResource</A>\r
+class is the basic class for resources that are accessible through the\r
+HTTP protocol. Instances of this class define a <A HREF="../../User/Reference/w3c.jigsaw.resources.HTTPResource.html">number\r
+of attributes</A> along with the method that implements the HTTP methods\r
+(e.g. GET, POST, PUT, etc. which are mapped resp. to the <A HREF="../../User/api/w3c.jigsaw.resources.HTTPResource.html#get">get</A>,\r
+<A HREF="../../User/api/w3c.jigsaw.resources.HTTPResource.html#post">post</A>\r
+<A HREF="../../User/api/w3c.jigsaw.resources.HTTPResource.html#put">put</A>,\r
+etc methods of the class). These methods are all trigered through the <A HREF="../../User/api/w3c.jigsaw.resources.HTTPResource.html#perform">perform</A>\r
+method of the class, whose role is to <I>dispatch</I> a request to the\r
+appropriate handler.\r
+\r
+<P>Remember in the previous section, we said that request were handed out\r
+the the resource module. The <TT>perform</TT> method of HTTPResource are\r
+the one that get called by the daemon module once the target resource of\r
+the request has been looked up. The next section explains how this lookup\r
+is performed.\r
+<H3>\r
+<A NAME="lookup"></A>Looking up resources</H3>\r
+In the paragraph about the <A HREF="#protocol-life-time-of-a-connection">life-time\r
+of a connection</A>, we mention that at stage 4 the parsed request was\r
+handed out to the resource module. The first thing the resource module\r
+does when it receives a request, is to look up the target resource. This\r
+paragraph explains briefly how this is performed.\r
+\r
+<P><B>Jigsaw</B> defines a special subclass of the <A HREF="../../User/api/w3c.jigsaw.resources.HTTPResource.html">HTTPResource</A>\r
+class, the <A HREF="../../User/api/w3c.jigsaw.resources.ContainerResource.html">ContainerResource</A>,\r
+whose role is to implement the look up strategy for the sub-space it controls.\r
+All servers (i.e. all instances of the <A HREF="../../User/api/w3c.jigsaw.http.httpd.html">httpd</A>\r
+class) keeps a pointer to their <I>root resource</I>. This root resource\r
+<B>must</B> be a container resource: it must implement the <A HREF="../../User/api/w3c.jigsaw.resources.ContainerResource.html">lookup</A>\r
+method. Given a request, this method must return a suitable target resource\r
+for processing it. However, there is no constraints on <I>how</I> the lookup\r
+is performed. We will briefly sketch how directory resources implement\r
+their lookup method.\r
+\r
+<P>The directory resource's <A HREF="../../User/api/w3c.jigsaw.resources.DirectoryResource.html#lookup">lookup</A>\r
+method starts by checking that it has an up-to-date list of children. What\r
+is meant by up-to-date here might not be what you expect: <B>Jigsaw</B>\r
+caching strategy can make this notion quiet complex. Anyway, once the directory\r
+resource thinks its list of children is up-to-date, it looks up the first\r
+component of the URL in its children set. For example, if the URL is <TT>/foo/bar</TT>,\r
+it starts by looking up <TT>foo</TT> in itself. This can lead to three\r
+cases, depending on the result of this:\r
+<UL>\r
+<LI>\r
+The directory resource doesn't have a child resource named <TT>foo</TT>.\r
+In this case, it throws an exception to signal a <I>not found</I> error.</LI>\r
+\r
+<LI>\r
+The directory resource has a child named <TT>foo</TT>. As the looked up\r
+URL contains more components, the directory resource check that the found\r
+resource is a container resource. If this is not the case, then a <I>not\r
+found</I> error is signaled by throwing an appropriate exception. Otherwise,\r
+the looked up component is removed from the look up state, and the directory\r
+resource calls up the found child resource's lookup method.</LI>\r
+</UL>\r
+This look up process is just one example of how the look-up operation can\r
+be implemented. It has several advantages in the specific case of handling\r
+directory resources, but other situations may require other algorithms.\r
+One important property of the directory resource's lookup algorithm is\r
+that it is able to <I>delegate sub-space</I> naming to the resource\r
+that actually handles the sub-space.\r
+<H3>\r
+<A NAME="filters"></A>Resource filters</H3>\r
+We have briefly described <B>Jigsaw</B> resource module. The last thing\r
+you need to understand is <B>Jigsaw</B>'s concept of resource <I>filters</I>.\r
+You might have been surprised that until now, we haven't said a word on\r
+authentication. In <B>Jigsaw</B> authentication is implemented as a special\r
+resource filter. Resource filters are a special kind of resource (i.e.\r
+they are persistent, and can define any kind of attributes), that are attached\r
+to some <I>target resource</I>. Filter instances are called back twice\r
+during request processing:\r
+<UL>\r
+<LI>\r
+At lookup stage, the filter's <TT><A HREF="../../User/api/w3c.jigsaw.resources.ResourceFilter.html#ingoingFilter">ingoingFilter</A></TT>\r
+method is called. It is provided with the request whose URL we are looking\r
+up.</LI>\r
+\r
+<LI>\r
+After the target resource has generated its reply, the filter's <TT><A HREF="../../User/api/w3c.jigsaw.resources.ResourceFilter.html#outgoingFilter">outgoingFilter</A></TT>\r
+method gets (optionally - see below) called, with both the original request\r
+and the reply has parameters.</LI>\r
+</UL>\r
+For a resource to support filters, its class must be a subclass of the\r
+<A HREF="../../User/api/w3c.jigsaw.resources.FilteredResource.html">FilteredResource</A>\r
+class. Most resource classes provided with <B>Jigsaw</B> distribution are\r
+sub-classes of it.\r
+\r
+<P>Back to authentication now. As we said above, authentication is handled\r
+by a <A HREF="../../User/api/w3c.jigsaw.auth.GenericAuthFilter.html">special\r
+filter</A>, whose ingoingFilter method tries to authenticate the request.\r
+If this succeeds, normal processing of the request continues: it is performed\r
+by its target resource, and the corresponding reply is emited back to the\r
+browser. In the case of the authentication filter, as all the work is done\r
+only in the ingoing way (while the target resource is being looked up),\r
+there is no need to have the outgoingFilter method called. A filter <TT>ingoingFilter</TT>\r
+method can return a special value <A HREF="../../User/api/w3c.jigsaw.resources.ResourceFilter.html#DontCallOutgoing">DontCallOutgoing</A>\r
+to indicate that it has performed all its job, in such cases, the server\r
+won't spend time invoking its empty <TT>outgoingFilter</TT> method. More\r
+return codes are available, see the <A HREF="../../User/api/w3c.jigsaw.resources.ResourceFilter.html">api\r
+documentation for the ResourceFilter</A> to get into the details.\r
+<H2>\r
+Further reading</H2>\r
+The best way to continue your <B>Jigsaw</B> tour now, is to <A HREF="installation.html">install\r
+it</A>, and to read the following tutorials:\r
+<UL>\r
+<LI>\r
+<B>Jigsaw</B> <A HREF="configuration.html">administration guide</A> is\r
+the reference guide for <B>Jigsaw</B> configuration.</LI>\r
+\r
+<LI>\r
+The <A HREF="../Overview.html#User_Documentation">configuration tutorials</A>\r
+will go through the configuration process, explaining you the basics of\r
+<B>Jigsaw</B> configuration.</LI>\r
+\r
+<LI>\r
+Once you are familiar with the configuration process, you might want to\r
+know how to define new frame classes. The <A HREF="../Programmer/writing-frames.html">frames\r
+tutorial</A> walk through a full example of this.</LI>\r
+\r
+<LI>\r
+You might want to know also how to define a new resource classe. The <A HREF="../Programmer/writing-resources.html">resources\r
+tutorial</A> walk through a full example of this.</LI>\r
+\r
+<LI>\r
+Finally, you may want to learn more about resource filters, by reading\r
+the <A HREF="../Programmer/writing-filters.html">filter tutorial</A>, which\r
+explains how to write new resource filters.</LI>\r
+</UL>\r
+ </div> <!-- body -->\r
+ <div class="footer">\r
+<p>\r
+<HR noshade>\r
+ <a href="mailto:jigsaw@w3.org">Jigsaw Team</a><br>\r
+ <span class="mini">\r
+ $Id: architecture.html,v 1.1 2010/06/15 12:22:56 smhuang Exp $\r
+ </span>\r
+ <p class="policyfooter">\r
+ <font size=-1>\r
+ <a href="/Consortium/Legal/ipr-notice.html#Copyright">Copyright</a>\r
+ © 1999 <a href="http://www.w3.org">W3C</a> \r
+ (<a href="http://www.lcs.mit.edu">MIT</a>, \r
+ <a href="http://www.inria.fr/">INRIA</a>, \r
+ <a href="http://www.keio.ac.jp/">Keio</a> ), \r
+ All Rights Reserved. W3C \r
+ <a href="/Consortium/Legal/ipr-notice.html#Legal Disclaimer">\r
+ liability,\r
+ </a>\r
+ <a href="/Consortium/Legal/ipr-notice.html#W3C Trademarks">\r
+ trademark\r
+ </a>, \r
+ <a href="/Consortium/Legal/copyright-documents.html">\r
+ document use \r
+ </a>\r
+ and\r
+ <a href="/Consortium/Legal/copyright-software.html">\r
+ software licensing\r
+ </a> rules apply. Your interactions with this site are in\r
+ accordance with our \r
+ <a href="/Consortium/Legal/privacy-statement.html#Public">\r
+ public\r
+ </a> and \r
+ <a href="/Consortium/Legal/privacy-statement.html#Members">\r
+ Member\r
+ </a>\r
+ privacy statements.</font>\r
+ </div>\r
+</BODY>\r
+</HTML>\r
projects / Benchmarks_CSolver.git / blobdiff