os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

New article on Java / Jakarta / Tomcat

Browse source 
PR:		36722
Submitted by:	Hiten Pandya <hiten@uk.FreeBSD.org>
Approved by:	jim
This commit is contained in:
Tom Rhodes 2002-04-10 19:23:54 +00:00
parent 3bac820ce5
commit 57566389d3
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=12740
2 changed files with 619 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
en_US.ISO8859-1/articles/java-tomcat/Makefile Normal file
View file

@ -0,0 +1,22 @@
#
# FreeBSD Documentation Project
# $FreeBSD$
#
# Makefile for "Java and FreeBSD First Steps"
# Author: Victoria Chan, Hiten Pandya
MAINTAINER=vkchan@kendryl.net hiten@uk.FreeBSD.org
DOC?= article
FORMATS?= html
INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=
# SGML content
SRCS= article.sgml
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

597
en_US.ISO8859-1/articles/java-tomcat/article.sgml Normal file
View file

@ -0,0 +1,597 @@
<!-- Copyright (c) 2002, Hiten Pandya, Victoria Chan, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML, HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS AND CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.
-->
<!--
Written by Victoria Chan <vkchan@kendryl.net>. The original document can
be found at: http://www.kendryl.net/jdk13-1.html.
-->
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
<!--
URL Entities. These are in place, to allow wrapping long URLs to the 80th
column.
-->
<!ENTITY wwwurl "http://www.FreeBSD.org">
<!ENTITY ftpurl "ftp://ftp.FreeBSD.org">
<!ENTITY sunurl "http://www.sun.com">
<!ENTITY tomcaturl "http://jakarta.apache.org/tomcat">
<!-- The Download URL is too long! :-) -->
<!ENTITY tomcat403 "http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/v4.0.3/bin/">
%man;
]>
<article>
<!-- START of Article Metadata -->
<articleinfo>
<title>Java and Jakarta Tomcat on FreeBSD</title>
<authorgroup>
<author>
<firstname>Victoria</firstname>
<surname>Chan</surname>
<affiliation>
<address><email>vkchan@kendryl.net</email></address>
</affiliation>
</author>
<author>
<firstname>Hiten</firstname>
<surname>Pandya</surname>
<affiliation>
<address><email>hiten@uk.FreeBSD.org</email></address>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>2002</year>
<holder role="mailto:vkchan@kendryl.net">Victoria Chan</holder>
<holder role="mailto:hiten@uk.FreeBSD.org">Hiten Pandya</holder>
</copyright>
<pubdate>$FreeBSD$</pubdate>
<abstract>
<para>This document is presented in hopes of making it easier for anyone that
needs to get Java up and running on FreeBSD,
with the least amount of aggravation. Plan on spending a whole day on
such a project as it will take time to assemble all the pieces and
compile them individually, and then as a whole. It also shows how to
install the famous Jakarta Tomcat Servlet and
JSP container on the FreeBSD operating system.</para>
</abstract>
</articleinfo>
<!-- END of Article Metadata-->
<sect1>
<title>Introduction</title>
<para>The Java programming language was birthed on
<literal>May 23rd 1995</literal>. One would expect that after all this
time, Java applications would be easy to install and ready to run from a
single package, or port on FreeBSD, thus making it available for the
<quote>masses</quote>. This is not the case, unfortunately, as the Java
distribution is held very closely by Sun Microsystems, and prohibits re-distribution.
All Java Applets must be compiled from source code, together with the Java
Development Kit from Sun Microsystems. All these ingredients
must be blended together in the right order, assembled, and compiled by
the end user. With such distribution philosophies at heart, it is my
opinion that Java will always be developer or hacker use only. I certainly
found this to be true when I needed to serve up some
<filename>.jsp</filename> pages for a client on my web server, and needed
to get <filename role="package">www/jakarta-tomcat</filename> to work with
<filename role="package">www/apache13</filename> on my FreeBSD system.</para>
<para>The Tomcat portion of the install is very straight forward, but the
difficulty I had was getting Java Development Kit up and running for
FreeBSD 4.x, as Sun Microsystems only supplies Binaries for Linux,
Solaris, and Windows NT.
This means that I had to compile my own JDK for FreeBSD. I began by
searching for documentation on the Internet. I quickly found that there
is more source code than I need along with patches to the source code, but very
little documentation of what to do after obtaining everything.</para>
<para>In this article, you will find how to install the Java Development Kit
for FreeBSD, and how to get up and running with Tomcat. A
<xref linkend="ref"> section is also provided for further reading.</para>
</sect1>
<sect1>
<title>The Java Environment</title>
<para>Ensure that you have the current ports collection as
<command>make</command> it will fail if it attempts to build
older source. You can upgrade your entire ports collection by
using <application>CVSup</application>. See <ulink
url="&wwwurl;/doc/en_US.ISO8859-1/books/handbook/cvsup.html"></ulink>
for more information. You can also download the ports you need manually
from <ulink url="&ftpurl;/pub/FreeBSD/branches/-current/ports/"></ulink>
to get you going.</para>
<note>
<para>You will need the <literal>Linux Emulation</literal> (Linux-ABI)
enabled in your kernel configuration. Simply add the following option
to your kernel configuration file and recompile it. Instructions for
building a kernel can be found in the FreeBSD Handbook.</para>
<programlisting>options COMPAT_LINUX</programlisting>
<para>The above option will add Linux-ABI support to your kernel, when
it is recompiled.</para>
</note>
<para>The list of dependencies below, are required to be installed manually
in a certain order. Dependencies that are automatically downloaded are not
listed here.</para>
<itemizedlist>
<listitem>
<para><filename role="package">java/jdk13</filename></para>
</listitem>
<listitem>
<para><filename role="package">java/linux-jdk13</filename></para>
</listitem>
<listitem>
<para><filename role="package">archivers/gtar</filename></para>
</listitem>
<listitem>
<para><filename role="package">archivers/bzip2</filename></para>
</listitem>
<listitem>
<para><filename role="package">archivers/unzip</filename></para>
</listitem>
<listitem>
<para><filename role="package">archivers/zip</filename></para>
</listitem>
</itemizedlist>
<para>You will need to get the following:</para>
<procedure>
<step>
<para>Download <filename>bsd-jdk131-patches-5.tar.gz</filename> from
<ulink url="http://www.eyesbeyond.com/freebsddom/java/jdk13.html"></ulink>
and place it under <filename>/usr/ports/distfiles</filename>.</para>
</step>
<step>
<para>Next get out your web browser and head on over to
<ulink url="http://java.sun.com/j2se/1.3/download-linux.html"></ulink>
and find SDK downloads. Click on the <quote>continue</quote> button
below <quote>GNUZIP Tar Shell Script</quote>. Be sure you read every
word of the license page before you click on the <quote>Accept</quote>
button! You will be brought to a page titled <quote>Download Java(TM) 2
SDK, Standard Edition 1.3.1_02</quote>. Scroll to the bottom and click on
the <quote>HTTP download</quote> button. When the <quote>File Download</quote>
box comes up, be sure to click on the <quote>Open</quote> button rather than the
<quote>Save</quote> button. You will be presented with another
<quote>File Download</quote> box - this time choose <quote>Save</quote>
and you will be able to save j2sdk-1_3_1_02-linux-i386.bin.
Place it in /usr/ports/distfiles.</para>
</step>
<step>
<para>Go to <ulink url="http://www.sun.com/software/java2/download.html"></ulink>.
In the table under <literal>Produce Description</literal>, named
<literal>Java 2 SDK 1.3.1</literal>, go to the right-hand cell and
click <quote>download</quote>. You will be taken to the <quote>Sign On</quote>
page, where you must sign in if you already have an account, or
register for access. Once you have signed on, you will be taken to the
<quote>Legal</quote> page, where you must accept the license agreement;
scroll down (reading the license) and click on the <quote>Continue</quote>
button. Next page, is the <quote>Receipt</quote> page. This is where you
will save you order number. You will be able to choose the location
that is nearest to you. Click on <quote>Java 2 SDK, Standard
Edition, version 1.3.1</quote>. Save the
<filename>j2sdk-1_3_1-src.tar.gz</filename> to the
<filename>/usr/ports/distfiles/</filename> directory.</para>
</step>
</procedure>
<note><para>It is very important for you to read the License Agreement which
has been issued by Sun Microsystems Corp. There are several restrictions
in place on the use of Java, which you must address. The FreeBSD Project
does not take any responsibilities for your actions.</para>
<para>Do not discard any of the downloaded files, as they will be needed for
building some of the native ports for FreeBSD, which are discussed later
on.</para>
</note>
<para>Now that you have assembled all the source files and ports, you need
to start by building
<filename role="package">java/linux-jdk13</filename>:</para>
<screen>&prompt.root; cd /usr/ports/archivers/gtar; make all install clean</screen>
<screen>&prompt.root; cd /usr/ports/archivers/unzip; make all install clean</screen>
<screen>&prompt.root; cd /usr/ports/archivers/zip; make all install clean</screen>
<para>And finally:</para>
<screen>&prompt.root; cd /usr/ports/java/linux-jdk13</screen>
<screen>&prompt.root; make all install clean</screen>
<para>Once you have built
<filename role="package">java/linux-jdk13</filename>, you need to test
it, to make sure it works as intended. To do that:
<screen>&prompt.root; cd /usr/local/linux-jdk1.3.1/bin</screen>
<screen>&prompt.root; ./java-version</screen>
<para>The output of the above command should be as follows:</para>
<programlisting>java version "1.3.1_02"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_02-b02)
Classic VM (build 1.3.1_02-b02, green threads, nojit)</programlisting>
<para>If you did not get the correct response, you need to:</para>
<screen>&prompt.root; cd /usr/ports/java/linux-jdk13</screen>
<screen>&prompt.root; make deinstall</screen>
<para>And make sure that <filename>/usr/local</filename> does not contain a
<filename>linux-jdk1.3.1</filename> directory. If you find a fragment of
the directory, delete it. Repeat the <literal>build and install</literal>
process for <filename role="package">java/linux-jdk13</filename>.</para>
<para>To make the native <literal>Java Development Kit 1.3.1</literal> for
FreeBSD, do the following:</para>
<procedure>
<step>
<para>Make sure you have the <filename>j2sdk-1_3_1-src.tar.gz</filename>
file in your <filename>/usr/ports/distfiles</filename>. This file is
needed for applying the <quote>patch-sets</quote> discussed below.</para>
</step>
<step>
<para>You will need to download the <literal>patch set</literal>
for building the port. The patch-set file is called
<filename>bsd-jdk131-patches-6.tar.gz</filename>. You should also make sure
the integrity of the files by matching it with the following
<acronym>MD5</acronym> checksum. The patch-set is called
<literal>Patch-set 6</literal>.</para>
<programlisting>
MD5 (bsd-jdk131-patches-6.tar.gz) = 9cade10b81d6034fdd2176bef32bdbf9
</programlisting>
<para>The patch-set is available from:
<ulink url="http://www.eyesbeyond.com/freebsddom/java/index.html"></ulink></para>
</step>
</procedure>
<para>The last procedure discussed above (building the native
<literal>jdk</literal>) will take some time.</para>
</sect1>
<sect1>
<title>Jakarta Tomcat Setup</title>
<sect2>
<title>Overview</title>
<para>Java is becoming an even more popular
for making diverse and scalable platform independent
solutions. One of the most growing needs of Java is in the
<literal>ASP (Application Service Provider)</literal> market.
Java serves as the perfect solution for these types
of markets, with the following advantages:</para>
<itemizedlist>
<listitem>
<para>Platform Independence</para>
</listitem>
<listitem>
<para>Industry Wide Commitment</para>
</listitem>
<listitem>
<para>Scalability</para>
</listitem>
<listitem>
<para>Reliable Performance</para>
</listitem>
<listitem>
<para>Distributed, Multi-threaded, Secure etc.</para>
</listitem>
</itemizedlist>
<para>A very important and growing technology which has emerged
from Java is <acronym>JSP</acronym> (JavaServer Pages).</para>
<para><acronym>JSP</acronym> (JavaServer Pages) is a server-side technology
introduced by <literal>Sun Microsystems Corp.</literal>, which provides a
quick simple way to generate dynamic content from within
<acronym>HTML</acronym> pages. It uses <acronym>XML</acronym> tags
along with Java scriptlets to encapsulate and separate the logic from
the design and display. When a <acronym>JSP</acronym> page is
invoked, it is dynamically converted into a Servlet and processed by the
server to produce the resulting <acronym>HTML/XML</acronym> page for
the client. When <acronym>JSP</acronym> is used in conjunction with
JavaBeans, it is possible to produce very diverse and scalable applications,
which may be combined with the strength and performance of FreeBSD.</para>
<para><application>Tomcat</application> is an open-source implementation
of the Java Servlets and JavaServer Pages technologies, developed under the
Jakarta project at the Apache Software Foundation.
Tomcat implements a new Servlet framework (called Catalina) that is
based on completely new architecture with the Servlet 2.3 and
<acronym>JSP</acronym> 1.2 specifications. It includes many
additional features that make it a useful platform for developing
and deploying web applications and web services. In a nutshell,
Tomcat is an application server written in 100% Pure Java.</para>
<para>Tomcat is used for many purposes, and is not limited to Application
Servers. It provides and open platform to develop extensible web and
content management services. When Tomcat is used with an optimized
FreeBSD system, it can provide highly reliable and fast pacing services.</para>
<para>Please refer to the <xref linkend="ref"> section for more
information on Tomcat and <acronym>JSP</acronym>. The next section
will demonstrate how to build the <quote>Tomcat Environment</quote>
for FreeBSD. The version of Tomcat used in this guide is
<literal>4.0.3</literal>. This version contains
major bug fixes, and the following updates/changes:</para>
<itemizedlist>
<listitem>
<para><literal>JSP 1.2 Specification</literal></para>
</listitem>
<listitem>
<para><literal>Java Servlet 2.3 Specification</literal></para>
</listitem>
<listitem>
<para><literal>Full backward compatibility with the Java Servlet
2.2 and JSP 1.1 Specification</literal></para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>The Tomcat environment for FreeBSD</title>
<para>It is very simple to install Tomcat on a FreeBSD machine, after
setting up the necessary Java environment, which
we have previously completed.</para>
<para>In-order to setup Tomcat on FreeBSD, follow the below
procedure:</para>
<procedure>
<step>
<para>Follow the above steps to setup the necessary
Java environment.</para>
</step>
<step>
<para>Set an environment variable <envar>JAVA_HOME</envar> which,
points to the directory where you have installed the JDK (the below
example points to a native build of the JDK):</para>
<screen>&prompt.root; setenv JAVA_HOME /usr/local/jdk1.3.1 (for C Shells)</screen>
<screen>&prompt.root; export JAVA_HOME=/usr/local/jdk1.3.1 (for Bourne Shells)</screen>
<para>This environment variable should be made permanent by adding it
into either <filename>.profile</filename> or <filename>.cshrc</filename>,
depending on the shell you are using. This variable is very crucial for
the functioning of all the Java based programs, including Tomcat itself.</para>
</step>
<step>
<para>Download the Tomcat <quote>binary distribution</quote> from
the Jakarta website, which is located at
<literal><ulink url="&tomcat403"></ulink></literal>. The file to
download is called <filename>jakarta-tomcat-4.0.3.tar.gz</filename>.</para>
</step>
<step>
<para>The compressed and archived file we downloaded in the previous
step uses special <quote>GNU Extensions</quote>. In-order to untar
and uncompress the file, we will need to install
<literal>GNU Tar (<filename role="package">archivers/gtar</filename>)</literal>,
by doing the following:</para>
<screen>&prompt.root; cd /usr/ports/archivers &amp; &amp; make all install clean</screen>
</step>
<step>
<para>Un-tar and Un-compress the
<filename>jakarta-tomcat-4.0.3.tar.gz</filename> file into the
<filename>/usr/local</filename> directory and rename the directory
to <filename>tomcat-4.0</filename> for ease of reference:</para>
<screen>&prompt.root; cd /usr/local</screen>
<screen>&prompt.root; gtar zxvf jakarta-tomcat-4.0.3.tar.gz</screen>
<screen>&prompt.root; ls jakarta*</screen>
<screen>jakarta-tomcat-4.0.3</screen>
<screen>&prompt.root; mv jakarta-tomcat-4.0.3 tomcat-4.0</screen>
<para>You can remove the
<filename>jakarta-tomcat-4.0.3.tar.gz</filename> at your preference.</para>
</step>
</procedure>
<note>
<para><literal>Installation by using the source code is currently out of
scope for this document. Please refer to the following files for
addition information on building from source, available from your
Tomcat distribution directory:</literal></para>
<itemizedlist>
<listitem>
<para><filename>/usr/local/tomcat-4.0/README.txt</filename></para>
</listitem>
<listitem>
<para><filename>/usr/local/tomcat-4.0/BUILDING.txt</filename></para>
</listitem>
</itemizedlist>
</note>
</sect2>
<sect2>
<title>Operating Tomcat - Basics</title>
<para>Now that we have finished installing Tomcat. The following
example shows how to start the Tomcat server:</para>
<screen>&prompt.root; cd /usr/local/tomcat-4.0/bin</screen>
<screen>&prompt.root; ./startup.sh (for starting Tomcat)</screen>
<para>You can test if your Tomcat server has started by visiting the
following URL: <literal>http://127.0.0.1:8080</literal> or
<literal>http://localhost:8080</literal>. To stop Tomcat:</para>
<screen>&prompt.root; cd /usr/local/tomcat-4.0/bin</screen>
<screen>&prompt.root; ./shutdown.sh</screen> <para>(for stopping Tomcat)</para>
<para>The <filename>startup.sh</filename> and
<filename>shutdown.sh</filename> are frontends to the
<filename>catalina.sh</filename> executable script in the same directory;
if you would like to start Tomcat automatically at boot-time run:</para>
<screen>&prompt.root; cd /usr/local/etc/rc.d</screen>
<screen>&prompt.root; ln -s /usr/local/tomcat-4.0/bin/catalina.sh</screen>
<para>Edit the <filename>catalina.sh</filename>, and add the following
at the beginning of the file (after the comment box):</para>
<programlisting>JAVA_HOME=/usr/local/jdk1.3.1</programlisting>
<para>If your port <literal>8080</literal> is occupied by some other
service, you can change it by editing the <filename>server.xml</filename>
in your Tomcat's <filename>conf/</filename> directory. In the
example below, the port will be changed to 80, assuming there is no
service running on that port.</para>
<screen>&prompt.root; cd /usr/local/tomcat-4.0/conf</screen>
<screen>&prompt.root; fgrep -n 8080 server.xml</screen>
<screen>~65: By default, a non-SSL HTTP/1.1 Connector is established on port 8080.</screen>
<screen>~89: port="8080" minProcessors="5" maxProcessors="75"</screen>
<screen>&prompt.root; cat server.xml | sed s/8080/80/ > server.xml</screen>
</sect2>
</sect1>
<sect1 id="ref" xreflabel="reference">
<title>Reference</title>
<informaltable>
<tgroup cols="1">
<tbody>
<row>
<entry>
<ulink url="&wwwurl;/java">The FreeBSD Java Project</ulink>
</entry>
</row>
<row>
<entry>
<ulink url="http://java.sun.com">JavaSoft. Home of Java</ulink>
</entry>
</row>
<row>
<entry>
<ulink
url="&sunurl;/software/communitysource/java2/licensing.html">The
Sun Community Source Licensing for Java</ulink>
</entry>
</row>
<row>
<entry>
<ulink url="&tomcaturl">Jakarta Tomcat Homepage</ulink>
</entry>
</row>
<row>
<entry>
<ulink url="http://java.sun.com/docs/index.html">J2SE
Documentation</ulink>
</entry>
</row>
<row>
<entry>
<ulink url="&wwwurl;/ports/java.html">FreeBSD Ports - Java
Section</ulink>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<sect2>
<title>Conclusion</title>
<para>Finally, we are at the end of the article and have a working version of
Tomcat. We hope that you have learned the basics of installing and
building the Java Development Kit on FreeBSD, along with installation
of the Tomcat binary distribution application server released by the
Apache Software Foundation. The <xref linkend="ref"> section
contains pointers to additional resources on this topic, some which
are in print, some which are on the World Wide Web, or both.</para>
<para>The most important thing is drive space. I suggest having
<literal>700MB</literal> or more free space in <filename>/usr</filename>.
I hope this article has helped you in some small way. For
questions, comments, compliments, or rants, please direct them to
<ulink url="mailto:vkchan@kendryl.net">Victoria Chan</ulink>.</para>
</sect2>
</sect1>
</article>