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 oweb.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 oservlet-name
e oservlet-class
, e um<servlet-mapping>
para especificar a URL de umservlet-name
em particular. No exemplo acima,TestServlet
pode ser acessado pela URLhttp://host:port/context-path/Echo
, eQueryServlet
pela URLhttp://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