mthl
/
texinfo


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336
							<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Installing web page scripts as Servlets</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Overall-Index.xhtml" title="Index"/>
    <link rel="next" href="CGI-scripts.xhtml" title="Installing Kawa programs as CGI scripts"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Installing web page scripts as Servlets" epub:type="subchapter" id="Servlets">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Installing web page scripts as Servlets</h2>
          </div>
        </div>
      </div>
      <p>You can compile a Kawa program to a <a class="ulink" href="http://en.wikipedia.org/wiki/Java_Servlet" target="_top">Servlet</a>, and run it
in a servlet engine (a Servlet-aware web server).
One or more servlets are installed together as a web application.
This section includes specific information for
the Tomcat and Glassfish web servers.
</p>
      <section class="sect2" title="Creating a web application" epub:type="division" id="idm139667870369168">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Creating a web application</h3>
            </div>
          </div>
        </div>
        <p>A <em class="firstterm">web application</em> is a group of data, servlets, and
configuration files to handle a related set of URLs.
The <a class="ulink" href="http://jcp.org/aboutJava/communityprocess/final/jsr315/index.html" target="_top">servlet specification</a>
specifies the directory structure of a web application.
</p>
        <p>Assume the web application is called <code class="literal">myapp</code>, and lives in a
directory with the same name.  The application normally handles
requests for URLs that start with <code class="literal">http://example.com/myapp</code>.
Most files in the application directory are used to handle
requests with corresponding URL.  For example,
a file <code class="literal">myapp/list/help.html</code> would be the response
to the request <code class="literal">http://example.com/myapp/list/help.html</code>.
</p>
        <p>The directory <code class="literal">WEB-INF</code> is special.  It contains configuration
files, library code, and other server data.
</p>
        <p>So to create the <code class="literal">myapp</code> application, start with:
</p>
        <pre class="screen">mkdir myapp
cd myapp
mkdir WEB-INF WEB-INF/lib WEB-INF/classes
</pre>
        <p>Copy the Kawa jar from the <code class="literal">lib</code> direcory.
(You can also use a “hard” link, but symbolic links may not
work, for security systems.)
</p>
        <pre class="screen">cp <em class="replaceable"><code>kawa-home</code></em>/kawa-2.92_invoke.jar WEB-INF/lib/kawa.jar
</pre>
        <p>If you build Kawa from source, you must specify the
<code class="literal">--with-servlet</code> <a class="link" href="Source-distribution.xhtml#configure-options">configure option</a>.
</p>
        <p>You should also create the file <code class="literal">WEB-INF/web.xml</code>.
For now, this is is just a place-holder:
</p>
        <pre class="screen">&lt;web-app&gt;
  &lt;display-name&gt;My Application&lt;/display-name&gt;
&lt;/web-app&gt;
</pre>
      </section>
      <section class="sect2" title="Compiling a web page script to a servlet" epub:type="division" id="idm139667870357024">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Compiling a web page script to a servlet</h3>
            </div>
          </div>
        </div>
        <p>Assume for simplicity that the source files
are in the <code class="literal">WEB-INF/classes</code> directory, and make that the
current directory:
</p>
        <pre class="screen">cd .../myapp/WEB-INF/classes
</pre>
        <p>Depending on the source language, you compile your script
sing the <code class="literal">--servlet</code> switch:
</p>
        <pre class="screen">kawa --servlet -C hello.scm
</pre>
        <p>or:
</p>
        <pre class="screen">kawa --servlet --krl -C hello.krl
</pre>
        <p>or:
</p>
        <pre class="screen">kawa --servlet --xquery -C hello.xql
</pre>
        <p>This lets the web-application find the compiled servlets.
Finally, you just need to add the new servlet to
the <code class="literal">WEB-INF/web.xml</code> file:
</p>
        <pre class="screen">&lt;web-app&gt;
  &lt;display-name&gt;My Application&lt;/display-name&gt;

  &lt;servlet&gt;
    &lt;servlet-name&gt;MyHello&lt;/servlet-name&gt;
    &lt;servlet-class&gt;hello&lt;/servlet-class&gt;
  &lt;/servlet&gt;

  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;MyHello&lt;/servlet-name&gt;
    &lt;url-pattern&gt;/hello&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;
