Como instalar e configurar o Tomcat no Windows

O Apache Tomcat é a Implementação de Referência para Servlets Java e Páginas JSP. O Tomcat é um projeto open-source, desenvolvido sob a administração da Fundação Apache (que também fornece o famoso servidor HTTP Apache). O site do Tomcat é o http://tomcat.apache.org.  Esse guia é aplicável ao Tomcat 6.0.x. Leia o artigo “Tomcat 7 – How to Install and Configure”  para informações sobre a instalação da versão 7.

Passo 1: Baixe o Tomcat

• No site http://tomcat.apache.org ⇒ Selecione “Downloads” ⇒ “Tomcat 6.0” ⇒ “6.0.xx” ⇒ “Binary Distributions” ⇒ “Core” ⇒ “zip” ⇒ “apache-tomcat-6.0.xx.zip“.
• Descompacte o arquivo em um diretório de sua escolha (como o C:\). O Tomcat será descompactado no diretório “c:\apache-tomcat-6.0.xx“. Nesse artigo, o diretório onde o Tomcat está instalado será referenciado como $CATALINA_HOME or %CATALINA_HOME% (Catalina é o codinome para o Tomcat 5 e versões mais atuais). As versões mais antigas são chamadas somente de Tomcat). A versão “zip” é recomendável por que simplesmente é necessário apagar o diretório inteiro quando o Tomcat não for mais necessário. Você deve também renomear o nome do diretório para algo mais curto (como C:\Tomcat6).

Passo 2: Criar as variáveis de ambiente

• Crie uma variável de ambiente chamada “JAVA_HOME” e ajuste o valor dela para o diretório do JDK (exemplo: c:\program files\java\jdk1.6.0_xx).
• No Windows XP/Vista/7: Clique no botão Iniciar -> Painel de Controle -> Sistema -> Configurações avançadas -> Avançado -> Variáveis de ambiente -> Variáveis do sistema -> Nova -> Informe o valor “JAVA_HOME” no campo “Nome de variável” e o diretório do JDK no campo “Valor da variável”.
• Para verificar, inicie o terminal e digite:

  > set JAVA_HOME
  JAVA_HOME=c:\program file\java\jdk1.6.0_xx

Passo 3: Configurar o arquivo “$CATALINA_HOME\conf\server.xml”

Número da porta TCP: O número padrão da porta TCP para o Tomcat é 8080, mas você pode escolher qualquer número entre 1024 e 65535 para o seu servidor. Iremos manter a porta 8080 nesse artigo (Para servidores de produção, você deve usar a porta 80, que é associada ao protocolo HTTP).

<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />

Contexto: Um contexto web é simplesmente uma aplicação web que roda dentro do servidor Tomcat. Para criar uma nova aplicação web, adicione o caminho de sua aplicação (URL usada pelo usuário para acessar a sua aplicação) e forneça um “docBase” (diretório onde você armazenar o código da aplicação), antes da tag </Host>, como no exemplo a seguir:

        ......
        ......
        <Context path="/ws" docBase="d:/workshop" reloadable="true">
        </Context>
      </Host>
    </Engine>
  </Service>
</Server>

Explicação:

• O atributo ˜path” refere-se a URl usada pelos usuários para acessar a aplicação web. No exemplo acima, um caminho “/ws” é definido. Para acessar essa aplicação, os usuários usam a URL http://hostname:8080/ws.
• O atributo “docBase” refere-se ao Diretório base (também conhecido como Raiz do contexto) do sistema de arquivos de seu servidor, onde está armazenado os códigos de sua aplicação. No exemplo acima, o diretório base para o contexto “/ws” fica no diretório “d:\workshop”.
• É importante notar que a configuração acima cria um mapeamento da URL chamada pelo usuário até o diretório base no seu servidor, onde a aplicação armazena os códigos.
• Use o caractere ‘/’ como no Unix como separador de diretório no arquivo de configuração, ao invés do caractere ‘\’ usado no Windows.
• O atributo reloadable="true" pede que o tomcat monitore os servlets por alterações, e automaticamente recarregue-os se alguma mudança for detectada. Isso é muito útil durante o desenvolvimento, mas ineficiente no ambiente de produção.

Na raiz do contexto de sua aplicação “d:\workshop“:

• Crie o sub-diretório “WEB-INF” (em maiusculas com um traço separando) dentro de “d:\workshop“.
• Crie um sub-diretório “classes” (em minúsculos) dentro de “d:\workshop\WEB-INF“. Esse diretório é onde você deve manter todas as classes dos servlets.

Passo 4: Configurar os arquivos “conf\web.xml” e “conf\context.xml” para “Invoker Servlet”

AVISO: O “Invoker Servlet” que estaremos usando aqui é ruim (veja o FAQ do Tomcat em http://wiki.apache.org/tomcat/FAQ/Miscellaneous para saber o por quê disso), e não deve ser usado em produção. mas esta é uma forma rápida de ensinar os conceitos básicos relacionados ao Tomcat.

“$CATALINA_HOME\conf\web.xml”: Ativar a listagem de diretório

<servlet>
  <servlet-name>default</servlet-name>
  <servlet-class>
    org.apache.catalina.servlets.DefaultServlet
  </servlet-class>
  <init-param>
    <param-name>debug</param-name>
    <param-value>0</param-value>
  </init-param>
  <init-param>
    <param-name>listings</param-name>
    <param-value>true</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
</servlet>

 
← The default servlet name
← The default servlet class
← Directory Listing
← Change from "false" to "true" to enable directory listing

Nota: Se a listagem estiver ativa, o Tomcat irá exibir a listagem do diretório quando o usuário acessar a URL de um diretório. Em caso contrário, seroa retornado um erro “404 Página não encontrado”. Novamente, ativar a listagem de diretório é útil para desenvolvimento, mas um risco de segurança em produção.

“$CATALINA_HOME\conf\web.xml”: Ativar o “Invoker Servlet” e especificar o mapeamento de URL

<!--
  <servlet>
  <servlet-name>invoker</servlet-name>
  <servlet-class>org.apache.catalina.servlets.InvokerServlet
  </servlet-class>
  <init-param>
  <param-name>debug</param-name>
  <param-value>0</param-value>
  </init-param>
  <load-on-startup>2</load-on-startup>
  </servlet>
-->
......
<!-- The mapping for the invoker servlet -->
<!--
  <servlet-mapping>
  <servlet-name>invoker</servlet-name>
  <url-pattern>/servlet/*</url-pattern>
  </servlet-mapping>
-->

← Remove this line (comment begin)
← Remove this line (comment end)
← Remove this line (comment begin)
← Remove this line (comment end)

“$CATALINA_HOME\conf\context.xml”: Ativar os privilégios do “Invoker Servlet”

Precisamos garantir privilégios ao “Invoker Servlet” alterando a tag de abertura <Context> em “conf\context.xml“:

<Context privileged="true" reloadable="true">
  ......
  ......
</Context>

Nota: Nessa configuração, damos privilégios a todas as aplicações do lado do servidor, o que é realmente uma coisa ruim.

Mais o que é o “Invoker Servlet”?

Em resumo, é uma forma de carregar servlets em massa. A maneira adequada é carregar servlets é configura-los um por um no arquivo de configuração da aplicação. Isso é realmente tedioso.

Suponhamos que temos um contexto “ws” com o documentos base em “d:\workshop“, e criamos um servlet chamado “TestServlet.class“. Com o “Invoker Servlet” ativo, poderíamos simplesmente salvar nosso servlet em “WEB-INF\classes” (isto é, no diretório “d:\workshop\WEB-INF\classes\TestServlet.class"). Os usuários podem requisitar esse servlet pela URL http://hostname:8080/ws/servlet/TestServlet. Em outras palavras, o caminho da URL é mapeado para “WEB-INF\classes“.

Passo 5: Iniciar o servidor Tomcat

Você pode iniciar o servidor do Tomcat executando “$CATALINA_HOME\bin\startup.bat“. Uma nova janela de terminal será iniciada. Estude as  mensagens (especialmente o número de porta do Tomcat). Mensagens de erro futuras serão enviadas para esa janela. O comando System.out.println() disparado por seus servlets também envia sua saída pra essa janela.

... change directory to $CATALINA_HOME\bin ...
> startup
......
......
Oct 20, 2009 10:56:37 PM org.apache.coyote.http11.Http11Protocol init
INFO: Initializing Coyote HTTP/1.1 on http-8080
......
Oct 20, 2009 10:56:46 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 9215 ms

Inicie um navegador e acesse a URL “http://localhost:8080” para abrir a página inicial do Tomcat, e a URL “http://localhost:8080/ws” para acessar a aplicação web criada. O localhost (com endereço IP 127.0.0.1) é designado apra teste apenas. Para usuários de outras máquinas da Internet, será usada o endereço IP apropriado ou hostname DNS para acessar o servidor.

Você pode desligar o servidor executando “$CATALINA_HOME\bin\shutdown.bat“. Se o Tomcat não responder ao comando shutdown, você terá que encerra-lo pelo pressionamento das teclas Ctrl_Break (ou Ctrl-C) na janela do terminal no Tomcat. Mas não encerre ele pressionando o botão “fechar”.

Passo 6: Arquivo JAR do servlet Java

A API de Servlet é necessária para compilar os servlets do Java. Essa API não é parte do JDL (mas pertence a especificação Java EE). O Tomcat inclui uma cópia dessa API. Por questões de simplicidade. poderíamos copiar o arquivo “$CATALINA_HOME\lib\servlet-api.jar” para o diretório “$JAVA_HOME\jre\lib\ext” (onde $JAVA_HOME é o diretório onde o JDK está instalado).

Alternativamente, podeira também incluir o arquivo jar citado na CLASSPATH.

Passo 7: Escrever e carregar um Servlet Java de teste

Escreva o servlet abaixo chamado “EchoServlet.java” e salve-o dentro do diretório “WEB-INF\classes” (i.e., “d:\workshop\WEB-INF\classes\EchoServlet.java“). Compile o código para “EchoServlet.class“.

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
public class EchoServlet extends HttpServlet {
   public void doGet(HttpServletRequest request,
         HttpServletResponse response)
         throws IOException, ServletException {
      response.setContentType("text/html");
      PrintWriter out = response.getWriter();
      out.println("<html>");
      out.println("<head><title>Servlet Test</title></head>");
      out.println("<body>");
      out.println("<p>Hello,</p>");
      out.println("<p>Request URI: " + request.getRequestURI() + "</p>");
      out.println("<p>Protocol: " + request.getProtocol() + "</p>");
      out.println("<p>PathInfo: " + request.getPathInfo() + "</p>");
      out.println("<p>Remote Address: " + request.getRemoteAddr() + "</p>");
      out.println("</body>");
      out.println("</html>");
   }
}

Para invocar esse servlet, acesse a URL http://localhost:8080/ws/servlet/EchoServlet.

Se alguma coisa ser errado…

• Cheque as mensagens de erro no terminal do Tomcat (e use as mensagens de erro para pesquisar a solução no google).
• Cheque os arquivos de log (em "$CATALINA_HOME\logs“).
• Se o terminal do Tomcat piscar e desaparecer imediatamente, você pode iniciar o tomcat em modo de depuração executando “catalina.bat debug” e digitando “run” no prompt do “jdb“. Observe as mensagens de erro.
• Cheque os seus arquivos de configuração do Tomcat (“server.xml“, “web.xml“, “content.xml“, etc.). Uma sugestão é voltar com os arquivos originais para iniciar o Tomcat. Vocẽ pode também modificar os scripts de inicialização do Tomcat “startup.bat” e “catalina.bat” para exibir as mensagens de erro, removendo o comando “echo off” desses arquivos.

Carregando a aplicação no Tomcat

Essa é maneira apropriada de carregar aplicações web (sem usar o Invoker Servlet):

Criar um novo contexto (aplicação web):

• (RECOMENDADO) Crie um diretório dentro de $CATALINA_HOME\webapps e mova os códigos de sua aplicação para esse diretório. Um contexto será criado automaticamente baseado no nome do diretório.
• Escreva um elemento  <Context> no arquivo $CATALINA_HOME\conf\server.xml, para especificar a URL do contexto e o diretório base.

Criar a estrutura de diretório para o novo contexto:

• O diretório que a sua aplicação está armazenada é chamado de raiz do contexto ou diretório base. Você deve manter dentro dela todos os arquivos HTML e recursos visíveis na Internet dentro desse diretório.
• Crie um diretório “WEB-INF”  dentro da raiz do contexto. Esse diretório, apesar de estar dentro da raiz do contexto, não é visível para os usuários. Aqui é onde você manterá os arquivos de configuração da aplicação como o web.xml.
• Crie um diretório chamado “classes” dentro de “WEB-INF“. Nesse diretório você manterá todas as classes Java como os servlets.
• Crie um diretório chamado “lib” dentro de “WEB-INF“.  Nesse diretório você manterá os arquivos jar e bibliotecas nativas.
• Opcionalmente, crie um diretório chamado “src” dentro de “WEB-INF“, para manter o código fonte.

Escreva o arquivo de configuração de sua aplicação e salve-o com o nome “web.xml” dentro do diretório “WEB-INF” de sua aplicação.

A especificação completa do arquivo “web.xml”  pode ser encontrada no “Java Servlet Specification” (@ http://java.sun.com/products/servlet), em “Deployment Descriptor”.

Vamos supor que queremos carregar dois servlets:

TestServlet.class e QueryServlet.class (que são mantidos dentro do diretório “WEB-INF\classes” da sua aplicação):

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
  <servlet>
    <servlet-name>Test</servlet-name>
    <servlet-class>TestServlet</servlet-class>
  </servlet>
  <servlet>
    <servlet-name>Query</servlet-name>
    <servlet-class>QueryServlet</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>Test</servlet-name>
    <url-pattern>/Echo</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>Query</servlet-name>
    <url-pattern>/Query</url-pattern>
  </servlet-mapping>
  <session-config>
    <session-timeout>30</session-timeout>    <!-- 30 minutes -->
  </session-config>
</web-app>

Explicação:

• Cada servlet requer dois elementos de configuração diferentes. Um elemento <servlet> para especificar o servlet-name e o servlet-class, e um <servlet-mapping> para especificar a URL de um servlet-name em particular. No exemplo acima, TestServlet pode ser acessado pela URL http://host:port/context-path/Echo, e QueryServlet pela URL http://host:port/context-path/Query.
• Você tem que listar TODOS os elementos <servlet> primeiro, seguido pelos elementos <servlet-mapping>.

Alterando o diretório “webapps” padrão

O diretório padrão para carregamento de aplicações web é o $CATALINA_HOME\webapps. Você pode alterar esse padrão pela modificação da tag <host> no arquivo de configuração "conf\server.xml":

<Host name="localhost"  appBase="webapps"       unpackWARs="true" autoDeploy="true"
      xmlValidation="false" xmlNamespaceAware="false">
   ......
</host>

Listagem do diretório

Ativar a listagem de diretório é útil para testar o servidor mas não desejável para servidores de produção. Para ativar a listagem de diretório para todas as aplicações web, modifique o arquivo $CATALINA_HOME\conf\web.xml, alterando a propriedade “listings” para “true“, como segue:

<!-- The default servlet for all web applications, that serves static     -->
<!-- resources.  It processes all requests that are not mapped to other   -->
<!-- servlets with servlet mappings.                                      -->
<servlet>
  <servlet-name>default</servlet-name>
  <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
  <init-param>
    <param-name>debug</param-name>
    <param-value>0</param-value>
  </init-param>
  <init-param>
    <param-name>listings</param-name>
    <param-value>true</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
</servlet>
<!-- The mapping for the default servlet -->
<servlet-mapping>
  <servlet-name>default</servlet-name>
  <url-pattern>/</url-pattern>
</servlet-mapping>

Explicação: Quando um usuário faz referencia a URL “/” (i.e., http://host:port/context-path/), o servlet DefaultServlet será invocado para exibir a listagem do diretório.

Se você deseja permitir a listagem de diretório apenas para uma aplicação web em particular, deve desativar a listagem globalmente no “$CATALINA_HOME\conf\web.xml“, e definir os seguintes <servlet> e <servlet-mapping> no arquivo “WEB-INF\web.xml” de sua aplicação. Você precisa usar outro servlet-name para o DefaultServlet.

<servlet>
  <servlet-name>DirectoryListing</servlet-name>
  <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
  <init-param>
    <param-name>debug</param-name>
    <param-value>0</param-value>
  </init-param>
  <init-param>
    <param-name>listings</param-name>
    <param-value>true</param-value>
  </init-param>
</servlet>
<servlet-mapping>
  <servlet-name>DirectoryListing</servlet-name>
  <url-pattern>/</url-pattern>
</servlet-mapping>

Carregando uma aplicação web em arquivo WAR

Você pode usar o utilitário jar do JDK para compactar todos os arquivos de uma aplicação web e produzir um arquivo WAR para distribuição.

.... Mude o dietório atual para a raiz do contexto de sua aplicação web
> jar cvf test.war .

Copie o arquivo test.war no diretório $CATALINA_HOME\webapps. Um contexto chamado test será criado automaticamente. Você pode acessar a aplicação web pela URL http://host:port/test.
(O Tomcat  normalmente descompacta o arquivo test.war em um diretório test em $CATALINA_HOME\webapps.)

Recarregamento automático de Servlet

Para ativar o recarregamento automático do servlet, precisa especificar <Context reloadable="true">...</Context> (tanto no “$CATALINA_HOME\conf\context.xml” ou no “$CATALINA_HOME\conf\server.xml“).

A mensagem seguinte aparece no terminal do Tomcat se você re-compilar o seu servlet:

XXX X, XXXX XX:XX:XX XX org.apache.catalina.core.StandardContext reload
INFO: Reloading this Context has started

Script de inicialização do Tomcat

Para iniciar o servidor Tomcat, você deve invocar o arquivo de lote “startup.bat” (no diretório “$CATALINA_HOME\bin“, onde o CATALINA_HOME se refere ao diretório de instalação do Tomcat). O arquivo “startup.bat” invocará o “catalina.bat start“.

Alternativamente, você pode chamar o arquivo “catalina.bat” diretamente, o que lhe dá mais opções de inicialização do Tomcat. Execute apenas “catalina” para ver as opções:

> catalina
Using CATALINA_BASE:   D:\bin\tomcat6.0.16
Using CATALINA_HOME:   D:\bin\tomcat6.0.16
Using CATALINA_TMPDIR: D:\bin\tomcat6.0.16\temp
Using JRE_HOME:        d:\bin\jdk1.6
Usage:  catalina ( commands ... )
commands:
  debug             Start Catalina in a debugger
  debug -security   Debug Catalina with a security manager
  jpda start        Start Catalina under JPDA debugger
  run               Start Catalina in the current window
  run -security     Start in the current window with security manager
  start Start Catalina in a separate window
  start -security   Start in a separate window with security manager
  stop              Stop Catalina
  version           What version of tomcat are you running?

Executando o Tomcat como um serviço do Windows

Se estiver em um ambiente de produção, é mais conveniente executar o Tomcat como um “serviço”, de forma que pode ser iniciado automaticamente toda vez que o sistema foi iniciado (ou re-iniciado automaticamente depois de uma interrupção inesperada).

Para instalar o Tomcat como um serviço, inicie o terminal (com privilégios de administrador) e execute:

... Mude o diretório para o $CATALINA_HOME\bin ...
$CATALINA_HOME\bin> service install
Installing the service 'Tomcat6' ...
Using CATALINA_HOME:    d:\tomcat-6.0.20
Using CATALINA_BASE:    d:\tomcat-6.0.20
Using JAVA_HOME:        d:\jdk1.6
Using JVM:              d:\jdk1.6\jre\bin\server\jvm.dll
The service 'Tomcat6' has been installed.

O serviço Tomcat  chamado “Apache Tomcat 6” é instalado e será iniciado automaticamente sempre que o sistema for iniciado. Cheque em “Serviços” em “Painel de Controle” -> “Ferramentas Administrativas”.
Uma aplicação gráfica chamada Tomcat6w está disponível para monitorar e configurar serviços Tomcat. Leia o documento “Windows service HOW-TO” localizado em $CATALINA_HOME\webapps\docs\windows-service-howto.html. Tente executar a aplicação Tomcat6w.

$CATALINA_HOME\bin> tomcat6w

Você pode colocar um icone para o Tomcat na bandeja do sistema pela opção MS (Monitor Service):

$CATALINA_HOME\bin> tomcat6w //MS//

Vocẽ pode iniciar/parar o Tomcat via (a) Tomcat6w; (b) “Painel de Controle” -> “Ferramentas Administrativas” -> “Serviços” -> “Apache Tomcat 6” -> “Iniciar”; ou (c) executando o comando abaixo pelo terminal:

> net start tomcat6
The Apache Tomcat 6 service is starting..
The Apache Tomcat 6 service was started successfully.
......
......
> net stop tomcat6
The Apache Tomcat 6 service is stopping..
The Apache Tomcat 6 service was stopped successfully.

Para desinstalar o Serviço Tomcat, use o Tomcat6w ou execute o comando abaixo:

$CATALINA_HOME\bin> service remove
The service 'Tomcat6' has been removed

REFEÊNCIA

• http://www.ntu.edu.sg/home/ehchua/programming/howto/Tomcat_HowTo.html