[claw-cvs] r2 - trunk/doc/chapters

Tue Jan 22 14:50:27 UTC 2008

Author: achiumenti
Date: Tue Jan 22 09:50:27 2008
New Revision: 2

Added:
   trunk/doc/chapters/intro.texinfo
   trunk/doc/chapters/server.texinfo
Log:
first commit

Added: trunk/doc/chapters/intro.texinfo
==============================================================================

--- (empty file)
+++ trunk/doc/chapters/intro.texinfo	Tue Jan 22 09:50:27 2008
@@ -0,0 +1,36 @@
+ at node Introduction
+ at comment  node-name,  next,  previous,  up
+ at chapter Introduction
+
+ at value{claw} is a comprehensive web application for Common Lisp programming language.
+
+ at section What is @value{claw}
+
+ at value{claw} is a comprehensive web application framework for the Common Lisp programming language.
+ at value{claw} is based on components, highly reusable building blocks the make easy and fast the creation of a web application.
+By using and creating new components, the developer can create robust and consistent web application with the minimal effort.
+
+The main aim of @value{claw} is @cite{`divide et impera'}, that means that dividing problems into small problems let programmers
+work on different part of an application, creating ad hoc components for both generic and specific tasks.
+
+ at value{claw} can easily handle all the request cycle,letting you to concentrate only in application business side problems, letting 
+ at value{claw} automatically manage all the mechanism of the web layer, such as form submission and user interactions.
+
+ at value{claw} comes integrated with the dojotoolkit, giving you the possibility to easily and quickly create full WEB 2.0 eye candy application,
+with powerful and very user friendly UI.
+
+ at subsection The request cycle
+
+When a user asks for a page the request is sent to the woserver that dispatches the request to the registered lisplets.
+
+Lisplets are web resource containers that hold web pages and other resource files, such as javascript, image, css, etc. files, under a common path.
+
+When a matching lisplet is then found, it dispatches the request to a registered resource that can be a page or a file.
+
+If the request is sent for a file, this is then sent pack to the browser if found.
+
+If the request is sent for a page, usually mapped to a html url, the dispatcher calls the page rendering function to display the page as an html resource.
+
+If no resource is found a 404 message page, is sent to the user as feedback.
+
+ at image{figure1,15cm,,,png}

Added: trunk/doc/chapters/server.texinfo
==============================================================================
--- (empty file)
+++ trunk/doc/chapters/server.texinfo	Tue Jan 22 09:50:27 2008
@@ -0,0 +1,442 @@
+ at node Server
+ at comment  node-name,  next,  previous,  up
+ at chapter The server
+
+ at value{claw} wraps the Hunchentoot (see: @url{http://www.weitz.de/hunchentoot/, unchentoot}), a wonderful as powerful web server written in Common Lisp, 
+into the @code{CLAWSERVER} class.
+
+As an Hunchentoot wrapper @code{CLAWSERVER} ``provides facilities like automatic session handling (with and without cookies), logging 
+(to Apache's log files or to a file in the file system), customizable error handling, and easy access to GET and POST parameters sent by the client.''
+
+ at section Understanding the clawserver
+
+ at code{CLAWSERVER} is not only a Hunchentoot wrapper, it is also the common place where you put your web applications 
+built with @value{claw} into lisplet that you can see as application resource containers and request dispatchers.
+
+ at subsection @code{CLAWSERVER} instance initialization
+
+When you want to instantiate a @code{CLAWSERVER} class, remember that it accepts the following initialization arguments:
+ at itemize @minus
+ at item
+ at emph{port} The port the server will be listening on, default is 80 
+ at item
+ at emph{sslport} The SSL port the server will be listening on, default is 443 if the server has a certificate file defined.
+ at item
+ at emph{address} A string denoting an IP address, if provided then the server only receives connections for that address.
+If address is NIL, then the server will receive connections to all IP addresses on the machine (default).
+ at item
+ at emph{name} Should be a symbol which can be used to name the server. 
+This name can utilized when defining easy handlers. The default name is an uninterned symbol as returned by GENSYM
+ at item
+ at emph{sslname} Should be a symbol which can be used to name the server running in SSL mode when a certificate file is provided. 
+This name can utilized when defining easy handlers. The default name is an uninterned symbol as returned by GENSYM
+ at item
+ at emph{mod-lisp-p} If  true (the default is NIL), the server will act as a back-end for mod_lisp, otherwise it will be a stand-alone web server.
+ at item
+ at emph{use-apache-log-p} If true (which is the default), log messages will be written to the Apache log file - this parameter has no effect if @emph{mod-lisp-p} is NIL.
+ at item
+ at emph{input-chunking-p} If true (which is the default), the server will accept request bodies without a Content-Length header if the client uses chunked transfer encoding.
+ at item
+ at emph{read-timeout} Is the read timeout (in seconds) for the socket stream used by the server. 
+The default value is @url{http://www.weitz.de/hunchentoot/#*default-read-timeout*,HUNCHENTOOT:*DEFAULT-READ-TIMEOUT*} (20 seconds)
+ at item
+ at emph{write-timeout} Is the write timeout (in seconds) for the socket stream used by the server. 
+The default value is @url{http://www.weitz.de/hunchentoot/#*default-write-timeout*,HUNCHENTOOT:*DEFAULT-WRITE-TIMEOUT*} (20 seconds)
+ at item
+ at emph{setuid} On Unix systems, changes the UID of the process directly after the server has been started.
+ at item
+ at emph{setgid} On Unix systems, changes the GID of the process directly after the server has been started.
+ at item
+ at emph{ssl-certificate-file} If you want your server to use SSL, you must provide the pathname designator(s) for the certificate file (must be in PEM format).
+ at item
+ at emph{ssl-privatekey-file} the pathname designator(s) for the private key file (must be in PEM format).
+ at item
+ at emph{ssl-privatekey-password} If private key file needs a password set this parameter to the required password
+ at end itemize
+
+ at subsection @code{CLAWSERVER} class methods
+
+ at sp 1
+ at fnindex clawserver-port
+ at noindent
+ at code{clawserver-port obj}@*
+ at code{(setf clawserver-port) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} The numeric value of listening port to assign 
+ at end itemize
+Returns and sets the port on which the server is listening to (default 80).
+If the server is started and you try to change the listening value an error will be signaled
+
+ at sp 1
+ at fnindex clawserver-sslport
+ at noindent
+ at code{clawserver-sslport obj}@*
+ at code{(setf clawserver-sslport) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} The numeric value of listening port to assign for SSL connections
+ at end itemize
+Returns and sets the port on which the server is listening to in SSL mode if a certificate file is provided (default 443).
+If the server is started and you try to change the listening value an error will be signaled
+
+ at sp 1
+ at fnindex clawserver-address
+ at noindent
+ at code{clawserver-address obj}@*
+ at code{(setf clawserver-address) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} The string value denoting the IP address
+ at end itemize
+Returns and sets the IP address where the server is bound to (default @code{NIL} @result{} any).
+If the server is started and you try to change the listening value an error will be signaled
+
+ at sp 1
+ at fnindex clawserver-name
+ at noindent
+ at code{clawserver-name obj}@*
+ at code{(setf clawserver-name) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} The symbol value denoting the server name
+ at end itemize
+Should be a symbol which can be used to name the server. 
+This name can utilized when defining easy handlers. The default name is an uninterned symbol as returned by GENSYM
+
+ at sp 1
+ at fnindex clawserver-sslname
+ at noindent
+ at code{clawserver-sslname obj}@*
+ at code{(setf clawserver-sslname) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} The symbol value denoting the server name running in SSL mode
+ at end itemize
+Should be a symbol which can be used to name the server running in SSL mode, when a certificate file is provided. 
+This name can utilized when defining easy handlers. The default name is an uninterned symbol as returned by GENSYM
+
+ at sp 1
+ at fnindex clawserver-mod-lisp-p
+ at noindent
+ at code{clawserver-mod-lisp-p obj}@*
+ at code{(setf clawserver-mod-lisp-p) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} The boolean value denoting the use of mod_lisp.
+ at end itemize
+Returns and sets the server startup modality .
+If  true (the default is @code{NIL}), the server will act as a back-end for mod_lisp, otherwise it will be a stand-alone web server.
+If the server is started and you try to change the listening value an error will be signaled
+
+ at sp 1
+ at fnindex clawserver-use-apache-log-p
+ at noindent
+ at code{clawserver-use-apache-log-p obj}@*
+ at code{(setf clawserver-use-apache-log-p) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} The boolean value denoting the use of Apache log.
+ at end itemize
+Returns and sets where the server should log messages. This parameter has no effects if clawserver-mod-lisp-p is set to @code{NIL}. (default @code{T} if @code{mod_lisp} 
+is activated.
+If the server is started and you try to change the listening value an error will be signaled
+
+ at sp 1
+ at fnindex clawserver-input-chunking-p
+ at noindent
+ at code{clawserver-input-chunking-p obj}@*
+ at code{(setf clawserver-input-chunking-p) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} The boolean value denoting the ability to accept request bodies without a Content-Length header.
+ at end itemize
+Returns and sets the ability to accept request bodies without a Content-Length header (default is @code{T})
+If the server is started and you try to change the listening value an error will be signaled
+
+ at sp 1
+ at fnindex clawserver-read-timeout
+ at noindent
+ at code{clawserver-read-timeout obj}@*
+ at code{(setf clawserver-read-timeout) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} The integer value denoting the server read timeout.
+ at end itemize
+Returns and sets the server read timeout in seconds (default is @code{T})
+(default to @url{http://www.weitz.de/hunchentoot/#*default-read-timeout*,HUNCHENTOOT:*DEFAULT-READ-TIMEOUT*} [20 seconds]).
+If the server is started and you try to change the listening value an error will be signaled
+
+ at sp 1
+ at fnindex clawserver-write-timeout
+ at noindent
+ at code{clawserver-write-timeout obj}@*
+ at code{(setf clawserver-write-timeout) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} The integer value denoting the server write timeout.
+ at end itemize
+Returns and sets the server write timeout in seconds (default is @code{T})
+(default to @url{http://www.weitz.de/hunchentoot/#*default-read-timeout*,HUNCHENTOOT:*DEFAULT-WRITE-TIMEOUT*} [20 seconds]).
+If the server is started and you try to change the listening value an error will be signaled
+
+ at sp 1
+ at fnindex clawserver-setuid
+ at noindent
+ at code{clawserver-setuid obj}@*
+ at code{(setf clawserver-setuid) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} The string or integer value of the UID with which the server instance will run.
+ at end itemize
+Returns and sets the server instance UID (user id).
+If the server is started and you try to change the listening value an error will be signaled
+
+ at sp 1
+ at fnindex clawserver-setgid
+ at noindent
+ at code{clawserver-setgid obj}@*
+ at code{(setf clawserver-setgid) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} The string or integer value of the GID with which the server instance will run.
+ at end itemize
+Returns and sets the server instance GID (group id).
+If the server is started and you try to change the listening value an error will be signaled
+
+ at sp 1
+ at fnindex clawserver-ssl-certificate-file
+ at noindent
+ at code{clawserver-ssl-certificate-file obj}@*
+ at code{(setf clawserver-ssl-certificate-file) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} Pathname designator(s) for the certificate file
+ at end itemize
+Returns and sets the pathname designator(s) for the certificate file if the @code{CLAWSERVER} is SSL enabled
+If the server is started and you try to change the listening value an error will be signaled
+
+ at sp 1
+ at fnindex clawserver-ssl-privatekey-file
+ at noindent
+ at code{clawserver-ssl-privatekey-file obj}@*
+ at code{(setf clawserver-ssl-privatekey-file) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} Pathname designator(s) for the private key file
+ at end itemize
+Returns and sets the pathname designator(s) for the private key file if the @code{CLAWSERVER} is SSL enabled
+If the server is started and you try to change the listening value an error will be signaled
+
+ at sp 1
+ at fnindex clawserver-ssl-privatekey-password
+ at noindent
+ at code{clawserver-ssl-privatekey-password obj}@*
+ at code{(setf clawserver-ssl-privatekey-password) val obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{val} Password for the private key file
+ at end itemize
+Returns and sets the password for the private key file if the @code{CLAWSERVER} is SSL enabled
+If the server is started and you try to change the listening value an error will be signaled
+
+ at sp 1
+ at fnindex clawserver-start
+ at noindent
+ at code{clawserver-start obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at end itemize
+Make the @code{CLAWSERVER} begin to dispatch requests
+
+ at sp 1
+ at fnindex clawserver-stop
+ at noindent
+ at code{clawserver-stop obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at end itemize
+Make the @code{CLAWSERVER} stop.
+
+ at sp 1
+ at fnindex clawserver-register-lisplet
+ at fnindex lisplet
+ at noindent
+ at code{clawserver-register-lisplet clawserver lisplet-obj}@*
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{lisplet-obj} A @code{LISPLET} class instance
+ at end itemize
+Registers a @code{LISPLET}, that is an `application container` for request dispatching.
+
+ at sp 1
+ at fnindex clawserver-unregister-lisplet
+ at noindent
+ at code{clawserver-unregister-lisplet clawserver lisplet-obj}
+ at indent
+
+ at itemize
+ at item
+ at emph{obj} The @code{CLAWSERVER} instance
+ at item
+ at emph{lisplet-obj} A @code{LISPLET} class instance
+ at end itemize
+Unregisters a @code{LISPLET}, that is an `application container`, an so all it's resources,  from the @code{CLAWSERVER} instance.
+
+ at section Starting the server
+
+Starting @value{claw} is very easy and requires a minimal effort.
+ at value{claw} supports both http and https protocols, thought enabling SSL connection for @value{claw} requires 
+a little more work then having it responding only to http calls.
+
+ at subsection Making @value{claw} work on http protocol
+
+To simply start @value{claw} server, without enabling SSL requests handling, you just need few steps:
+
+ at cartouche
+ at lisp
+(defparameter *clawserver* (make-instance 'clawserver))
+(clawserver-start *clawserver*)
+ at end lisp
+ at end cartouche
+
+This will start the web server on port 80 that is the default.
+
+
+Of course you can create a parametrized version of @code{CLAWSERVER} instance for example specifying the listening port as the following:
+
+ at cartouche
+ at lisp
+(defparameter *clawserver* (make-instance 'clawserver :port 4242))
+(clawserver-start *clawserver*)
+ at end lisp
+ at end cartouche
+
+ at subsection Making @value{claw} work on both http and https protocols
+
+To enable @value{claw} to https firt you need a certificate file.
+A quick way to get one on a Linux system is to use openssl to generate the a certificate PEM file, the following example explains how to do.
+
+Firstly you'll generate the private key file:
+
+ at cartouche
+ at example
+#> openssl genrsa -out privkey.pem 2048
+ at sp 1
+Generating RSA private key, 2048 bit long modulus
+............................+++
+..................................................+++
+e is 65537 (0x10001)
+ at sp 1
+#>
+ at end example
+ at end cartouche
+
+Then the certificate file:
+
+ at cartouche
+ at example
+#> openssl req -new -x509 -key privkey.pem -out cacert.pem -days 1095
+ at sp 1
+You are about to be asked to enter information that will be incorporated
+into your certificate request.
+What you are about to enter is what is called a Distinguished Name or a DN.
+There are quite a few fields but you can leave some blank
+For some fields there will be a default value,
+If you enter '.', the field will be left blank.
+-----
+Country Name (2 letter code) [AU]:IT
+State or Province Name (full name) [Some-State]: bla-bla
+Locality Name (eg, city) []: bla-bla
+Organization Name (eg, company) [Internet Widgits Pty Ltd]: mycompany
+Organizational Unit Name (eg, section) []:
+Common Name (eg, YOUR name) []:www.mycompany.com
+Email Address []:admin@@mycompany.com
+ at sp 1
+#>
+ at end example
+ at end cartouche
+
+Now you can start @code{CLAWSERVER} in both http and https mode:
+
+ at cartouche
+ at lisp
+(defparameter *clawserver* (make-instance 'clawserver :port 4242 :sslport 4443 
+              :ssl-certificate-file #P"/path/to/certificate/cacert.pem" 
+              :ssl-privatekey-file #P"/path/to/certificate/privkey.pem")))
+(clawserver-start *clawserver*)
+ at end lisp
+ at end cartouche
+
+ at value{claw} is now up and you can browse it with your browser using address http://www.yourcompany.com:4242 and http://www.yourcompany.com:4443. 
+Of course you will have only a 404 response page!