&lt;/web-app&gt;
</pre>
        <p>The <code class="literal">&lt;servlet&gt;</code> clause says that the servlet named
<code class="literal">MyHello</code> is implemented by the Java class <code class="literal">hello</code>.
The <code class="literal">&lt;servlet-mapping&gt;</code> clause says that a request
URL <code class="literal">/hello</code> should be handled by the servlet named <code class="literal">MyHello</code>.
The URL is relative to the application context path,
so the actual URL would be <code class="literal">http://example.com/myapp/hello</code>.
</p>
      </section>
      <section class="sect2" title="Installing a servlet under Tomcat" epub:type="division" id="idm139667870346784">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Installing a servlet under Tomcat</h3>
            </div>
          </div>
        </div>
        <a id="idm139667870345824" class="indexterm"/>
        <p>Apache’s <a class="ulink" href="http://tomcat.apache.org/" target="_top">Tomcat</a> is an open-source
implementation of the servlet specifications.
After you <a class="ulink" href="http://tomcat.apache.org/download-60.cgi" target="_top">download it</a>,
uncompress it in some convenient location,
which is commonly referred to as <code class="literal">$CATALINA_HOME</code>.
</p>
        <p>To install your web application, copy/move its directory
to be in the <code class="literal">$CATALINA_HOME/webapps</code> directory.
Thus for the example above you would have
a <code class="literal">$CATALINA_HOME/webapps/myapp</code> directory.
</p>
        <p>To start or stop Tomcat use the scripts in <code class="literal">$CATALINA_HOME/bin</code>.
For example to start Tomcat on a GNU/Linux system run
<code class="literal">$CATALINA_HOME/bin/startup.sh</code>.  This will start a web server
that listens on the default port of 8080,
so you can browse the above example at <code class="literal">http://localhost:8080/myapp/hello</code>.
</p>
        <p>If you’re running Fedora GNU/Linux, you can use the <code class="literal">tomcat6</code> package:
</p>
        <pre class="screen"># yum install tomcat6
# export CATALINA_HOME=/usr/share/tomcat6
</pre>
        <p>You can the manage Tomcat like other system services.
You can install webapps under <code class="literal">$CATALINA_HOME/webapps</code>.
</p>
      </section>
      <section class="sect2" title="Installing a servlet under Glassfish" epub:type="division" id="idm139667870337024">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Installing a servlet under Glassfish</h3>
            </div>
          </div>
        </div>
        <a id="idm139667870336064" class="indexterm"/>
        <p><a class="ulink" href="https://glassfish.dev.java.net/" target="_top">Glassfish</a> from Oracle/Sun
is a open-source “application server” that implements
Java EE 6, including the 3.0 servlet specification.
After you <a class="ulink" href="https://glassfish.dev.java.net/downloads/3.0.1-final.html" target="_top">download it</a>, uncompress it in some convenient location.
This location is called <em class="replaceable"><code>as-install-parent</code></em> in the
<a class="ulink" href="http://docs.sun.com/app/docs/doc/820-7689/aboaa?a=view" target="_top">Quick Start Guide</a>.
The commands you will use is most in <code class="literal"><em class="replaceable"><code>as-install</code></em>/bin</code>,
where <em class="replaceable"><code>as-install</code></em> is <code class="literal"><em class="replaceable"><code>as-install</code></em>/glassfish</code>.
</p>
        <p>To start the server, do:
</p>
        <pre class="screen"><em class="replaceable"><code>as-install</code></em>/bin/startserv
</pre>
        <p>or under under Windows:
</p>
        <pre class="screen"><em class="replaceable"><code>as-install</code></em>\bin\startserv.bat
</pre>
        <p>The default post to listen to is <code class="literal">8080</code>;
you can the port (and lots of other properties)
using the adminstration console at port <code class="literal">4848</code>.
</p>
        <p>A web application does not need to be any particular
location, instead you just install it with this command:
</p>
        <pre class="screen"><em class="replaceable"><code>as-install</code></em>/bin/adadmin deploy <em class="replaceable"><code>appdir</code></em>
</pre>
        <p>where <em class="replaceable"><code>appdir</code></em> is the application directory - <code class="literal">myapp</code> in the example.
(Use <code class="literal">asadmin.bat</code> under Windows.)
</p>
      </section>
      <section class="sect2" title="Servlet-specific script functions" epub:type="division" id="idm139667870323664">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Servlet-specific script functions</h3>
            </div>
          </div>
        </div>
        <p>The following functions only work within a servlet container.
To use these functions, first do:
</p>
        <pre class="screen">(require 'servlets)
</pre>
        <p>You can conditionalize your code to check at compile-time for servlets,
like this:
</p>
        <pre class="screen">(cond-expand
 (in-servlet
   (require 'servlets)
   (format "[servlet-context: ~s]" (current-servlet-context)))
 (else
   "[Not in a servlet]"))
</pre>
        <p>For a run-time check you can test if <code class="literal">(current-servlet)</code> is
non-<code class="literal">#!null</code>.
</p>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870319328" class="indexterm"/> <code class="function">current-servlet</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>When called from a Kawa servlet handler, returns the
actual <code class="literal">javax.servlet.http.HttpServlet</code> instance.
Returns <code class="literal">#!null</code> if the current context is not that of
<code class="literal">KawaServlet</code>.
(Hence this function also returns <code class="literal">#!null</code> if you compile a servlet
“by hand” rather that using the <code class="literal">--servet</code> option.)
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870313888" class="indexterm"/> <code class="function">current-servlet-context</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Returns the context of the currently executing servlet,
as an instance of <code class="literal">javax.servlet.ServletContext</code>.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870310432" class="indexterm"/> <code class="function">current-servlet-config</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Returns the <code class="literal">ServletConfig</code> of the currently executing servlet.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870307008" class="indexterm"/> <code class="function">get-request</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Return the current servlet request, as an instance of
<code class="literal">javax.servlet.http.HttpServletRequest</code>.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870303584" class="indexterm"/> <code class="function">get-response</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Return the current servlet response, as an instance of
<code class="literal">javax.servlet.http.HttpServletResponse</code>.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870300160" class="indexterm"/> <code class="function">request-servlet-path</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Get the servlet path of the current request.
Similar to <code class="literal">request-script-path</code>, but not always the same,
depending on configuration, and does <span class="emphasis"><em>not</em></span> end with a <code class="literal">"/"</code>.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870295824" class="indexterm"/> <code class="function">request-path-info</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Get the path info of the current request.
Corresponds to the CGI variable <code class="literal">PATH_INFO</code>.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870292384" class="indexterm"/> <code class="function">servlet-context-realpath</code> [<em class="replaceable"><code>path</code></em>]</p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Returns the file path of the current servlet’s "Web application".
</p>
          </blockquote>
        </div>
      </section>
    </section>
    <footer>
      <div class="navfooter">
        <ul>
          <li>
            <b class="toc">
              <a href="Servlets.xhtml#idm139667870369168">Creating a web application</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Servlets.xhtml#idm139667870357024">Compiling a web page script to a servlet</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Servlets.xhtml#idm139667870346784">Installing a servlet under Tomcat</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Servlets.xhtml#idm139667870337024">Installing a servlet under Glassfish</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Servlets.xhtml#idm139667870323664">Servlet-specific script functions</a>
            </b>
          </li>
        </ul>
        <p>
          Up: <a accesskey="u" href="XML-tools.xhtml">Working with XML and HTML</a></p>
        <p>
        Previous: <a accesskey="p" href="Self-configuring-page-scripts.xhtml">Self-configuring web page scripts</a></p>
        <p>
        Next: <a accesskey="n" href="CGI-scripts.xhtml">Installing Kawa programs as CGI scripts</a></p>
      </div>
    </footer>
  </body>
</html>