Collapse All | Expand All

 Lines 41-47 Lines 59-67 Lines 96-102 Lines 173-179 (-)modules/jdbc-pool/doc/jdbc-pool.xml (-91 / +75 lines) 41 41 42 

So why do we need a new connection pool?

42 

So why do we need a new connection pool?

43 43 44 

Here are a few of the reasons: 44 

Here are a few of the reasons:

45 
45 
46 
1. commons-dbcp is single threaded, in order to be thread safe commons-dbcp locks the entire pool, even during query validation.
2.  46 
3. commons-dbcp is single threaded, in order to be thread safe commons-dbcp locks the entire pool, even during query validation.
4.  47 
5. commons-dbcp is slow - as the number of logical CPUs grow, the performance suffers, the above point shows that there is not support for high concurrency 47 
6. commons-dbcp is slow - as the number of logical CPUs grow, the performance suffers, the above point shows that there is not support for high concurrency 59 
7. Starvation proof. If a pool is empty, and threads are waiting for a connection, when a connection is returned, 59 
8. Starvation proof. If a pool is empty, and threads are waiting for a connection, when a connection is returned, 60  the pool will awake the correct thread waiting. Most pools will simply starve.
9.  60  the pool will awake the correct thread waiting. Most pools will simply starve. 61 
61 
62 

63 62 64 

Features added over other connection pool implementations 63 

Features added over other connection pool implementations

65 
64 
66 
1. Support for highly concurrent environments and multi core/cpu systems.
2.  65 
3. Support for highly concurrent environments and multi core/cpu systems.
4.  67 
5. Dynamic implementation of interface, will support java.sql and javax.sql interfaces for 66 
6. Dynamic implementation of interface, will support java.sql and javax.sql interfaces for 96  This is achieved using the dataSource and dataSourceJNDI attributes.
7.  95  This is achieved using the dataSource and dataSourceJNDI attributes. 97 
8. XA connection support
9.  96 
10. XA connection support
11.  98 
97 
99 

100 98 101 99 102  100  173   171   174 172 175   173   176 

(String) The default TransactionIsolation state of connections created by this pool. One of the following: (see javadoc ) 174 

(String) The default TransactionIsolation state of connections created by this pool. One of the following: (see javadoc )

177 
175 
178 
• NONE
•  176 
• NONE
•  179 
•  177 
•  181 
•  179 
•  182 
• SERIALIZABLE
•  180 
• SERIALIZABLE
•  183 
181 
184  If not set, the method will not be called and it defaults to the JDBC driver. 182 

If not set, the method will not be called and it defaults to the JDBC driver.

185 

186 
183 
187 184 188   185   673 

Other examples of Tomcat configuration for JDBC usage can be found in the Tomcat documentation.

670 

Other examples of Tomcat configuration for JDBC usage can be found in the Tomcat documentation.

674   671   675 

Here is a simple example of how to create and use a data source.

672 

Here is a simple example of how to create and use a data source.

676  673  731  732 
727 
733   728   734 

And here is an example on how to configure a resource for JNDI lookups

729 

And here is an example on how to configure a resource for JNDI lookups

735  730 ]]> 760  url="jdbc:mysql://localhost:3306/mysql"/> 761  762 755 763 
756 
764   757   765 

The Tomcat JDBC connection pool supports asynchronous connection retrieval without adding additional threads to the 758 

The Tomcat JDBC connection pool supports asynchronous connection retrieval without adding additional threads to the 766  pool library. It does this by adding a method to the data source called Future<Connection> getConnectionAsync(). 759  pool library. It does this by adding a method to the data source called Future<Connection> getConnectionAsync(). 767  In order to use the async retrieval, two conditions must be met: 760  In order to use the async retrieval, two conditions must be met: 761 

768 
762 
769 
1. You must configure the fairQueue property to be true.
2.  763 
3. You must configure the fairQueue property to be true.
4.  770 
5. You will have to cast the data source to org.apache.tomcat.jdbc.pool.DataSource
6.  764 
7. You will have to cast the data source to org.apache.tomcat.jdbc.pool.DataSource
8.  771 
765 
772  An example of using the async feature is show below. 766  An example of using the async feature is show below. 773  767  future = datasource.getConnectionAsync(); 777  while (!future.isDone()) { 770  while (!future.isDone()) { 778  System.out.println("Connection is not yet available. Do some background work"); 771  System.out.println("Connection is not yet available. Do some background work"); 779  try { 772  try { 784  } 777  } 785  con = future.get(); //should return instantly 778  con = future.get(); //should return instantly 786  Statement st = con.createStatement(); 779  Statement st = con.createStatement(); 787  ResultSet rs = st.executeQuery("select * from user"); 780  ResultSet rs = st.executeQuery("select * from user");]]> 788  781 789 

790 
782 
791   783   792 

Interceptors are a powerful way to enable, disable or modify functionality on a specific connection or its sub components. 784 

Interceptors are a powerful way to enable, disable or modify functionality on a specific connection or its sub components. 796  the pool itself will not reset them.

788  the pool itself will not reset them.

797 

An interceptor has to extend the org.apache.tomcat.jdbc.pool.JdbcInterceptor class. This class is fairly simple, 789 

An interceptor has to extend the org.apache.tomcat.jdbc.pool.JdbcInterceptor class. This class is fairly simple, 798  You will need to have a no arg constructor

790  You will need to have a no arg constructor

799  791  801  } 802  803 

793 

804  When a connection is borrowed from the pool, the interceptor can initialize or in some other way react to the event by implementing the 794  When a connection is borrowed from the pool, the interceptor can initialize or in some other way react to the event by implementing the 805  795 

806  public abstract void reset(ConnectionPool parent, PooledConnection con); 796  807  797 

808  method. This method gets called with two parameters, a reference to the connection pool itself ConnectionPool parent 798  method. This method gets called with two parameters, a reference to the connection pool itself ConnectionPool parent 809  and a reference to the underlying connection PooledConnection con. 799  and a reference to the underlying connection PooledConnection con. 810 

800 

811 

801 

812  When a method on the java.sql.Connection object is invoked, it will cause the 802  When a method on the java.sql.Connection object is invoked, it will cause the 813  803 

814  public Object invoke(Object proxy, Method method, Object[] args) throws Throwable 804  815  805 

816  method to get invoked. The Method method is the actual method invoked, and Object[] args are the arguments. 806  method to get invoked. The Method method is the actual method invoked, and Object[] args are the arguments. 817  To look at a very simple example, where we demonstrate how to make the invokation to java.sql.Connection.close() a noop 807  To look at a very simple example, where we demonstrate how to make the invokation to java.sql.Connection.close() a noop 818  if the connection has been closed 808  if the connection has been closed 819  809 

820  if (CLOSE_VAL==method.getName()) { 810  824  814 

825  There is an observation being made. It is the comparison of the method name. One way to do this would be to do 815  There is an observation being made. It is the comparison of the method name. One way to do this would be to do 826  "close".equals(method.getName()). 816  "close".equals(method.getName()). 827  Above we see a direct reference comparison between the method name and static final String reference. 817  Above we see a direct reference comparison between the method name and static final String reference. 828  According to the JVM spec, method names and static final String end up in a shared constant pool, so the reference comparison should work. 818  According to the JVM spec, method names and static final String end up in a shared constant pool, so the reference comparison should work. 829  One could of course do this as well: 819  One could of course do this as well: 830  820 

831  if (compare(CLOSE_VAL,method)) { 821  835  825 

836  The compare(String,Method) will use the useEquals flag on an interceptor and do either reference comparison or 826  The compare(String,Method) will use the useEquals flag on an interceptor and do either reference comparison or 837  a string value comparison when the useEquals=true flag is set. 827  a string value comparison when the useEquals=true flag is set. 838 

828 

839 

Pool start/stop
829 

Pool start/stop
840  When the connection pool is started or closed, you can be notifed. You will only be notified once per interceptor class 830  When the connection pool is started or closed, you can be notifed. You will only be notified once per interceptor class 841  even though it is an instance method. and you will be notified using an interceptor currently not attached to a pool. 831  even though it is an instance method. and you will be notified using an interceptor currently not attached to a pool. 842  832 

843  public void poolStarted(ConnectionPool pool) { 833  848  838 

849  When overriding these methods, don't forget to call super if you are extending a class other than JdbcInterceptor 839  When overriding these methods, don't forget to call super if you are extending a class other than JdbcInterceptor 850 

840 

851 

Configuring interceptors
841 

Configuring interceptors
852  Interceptors are configured using the jdbcInterceptors property or the setJdbcInterceptors method. 842  Interceptors are configured using the jdbcInterceptors property or the setJdbcInterceptors method. 853  An interceptor can have properties, and would be configured like this 843  An interceptor can have properties, and would be configured like this 854  855  String jdbcInterceptors= 856  "org.apache.tomcat.jdbc.pool.interceptor.ConnectionState(useEquals=true,fast=yes)" 857  858 

844 

845  847 859 

Interceptor properties
848 

Interceptor properties
860  Since interceptors can have properties, you need to be able to read the values of these properties within your 849  Since interceptors can have properties, you need to be able to read the values of these properties within your 861  interceptor. Taking an example like the one above, you can override the setProperties method. 850  interceptor. Taking an example like the one above, you can override the setProperties method. 862  851 

863  public void setProperties(Map<String, InterceptorProperty> properties) { 852  properties) { 864  super.setProperties(properties); 853  super.setProperties(properties); 865  final String myprop = "myprop"; 854  final String myprop = "myprop"; 866  InterceptorProperty p1 = properties.get(myprop); 855  InterceptorProperty p1 = properties.get(myprop); 867  if (p1!=null) { 856  if (p1!=null) { 868  setMyprop(Long.parseLong(p1.getValue())); 857  setMyprop(Long.parseLong(p1.getValue())); 869  } 858  } 870  } 859  }]]> 871  860 872 

873 
861 
874   862   875 

Connection pools create wrappers around the actual connection in order to properly pool them. 863 

Connection pools create wrappers around the actual connection in order to properly pool them. 876  We also create interceptors in these wrappers to be able to perform certain functions. 864  We also create interceptors in these wrappers to be able to perform certain functions. 877  If there is a need to retrieve the actual connection, one can do so using the javax.sql.PooledConnection 865  If there is a need to retrieve the actual connection, one can do so using the javax.sql.PooledConnection 878  interface. 866  interface. 879  880  Connection con = datasource.getConnection(); 881  Connection actual = ((javax.sql.PooledConnection)con).getConnection(); 882  883 

867 

868  870 884 
871 
885 872 886  873  890 

Other examples of Tomcat configuration for JDBC usage can be found in the Tomcat documentation.

877 

Other examples of Tomcat configuration for JDBC usage can be found in the Tomcat documentation.

891   878   892 

Building is pretty simple. The pool has a dependency on tomcat-juli.jar and in case you want the SlowQueryReportJmx

879 

Building is pretty simple. The pool has a dependency on tomcat-juli.jar and in case you want the SlowQueryReportJmx

893  880  899  900 

885 

901  A build file can be found in the Tomcat source repository. 886  A build file can be found in the Tomcat source repository. 902 

887 

903 

888 

904  As a convenience, a build file is also included where a simple build command will generate all files needed. 889  As a convenience, a build file is also included where a simple build command will generate all files needed. 905  890 

906  ant download (downloads dependencies) 891  ant download (downloads dependencies) 907  ant build (compiles and generates .jar files) 892  ant build (compiles and generates .jar files) 908  ant dist (creates a release package) 893  ant dist (creates a release package) 909  ant test (runs tests, expects a test database to be setup) 894  ant test (runs tests, expects a test database to be setup) 910  895 911 

912 

896 

913  The system is structured for a Maven build, but does generate release artifacts. Just the library itself. 897  The system is structured for a Maven build, but does generate release artifacts. Just the library itself. 914 

898 

 Lines 161-172 Lines 197-204 Lines 215-221 Lines 222-231 (-)webapps/docs/aio.xml (-19 / +19 lines) 161  described above: 161  described above: 162 

162 

163 163 164   164  connections = 167  protected ArrayList connections = 169  new ArrayList<HttpServletResponse>(); 168  new ArrayList(); 170  protected MessageSender messageSender = null; 169  protected MessageSender messageSender = null; 171 170 172  public void init() throws ServletException { 171  public void init() throws ServletException { 197  if (event.getEventType() == CometEvent.EventType.BEGIN) { 196  if (event.getEventType() == CometEvent.EventType.BEGIN) { 198  log("Begin for session: " + request.getSession(true).getId()); 197  log("Begin for session: " + request.getSession(true).getId()); 199  PrintWriter writer = response.getWriter(); 198  PrintWriter writer = response.getWriter(); 200  writer.println("<!doctype html public \"-//w3c//dtd html 4.0 transitional//en\">"); 199  writer.println(""); 201  writer.println("<head><title>JSP Chat</title></head><body bgcolor=\"#FFFFFF\">"); 200  writer.println("JSP Chat"); 202  writer.flush(); 201  writer.flush(); 203  synchronized(connections) { 202  synchronized(connections) { 204  connections.add(response); 203  connections.add(response); 215  connections.remove(response); 214  connections.remove(response); 216  } 215  } 217  PrintWriter writer = response.getWriter(); 216  PrintWriter writer = response.getWriter(); 218  writer.println("</body></html>"); 217  writer.println(""); 219  event.close(); 218  event.close(); 220  } else if (event.getEventType() == CometEvent.EventType.READ) { 219  } else if (event.getEventType() == CometEvent.EventType.READ) { 221  InputStream is = request.getInputStream(); 220  InputStream is = request.getInputStream(); 222  byte[] buf = new byte[512]; 221  byte[] buf = new byte[512]; 223  do { 222  do { 224  int n = is.read(buf); //can throw an IOException 223  int n = is.read(buf); //can throw an IOException 225  if (n > 0) { 224  if (n > 0) { 226  log("Read " + n + " bytes: " + new String(buf, 0, n) 225  log("Read " + n + " bytes: " + new String(buf, 0, n) 227  + " for session: " + request.getSession(true).getId()); 226  + " for session: " + request.getSession(true).getId()); 228  } else if (n < 0) { 227  } else if (n < 0) { 229  error(event, request, response); 228  error(event, request, response); 230  return; 229  return; 231  } 230  } 236  public class MessageSender implements Runnable { 235  public class MessageSender implements Runnable { 237 236 238  protected boolean running = true; 237  protected boolean running = true; 239  protected ArrayList<String> messages = new ArrayList<String>(); 238  protected ArrayList messages = new ArrayList(); 240 239 241  public MessageSender() { 240  public MessageSender() { 242  } 241  } 276  messages.clear(); 275  messages.clear(); 277  } 276  } 278  // Send any pending message on all the open connections 277  // Send any pending message on all the open connections 279  for (int i = 0; i < connections.size(); i++) { 278  for (int i = 0; i < connections.size(); i++) { 280  try { 279  try { 281  PrintWriter writer = connections.get(i).getWriter(); 280  PrintWriter writer = connections.get(i).getWriter(); 282  for (int j = 0; j < pendingMessages.length; j++) { 281  for (int j = 0; j < pendingMessages.length; j++) { 283  writer.println(pendingMessages[j] + "<br>"); 282  writer.println(pendingMessages[j] + "
"); 284  } 283  } 285  writer.flush(); 284  writer.flush(); 286  } catch (IOException e) { 285  } catch (IOException e) { 295 294 296  } 295  } 297 296 298 } 297 }]]> 299   300 298 301   299   302   300   303 

If you are using the NIO connector, you can set individual timeouts for your different comet connections. 301 

If you are using the NIO connector, you can set individual timeouts for your different comet connections. 304  To set a timeout, simply set a request attribute like the following code shows: 302  To set a timeout, simply set a request attribute like the following code shows:

305  CometEvent event.... event.setTimeout(30*1000); or 303  CometEvent event.... event.setTimeout(30*1000); 306  event.getHttpServletRequest().setAttribute("org.apache.tomcat.comet.timeout", new Integer(30 * 1000)); 304 

or

307  This sets the timeout to 30 seconds. 305  event.getHttpServletRequest().setAttribute("org.apache.tomcat.comet.timeout", new Integer(30 * 1000)); 306 

307  This sets the timeout to 30 seconds. 308  Important note: in order to set this timeout, it has to be done on the BEGIN event. 308  Important note: in order to set this timeout, it has to be done on the BEGIN event. 309  The default value is soTimeout 309  The default value is soTimeout 310 

310 

 Lines 57-68 Lines 87-99 Lines 100-107 Lines 119-136 (-)webapps/docs/apr.xml (-28 / +28 lines) 57 57 58 

58 

59  APR support requires three main native components to be installed: 59  APR support requires three main native components to be installed: 60 

61 
• APR library
•  62 
• JNI wrappers for APR used by Tomcat (libtcnative)
•  63 
• OpenSSL libraries
•  64 
65 

60 

61 
62 
• APR library
•  63 
• JNI wrappers for APR used by Tomcat (libtcnative)
•  64 
• OpenSSL libraries
•  65 
66 66 67   67   68 68 87 87 88 

88 

89  Requirements: 89  Requirements: 90 

91 
• APR 1.2+ development headers (libapr1-dev package)
•  92 
• OpenSSL 0.9.7+ development headers (libssl-dev package)
•  93 
• JNI headers from Java compatible JDK 1.4+
•  94 
• GNU development environment (gcc, make)
•  95 
96 

90 

91 
92 
• APR 1.2+ development headers (libapr1-dev package)
•  93 
• OpenSSL 0.9.7+ development headers (libssl-dev package)
•  94 
• JNI headers from Java compatible JDK 1.4+
•  95 
• GNU development environment (gcc, make)
•  96 
97 97 98 

98 

99  The wrapper library sources are located in the Tomcat binary bundle, in the 99  The wrapper library sources are located in the Tomcat binary bundle, in the 100  bin/tomcat-native.tar.gz archive. 100  bin/tomcat-native.tar.gz archive. 101  Once the build environment is installed and the source archive is extracted, the wrapper library 101  Once the build environment is installed and the source archive is extracted, the wrapper library 102  can be compiled using (from the folder containing the configure script): 102  can be compiled using (from the folder containing the configure script): 103  ./configure && make && make install 104 

103 

104  ./configure && make && make install 105 105 106 
106 
107 107 119 119 120 

120 

121  When APR is enabled, the following features are also enabled in Tomcat: 121  When APR is enabled, the following features are also enabled in Tomcat: 122 

123 
• Secure session ID generation by default on all platforms (platforms other than Linux required 124  random number generation using a configured entropy)
•  125 
• OS level statistics on memory usage and CPU usage by the Tomcat process are displayed by 126  the status servlet
•  127 
128 

122 

123 
124 
• Secure session ID generation by default on all platforms (platforms other than Linux required 125  random number generation using a configured entropy)
•  126 
• OS level statistics on memory usage and CPU usage by the Tomcat process are displayed by 127  the status servlet
•  128 
129 129 130   130   131 131 132 
132 
133   133   134   134   135   135 

136 

136  Name of the SSLEngine to use. off: Do not use SSL, on: Use SSL but no specific ENGINE. 137  Name of the SSLEngine to use. off: Do not use SSL, on: Use SSL but no specific ENGINE. 137  The default value is on. 138  The default value is on. 138  This initializes the native SSL engine, then enable the use of this engine in the connector 139  This initializes the native SSL engine, then enable the use of this engine in the connector 139  using the SSLEnabled attribute. Example: 140  using the SSLEnabled attribute. Example: 140   141 

141 <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" /> 142  ]]> 142   143   143 

144 

See the Official OpenSSL 144 

See the Official OpenSSL 145  website for more details on SSL hardware engines and manufacturers. 145  website for more details on SSL hardware engines and manufacturers. 146 

146 

147 
147 
148 
148 
149 
149 
150 
150 151 156  connector configuration documentation.

157  connector configuration documentation.

157 158 158 

For HTTPS configuration, see the 159 

For HTTPS configuration, see the 159  HTTPS connector configuration 160  HTTPS connector configuration 160  documentation.

161  documentation.

161 162 162 

An example SSL Connector declaration is: 163 

An example SSL Connector declaration is:

163   164   170  SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" />]]> 171   171   172 172 173   173   174 174  Lines 107-116 Lines 133-153 Lines 204-217 Lines 232-239 (-)webapps/docs/building.xml (-22 / +20 lines) 107 107 108   108   109 Use the following commands to build Tomcat: 109 Use the following commands to build Tomcat: 110   110   111   111  112  cd${tomcat.source}
112  cd ${tomcat.source}  113  ant  113  ant 114   114   115   115   116 116 133   133   134  The build can be controlled by creating a${tomcat.source}/build.properties 134  The build can be controlled by creating a ${tomcat.source}/build.properties 135  file and adding the following content to it: 135  file and adding the following content to it: 136   137   138  # ----- Proxy setup -----  139  # Uncomment if using a proxy server.  140  #proxy.host=proxy.domain  141  #proxy.port=8080  142  #proxy.use=on  143   144  # ----- Default Base Path for Dependent Packages -----  145  # Replace this path with the directory path where  146  # dependencies binaries should be downloaded.  147  base.path=/home/me/some-place-to-download-to  148   149   136   137 # ----- Proxy setup ----- 138 # Uncomment if using a proxy server. 139 #proxy.host=proxy.domain 140 #proxy.port=8080 141 #proxy.use=on 150 142 143 # ----- Default Base Path for Dependent Packages ----- 144 # Replace this path with the directory path where 145 # dependencies binaries should be downloaded. 146 base.path=/home/me/some-place-to-download-to 147 148 151   149   152 Once the build has completed successfully, a usable Tomcat installation will have been 150 Once the build has completed successfully, a usable Tomcat installation will have been 153 produced in the${tomcat.source}/output/build directory, and can be started 151 produced in the ${tomcat.source}/output/build directory, and can be started 204 Variables to add two new Classpath Variables: 202 Variables to add two new Classpath Variables: 205   203   206 204 207   205 208  206  209  TOMCAT_LIBS_BASEThe same location as the base.path 207  TOMCAT_LIBS_BASEThe same location as the base.path 210  setting in build.properties, where the binary dependencies have been downloaded ANT_HOMEthe base path of Ant 1.8.1 or later ANT_HOMEthe base path of Ant 1.8.1 or later  208  setting in build.properties, where the binary dependencies have been downloaded 211   209   212  210  213   214 211 212 215   213   216 Use File->Import and choose Existing Projects into Workspace. 214 Use File->Import and choose Existing Projects into Workspace. 217 From there choose the root directory of the Tomcat source tree (${tomcat.source}) 215 From there choose the root directory of the Tomcat source tree (${tomcat.source}) 232 Tweaking a few formatting preferences will make it much easier to keep consistent with Tomcat 230 Tweaking a few formatting preferences will make it much easier to keep consistent with Tomcat 233 coding conventions (and have your contributions accepted): 231 coding conventions (and have your contributions accepted): 234   232   235   233 236  234  237  Java -> Code Style -> Formatter -> Edit... Java -> Code Style -> Formatter -> Edit...Tab policy: Spaces only Tab and Indentation size: 4 Tab policy: Spaces only Tab and Indentation size: 4 General -> Editors -> Text Editors General -> Editors -> Text Editors XML -> XML Files -> EditorIndent using spaces Indentation size: 2 XML -> XML Files -> EditorIndent using spaces Indentation size: 2 Ant -> Editor -> FormatterTab size: 2 Use tab character instead of spaces: unchecked Ant -> Editor -> FormatterTab size: 2 Use tab character instead of spaces: unchecked  235   238   236   239   237   241   239   242   240   243  241  244   245 242 243 246  244  247 245 248   246    Lines 72-78 Lines 96-103 (-)webapps/docs/cgi-howto.xml (-2 / +2 lines) 72   72   73 73 74  There are several servlet init parameters which can be used to 74  There are several servlet init parameters which can be used to 75 configure the behaviour of the CGI servlet. 75 configure the behaviour of the CGI servlet.  76   76   77  • cgiPathPrefix - The CGI search path will start at 77  • cgiPathPrefix - The CGI search path will start at 78 the web application root directory + File.separator + this prefix. 78 the web application root directory + File.separator + this prefix. 96 the reading of stderr to complete before terminating the CGI process. Default 96 the reading of stderr to complete before terminating the CGI process. Default 97 is 2000. •  97 is 2000. 98   98   99   100 99 100 101   101   102 102 103  103   Lines 56-70 (-)webapps/docs/class-loader-howto.xml (-4 / +2 lines) 56 organized into the following parent-child relationships, where the parent 56 organized into the following parent-child relationships, where the parent 57 class loader is above the child class loader:  57 class loader is above the child class loader:  58 58 59  59  Bootstrap 60  Bootstrap 61  | 60  | 62  System 61  System 63  | 62  | 64  Common 63  Common 65  / \ 64  / \ 66  Webapp1 Webapp2 ... 65  Webapp1 Webapp2 ... 67  68 66 69  The characteristics of each of these class loaders, including the source 67  The characteristics of each of these class loaders, including the source 70 of classes and resources that they make visible, are discussed in detail in 68 of classes and resources that they make visible, are discussed in detail in  Lines 41-47 Lines 51-107 Lines 128-134 Lines 152-166 (-)webapps/docs/cluster-howto.xml (-177 / +154 lines) 41 41 42   42   43   43   44  Simply add <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/> 44  Simply add 45   46  <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/> 47   45  to your <Engine> or your <Host> element to enable clustering. 48  to your <Engine> or your <Host> element to enable clustering. 46   49   47   50   51  Also when using the delta manager it will replicate to all nodes, even nodes that don't have the application deployed.  54  Also when using the delta manager it will replicate to all nodes, even nodes that don't have the application deployed.  52  To get around this problem, you'll want to use the BackupManager. This manager only replicates the session data to one backup 55  To get around this problem, you'll want to use the BackupManager. This manager only replicates the session data to one backup 53  node, and only to nodes that have the application deployed. Downside of the BackupManager: not quite as battle tested as the delta manager. 56  node, and only to nodes that have the application deployed. Downside of the BackupManager: not quite as battle tested as the delta manager. 54   57   55  Here are some of the important default values:  58   56  1. Multicast address is 228.0.0.4  59  Here are some of the important default values: 57  2. Multicast port is 45564 (the port and the address together determine cluster membership.  60   58  3. The IP broadcasted is java.net.InetAddress.getLocalHost().getHostAddress() (make sure you don't broadcast 127.0.0.1, this is a common error)  61   59  4. The TCP port listening for replication messages is the first available server socket in range 4000-4100  62  1. Multicast address is 228.0.0.4 2.  60  5. Two listeners are configured ClusterSessionListener  63  3. Multicast port is 45564 (the port and the address together determine cluster membership. 4.  61  6. Two interceptors are configured TcpFailureDetector and MessageDispatch15Interceptor  64  5. The IP broadcasted is java.net.InetAddress.getLocalHost().getHostAddress() (make sure you don't broadcast 127.0.0.1, this is a common error) 6.  62  The following is the default cluster configuration:  65  7. The TCP port listening for replication messages is the first available server socket in range 4000-4100 8.  63   66  9. Two listeners are configured ClusterSessionListener 10.  64  <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster" 67  11. Two interceptors are configured TcpFailureDetector and MessageDispatch15Interceptor 12.  65  channelSendOptions="8"> 68   69   70  The following is the default cluster configuration: 71   72   66 74 67  <Manager className="org.apache.catalina.ha.session.DeltaManager" 75   70 78 71  <Channel className="org.apache.catalina.tribes.group.GroupChannel"> 79   72  <Membership className="org.apache.catalina.tribes.membership.McastService" 80   77  <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver" 85   83 91 84  <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"> 92   85  <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/> 93   86  </Sender> 94   87  <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/> 95   88  <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/> 96   89  </Channel> 97   90 98 91  <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" 99   93  <Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve"/> 101   94 102 95  <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer" 103   100 108 101  <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/> 109   102  </Cluster> 110  ]]> 103   104   105  Will cover this section in more detail later in this document.  111  Will cover this section in more detail later in this document.  106   112   107 113 128  side otherwise, a new session will be created.  134  side otherwise, a new session will be created.  129  Note: Clustering support currently requires the JDK version 1.5 or later.  135  Note: Clustering support currently requires the JDK version 1.5 or later.  130  The Cluster module uses the Tomcat JULI logging framework, so you can configure logging 136  The Cluster module uses the Tomcat JULI logging framework, so you can configure logging 131  through the regular logging.properties file. To track messages, you can enable logging on the key:org.apache.catalina.tribes.MESSAGES  137  through the regular logging.properties file. To track messages, you can enable logging on the key: org.apache.catalina.tribes.MESSAGES  132  138  133 139 134 140 152  A very simple setup would look like this: 158  A very simple setup would look like this: 153   159   154 160 155  161  DNS Round Robin 156  DNS Round Robin 157  | 162  | 158  Load Balancer 163  Load Balancer 159  / \ 164  / \ 160  Cluster1 Cluster2 165  Cluster1 Cluster2 161  / \ / \ 166  / \ / \ 162  Tomcat1 Tomcat2 Tomcat3 Tomcat4 167  Tomcat1 Tomcat2 Tomcat3 Tomcat4 163  164 168 165  What is important to mention here, is that session replication is only the beginning of clustering. 169  What is important to mention here, is that session replication is only the beginning of clustering. 166  Another popular concept used to implement clusters is farming, i.e., you deploy your apps only to one 170  Another popular concept used to implement clusters is farming, i.e., you deploy your apps only to one 231  235  232 236 233   237   234   238   236  channelSendOptions="6"> 237 240 238  <Manager className="org.apache.catalina.ha.session.BackupManager" 241   242  <!-- 245   247  <Channel className="org.apache.catalina.tribes.group.GroupChannel"> 250   248  <Membership className="org.apache.catalina.tribes.membership.McastService" 251   253  <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver" 256   258 261 259  <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"> 262   260  <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/> 263   261  </Sender> 264   262  <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/> 265   263  <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/> 266   264  <Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"/> 267   265  </Channel> 268   266 269 267  <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" 270   269 272 270  <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer" 273   275 278 276  <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/> 279   277  </Cluster> 280  ]]> 278   279   281   280  Break it down!! 282  Break it down!! 281   283   282   284  ]]> 284  channelSendOptions="6"> 285   286   286   287  The main element, inside this element all cluster details can be configured. 287  The main element, inside this element all cluster details can be configured. 288  The channelSendOptions is the flag that is attached to each message sent by the 288  The channelSendOptions is the flag that is attached to each message sent by the 293  sends it itself directly through the channel. 293  sends it itself directly through the channel. 294  For more info, Please visit the reference documentation 294  For more info, Please visit the reference documentation 295   295   296   296   300  mapSendOptions="6"/> 300  ]]> 305  --> 306   307   305   308  This is a template for the manager configuration that will be used if no manager is defined in the <Context> 306  This is a template for the manager configuration that will be used if no manager is defined in the <Context> 309  element. In Tomcat 5.x each webapp marked distributable had to use the same manager, this is no longer the case 307  element. In Tomcat 5.x each webapp marked distributable had to use the same manager, this is no longer the case 313  and create a manager instance cloning this configuration. 311  and create a manager instance cloning this configuration. 314  For more info, Please visit the reference documentation 312  For more info, Please visit the reference documentation 315   313   316   314  ]]> 317  <Channel className="org.apache.catalina.tribes.group.GroupChannel"> 318   319   315   320  The channel element is Tribes, the group communication framework 316  The channel element is Tribes, the group communication framework 321  used inside Tomcat. This element encapsulates everything that has to do with communication and membership logic. 317  used inside Tomcat. This element encapsulates everything that has to do with communication and membership logic. 322  For more info, Please visit the reference documentation 318  For more info, Please visit the reference documentation 323   319   324   320  ]]> 329  dropTime="3000"/> 330   331   325   332  Membership is done using multicasting. Please note that Tribes also supports static memberships using the 326  Membership is done using multicasting. Please note that Tribes also supports static memberships using the 333  StaticMembershipInterceptor if you want to extend your membership to points beyond multicasting. 327  StaticMembershipInterceptor if you want to extend your membership to points beyond multicasting. 339  Receiver.address attribute. 333  Receiver.address attribute. 340  For more info, Please visit the reference documentation 334  For more info, Please visit the reference documentation 341   335   342   336  ]]> 347  maxThreads="6"/> 348   349   341   350  In tribes the logic of sending and receiving data has been broken into two functional components. The Receiver, as the name suggests 342  In tribes the logic of sending and receiving data has been broken into two functional components. The Receiver, as the name suggests 351  is responsible for receiving messages. Since the Tribes stack is thread less, (a popular improvement now adopted by other frameworks as well), 343  is responsible for receiving messages. Since the Tribes stack is thread less, (a popular improvement now adopted by other frameworks as well), 353  The address attribute is the host address that will be broadcasted by the membership component to the other nodes. 345  The address attribute is the host address that will be broadcasted by the membership component to the other nodes. 354  For more info, Please visit the reference documentation 346  For more info, Please visit the reference documentation 355   347   356   348   357 349   358  <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"> 350  ]]> 359  <Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/> 360  </Sender> 361   362   351   363  The sender component, as the name indicates is responsible for sending messages to other nodes. 352  The sender component, as the name indicates is responsible for sending messages to other nodes. 364  The sender has a shell component, the ReplicationTransmitter but the real stuff done is done in the 353  The sender has a shell component, the ReplicationTransmitter but the real stuff done is done in the 369  at the same time. 358  at the same time. 370  For more info, Please visit the reference documentation 359  For more info, Please visit the reference documentation 371   360   372   361   373  <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/> 362   374  <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/> 363   375  <Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"/> 364  ]]> 376  </Channel> 377   378   365   379  Tribes uses a stack to send messages through. Each element in the stack is called an interceptor, and works much like the valves do 366  Tribes uses a stack to send messages through. Each element in the stack is called an interceptor, and works much like the valves do 380  in the Tomcat servlet container. 367  in the Tomcat servlet container. 387  channel stack. Think of it as a linked list, with the head being the first most interceptor and the tail the last. 374  channel stack. Think of it as a linked list, with the head being the first most interceptor and the tail the last. 388  For more info, Please visit the reference documentation 375  For more info, Please visit the reference documentation 389   376   390   377  ]]> 392  filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt"/> 393   394   379   395  The cluster uses valves to track requests to web applications, we've mentioned the ReplicationValve and the JvmRouteBinderValve above. 380  The cluster uses valves to track requests to web applications, we've mentioned the ReplicationValve and the JvmRouteBinderValve above. 396  The <Cluster> element itself is not part of the pipeline in Tomcat, instead the cluster adds the valve to its parent container. 381  The <Cluster> element itself is not part of the pipeline in Tomcat, instead the cluster adds the valve to its parent container. 397  If the <Cluster> elements is configured in the <Engine> element, the valves get added to the engine and so on. 382  If the <Cluster> elements is configured in the <Engine> element, the valves get added to the engine and so on. 398  For more info, Please visit the reference documentation 383  For more info, Please visit the reference documentation 399   384   400   385  ]]> 405  watchEnabled="false"/> 406   407   390   408  The default tomcat cluster supports farmed deployment, ie, the cluster can deploy and undeploy applications on the other nodes. 391  The default tomcat cluster supports farmed deployment, ie, the cluster can deploy and undeploy applications on the other nodes. 409  The state of this component is currently in flux but will be addressed soon. There was a change in the deployment algorithm 392  The state of this component is currently in flux but will be addressed soon. There was a change in the deployment algorithm 411  webapps directory. 394  webapps directory. 412  For more info, Please visit the reference documentation 395  For more info, Please visit the reference documentation 413   396   414   397   415  <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/> 398  ]]> 416  </Cluster> 417   418   399   419  Since the SimpleTcpCluster itself is a sender and receiver of the Channel object, components can register themselves as listeners to 400  Since the SimpleTcpCluster itself is a sender and receiver of the Channel object, components can register themselves as listeners to 420  the SimpleTcpCluster. The listener above ClusterSessionListener listens for DeltaManager replication messages 401  the SimpleTcpCluster. The listener above ClusterSessionListener listens for DeltaManager replication messages 426 407 427   408   428 409 429  Component Levels: 410  Component Levels:  430  411  Server 431  Server 432  | 412  | 433  Service 413  Service 434  | 414  | 473  \ 453  \ 474  -- FarmWarDeployer 454  -- FarmWarDeployer 475 455 476 477  456  478   479 457 458 480   459   481   460   482  To make it easy to understand how clustering works, We are gonna take you through a series of scenarios. 461  To make it easy to understand how clustering works, We are gonna take you through a series of scenarios. 507  Tomcat will create a DeltaManager for that context instead of a StandardManager. 486  Tomcat will create a DeltaManager for that context instead of a StandardManager. 508  The cluster class will start up a membership service (multicast) and a replication service (tcp unicast). 487  The cluster class will start up a membership service (multicast) and a replication service (tcp unicast). 509  More on the architecture further down in this document. 488  More on the architecture further down in this document. 510   489   511  490  512  • TomcatB starts up 491  • TomcatB starts up 513   492   520  entry. The session state gets transferred for each web application that has distributable in 499  entry. The session state gets transferred for each web application that has distributable in 521  its web.xml. Note: To use session replication efficiently, all your tomcat instances should be 500  its web.xml. Note: To use session replication efficiently, all your tomcat instances should be 522  configured the same. 501  configured the same. 523   502   524  •  503  525  • TomcatA receives a request, a session S1 is created. 504  • TomcatA receives a request, a session S1 is created. 526   505   534  in the session without calling setAttribute or removeAttribute to be replicated. 513  in the session without calling setAttribute or removeAttribute to be replicated. 535  a useDirtyFlag configuration parameter can be used to optimize the number of times 514  a useDirtyFlag configuration parameter can be used to optimize the number of times 536  a session is replicated. 515  a session is replicated. 537   516   538 517 539  •  518  540  • TomcatA crashes 519  • TomcatA crashes 544  be notified of any changes that occurs in TomcatB. 523  be notified of any changes that occurs in TomcatB. 545  The load balancer will redirect the requests from TomcatA to TomcatB and all the sessions 524  The load balancer will redirect the requests from TomcatA to TomcatB and all the sessions 546  are current. 525  are current. 547   526   548  •  527  549  • TomcatB receives a request for session S1 528  • TomcatB receives a request for session S1 550  Nothing exciting, TomcatB will process the request as any other request. 529  Nothing exciting, TomcatB will process the request as any other request. 551   530   552  •  531  553  • TomcatA starts up 532  • TomcatA starts up 554  Upon start up, before TomcatA starts taking new request and making itself 533  Upon start up, before TomcatA starts taking new request and making itself 556  It will join the cluster, contact TomcatB for the current state of all the sessions. 535  It will join the cluster, contact TomcatB for the current state of all the sessions. 557  And once it receives the session state, it finishes loading and opens its HTTP/mod_jk ports. 536  And once it receives the session state, it finishes loading and opens its HTTP/mod_jk ports. 558  So no requests will make it to TomcatA until it has received the session state from TomcatB. 537  So no requests will make it to TomcatA until it has received the session state from TomcatB. 559   538   560  •  539  561  • TomcatA receives a request, invalidate is called on the session (S1) 540  • TomcatA receives a request, invalidate is called on the session (S1) 562  The invalidate is call is intercepted, and the session is queued with invalidated sessions. 541  The invalidate is call is intercepted, and the session is queued with invalidated sessions. 563  When the request is complete, instead of sending out the session that has changed, it sends out 542  When the request is complete, instead of sending out the session that has changed, it sends out 564  an "expire" message to TomcatB and TomcatB will invalidate the session as well. 543  an "expire" message to TomcatB and TomcatB will invalidate the session as well. 565   544   566 545 567  •  546  568  • TomcatB receives a request, for a new session (S2) 547  • TomcatB receives a request, for a new session (S2) 569  Same scenario as in step 3) 548  Same scenario as in step 3) 570   549   571 550 572 551 573  •  552  576  and the session is queued with invalidated sessions. 555  and the session is queued with invalidated sessions. 577  At this point, the invalidet session will not be replicated across until 556  At this point, the invalidet session will not be replicated across until 578  another request comes through the system and checks the invalid queue. 557  another request comes through the system and checks the invalid queue. 579   558   580  559  581  560  582 561 613 592 614   593   615  Monitoring is a very important question when you use a cluster. Some of the cluster objects are JMX MBeans  594  Monitoring is a very important question when you use a cluster. Some of the cluster objects are JMX MBeans  616  Add the following parameter to your startup script with Java 5: 595  Add the following parameter to your startup script with Java 5:  617  596 set CATALINA_OPTS=\ 618 set CATALINA_OPTS=\ 619 -Dcom.sun.management.jmxremote \ 597 -Dcom.sun.management.jmxremote \ 620 -Dcom.sun.management.jmxremote.port=%my.jmx.port% \ 598 -Dcom.sun.management.jmxremote.port=%my.jmx.port% \ 621 -Dcom.sun.management.jmxremote.ssl=false \ 599 -Dcom.sun.management.jmxremote.ssl=false \ 622 -Dcom.sun.management.jmxremote.authenticate=false 600 -Dcom.sun.management.jmxremote.authenticate=false 623  601 602   603  List of Cluster Mbeans 624   604   625   605  626 List of Cluster Mbeans  627  628 606 629  NameNameDescriptionDescriptionMBean ObjectName - EngineMBean ObjectName - EngineMBean ObjectName - HostMBean ObjectName - Host  607   630   608   631   609   632   610   633   611   634   612   635 613 636   614   678   656   679 657 680  658  681   682  659  683 660 684   661    Lines 64-76 (-)webapps/docs/connectors.xml (-2 / +1 lines) 64 proxied HTTP. AJP clustering is the most efficient from the Tomcat perspective. 64 proxied HTTP. AJP clustering is the most efficient from the Tomcat perspective. 65 It is otherwise functionally equivalent to HTTP clustering.  65 It is otherwise functionally equivalent to HTTP clustering.  66 66 67  The native connectors supported with this Tomcat release are: 67  The native connectors supported with this Tomcat release are:  68   68   69  • JK 1.2.x with any of the supported servers •  69  • JK 1.2.x with any of the supported servers •  70  • mod_proxy on Apache HTTP Server 2.x (included by default in Apache HTTP Server 2.2), 70  • mod_proxy on Apache HTTP Server 2.x (included by default in Apache HTTP Server 2.2), 71 with AJP enabled •  71 with AJP enabled 72   72   73   74 73 75  Other native connectors supporting AJP may work, but are no longer supported.  74  Other native connectors supporting AJP may work, but are no longer supported.  76 75  Lines 34-92 Lines 96-114 Lines 115-125 Lines 127-137 (-)webapps/docs/default-servlet.xml (-164 / +128 lines) 34  34  35 35 36   36   37   37 The default servlet is the servlet which serves static resources as well 38 The default servlet is the servlet which serves static resources as well 38 as serves the directory listings (if directory listings are enabled). 39 as serves the directory listings (if directory listings are enabled). 39 40   40   41   41 42 42   43   44   43 It is declared globally in$CATALINA_BASE/conf/web.xml. 45 It is declared globally in CATALINA_BASE/conf/web.xml. 44 By default here is it's declaration: 46 By default here is it's declaration: 45  47   46  <servlet> 48  47  <servlet-name>default</servlet-name> 49  default 48  <servlet-class> 50   49  org.apache.catalina.servlets.DefaultServlet 51  org.apache.catalina.servlets.DefaultServlet 50  </servlet-class> 52   51  <init-param> 53   52  <param-name>debug</param-name> 54  debug 53  <param-value>0</param-value> 55  0 54  </init-param> 56   55  <init-param> 57   56  <param-name>listings</param-name> 58  listings 57  <param-value>false</param-value> 59  false 58  </init-param> 60   59  <load-on-startup>1</load-on-startup> 61  1 60  </servlet> 62   61 63 62 ... 64 ... 63 65 64  <servlet-mapping> 66   65  <servlet-name>default</servlet-name> 67  default 66  <url-pattern>/</url-pattern> 68  / 67  </servlet-mapping> 69  ]]> 68 70 69  70 71 So by default, the default servlet is loaded at webapp startup and 71 So by default, the default servlet is loaded at webapp startup and 72 directory listings are disabled and debugging is turned off. 72 directory listings are disabled and debugging is turned off. 73   73   74 74 75   75   76 The DefaultServlet allows the following initParamters: 76   77  The DefaultServlet allows the following initParamters: 78   77 79 78  80  79  debug 82  Debugging level. It is not very useful unless you are a tomcat 82  Debugging level. It is not very useful unless you are a tomcat 83  developer. As 83  developer. As 84  of this writing, useful values are 0, 1, 11, 1000. [0] 84  of this writing, useful values are 0, 1, 11, 1000. [0] 85  listings 90  If no welcome file is present, can a directory listing be 87  If no welcome file is present, can a directory listing be 91  shown? 88  shown? 92  value may be true or false [false] 89  value may be true or false [false] 96  WARNING: Listings of directories containing many entries are 93  WARNING: Listings of directories containing many entries are 97  expensive. Multiple requests for large directory listings can consume 94  expensive. Multiple requests for large directory listings can consume 98  significant proportions of server resources. 95  significant proportions of server resources. 99  readmeFile 104  If a directory listing is presented, a readme file may also 98  If a directory listing is presented, a readme file may also 105  be presented with the listing. This file is inserted as is 99  be presented with the listing. This file is inserted as is 106  so it may contain HTML. 100  so it may contain HTML. 107  globalXsltFile 112  If you wish to customize your directory listing, you 103  If you wish to customize your directory listing, you 113  can use an XSL transformation. This value is an absolute 104  can use an XSL transformation. This value is an absolute 114  file name which be used for all directory listings. 105  file name which be used for all directory listings. 115  This can be overridden per context and/or per directory. See 106  This can be overridden per context and/or per directory. See 116  contextXsltFile and localXsltFile 107  contextXsltFile and localXsltFile 117  below. The format of the xml is shown below. 108  below. The format of the xml is shown below. 118  contextXsltFile 123  You may also customize your directory listing by context by 111  You may also customize your directory listing by context by 124  configuring contextXsltFile. This should be a context 112  configuring contextXsltFile. This should be a context 125  relative path (e.g.: /path/to/context.xslt). This 113  relative path (e.g.: /path/to/context.xslt). This 127  file does not exist, then globalXsltFile will be used. If 115  file does not exist, then globalXsltFile will be used. If 128  globalXsltFile does not exist, then the default 116  globalXsltFile does not exist, then the default 129  directory listing will be shown. 117  directory listing will be shown. 130  localXsltFile 135  You may also customize your directory listing by directory by 120  You may also customize your directory listing by directory by 136  configuring localXsltFile. This should be a relative 121  configuring localXsltFile. This should be a relative 137  file name in the directory where the listing will take place. 122  file name in the directory where the listing will take place. 142  globalXsltFile will be used. If 127  globalXsltFile will be used. If 143  globalXsltFile does not exist, then the default 128  globalXsltFile does not exist, then the default 144  directory listing will be shown. 129  directory listing will be shown. 145  input 150  Input buffer size (in bytes) when reading 132  Input buffer size (in bytes) when reading 151  resources to be served. [2048] 133  resources to be served. [2048] 152  output 157  Output buffer size (in bytes) when writing 136  Output buffer size (in bytes) when writing 158  resources to be served. [2048] 137  resources to be served. [2048] 159  readonly 164  Is this context "read only", so HTTP commands like PUT and 140  Is this context "read only", so HTTP commands like PUT and 165  DELETE are rejected? [true] 141  DELETE are rejected? [true] 166  fileEncoding 171  File encoding to be used when reading static resources. 144  File encoding to be used when reading static resources. 172  [platform default] 145  [platform default] 173  sendfileSize 178  If the connector used supports sendfile, this represents the minimal 148  If the connector used supports sendfile, this represents the minimal 179  file size in KB for which sendfile will be used. Use a negative value 149  file size in KB for which sendfile will be used. Use a negative value 180  to always disable sendfile. [48] 150  to always disable sendfile. [48] 181  useAcceptRanges 186  If true, the Accept-Ranges header will be set when appropriate for the 153  If true, the Accept-Ranges header will be set when appropriate for the 187  response. [true] 154  response. [true] 188   81   80   81   85   86   86   87   88   89   96   100   97   101   102   103   101   108   102   109   110   111   109   119   110   120   121   122   118   131   119   132   133   134   130   146   131   147   148   149   134   153   135   154   155   156   138   160   139   161   162   163   142   167   143   168   169   170   146   174   147   175   176   177   151   182   152   183   184   185   155   189   156  190 191  192  157  193 158 194   159   210 175 211   176   212 Format: 177 Format: 213  178   214  <listing> 179  215  <entries> 180   216  <entry type='file|dir' urlPath='aPath' size='###' date='gmt date'> 181   217  fileName1 182  fileName1 218  </entry> 183   219  <entry type='file|dir' urlPath='aPath' size='###' date='gmt date'> 184   220  fileName2 185  fileName2 221  </entry> 186   222  ... 187  ... 223  </entries> 188   224  <readme></readme> 189   225  </listing> 190  ]]> 226  227   191   228  • size will be missing if type='dir' •  192  • size will be missing if type='dir' •  229  • Readme is a CDATA entry •  193  • Readme is a CDATA entry •  230   194   195 196   197  The following is a sample xsl file which mimics the default tomcat behavior: 231   198   232 The following is a sample xsl file which mimics the default tomcat behavior: 199  233  234 <?xml version="1.0"?> 235 200 236 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 201  238 203 239  <xsl:output method="xhtml" encoding="iso-8859-1" indent="no"/> 204   240 207 241  <xsl:template match="listing"> 208   242  <html> 209   243  <head> 210   244  <title> 211   245  Sample Directory Listing For 212  Sample Directory Listing For 246  <xsl:value-of select="@directory"/> 213  <xsl:value-of select="@directory"/> 247  </title> 214   248  <style> 215   257  <body> 224   258  <h1>Sample Directory Listing For 225   259  <xsl:value-of select="@directory"/> 226  Sample Directory Listing For 260  </h1> 227   261  <hr size="1" /> 228   262  <table cellspacing="0" 229   263  width="100%" 230   264  cellpadding="5" 231  FilenameSizeLast Modified  265  align="center"> 232   266  <tr> 233   267  <th align="left">Filename</th> 234   268  <th align="center">Size</th> 235   269  <th align="right">Last Modified</th> 236   270  </tr> 237   271  <xsl:apply-templates select="entries"/> 238   272  </table> 239   273  <xsl:apply-templates select="readme"/> 240  Apache Tomcat/8.0  274  <hr size="1" /> 241   275  <h3>Apache Tomcat/7.0</h3> 242   276  </body> 243   277  </html> 278  </xsl:template> 279 244 280 245 281  <xsl:template match="entries"> 246   282  <xsl:apply-templates select="entry"/> 247   283  </xsl:template> 248   284 249 285  <xsl:template match="readme"> 250   286  <hr size="1" /> 251   287  <pre><xsl:apply-templates/></pre> 252   288  </xsl:template> 253   289 254 290  <xsl:template match="entry"> 255   291  <tr> 256   293  <xsl:variable name="urlPath" select="@urlPath"/> 258   294  <a href="{urlPath}"> 259   295  <tt><xsl:apply-templates/></tt> 260 
296  </a> 261 
297  </td> 262 
299  <tt><xsl:value-of select="@size"/></tt> 264 
300  </td> 265 
302  <tt><xsl:value-of select="@date"/></tt> 267 
303  </td> 268 
292  <td align="left"> 257   298  <td align="right"> 263   301  <td align="right"> 266   304  </tr> 269   305  </xsl:template> 270   306 271 307 </xsl:stylesheet> 272 ]]> 308  309 273 310  274  311 275
 Lines 41-47 (-)webapps/docs/deployer-howto.xml (-1 / +2 lines) 41 

41 

42 

42 

43  Web application deployment may be accomplished in a number of ways 43  Web application deployment may be accomplished in a number of ways 44  within the Tomcat server.

44  within the Tomcat server. 45 

45 
46 
46 
• Statically; the web application is setup before Tomcat is started
•  47 
• Statically; the web application is setup before Tomcat is started
•  47 
•  48 
•
 Lines 125-157 Lines 164-196 Lines 219-253 Lines 254-260 (-)webapps/docs/html-manager-howto.xml (-98 / +55 lines) 125 users continuously encounter database exceptions.

125 users continuously encounter database exceptions.

126 126 127 

If this command succeeds, you will see a Message like this:

127 

If this command succeeds, you will see a Message like this:

128  128 OK - Started application at context path /examples 129 OK - Started application at context path /examples 130  131 129 132 

Otherwise, the Message will start with FAIL and include an 130 

Otherwise, the Message will start with FAIL and include an 133 error message. Possible causes for problems include:

131 error message. Possible causes for problems include:

134 
132 
135 
• Encountered exception 133 
• Encountered exception 136 
137 

An exception was encountered trying to start the web application. 134 

An exception was encountered trying to start the web application. 138  Check the Tomcat logs for the details.

135  Check the Tomcat logs for the details.

139 
•  136   140 
• Invalid context path was specified 137 
• Invalid context path was specified 141 
142 

The context path must start with a slash character, unless you are 138 

The context path must start with a slash character, unless you are 143  referencing the ROOT web application -- in which case the context path 139  referencing the ROOT web application -- in which case the context path 144  must be a zero-length string.

140  must be a zero-length string.

145 
•  141   146 
• No context exists for path /foo 142 
• No context exists for path /foo 147 
148 

There is no deployed application on the context path 143 

There is no deployed application on the context path 149  that you specified.

144  that you specified.

150 
•  145   151 
• No context path was specified 146 
• No context path was specified 152 
147 

153  The path parameter is required. 148  The path parameter is required. 154 

•  149 

150  155 
151 
156 152 157  153  164 "stopped" on a list applications command.

160 "stopped" on a list applications command.

165 161 166 

If this command succeeds, you will see a Message like this:

162 

If this command succeeds, you will see a Message like this:

167  163 OK - Stopped application at context path /examples 168 OK - Stopped application at context path /examples 169  170 164 171 

Otherwise, the Message will start with FAIL and include an 165 

Otherwise, the Message will start with FAIL and include an 172 error message. Possible causes for problems include:

166 error message. Possible causes for problems include:

173 
167 
174 
• Encountered exception 168 
• Encountered exception 175 
176 

An exception was encountered trying to stop the web application. 169 

An exception was encountered trying to stop the web application. 177  Check the Tomcat logs for the details.

170  Check the Tomcat logs for the details.

178 
•  171   179 
• Invalid context path was specified 172 
• Invalid context path was specified 180 
181 

The context path must start with a slash character, unless you are 173 

The context path must start with a slash character, unless you are 182  referencing the ROOT web application -- in which case the context path 174  referencing the ROOT web application -- in which case the context path 183  must be a zero-length string.

175  must be a zero-length string.

184 
•  176   185 
• No context exists for path /foo 177 
• No context exists for path /foo 186 
187 

There is no deployed application on the context path 178 

There is no deployed application on the context path 188  that you specified.

179  that you specified.

189 
•  180   190 
• No context path was specified 181 
• No context path was specified 191 
182 

192  The path parameter is required. 183  The path parameter is required. 193 

•  184 

185  194 
186 
195 187 196  188  219 error message. Possible causes for problems include:

211 error message. Possible causes for problems include:

220 
212 
221 
• Encountered exception 213 
• Encountered exception 222 
223 

An exception was encountered trying to restart the web application. 214 

An exception was encountered trying to restart the web application. 224  Check the Tomcat logs for the details.

215  Check the Tomcat logs for the details.

225 
•  216   226 
• Invalid context path was specified 217 
• Invalid context path was specified 227 
228 

The context path must start with a slash character, unless you are 218 

The context path must start with a slash character, unless you are 229  referencing the ROOT web application -- in which case the context path 219  referencing the ROOT web application -- in which case the context path 230  must be a zero-length string.

220  must be a zero-length string.

231 
•  221   232 
• No context exists for path /foo 222 
• No context exists for path /foo 233 
234 

There is no deployed application on the context path 223 

There is no deployed application on the context path 235  that you specified.

224  that you specified.

236 
•  225   237 
• No context path was specified 226 
• No context path was specified 238 
227 

The path parameter is required.

239  The path parameter is required. 228 
•  240   241 
• Reload not supported on WAR deployed at path /foo 229 
• Reload not supported on WAR deployed at path /foo 242 
230 

Currently, application reloading (to pick up changes to the classes or 243  Currently, application reloading (to pick up changes to the classes or 244  web.xml file) is not supported when a web application is 231  web.xml file) is not supported when a web application is 245  installed directly from a WAR file, which happens when the host is 232  installed directly from a WAR file, which happens when the host is 246  configured to not unpack WAR files. As it only works when the web 233  configured to not unpack WAR files. As it only works when the web 247  application is installed from an unpacked directory, if you are using 234  application is installed from an unpacked directory, if you are using 248  a WAR file, you should undeploy and then deploy 235  a WAR file, you should undeploy and then deploy 249  the application again to pick up your changes. 236  the application again to pick up your changes.

250 
•  237   251 
238 
252 239 253  240  254 241 255  242  256 243 257 

WARNING - This command will delete the 244 

WARNING - This command will delete the 258 contents of the web application directory and/or ".war" file if it exists within 245 contents of the web application directory and/or ".war" file if it exists within 259 the appBase directory (typically "webapps") for this virtual host 246 the appBase directory (typically "webapps") for this virtual host 260 . The web application temporary work directory is also deleted. If 247 . The web application temporary work directory is also deleted. If 268 in the HTML manager.

255 in the HTML manager.

269 256 270 

If this command succeeds, you will see a Message like this:

257 

If this command succeeds, you will see a Message like this:

271  258 OK - Undeployed application at context path /examples 272 OK - Undeployed application at context path /examples 273  274 259 275 

Otherwise, the Message will start with FAIL and include an 260 

Otherwise, the Message will start with FAIL and include an 276 error message. Possible causes for problems include:

261 error message. Possible causes for problems include:

277 
262 
278 
• Encountered exception 263 
• Encountered exception 279 
280 

An exception was encountered trying to undeploy the web application. 264 

An exception was encountered trying to undeploy the web application. 281  Check the Tomcat logs for the details.

265  Check the Tomcat logs for the details.

282 
•  266   283 
• Invalid context path was specified 267 
• Invalid context path was specified 284 
285 

The context path must start with a slash character, unless you are 268 

The context path must start with a slash character, unless you are 286  referencing the ROOT web application -- in which case the context path 269  referencing the ROOT web application -- in which case the context path 287  must be a zero-length string.

270  must be a zero-length string.

288 
•  271   289 
• No context exists for path /foo 272 
• No context exists for path /foo 290 
291 

There is no deployed application on the context path 273 

There is no deployed application on the context path 292  that you specified.

274  that you specified.

293 
•  275   294 
• No context path was specified 276 
• No context path was specified 295 
296  The path parameter is required. 277  The path parameter is required. 297 
•  278   298 
279 
299 280 300 
281 
319 300 320 

There are a number of different ways the deploy command can be used.

301 

There are a number of different ways the deploy command can be used.

321 302 322 

Deploy a Directory or WAR by URL

303 
Deploy a Directory or WAR by URL
323 304 324 

Install a web application directory or ".war" file located on the Tomcat 305 

Install a web application directory or ".war" file located on the Tomcat 325 server. If no Context Path is specified, the directory name or the 306 server. If no Context Path is specified, the directory name or the 344 context named /bar. Notice that there is no path 325 context named /bar. Notice that there is no path 345 parameter so the context path defaults to the name of the web application 326 parameter so the context path defaults to the name of the web application 346 archive file without the ".war" extension.

327 archive file without the ".war" extension.

347  328 WAR or Directory URL: jar:file:/path/to/bar.war!/ 348 WAR or Directory URL: jar:file:/path/to/bar.war!/ 349  350 329 351 330 352 

Deploy a Directory or War from the Host appBase

331 
Deploy a Directory or War from the Host appBase
353 332 354 

Install a web application directory or ".war" file located in your Host 333 

Install a web application directory or ".war" file located in your Host 355 appBase directory. If no Context Path is specified the directory name 334 appBase directory. If no Context Path is specified the directory name 360 deployed as the web application context named /foo. Notice 339 deployed as the web application context named /foo. Notice 361 that there is no path parameter so the context path defaults 340 that there is no path parameter so the context path defaults 362 to the name of the web application directory.

341 to the name of the web application directory.

363  342 WAR or Directory URL: foo 364 WAR or Directory URL: foo 365  366 343 367 344 368 

In this example the ".war" file bar.war located in your 345 

In this example the ".war" file bar.war located in your 369 Host appBase directory on the Tomcat server is deployed as the web 346 Host appBase directory on the Tomcat server is deployed as the web 370 application context named /bartoo.

347 application context named /bartoo.

371  348 Context Path: /bartoo 372 Context Path: /bartoo 349 WAR or Directory URL: bar.war 373 WAR or Directory URL: bar.war 374  375 350 376 351 377 

Deploy using a Context configuration ".xml" file

352 
Deploy using a Context configuration ".xml" file
378 353 379 

If the Host deployXML flag is set to true, you can install a web 354 

If the Host deployXML flag is set to true, you can install a web 380 application using a Context configuration ".xml" file and an optional 355 application using a Context configuration ".xml" file and an optional 386 web application Context just as if it were configured in your 361 web application Context just as if it were configured in your 387 Tomcat server.xml configuration file. Here is an 362 Tomcat server.xml configuration file. Here is an 388 example for Tomcat running on Windows:

363 example for Tomcat running on Windows:

389  364  390 <Context path="/foobar" docBase="C:\path\to\application\foobar"> 365 ]]> 391 </Context> 392  393 366 394 367 395 

Use of the WAR or Directory URL is optional. When used 368 

Use of the WAR or Directory URL is optional. When used 398 371 399 

Here is an example of installing an application using a Context 372 

Here is an example of installing an application using a Context 400 configuration ".xml" file for Tomcat running on Windows.

373 configuration ".xml" file for Tomcat running on Windows.

401  374 XML Configuration file URL: file:C:/path/to/context.xml 402 XML Configuration file URL: file:C:/path/to/context.xml 403  404 375 405 376 406 

Here is an example of installing an application using a Context 377 

Here is an example of installing an application using a Context 407 configuration ".xml" file and a web application ".war" file located 378 configuration ".xml" file and a web application ".war" file located 408 on the server (Tomcat running on Unix).

379 on the server (Tomcat running on Unix).

409  380 XML Configuration file URL: file:/path/to/context.xml 410 XML Configuration file URL: file:/path/to/context.xml 381 WAR or Directory URL: jar:file:/path/to/bar.war!/ 411 WAR or Directory URL: jar:file:/path/to/bar.war!/ 412  413 382 414 383 415  384  430 

Upload of a WAR file could fail for the following reasons:

399 

Upload of a WAR file could fail for the following reasons:

431 
400 
432 
• File uploaded must be a .war 401 
• File uploaded must be a .war 433 
434 

The upload install will only accept files which have the filename 402 

The upload install will only accept files which have the filename 435  extension of ".war".

403  extension of ".war".

436 
•  404   437 
• War file already exists on server 405 
• War file already exists on server 438 
439 

If a war file of the same name already exists in your Host's 406 

If a war file of the same name already exists in your Host's 440  appBase the upload will fail. Either undeploy the existing war file 407  appBase the upload will fail. Either undeploy the existing war file 441  from your Host's appBase or upload the new war file using a different 408  from your Host's appBase or upload the new war file using a different 442  name.

409  name.

443 
•  410   444 
• File upload failed, no file 411 
• File upload failed, no file 445 
446 

412 

447 
•  413   448 
• Install Upload Failed, Exception: 414 
• Install Upload Failed, Exception: 449 
450 

The war file upload or install failed with a Java Exception. 415 

The war file upload or install failed with a Java Exception. 451  The exception message will be listed.

416  The exception message will be listed.

452 
•  417   453 
418 
454 419 455  420  477 442 478 

If deployment and startup is successful, you will receive a Message 443 

If deployment and startup is successful, you will receive a Message 479 like this:

444 like this:

480  445 OK - Deployed application at context path /foo 481 OK - Deployed application at context path /foo 482  483 446 484 

Otherwise, the Message will start with FAIL and include an 447 

Otherwise, the Message will start with FAIL and include an 485 error message. Possible causes for problems include:

448 error message. Possible causes for problems include:

486 
449 
487 
• Application already exists at path /foo 450 
• Application already exists at path /foo 488 
489 

The context paths for all currently running web applications must be 451 

The context paths for all currently running web applications must be 490  unique. Therefore, you must either undeploy the existing web 452  unique. Therefore, you must either undeploy the existing web 491  application using this context path, or choose a different context path 453  application using this context path, or choose a different context path 492  for the new one.

454  for the new one.

493 
•  455   494 
• Document base does not exist or is not a readable directory 456 
• Document base does not exist or is not a readable directory 495 
496 

The URL specified by the WAR or Directory URL: field must 457 

The URL specified by the WAR or Directory URL: field must 497  identify a directory on this server that contains the "unpacked" version 458  identify a directory on this server that contains the "unpacked" version 498  of a web application, or the absolute URL of a web application archive 459  of a web application, or the absolute URL of a web application archive 499  (WAR) file that contains this application. Correct the value entered for 460  (WAR) file that contains this application. Correct the value entered for 500  the WAR or Directory URL: field.

461  the WAR or Directory URL: field.

501 
•  462   502 
• Encountered exception 463 
• Encountered exception 503 
504 

An exception was encountered trying to start the new web application. 464 

An exception was encountered trying to start the new web application. 505  Check the Tomcat logs for the details, but likely explanations include 465  Check the Tomcat logs for the details, but likely explanations include 506  problems parsing your /WEB-INF/web.xml file, or missing 466  problems parsing your /WEB-INF/web.xml file, or missing 507  classes encountered when initializing application event listeners and 467  classes encountered when initializing application event listeners and 508  filters.

468  filters.

509 
•  469   510 
• Invalid application URL was specified 470 
• Invalid application URL was specified 511 
512 

The URL for the WAR or Directory URL: field that you specified 471 

The URL for the WAR or Directory URL: field that you specified 513  was not valid. Such URLs must start with file:, and URLs 472  was not valid. Such URLs must start with file:, and URLs 514  for a WAR file must end in ".war".

473  for a WAR file must end in ".war".

515 
•  474   516 
• Invalid context path was specified 475 
• Invalid context path was specified 517 
518 

The context path must start with a slash character, unless you are 476 

The context path must start with a slash character, unless you are 519  referencing the ROOT web application -- in which case the context path 477  referencing the ROOT web application -- in which case the context path 520  must be a "/" string.

478  must be a "/" string.

521 
•  479   522 
• Context path must match the directory or WAR file name: 480 
• Context path must match the directory or WAR file name: 523 
481 

If the application war or directory is deployed in your Host appBase 524  If the application war or directory is deployed in your Host appBase 525  directory and either the Host is configured with autoDeploy=true the Context 482  directory and either the Host is configured with autoDeploy=true the Context 526  path must match the directory name or war file name without the ".war" 483  path must match the directory name or war file name without the ".war" 527  extension. 484  extension.

528 
•  485   529 
• Only web applications in the Host web application directory can 486 
• Only web applications in the Host web application directory can 530  be deployed 487  be deployed 531 
488 

532  If the Host deployXML flag is set to false this error will happen 489  If the Host deployXML flag is set to false this error will happen 533  if an attempt is made to install a web application directory or 490  if an attempt is made to install a web application directory or 534  ".war" file outside of the Host appBase directory. 491  ".war" file outside of the Host appBase directory. 535 

•  492 

536 
493 
537 494 538  495 
 Lines 42-48 Lines 61-68 Lines 71-83 Lines 198-205 (-)webapps/docs/jasper-howto.xml (-55 / +48 lines) 42 42 43 

Jasper 2 has been redesigned to significantly improve performance over 43 

Jasper 2 has been redesigned to significantly improve performance over 44 the original Jasper. In addition to general code improvements the following 44 the original Jasper. In addition to general code improvements the following 45 changes were made: 45 changes were made:

46 
46 
47 
• JSP Custom Tag Pooling - The java objects instantiated 47 
• JSP Custom Tag Pooling - The java objects instantiated 48 for JSP Custom Tags can now be pooled and reused. This significantly boosts 48 for JSP Custom Tags can now be pooled and reused. This significantly boosts 61 compilation. This compiler loads source dependencies from the container 61 compilation. This compiler loads source dependencies from the container 62 classloader. Ant and javac can still be used.
•  62 classloader. Ant and javac can still be used. 63 
63 
64 

65 64 65 66 

Jasper is implemented using the servlet class 66 

Jasper is implemented using the servlet class 67 org.apache.jasper.servlet.JspServlet.

67 org.apache.jasper.servlet.JspServlet.

68 68 71 
71 
72 72 73 

By default Jasper is configured for use when doing web application 73 

By default Jasper is configured for use when doing web application 74 development. See the section  74 development. See the section  75 Production Configuration for information on configuring Jasper 75 Production Configuration for information on configuring Jasper 76 for use on a production Tomcat server.

76 for use on a production Tomcat server.

77 77 78 

The servlet which implements Jasper is configured using init parameters 78 

The servlet which implements Jasper is configured using init parameters 79 in your global $CATALINA_BASE/conf/web.xml. 79 in your global$CATALINA_BASE/conf/web.xml. 80 80 

81 
81 
82 
• checkInterval - If development is false and checkInterval 82 
• checkInterval - If development is false and checkInterval 83 is greater than zero, background compiles are enabled. checkInterval is the time 83 is greater than zero, background compiles are enabled. checkInterval is the time 198 header is added by generated servlet. true or false, 198 header is added by generated servlet. true or false, 199 default false.
•  199 default false. 200 
200 
201 

202 201 202 203 

The Java compiler from Eclipse JDT in included as the default compiler. It is 203 

The Java compiler from Eclipse JDT in included as the default compiler. It is 204 an advanced Java compiler which will load all dependencies from the Tomcat class 204 an advanced Java compiler which will load all dependencies from the Tomcat class 205 loader, which will help tremendously when compiling on large installations with 205 loader, which will help tremendously when compiling on large installations with 222 java.lang.InternalError: name is too long to represent exception 222 java.lang.InternalError: name is too long to represent exception 223 when compiling very large JSPs. If this is observed then it may be worked around 223 when compiling very large JSPs. If this is observed then it may be worked around 224 by using one of the following: 224 by using one of the following: 225 

225 
226 
226 
• reduce the size of the JSP
•  227 
• reduce the size of the JSP
•  227 
• disable SMAP generation and JSR-045 support by setting 228 
• disable SMAP generation and JSR-045 support by setting 228 suppressSmap to true.
•  229 suppressSmap to true. 229 
230 
230 

231 231 232 
232 
233 233 239 Jasper servlet becomes critical.

239 Jasper servlet becomes critical.

240 240 241 

When using Jasper 2 in a production Tomcat server you should consider making 241 

When using Jasper 2 in a production Tomcat server you should consider making 242 the following changes from the default configuration. 242 the following changes from the default configuration.

243 
243 
244 
• development - To disable on access checks for JSP 244 
• development - To disable on access checks for JSP 245 pages compilation set this to false.
•  245 pages compilation set this to false. 251 
• trimSpaces - To remove useless bytes from the response, 251 
• trimSpaces - To remove useless bytes from the response, 252 set this to true.
•  252 set this to true. 253 
253 
254 

255 254 256  255  257 256 264 download) to precompile a webapp: 263 download) to precompile a webapp: 265 

264 

266 265 267 

266  268  269 <project name="Webapp Precompilation" default="all" basedir="."> 270 267 271  <import file="${tomcat.home}/bin/catalina-tasks.xml"/> 268   272 269 273  <target name="jspc"> 270   274 271 275  <jasper 272   280 277 281  </target> 278   282 279 283  <target name="compile"> 280   284 281 285  <mkdir dir="${webapp.path}/WEB-INF/classes"/> 282   286  <mkdir dir="${webapp.path}/WEB-INF/lib"/> 283   287 284 288  <javac destdir="${webapp.path}/WEB-INF/classes" 285   293  <classpath> 290   294  <pathelement location="${webapp.path}/WEB-INF/classes"/> 291   295  <fileset dir="${webapp.path}/WEB-INF/lib"> 292   296  <include name="*.jar"/> 293   297  </fileset> 294   298  <pathelement location="${tomcat.home}/lib"/> 295   299  <fileset dir="${tomcat.home}/lib"> 296   300  <include name="*.jar"/> 297   301  </fileset> 298   302  <fileset dir="${tomcat.home}/bin"> 299   303  <include name="*.jar"/> 300   304  </fileset> 301   305  </classpath> 302   306  <include name="**" /> 303   307  <exclude name="tags/**" /> 304   308  </javac> 305   309 306 310  </target> 307   311 308 312  <target name="all" depends="jspc,compile"> 309   313  </target> 310   314 311 315  <target name="cleanup"> 312   316  <delete> 313   317  <fileset dir="${webapp.path}/WEB-INF/src"/> 314   318  <fileset dir="${webapp.path}/WEB-INF/classes/org/apache/jsp"/> 315   319  </delete> 316   320  </target> 317   321 318 322 </project> 319 ]]> 323  324   325 320 326   321   327 The following command line can be used to run the script 322 The following command line can be used to run the script 328 (replacing the tokens with the Tomcat base path and the path to the webapp 323 (replacing the tokens with the Tomcat base path and the path to the webapp 329 which should be precompiled):  324 which should be precompiled): 330  331 $ANT_HOME/bin/ant -Dtomcat.home=<$TOMCAT_HOME> -Dwebapp.path=<$WEBAPP_PATH> 332  333 

325 

326 $ANT_HOME/bin/ant -Dtomcat.home=<$TOMCAT_HOME> -Dwebapp.path=<$WEBAPP_PATH> 334 327 328 335   329   336 Then, the declarations and mappings for the servlets which were generated 330 Then, the declarations and mappings for the servlets which were generated 337 during the precompilation must be added to the web application deployment 331 during the precompilation must be added to the web application deployment 366 ${webapp.path}/WEB-INF/classes/org/apache/jsp. 360 ${webapp.path}/WEB-INF/classes/org/apache/jsp. 367   361   368 362 369  Hints: 363  Hints:  370   364   371  • When you switch to another Tomcat release, then regenerate and recompile 365  • When you switch to another Tomcat release, then regenerate and recompile 372 your jsp's with the new Tomcat version. •  366 your jsp's with the new Tomcat version. 377 that changing from the defaults may affect performance, but it will vary 371 that changing from the defaults may affect performance, but it will vary 378 depending on the application. 372 depending on the application. 379   373   380   381  374  382 375 383   376    Lines 196-202 Lines 208-214 Lines 217-232 Lines 234-241 (-)webapps/docs/jndi-datasource-examples-howto.xml (-126 / +97 lines) 196 196 197  197  198 198 199  0. Introduction  199  0. Introduction  200  Versions of MySQL and JDBC 200  Versions of MySQL and JDBC 201 drivers that have been reported to work: 201 drivers that have been reported to work: 202   202   208 208 209  Before you proceed, don't forget to copy the JDBC Driver's jar into$CATALINA_HOME/lib.

209 

Before you proceed, don't forget to copy the JDBC Driver's jar into $CATALINA_HOME/lib.  210 210 211  1. MySQL configuration  211  1. MySQL configuration  212   212   213 Ensure that you follow these instructions as variations can cause problems. 213 Ensure that you follow these instructions as variations can cause problems. 214   214   217 Your MySQL user must have a password assigned. The driver 217 Your MySQL user must have a password assigned. The driver 218 will fail if you try to connect with an empty password. 218 will fail if you try to connect with an empty password. 219   219   220  220  GRANT ALL PRIVILEGES ON *.* TO javauser@localhost 221 mysql> GRANT ALL PRIVILEGES ON *.* TO javauser@localhost 221  -> IDENTIFIED BY 'javadude' WITH GRANT OPTION; 222  -> IDENTIFIED BY 'javadude' WITH GRANT OPTION; 222 mysql> create database javatest; 223 mysql> create database javatest; 223 mysql> use javatest; 224 mysql> use javatest; 224 mysql> create table testdata ( 225 mysql> create table testdata ( 225  -> id int not null auto_increment primary key, 226  -> id int not null auto_increment primary key, 226  -> foo varchar(25), 227  -> foo varchar(25), 227  -> bar int);]]> 228  -> bar int); 229  230   228   231 Note: the above user should be removed once testing is 229 Note: the above user should be removed once testing is 232 complete! 230 complete! 234 232 235  Next insert some test data into the testdata table. 233  Next insert some test data into the testdata table. 236   234   237  235  insert into testdata values(null, 'hello', 12345); 238 mysql> insert into testdata values(null, 'hello', 12345); 239 Query OK, 1 row affected (0.00 sec) 236 Query OK, 1 row affected (0.00 sec) 240 237 241 mysql> select * from testdata; 238 mysql> select * from testdata; 246 +----+-------+-------+ 243 +----+-------+-------+ 247 1 row in set (0.00 sec) 244 1 row in set (0.00 sec) 248 245 249 mysql> 246 mysql>]]> 250  251 247 252  2. Context configuration  248  2. Context configuration  253  Configure the JNDI DataSource in Tomcat by adding a declaration for your 249  Configure the JNDI DataSource in Tomcat by adding a declaration for your 254 resource to your Context.  250 resource to your Context.  255  For example:  251  For example:  256  252  257 <Context> 258 253 259  <!-- maxActive: Maximum number of database connections in pool. Make sure you 254   263 258 264  <!-- maxIdle: Maximum number of idle database connections to retain in pool. 259   268 263 269  <!-- maxWait: Maximum time to wait for a database connection to become available 264   273 268 274  <!-- username and password: MySQL username and password for database connections --> 269   275 270 276  <!-- driverClassName: Class name for the old mm.mysql JDBC driver is 271   280 275 281  <!-- url: The JDBC connection url for connecting to your MySQL database. 276   283 278 284  <Resource name="jdbc/TestDB" auth="Container" type="javax.sql.DataSource" 279   288 283 289 </Context> 284 ]]> 290  291 285 292  3. web.xml configuration  286  3. web.xml configuration  293 287 294  Now create a WEB-INF/web.xml for this test application.  288  Now create a WEB-INF/web.xml for this test application.  295  289  301  <description>MySQL Test App</description> 294  MySQL Test App 302  <resource-ref> 295   303  <description>DB Connection</description> 296  DB Connection 304  <res-ref-name>jdbc/TestDB</res-ref-name> 297  jdbc/TestDB 305  <res-type>javax.sql.DataSource</res-type> 298  javax.sql.DataSource 306  <res-auth>Container</res-auth> 299  Container 307  </resource-ref> 300   308 </web-app> 301 ]]> 309  310 302 311  4. Test code  303  4. Test code  312  Now create a simple test.jsp page for use later. 304  Now create a simple test.jsp page for use later.  313  305  314 <%@ taglib uri="http://java.sun.com/jsp/jstl/sql" prefix="sql" %> 306 <%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %> 315 <%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %> 316 307 317 <sql:query var="rs" dataSource="jdbc/TestDB"> 308  318 select id, foo, bar from testdata 309 select id, foo, bar from testdata 319 </sql:query> 310  320 311 321 <html> 312  322  <head> 313   323  <title>DB Test</title> 314  DB Test 324  </head> 315   325  <body> 316   326 317 327  <h2>Results</h2> 318  Results  328 319 329 <c:forEach var="row" items="${rs.rows}"> 320  330  Foo ${row.foo}<br/> 321  Foo${row.foo}
331  Bar ${row.bar}<br/> 322  Bar${row.bar}
332 </c:forEach> 323 
333 324 334  </body> 325   335 </html> 326 ]]> 336  337 

338 327 339 

That JSP page makes use of JSTL's 328 

That JSP page makes use of JSTL's 340 SQL and Core taglibs. You can get it from 329 SQL and Core taglibs. You can get it from 355  344  356 345 357  346  358 

0. Introduction

347 
0. Introduction
359 348 360 

Oracle requires minimal changes from the MySQL configuration except for the 349 

Oracle requires minimal changes from the MySQL configuration except for the 361 usual gotchas :-)

350 usual gotchas :-)

372 for this driver class will be discontinued in the next major release. 361 for this driver class will be discontinued in the next major release. 373 

362 

374 363 375 

1. Context configuration

364 
1. Context configuration
376 

In a similar manner to the mysql config above, you will need to define your 365 

In a similar manner to the mysql config above, you will need to define your 377 Datasource in your Context. Here we define a 366 Datasource in your Context. Here we define a 378 Datasource called myoracle using the thin driver to connect as user scott, 367 Datasource called myoracle using the thin driver to connect as user scott, 382 371 383 

Use of the OCI driver should simply involve a changing thin to oci in the URL string. 372 

Use of the OCI driver should simply involve a changing thin to oci in the URL string. 384 

373 

385  374 ]]> 391  392 379 393 

2. web.xml configuration

380 
2. web.xml configuration
394 

You should ensure that you respect the element ordering defined by the DTD when you 381 

You should ensure that you respect the element ordering defined by the DTD when you 395 create you applications web.xml file.

382 create you applications web.xml file.

396  383  397 <resource-ref> 384  Oracle Datasource example 398  <description>Oracle Datasource example</description> 385  jdbc/myoracle 399  <res-ref-name>jdbc/myoracle</res-ref-name> 386  javax.sql.DataSource 400  <res-type>javax.sql.DataSource</res-type> 387  Container 401  <res-auth>Container</res-auth> 388 ]]> 402 </resource-ref> 389 
3. Code example
403  404 

3. Code example

405 

You can use the same example application as above (asuming you create the required DB 390 

You can use the same example application as above (asuming you create the required DB 406 instance, tables etc.) replacing the Datasource code with something like

391 instance, tables etc.) replacing the Datasource code with something like

407  392  413  414  397  415 398 416 399 417  400  418 

0. Introduction

401 
0. Introduction
419 

PostgreSQL is configured in a similar manner to Oracle.

402 

PostgreSQL is configured in a similar manner to Oracle.

420 403 421 

1. Required files

404 
1. Required files
422 

405 

423 Copy the Postgres JDBC jar to $CATALINA_HOME/lib. As with Oracle, the 406 Copy the Postgres JDBC jar to$CATALINA_HOME/lib. As with Oracle, the 424 jars need to be in this directory in order for DBCP's Classloader to find 407 jars need to be in this directory in order for DBCP's Classloader to find 425 them. This has to be done regardless of which configuration step you take next. 408 them. This has to be done regardless of which configuration step you take next. 426 

409 

427 410 428 

2. Resource configuration

411 
2. Resource configuration
429 412 430 

413 

431 You have two choices here: define a datasource that is shared across all Tomcat 414 You have two choices here: define a datasource that is shared across all Tomcat 432 applications, or define a datasource specifically for one application. 415 applications, or define a datasource specifically for one application. 433 

416 

434 417 435 

2a. Shared resource configuration

418 
2a. Shared resource configuration
436 

419 

437 Use this option if you wish to define a datasource that is shared across 420 Use this option if you wish to define a datasource that is shared across 438 multiple Tomcat applications, or if you just prefer defining your datasource 421 multiple Tomcat applications, or if you just prefer defining your datasource 441 

This author has not had success here, although others have reported so. 424 

This author has not had success here, although others have reported so. 442 Clarification would be appreciated here.

425 Clarification would be appreciated here.

443 426 444  427 ]]> 449  431 
2b. Application-specific resource configuration
450 

2b. Application-specific resource configuration

451 432 452 

433 

453 Use this option if you wish to define a datasource specific to your application, 434 Use this option if you wish to define a datasource specific to your application, 460 The Context element should look something like the following. 441 The Context element should look something like the following. 461 

442 

462 443 463  444  464 <Context> 465 445 466 <Resource name="jdbc/postgres" auth="Container" 446  471 </Context> 451 ]]> 472  473 452 474 

3. web.xml configuration

453 
3. web.xml configuration
475  454  476 <resource-ref> 455  postgreSQL Datasource example 477  <description>postgreSQL Datasource example</description> 456  jdbc/postgres 478  <res-ref-name>jdbc/postgres</res-ref-name> 457  javax.sql.DataSource 479  <res-type>javax.sql.DataSource</res-type> 458  Container 480  <res-auth>Container</res-auth> 459 ]]> 481 </resource-ref> 482  483 460 484 

4. Accessing the datasource

461 
4. Accessing the datasource
485 

462 

486 When accessing the datasource programmatically, remember to prepend 463 When accessing the datasource programmatically, remember to prepend 487 java:/comp/env to your JNDI lookup, as in the following snippet of 464 java:/comp/env to your JNDI lookup, as in the following snippet of 489 you change it in the above resource definition file as well. 466 you change it in the above resource definition file as well. 490 

467 

491 468 492  469  503  504 479 505 
480 
506  481  539 You should next create a simple test servlet or jsp that has these 514 You should next create a simple test servlet or jsp that has these 540 critical lines: 515 critical lines: 541 

516 

542  517  547  548 

521 

549 where database is of the form host:port:SID Now if you try to access the URL of your 522 where database is of the form host:port:SID Now if you try to access the URL of your 550 test servlet/jsp and what you get is a 523 test servlet/jsp and what you get is a 552 

525 

553 

526 

554 First, the UnsatisfiedLinkError indicates that you have 527 First, the UnsatisfiedLinkError indicates that you have 528 

555 
529 
556 
• a mismatch between your JDBC classes file and 530 
• a mismatch between your JDBC classes file and 557 your Oracle client version. The giveaway here is the message stating that a needed library file cannot be 531 your Oracle client version. The giveaway here is the message stating that a needed library file cannot be 563 the classes12.zip file from the directory $ORAHOME\jdbc\lib will also work. 537 the classes12.zip file from the directory$ORAHOME\jdbc\lib will also work. 564 
•  538  565 
539 
566 

567 

540 

568 Next you may experience the error ORA-06401 NETCMN: invalid driver designator 541 Next you may experience the error ORA-06401 NETCMN: invalid driver designator 569 

542 

640 Here is an example of properly written code to use a database connection 613 Here is an example of properly written code to use a database connection 641 obtained from a connection pool: 614 obtained from a connection pool: 642 

615 

643 
616                          
676                                                                          
677 648 678  649  679 650
 Lines 108-125 Lines 161-171 Lines 181-188 Lines 193-200 (-)webapps/docs/jndi-resources-howto.xml (-145 / +111 lines) 108 element:

108 element:

109 109 110 
110 
111 
• <Environment> - 111 
• <Environment> - 112  Configure names and values for scalar environment entries that will be 112  Configure names and values for scalar environment entries that will be 113  exposed to the web application through the JNDI 113  exposed to the web application through the JNDI 114  InitialContext (equivalent to the inclusion of an 114  InitialContext (equivalent to the inclusion of an 115  <env-entry> element in the web application 115  <env-entry> element in the web application 116  deployment descriptor).
•  116  deployment descriptor). 117 
• <Resource> - 117 
• <Resource> - 118  Configure the name and data type of a resource made available to the 118  Configure the name and data type of a resource made available to the 119  application (equivalent to the inclusion of a 119  application (equivalent to the inclusion of a 120  <resource-ref> element in the web application 120  <resource-ref> element in the web application 121  deployment descriptor).
•  121  deployment descriptor). 122 
• <ResourceLink> - 122 
• <ResourceLink> - 123  Add a link to a resource defined in the global JNDI context. Use resource 123  Add a link to a resource defined in the global JNDI context. Use resource 124  links to give a web application access to a resource defined in 124  links to give a web application access to a resource defined in 125  the <GlobalNamingResources> 125  the <GlobalNamingResources> 161 <GlobalNamingResources> element of 161 <GlobalNamingResources> element of 162 $CATALINA_BASE/conf/server.xml. You may expose these resources to 162 $CATALINA_BASE/conf/server.xml. You may expose these resources to 163 web applications by using a 163 web applications by using a 164 <ResourceLink> to 164 <ResourceLink> to 165 include it in the per-web-application context.

165 include it in the per-web-application context.

166 166 167 

If a resource has been defined using a 167 

If a resource has been defined using a 168 <ResourceLink>, it is not 168 <ResourceLink>, it is not 169 necessary for that resource to be defined in /WEB-INF/web.xml. 169 necessary for that resource to be defined in /WEB-INF/web.xml. 170 However, it is recommended to keep the entry in /WEB-INF/web.xml 170 However, it is recommended to keep the entry in /WEB-INF/web.xml 171 to document the resource requirements for the web application.

171 to document the resource requirements for the web application.

181 access to a resource - in this case, to a JDBC DataSource - 181 access to a resource - in this case, to a JDBC DataSource - 182 would look something like this:

182 would look something like this:

183 183 184  184  197  198 196 199  197  200 198 208  subsection below details the configuration and usage of the standard resource 206  subsection below details the configuration and usage of the standard resource 209  factories.

207  factories.

210 208 211 

See Adding Custom 209 

See Adding Custom 212  Resource Factories for information about how to create, install, 210  Resource Factories for information about how to create, install, 213  configure, and use your own custom resource factory classes with 211  configure, and use your own custom resource factory classes with 214  Tomcat.

212  Tomcat.

223 221 224   222   225 223 226 

0. Introduction

224 
0. Introduction
227 225 228 

This resource factory can be used to create objects of any 226 

This resource factory can be used to create objects of any 229  Java class that conforms to standard JavaBeans naming conventions (i.e. 227  Java class that conforms to standard JavaBeans naming conventions (i.e. 234 232 235 

The steps required to use this facility are described below.

233 

The steps required to use this facility are described below.

236 234 237 

235 
238 236 239 

Create the JavaBean class which will be instantiated each time 237 

Create the JavaBean class which will be instantiated each time 240  that the resource factory is looked up. For this example, assume 238  that the resource factory is looked up. For this example, assume 241  you create a class com.mycompany.MyBean, which looks 239  you create a class com.mycompany.MyBean, which looks 242  like this:

240  like this:

243 241 244  242  271  272 268 273 

269 
274 270 275 

Next, modify your web application deployment descriptor 271 

Next, modify your web application deployment descriptor 276  (/WEB-INF/web.xml) to declare the JNDI name under which 272  (/WEB-INF/web.xml) to declare the JNDI name under which 277  you will request new instances of this bean. The simplest approach is 273  you will request new instances of this bean. The simplest approach is 278  to use a <resource-env-ref> element, like this:

274  to use a <resource-env-ref> element, like this:

279 275 280  276  281 <resource-env-ref> 277   282  <description> 283  Object factory for MyBean instances. 278  Object factory for MyBean instances. 284  </description> 279   285  <resource-env-ref-name> 280   286  bean/MyBeanFactory 281  bean/MyBeanFactory 287  </resource-env-ref-name> 282   288  <resource-env-ref-type> 283   289  com.mycompany.MyBean 284  com.mycompany.MyBean 290  </resource-env-ref-type> 285   291 </resource-env-ref> 286 ]]> 292  293 287 294 

WARNING - Be sure you respect the element ordering 288 

WARNING - Be sure you respect the element ordering 295  that is required by the DTD for web application deployment descriptors! 289  that is required by the DTD for web application deployment descriptors! 297  Servlet 291  Servlet 298  Specification for details.

292  Specification for details.

299 293 300 

3. Code Your Application's Use Of This Resource

294 
3. Code Your Application's Use Of This Resource
301 295 302 

A typical use of this resource environment reference might look 296 

A typical use of this resource environment reference might look 303  like this:

297  like this:

304 298 305  299  312  313 305 314 

4. Configure Tomcat's Resource Factory

306 
4. Configure Tomcat's Resource Factory
315 307 316 

To configure Tomcat's resource factory, add an element like this to the 308 

To configure Tomcat's resource factory, add an element like this to the 317  <Context> element for 309  <Context> element for 318  this web application.

310  this web application.

319 311 320  312  321 <Context ...> 322  ... 313  ... 323  <Resource name="bean/MyBeanFactory" auth="Container" 314   327  ... 318  ... 328 </Context> 319 ]]> 329  330 320 331 

Note that the resource name (here, bean/MyBeanFactory 321 

Note that the resource name (here, bean/MyBeanFactory 332  must match the value specified in the web application deployment 322  must match the value specified in the web application deployment 341 331 342   332   343 333 344 

0. Introduction

334 
0. Introduction
345 335 346 

UserDatabase resources are typically configured as global resources for 336 

UserDatabase resources are typically configured as global resources for 347  use by a UserDatabase realm. Tomcat includes a UserDatabaseFactoory that 337  use by a UserDatabase realm. Tomcat includes a UserDatabaseFactoory that 351 

The steps required to set up a global UserDatabase resource are described 341 

The steps required to set up a global UserDatabase resource are described 352  below.

342  below.

353 343 354 

1. Create/edit the XML file

344 
1. Create/edit the XML file
355 345 356 

The XMl file is typically located at 346 

The XMl file is typically located at 357  $CATALINA_BASE/conf/tomcat-users.xml however, you are free to 347 $CATALINA_BASE/conf/tomcat-users.xml however, you are free to 359  files are placed in $CATALINA_BASE/conf. A typical XML would 349  files are placed in$CATALINA_BASE/conf. A typical XML would 360  look like:

350  look like:

361 351 362  352  363 <?xml version='1.0' encoding='utf-8'?> 353  364 <tomcat-users> 354   365  <role rolename="tomcat"/> 355   366  <role rolename="role1"/> 356   367  <user username="tomcat" password="tomcat" roles="tomcat"/> 357   368  <user username="both" password="tomcat" roles="tomcat,role1"/> 358   369  <user username="role1" password="tomcat" roles="role1"/> 359 ]]> 370 </tomcat-users> 371  372 360 373 

361 
374 362 375 

Next, modify $CATALINA_BASE/conf/server.xml to create the 363  Next, modify$CATALINA_BASE/conf/server.xml to create the 376  UserDatabase resource based on your XMl file. It should look something like 364  UserDatabase resource based on your XMl file. It should look something like 377  this:

365  this:

378 366 379  367 ]]> 387  388 374 389 

The pathname attribute can be absolute or relative. If 375 

The pathname attribute can be absolute or relative. If 390  relative, it is relative to $CATALINA_BASE.  376  relative, it is relative to$CATALINA_BASE.

396  is running as. Ensure that these are appropriate to maintain the security 382  is running as. Ensure that these are appropriate to maintain the security 397  of your installation.

383  of your installation.

398 384 399 

3. Configure the Realm

385 
3. Configure the Realm
400 386 401 

Configure a UserDatabase Realm to use this resource as described in the 387 

Configure a UserDatabase Realm to use this resource as described in the 402  Realm configuration documentation.

388  Realm configuration documentation.

406 392 407   393   408 394 409 

0. Introduction

395 
0. Introduction
410 396 411 

In many web applications, sending electronic mail messages is a 397 

In many web applications, sending electronic mail messages is a 412  required part of the system's functionality. The 398  required part of the system's functionality. The 424 410 425 

The steps required for this are outlined below.

411 

The steps required for this are outlined below.

426 412 427 

413 
428 414 429 

The first thing you should do is modify the web application deployment 415 

The first thing you should do is modify the web application deployment 430  descriptor (/WEB-INF/web.xml) to declare the JNDI name under 416  descriptor (/WEB-INF/web.xml) to declare the JNDI name under 433  standard java:comp/env naming context that is the root of 419  standard java:comp/env naming context that is the root of 434  all provided resource factories. A typical web.xml entry 420  all provided resource factories. A typical web.xml entry 435  might look like this:

421  might look like this:

436  422  437 <resource-ref> 423   438  <description> 439  Resource reference to a factory for javax.mail.Session 424  Resource reference to a factory for javax.mail.Session 440  instances that may be used for sending electronic mail 425  instances that may be used for sending electronic mail 441  messages, preconfigured to connect to the appropriate 426  messages, preconfigured to connect to the appropriate 442  SMTP server. 427  SMTP server. 443  </description> 428   444  <res-ref-name> 429   445  mail/Session 430  mail/Session 446  </res-ref-name> 431   447  <res-type> 432   448  javax.mail.Session 433  javax.mail.Session 449  </res-type> 434   450  <res-auth> 435   451  Container 436  Container 452  </res-auth> 437   453 </resource-ref> 438 ]]> 454  455 439 456 

WARNING - Be sure you respect the element ordering 440 

WARNING - Be sure you respect the element ordering 457  that is required by the DTD for web application deployment descriptors! 441  that is required by the DTD for web application deployment descriptors! 459  Servlet 443  Servlet 460  Specification for details.

444  Specification for details.

461 445 462 

2. Code Your Application's Use Of This Resource

446 
2. Code Your Application's Use Of This Resource
463 447 464 

A typical use of this resource reference might look like this:

448 

A typical use of this resource reference might look like this:

465  449  478  479 461 480 

Note that the application uses the same resource reference name 462 

Note that the application uses the same resource reference name 481  that was declared in the web application deployment descriptor. This 463  that was declared in the web application deployment descriptor. This 483  <Context> element 465  <Context> element 484  for the web application as described below.

466  for the web application as described below.

485 467 486 

3. Configure Tomcat's Resource Factory

468 
3. Configure Tomcat's Resource Factory
487 469 488 

To configure Tomcat's resource factory, add an elements like this to the 470 

To configure Tomcat's resource factory, add an elements like this to the 489  <Context> element for 471  <Context> element for 490  this web application.

472  this web application.

491 473 492  474  493 <Context ...> 494  ... 475  ... 495  <Resource name="mail/Session" auth="Container" 476   498  ... 479  ... 499 </Context> 480 ]]> 500  501 481 502 

Note that the resource name (here, mail/Session) must 482 

Note that the resource name (here, mail/Session) must 503  match the value specified in the web application deployment descriptor. 483  match the value specified in the web application deployment descriptor. 517  then Tomcat's resource factory will configure and add a 497  then Tomcat's resource factory will configure and add a 518  javax.mail.Authenticator to the mail session.

498  javax.mail.Authenticator to the mail session.

519 499 520 

4. Install the JavaMail libraries

500 
4. Install the JavaMail libraries
521 501 522 

502 

523  Download the JavaMail API.

503  Download the JavaMail API.

524 504 525 

Unpackage the distribution and place mail.jar into $CATALINA_HOME/lib so 505  Unpackage the distribution and place mail.jar into$CATALINA_HOME/lib so 529  it in the $CATALINA_HOME/lib location only. 509  it in the$CATALINA_HOME/lib location only. 530 

510 

531 511 532 

5. Restart Tomcat

512 
5. Restart Tomcat
533 513 534 

For the additional JAR to be visible to Tomcat, it is necessary for the 514 

For the additional JAR to be visible to Tomcat, it is necessary for the 535  Tomcat instance to be restarted.

515  Tomcat instance to be restarted.

536 516 537 517 538 

Example Application

518 
Example Application
539 519 540 

The /examples application included with Tomcat contains 520 

The /examples application included with Tomcat contains 541  an example of utilizing this resource factory. It is accessed via the 521  an example of utilizing this resource factory. It is accessed via the 555 535 556   536   557 537 558 

0. Introduction

538 
0. Introduction
559 539 560 

Many web applications need to access a database via a JDBC driver, 540 

Many web applications need to access a database via a JDBC driver, 561  to support the functionality required by that application. The Java EE 541  to support the functionality required by that application. The Java EE 586  project. However, it is possible to use any other connection pool 566  project. However, it is possible to use any other connection pool 587  that implements javax.sql.DataSource, by writing your 567  that implements javax.sql.DataSource, by writing your 588  own custom resource factory, as described 568  own custom resource factory, as described 589  below.

569  below.

590 570 591 

571 
592 572 593 

Use of the JDBC Data Sources JNDI Resource Factory requires 573 

Use of the JDBC Data Sources JNDI Resource Factory requires 594  that you make an appropriate JDBC driver available to both Tomcat internal 574  that you make an appropriate JDBC driver available to both Tomcat internal 597  $CATALINA_HOME/lib directory, which makes the driver 577 $CATALINA_HOME/lib directory, which makes the driver 598  available both to the resource factory and to your application.

578  available both to the resource factory and to your application.

599 579 600 

580 
601 581 602 

Next, modify the web application deployment descriptor 582 

Next, modify the web application deployment descriptor 603  (/WEB-INF/web.xml) to declare the JNDI name under 583  (/WEB-INF/web.xml) to declare the JNDI name under 606  standard java:comp/env naming context that is the root of 586  standard java:comp/env naming context that is the root of 607  all provided resource factories. A typical web.xml entry 587  all provided resource factories. A typical web.xml entry 608  might look like this:

588  might look like this:

609  589  610 <resource-ref> 590   611  <description> 612  Resource reference to a factory for java.sql.Connection 591  Resource reference to a factory for java.sql.Connection 613  instances that may be used for talking to a particular 592  instances that may be used for talking to a particular 614  database that is configured in the <Context> 593  database that is configured in the  615  configurartion for the web application. 594  configurartion for the web application. 616  </description> 595   617  <res-ref-name> 596   618  jdbc/EmployeeDB 597  jdbc/EmployeeDB 619  </res-ref-name> 598   620  <res-type> 599   621  javax.sql.DataSource 600  javax.sql.DataSource 622  </res-type> 601   623  <res-auth> 602   624  Container 603  Container 625  </res-auth> 604   626 </resource-ref> 605 ]]> 627  628 606 629 

WARNING - Be sure you respect the element ordering 607 

WARNING - Be sure you respect the element ordering 630  that is required by the DTD for web application deployment descriptors! 608  that is required by the DTD for web application deployment descriptors! 632  Servlet 610  Servlet 633  Specification for details.

611  Specification for details.

634 612 635 

3. Code Your Application's Use Of This Resource

613 
3. Code Your Application's Use Of This Resource
636 614 637 

A typical use of this resource reference might look like this:

615 

A typical use of this resource reference might look like this:

638  616  647  648 624 649 

Note that the application uses the same resource reference name that was 625 

Note that the application uses the same resource reference name that was 650  declared in the web application deployment descriptor. This is matched up 626  declared in the web application deployment descriptor. This is matched up 652  <Context> element for 628  <Context> element for 653  the web application as described below.

629  the web application as described below.

654 630 655 

4. Configure Tomcat's Resource Factory

631 
4. Configure Tomcat's Resource Factory
656 632 657 

To configure Tomcat's resource factory, add an element like this to the 633 

To configure Tomcat's resource factory, add an element like this to the 658  <Context> element for 634  <Context> element for 659  the web application.

635  the web application.

660 636 661  637  662 <Context ...> 663  ... 638  ... 664  <Resource name="jdbc/EmployeeDB" 639   673  ... 648  ... 674 </Context> 649 ]]> 675  676 650 677 

Note that the resource name (here, jdbc/EmployeeDB) must 651 

Note that the resource name (here, jdbc/EmployeeDB) must 678  match the value specified in the web application deployment descriptor.

652  match the value specified in the web application deployment descriptor.

807  <Context> element for 781  <Context> element for 808  the web application. In the example below, we will create a factory that only 782  the web application. In the example below, we will create a factory that only 809  knows how to create com.mycompany.MyBean beans from the 783  knows how to create com.mycompany.MyBean beans from the 810  Generic JavaBean Resources example 784  Generic JavaBean Resources example 811  above.

785  above.

812 786 813 

1. Write A Resource Factory Class

787 

1. Write A Resource Factory Class

814 788 815 

You must write a class that implements the JNDI service provider 789 

You must write a class that implements the JNDI service provider 816  javax.naming.spi.ObjectFactory inteface. Every time your 790  javax.naming.spi.ObjectFactory inteface. Every time your 839 

To create a resource factory that knows how to produce MyBean 813 

To create a resource factory that knows how to produce MyBean 840  instances, you might create a class like this:

814  instances, you might create a class like this:

841 815 842  816  887  888 860 889 

In this example, we are unconditionally creating a new instance of 861 

In this example, we are unconditionally creating a new instance of 890  the com.mycompany.MyBean class, and populating its properties 862  the com.mycompany.MyBean class, and populating its properties 907  files are visible to both Catalina internal resources and your web 879  files are visible to both Catalina internal resources and your web 908  application.

880  application.

909 881 910 

882 

911 883 912 

Next, modify your web application deployment descriptor 884 

Next, modify your web application deployment descriptor 913  (/WEB-INF/web.xml) to declare the JNDI name under which 885  (/WEB-INF/web.xml) to declare the JNDI name under which 914  you will request new instances of this bean. The simplest approach is 886  you will request new instances of this bean. The simplest approach is 915  to use a <resource-env-ref> element, like this:

887  to use a <resource-env-ref> element, like this:

916 888 917  889  918 <resource-env-ref> 890   919  <description> 920  Object factory for MyBean instances. 891  Object factory for MyBean instances. 921  </description> 892   922  <resource-env-ref-name> 893   923  bean/MyBeanFactory 894  bean/MyBeanFactory 924  </resource-env-ref-name> 895   925  <resource-env-ref-type> 896   926  com.mycompany.MyBean 897  com.mycompany.MyBean 927  </resource-env-ref-type> 898   928 <resource-env-ref> 899 ]]> 929  930 900 931 

WARNING - Be sure you respect the element ordering 901 

WARNING - Be sure you respect the element ordering 932  that is required by the DTD for web application deployment descriptors! 902  that is required by the DTD for web application deployment descriptors! 934  Servlet 904  Servlet 935  Specification for details.

905  Specification for details.

936 906 937 

3. Code Your Application's Use Of This Resource

907 

3. Code Your Application's Use Of This Resource

938 908 939 

A typical use of this resource environment reference might look 909 

A typical use of this resource environment reference might look 940  like this:

910  like this:

941 911 942  912  949  950 918 951 

4. Configure Tomcat's Resource Factory

919 

4. Configure Tomcat's Resource Factory

952 920 953 

To configure Tomcat's resource factory, add an elements like this to the 921 

To configure Tomcat's resource factory, add an elements like this to the 954  <Context> element for 922  <Context> element for 955  this web application.

923  this web application.

956 924 957  925  958 <Context ...> 959  ... 926  ... 960  <Resource name="bean/MyBeanFactory" auth="Container" 927   964  ... 931  ... 965 </Context> 932 ]]> 966  967 933 968 

Note that the resource name (here, bean/MyBeanFactory 934 

Note that the resource name (here, bean/MyBeanFactory 969  must match the value specified in the web application deployment 935  must match the value specified in the web application deployment

 Lines 222-227 Lines 234-240 Lines 253-262 Lines 295-302 (-)webapps/docs/logging.xml (-22 / +14 lines) 222  JULI is enabled by default, and supports per classloader configuration, in 222  JULI is enabled by default, and supports per classloader configuration, in 223  addition to the regular global java.util.logging configuration. This means 223  addition to the regular global java.util.logging configuration. This means 224  that logging can be configured at the following layers: 224  that logging can be configured at the following layers: 225 

225 
226 
226 
• Globally. That is usually done in the 227 
• Globally. That is usually done in the 227  ${catalina.base}/conf/logging.properties file. 228 ${catalina.base}/conf/logging.properties file. 234  WEB-INF/classes/logging.properties 235  WEB-INF/classes/logging.properties 235 
•  236   236 
237 
237 

238 

238 

239  The default logging.properties in the JRE specifies a 239  The default logging.properties in the JRE specifies a 240  ConsoleHandler that routes logging to System.err. 240  ConsoleHandler that routes logging to System.err. 253  so FINEST or ALL should be set. Please refer to java.util.logging 253  so FINEST or ALL should be set. Please refer to java.util.logging 254  documentation in the JDK for the complete details: 254  documentation in the JDK for the complete details: 255 

255 

256  org.apache.catalina.level=FINEST 256 

257 

257  org.apache.catalina.level=FINEST 258 

259 

260  The configuration used by JULI is extremely similar to the one supported by 258  The configuration used by JULI is extremely similar to the one supported by 261  plain java.util.logging, but uses a few 259  plain java.util.logging, but uses a few 262  extensions to allow better flexibility in assigning loggers. The main 260  extensions to allow better flexibility in assigning loggers. The main 295 

293 

296 

294 

297  Example logging.properties file to be placed in $CATALINA_BASE/conf: 295  Example logging.properties file to be placed in$CATALINA_BASE/conf: 298   296 

299 handlers = 1catalina.org.apache.juli.FileHandler, \ 297   344  345 

346 342 347 

343 

348  Example logging.properties for the servlet-examples web application to be 344  Example logging.properties for the servlet-examples web application to be 349  placed in WEB-INF/classes inside the web application: 345  placed in WEB-INF/classes inside the web application: 350   346 

351 handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler 347   364  365 

366 360 361 367   362   368 

See the following resources for additional information:

363 

See the following resources for additional information:

369 
364 
423 
• Create a file called log4j.properties with the 418 
• Create a file called log4j.properties with the 424  following content and save it into $CATALINA_BASE/lib •  419  following content and save it into$CATALINA_BASE/lib 425   420   426   421   474  475 
469 
476 
1. Download Log4J 470 
2. Download Log4J 477  (v1.2 or later).
3.  471  (v1.2 or later). 546  configuration files, so we recommend you use a properties file as 540  configuration files, so we recommend you use a properties file as 547  described until a future version of log4j allows this convention. 541  described until a future version of log4j allows this convention. 548 

542 

549   543   544 log4j.logger.org.apache.catalina.core=DEBUG 551 log4j.logger.org.apache.catalina.core=DEBUG
545 log4j.logger.org.apache.catalina.session=DEBUG]]> 552 log4j.logger.org.apache.catalina.session=DEBUG
553  554 546 555 

547 

556  Be warned: a level of DEBUG will produce megabytes of logging and slow 548  Be warned: a level of DEBUG will produce megabytes of logging and slow

 Lines 70-82 Lines 89-99 Lines 101-113 Lines 175-183 (-)webapps/docs/manager-howto.xml (-374 / +252 lines) 70 manager.xml context configuration file in the 70 manager.xml context configuration file in the 71 $CATALINA_BASE/conf/[enginename]/[hostname] folder. Here is an 71 $CATALINA_BASE/conf/[enginename]/[hostname] folder. Here is an 72 example:

72 example:

73 
73                           
75                                                                    docBase="${catalina.home}/webapps/manager"> 75   77  allow="127\.0\.0\.1" /> 77 ]]> 78 </Context> 79   80 78 81  If you have Tomcat configured to support multiple virtual hosts 79  If you have Tomcat configured to support multiple virtual hosts 82 (websites) you would need to configure a Manager for each.  80 (websites) you would need to configure a Manager for each.  89  • A minimal version using HTTP requests only which is suitable for use 87  • A minimal version using HTTP requests only which is suitable for use 90 by scripts setup by system administrators. Commands are given as part of the 88 by scripts setup by system administrators. Commands are given as part of the 91 request URI, and responses are in the form of simple text that can be easily 89 request URI, and responses are in the form of simple text that can be easily 92 parsed and processed. See  90 parsed and processed. See  93 Supported Manager Commands for more information. •  91 Supported Manager Commands for more information. 94  • A convenient set of task definitions for the Ant 92  • A convenient set of task definitions for the Ant 95 (version 1.4 or later) build tool. See 93 (version 1.4 or later) build tool. See 96 Executing Manager Commands 94 Executing Manager Commands 97 With Ant for more information. •  95 With Ant for more information. 98  96  99 97 101 99 102   100   103 101 104   102   105  The description below uses the variable name$CATALINA_BASE to refer the 103 

The description below uses the variable name $CATALINA_BASE to refer the 106  base directory against which most relative paths are resolved. If you have 104  base directory against which most relative paths are resolved. If you have 107  not configured Tomcat for multiple instances by setting a CATALINA_BASE 105  not configured Tomcat for multiple instances by setting a CATALINA_BASE 108  directory, then$CATALINA_BASE will be set to the value of $CATALINA_HOME, 106  directory, then$CATALINA_BASE will be set to the value of $CATALINA_HOME, 109  the directory into which you have installed Tomcat.  107  the directory into which you have installed Tomcat.  110   108   111 109 112  It would be quite unsafe to ship Tomcat with default settings that allowed 110  It would be quite unsafe to ship Tomcat with default settings that allowed 113 anyone on the Internet to execute the Manager application on your server. 111 anyone on the Internet to execute the Manager application on your server. 175  edited with any text editor. This file contains an XML 173  edited with any text editor. This file contains an XML 176  <user> for each individual user, which might 174  <user> for each individual user, which might 177  look something like this: 175  look something like this: 178  176 ]]> 179 <user name="craigmcc" password="secret" roles="standard,manager-script" /> 180  181  which defines the username and password used by this individual to 177  which defines the username and password used by this individual to 182  log on, and the role names he or she is associated with. You can 178  log on, and the role names he or she is associated with. You can 183  add the manager-script role to the comma-delimited 179  add the manager-script role to the comma-delimited 207 See valves documentation 203 See valves documentation 208 for details. Here is 204 for details. Here is 209 an example of restricting access to the localhost by IP address:  205 an example of restricting access to the localhost by IP address:  210   206  211 <Context privileged="true"> 207   213  allow="127\.0\.0\.1"/> 209 ]]> 214 </Context> 215   216 210 217   211   218 212 221 215 222  All commands that the Manager application knows how to process are 216  All commands that the Manager application knows how to process are 223 specified in a single request URI like this:  217 specified in a single request URI like this:  224  218 http://{host}:{port}/manager/text/{command}?{parameters} 225 http://{host}:{port}/manager/text/{command}?{parameters} 226  227  where {host} and {port} represent the hostname 219  where {host} and {port} represent the hostname 228 and port number on which Tomcat is running, {command} 220 and port number on which Tomcat is running, {command} 229 represents the Manager command you wish to execute, and 221 represents the Manager command you wish to execute, and 282 274 283  275  284 276 285  277 http://localhost:8080/manager/text/deploy?path=/foo 286 http://localhost:8080/manager/text/deploy?path=/foo 287  288 278 289  Upload the web application archive (WAR) file that is specified as the 279  Upload the web application archive (WAR) file that is specified as the 290 request data in this HTTP PUT request, install it into the appBase 280 request data in this HTTP PUT request, install it into the appBase 311 301 312  If installation and startup is successful, you will receive a response 302  If installation and startup is successful, you will receive a response 313 like this:  303 like this:  314  304 OK - Deployed application at context path /foo 315 OK - Deployed application at context path /foo 316  317 305 318  Otherwise, the response will start with FAIL and include an 306  Otherwise, the response will start with FAIL and include an 319 error message. Possible causes for problems include:  307 error message. Possible causes for problems include:  320   308   321  • Application already exists at path /foo 309  • Application already exists at path /foo 322   323  The context paths for all currently running web applications must be 310  The context paths for all currently running web applications must be 324  unique. Therefore, you must undeploy the existing web 311  unique. Therefore, you must undeploy the existing web 325  application using this context path, or choose a different context path 312  application using this context path, or choose a different context path 327  a parameter on the URL, with a value of true to avoid this 314  a parameter on the URL, with a value of true to avoid this 328  error. In that case, an undeploy will be performed on an existing 315  error. In that case, an undeploy will be performed on an existing 329  application before performing the deployment.  316  application before performing the deployment.  330  •  317   331  • Encountered exception 318  • Encountered exception 332   333  An exception was encountered trying to start the new web application. 319  An exception was encountered trying to start the new web application. 334  Check the Tomcat logs for the details, but likely explanations include 320  Check the Tomcat logs for the details, but likely explanations include 335  problems parsing your /WEB-INF/web.xml file, or missing 321  problems parsing your /WEB-INF/web.xml file, or missing 336  classes encountered when initializing application event listeners and 322  classes encountered when initializing application event listeners and 337  filters.  323  filters.  338  •  324   339   325   340 326 341  327  348 334 349  There are a number of different ways the deploy command can be used.  335  There are a number of different ways the deploy command can be used.  350 336 351  Deploy a previously deployed webapp  337  Deploy a previously deployed webapp  352 338 353  This can be used to deploy a previously deployed web application, which 339  This can be used to deploy a previously deployed web application, which 354 has been deployed using the tag attribute. Note that the work 340 has been deployed using the tag attribute. Note that the work 355 directory for the Manager webapp will contain the previously deployed WARs; 341 directory for the Manager webapp will contain the previously deployed WARs; 356 removing it would make the deployment fail.  342 removing it would make the deployment fail.  357  343 http://localhost:8080/manager/text/deploy?path=/footoo&tag=footag 358 http://localhost:8080/manager/text/deploy?path=/footoo&tag=footag 359  360 344 361 345 362  Deploy a Directory or WAR by URL  346  Deploy a Directory or WAR by URL  363 347 364  Deploy a web application directory or ".war" file located on the Tomcat 348  Deploy a web application directory or ".war" file located on the Tomcat 365 server. If no path is specified, the directory name or the war file 349 server. If no path is specified, the directory name or the war file 373  In this example the web application located in the directory 357  In this example the web application located in the directory 374 /path/to/foo on the Tomcat server is deployed as the 358 /path/to/foo on the Tomcat server is deployed as the 375 web application context named /footoo.  359 web application context named /footoo.  376  360 http://localhost:8080/manager/text/deploy?path=/footoo&war=file:/path/to/foo 377 http://localhost:8080/manager/text/deploy?path=/footoo&war=file:/path/to/foo 378  379 361 380 362 381  In this example the ".war" file /path/to/bar.war on the 363  In this example the ".war" file /path/to/bar.war on the 383 /bar. Notice that there is no path parameter 365 /bar. Notice that there is no path parameter 384 so the context path defaults to the name of the web application archive 366 so the context path defaults to the name of the web application archive 385 file without the ".war" extension.  367 file without the ".war" extension.  386  368 http://localhost:8080/manager/text/deploy?war=jar:file:/path/to/bar.war!/ 387 http://localhost:8080/manager/text/deploy?war=jar:file:/path/to/bar.war!/ 388  389 369 390 370 391  Deploy a Directory or War from the Host appBase  371  Deploy a Directory or War from the Host appBase  392 372 393  Deploy a web application directory or ".war" file located in your Host 373  Deploy a web application directory or ".war" file located in your Host 394 appBase directory. The directory name or the war file name without the ".war" 374 appBase directory. The directory name or the war file name without the ".war" 398 foo in the Host appBase directory of the Tomcat server is 378 foo in the Host appBase directory of the Tomcat server is 399 deployed as the web application context named /foo. Notice 379 deployed as the web application context named /foo. Notice 400 that the context path used is the name of the web application directory.  380 that the context path used is the name of the web application directory.  401  381 http://localhost:8080/manager/text/deploy?war=foo 402 http://localhost:8080/manager/text/deploy?war=foo 403  404 382 405 383 406  In this example the ".war" file bar.war located in your 384  In this example the ".war" file bar.war located in your 407 Host appBase directory on the Tomcat server is deployed as the web 385 Host appBase directory on the Tomcat server is deployed as the web 408 application context named /bar.  386 application context named /bar.  409  387 http://localhost:8080/manager/text/deploy?war=bar.war 410 http://localhost:8080/manager/text/deploy?war=bar.war 411  412 388 413 389 414  Deploy using a Context configuration ".xml" file  390  Deploy using a Context configuration ".xml" file  415 391 416  If the Host deployXML flag is set to true you can deploy a web 392  If the Host deployXML flag is set to true you can deploy a web 417 application using a Context configuration ".xml" file and an optional 393 application using a Context configuration ".xml" file and an optional 423 web application Context just as if it were configured in your 399 web application Context just as if it were configured in your 424 Tomcat server.xml configuration file. Here is an 400 Tomcat server.xml configuration file. Here is an 425 example:  401 example:  426  402  427 <Context path="/foobar" docBase="/path/to/application/foobar"> 403 ]]> 428 </Context> 429  430 404 431 405 432  When the optional war parameter is set to the URL 406  When the optional war parameter is set to the URL 435 409 436  Here is an example of deploying an application using a Context 410  Here is an example of deploying an application using a Context 437 configuration ".xml" file.  411 configuration ".xml" file.  438  412 http://localhost:8080/manager/text/deploy?config=file:/path/context.xml 439 http://localhost:8080/manager/text/deploy?config=file:/path/context.xml 440  441 413 442 414 443  Here is an example of deploying an application using a Context 415  Here is an example of deploying an application using a Context 444 configuration ".xml" file and a web application ".war" file located 416 configuration ".xml" file and a web application ".war" file located 445 on the server.  417 on the server.  446  418 http://localhost:8080/manager/text/deploy 447 http://localhost:8080/manager/text/deploy 419  ?config=file:/path/context.xml&war=jar:file:/path/bar.war!/ 448  ?config=file:/path/context.xml&war=jar:file:/path/bar.war!/ 449  450 420 451 421 452  Deployment Notes  422  Deployment Notes  453 423 454  If the Host is configured with unpackWARs=true and you deploy a war 424  If the Host is configured with unpackWARs=true and you deploy a war 455 file, the war will be unpacked into a directory in your Host appBase 425 file, the war will be unpacked into a directory in your Host appBase 467 files located outside of their Host appBase.  437 files located outside of their Host appBase.  468 438 469 439 470  Deploy Response  440  Deploy Response  471 441 472  If installation and startup is successful, you will receive a response 442  If installation and startup is successful, you will receive a response 473 like this:  443 like this:  474  444 OK - Deployed application at context path /foo 475 OK - Deployed application at context path /foo 476  477 445 478  Otherwise, the response will start with FAIL and include an 446  Otherwise, the response will start with FAIL and include an 479 error message. Possible causes for problems include:  447 error message. Possible causes for problems include:  480   448   481  • Application already exists at path /foo 449  • Application already exists at path /foo 482   483  The context paths for all currently running web applications must be 450  The context paths for all currently running web applications must be 484  unique. Therefore, you must undeploy the existing web 451  unique. Therefore, you must undeploy the existing web 485  application using this context path, or choose a different context path 452  application using this context path, or choose a different context path 487  a parameter on the URL, with a value of true to avoid this 454  a parameter on the URL, with a value of true to avoid this 488  error. In that case, an undeploy will be performed on an existing 455  error. In that case, an undeploy will be performed on an existing 489  application before performing the deployment.  456  application before performing the deployment.  490  •  457   491  • Document base does not exist or is not a readable directory 458  • Document base does not exist or is not a readable directory 492   493  The URL specified by the war parameter must identify a 459  The URL specified by the war parameter must identify a 494  directory on this server that contains the "unpacked" version of a 460  directory on this server that contains the "unpacked" version of a 495  web application, or the absolute URL of a web application archive (WAR) 461  web application, or the absolute URL of a web application archive (WAR) 496  file that contains this application. Correct the value specified by 462  file that contains this application. Correct the value specified by 497  the war parameter.  463  the war parameter.  498  •  464   499  • Encountered exception 465  • Encountered exception 500   501  An exception was encountered trying to start the new web application. 466  An exception was encountered trying to start the new web application. 502  Check the Tomcat logs for the details, but likely explanations include 467  Check the Tomcat logs for the details, but likely explanations include 503  problems parsing your /WEB-INF/web.xml file, or missing 468  problems parsing your /WEB-INF/web.xml file, or missing 504  classes encountered when initializing application event listeners and 469  classes encountered when initializing application event listeners and 505  filters.  470  filters.  506  •  471   507  • Invalid application URL was specified 472  • Invalid application URL was specified 508   509  The URL for the directory or web application that you specified 473  The URL for the directory or web application that you specified 510  was not valid. Such URLs must start with file:, and URLs 474  was not valid. Such URLs must start with file:, and URLs 511  for a WAR file must end in ".war".  475  for a WAR file must end in ".war".  512  •  476   513  • Invalid context path was specified 477  • Invalid context path was specified 514   515  The context path must start with a slash character. To reference the 478  The context path must start with a slash character. To reference the 516  ROOT web application use "/".  479  ROOT web application use "/".  517  •  480   518  • Context path must match the directory or WAR file name: 481  • Context path must match the directory or WAR file name: 519   482  If the application war or directory is installed in your Host appBase 520  If the application war or directory is installed in your Host appBase 521  directory and either the Host is configured with autoDeploy=true the 483  directory and either the Host is configured with autoDeploy=true the 522  Context path must match the directory name or war file name without 484  Context path must match the directory name or war file name without 523  the ".war" extension. 485  the ".war" extension.  524  •  486   525  • Only web applications in the Host web application directory can 487  • Only web applications in the Host web application directory can 526  be installed 488  be installed 527   489   528  If the Host deployXML flag is set to false this error will happen 490  If the Host deployXML flag is set to false this error will happen 529  if an attempt is made to deploy a web application directory or 491  if an attempt is made to deploy a web application directory or 530  ".war" file outside of the Host appBase directory. 492  ".war" file outside of the Host appBase directory. 531  •  493   532   494   533 495 534  496  535 497 536  498  537 499 538  500 http://localhost:8080/manager/text/list 539 http://localhost:8080/manager/text/list 540  541 501 542  List the context paths, current status (running or 502  List the context paths, current status (running or 543 stopped), and number of active sessions for all currently 503 stopped), and number of active sessions for all currently 544 deployed web applications. A typical response immediately 504 deployed web applications. A typical response immediately 545 after starting Tomcat might look like this:  505 after starting Tomcat might look like this:  546  506 OK - Listed applications for virtual host localhost 547 OK - Listed applications for virtual host localhost 548 /webdav:running:0 507 /webdav:running:0 549 /examples:running:0 508 /examples:running:0 550 /manager:running:0 509 /manager:running:0 551 /:running:0 510 /:running:0 552  553 511 554   512   555 513 556  514  557 515 558  516 http://localhost:8080/manager/text/reload?path=/examples 559 http://localhost:8080/manager/text/reload?path=/examples 560  561 517 562  Signal an existing application to shut itself down and reload. This can 518  Signal an existing application to shut itself down and reload. This can 563 be useful when the web application context is not reloadable and you have 519 be useful when the web application context is not reloadable and you have 572   528   573 529 574  If this command succeeds, you will see a response like this:  530  If this command succeeds, you will see a response like this:  575  531 OK - Reloaded application at context path /examples 576 OK - Reloaded application at context path /examples 577  578 532 579  Otherwise, the response will start with FAIL and include an 533  Otherwise, the response will start with FAIL and include an 580 error message. Possible causes for problems include:  534 error message. Possible causes for problems include:  581   535   582  • Encountered exception 536  • Encountered exception 583   584  An exception was encountered trying to restart the web application. 537  An exception was encountered trying to restart the web application. 585  Check the Tomcat logs for the details.  538  Check the Tomcat logs for the details.  586  •  539   587  • Invalid context path was specified 540  • Invalid context path was specified 588   589  The context path must start with a slash character. To reference the 541  The context path must start with a slash character. To reference the 590  ROOT web application use "/".  542  ROOT web application use "/".  591  •  543   592  • No context exists for path /foo 544  • No context exists for path /foo 593   594  There is no deployed application on the context path 545  There is no deployed application on the context path 595  that you specified.  546  that you specified.  596  •  547   597  • No context path was specified 548  • No context path was specified 598   549   599  The path parameter is required. 550  The path parameter is required. 600  •  551   601  • Reload not supported on WAR deployed at path /foo 552  • Reload not supported on WAR deployed at path /foo 602   553   603  Currently, application reloading (to pick up changes to the classes or 554  Currently, application reloading (to pick up changes to the classes or 604  web.xml file) is not supported when a web application is 555  web.xml file) is not supported when a web application is 605  deployed directly from a WAR file. It only works when the web application 556  deployed directly from a WAR file. It only works when the web application 607  you should undeploy and then deploy or 558  you should undeploy and then deploy or 608  deploy with the update parameter the 559  deploy with the update parameter the 609  application again to pick up your changes. 560  application again to pick up your changes. 610  •  561   611   562   612 563 613   564   614 565 615  566  616 567 617  568 http://localhost:8080/manager/text/serverinfo 618 http://localhost:8080/manager/text/serverinfo 619  620 569 621  Lists information about the Tomcat version, OS, and JVM properties.  570  Lists information about the Tomcat version, OS, and JVM properties.  622 571 624 include an error message. Possible causes for problems include:  573 include an error message. Possible causes for problems include:  625   574   626  • Encountered exception 575  • Encountered exception 627   628  An exception was encountered trying to enumerate the system properties. 576  An exception was encountered trying to enumerate the system properties. 629  Check the Tomcat logs for the details.  577  Check the Tomcat logs for the details.  630  •  578   631   579   632 580 633   581   634 582 635  583  636 584 637  585 http://localhost:8080/manager/text/resources[?type=xxxxx] 638 http://localhost:8080/manager/text/resources[?type=xxxxx] 639  640 586 641  List the global JNDI resources that are available for use in resource 587  List the global JNDI resources that are available for use in resource 642 links for context configuration files. If you specify the type 588 links for context configuration files. If you specify the type 648 594 649  Depending on whether the type request parameter is specified 595  Depending on whether the type request parameter is specified 650 or not, the first line of a normal response will be:  596 or not, the first line of a normal response will be:  651   597 OK - Listed global resources of all types 652  OK - Listed global resources of all types 653   654  or  598  or  655   599 OK - Listed global resources of type xxxxx 656  OK - Listed global resources of type xxxxx 657   658  followed by one line for each resource. Each line is composed of fields 600  followed by one line for each resource. Each line is composed of fields 659 delimited by colon characters (":"), as follows:  601 delimited by colon characters (":"), as follows:  660   602   669 include an error message. Possible causes for problems include:  611 include an error message. Possible causes for problems include:  670   612   671  • Encountered exception 613  • Encountered exception 672   673  An exception was encountered trying to enumerate the global JNDI 614  An exception was encountered trying to enumerate the global JNDI 674  resources. Check the Tomcat logs for the details.  615  resources. Check the Tomcat logs for the details.  675  •  616   676  • No global JNDI resources are available 617  • No global JNDI resources are available 677   678  The Tomcat server you are running has been configured without 618  The Tomcat server you are running has been configured without 679  global JNDI resources.  619  global JNDI resources.  680  •  620   681   621   682 622 683 623 685 625 686  626  687 627 688  628 http://localhost:8080/manager/text/sessions?path=/examples 689 http://localhost:8080/manager/text/sessions?path=/examples 690  691 629 692  Display the default session timeout for a web application, and the 630  Display the default session timeout for a web application, and the 693 number of currently active sessions that fall within ten-minute ranges of 631 number of currently active sessions that fall within ten-minute ranges of 694 their actual timeout times. For example, after restarting Tomcat and then 632 their actual timeout times. For example, after restarting Tomcat and then 695 executing one of the JSP samples in the /examples web app, 633 executing one of the JSP samples in the /examples web app, 696 you might get something like this:  634 you might get something like this:  697  635 OK - Session information for application at context path /examples 698 OK - Session information for application at context path /examples 699 Default maximum session inactive interval 30 minutes 636 Default maximum session inactive interval 30 minutes 700 30 - <40 minutes:1 sessions 637 30 - <40 minutes:1 sessions 701  702 638 703   639   704 640 705 641 706  642  707 643 708  644 http://localhost:8080/manager/text/start?path=/examples 709 http://localhost:8080/manager/text/start?path=/examples 710  711 645 712  Signal a stopped application to restart, and make itself available again. 646  Signal a stopped application to restart, and make itself available again. 713 Stopping and starting is useful, for example, if the database required by 647 Stopping and starting is useful, for example, if the database required by 716 users continuously encounter database exceptions.  650 users continuously encounter database exceptions.  717 651 718  If this command succeeds, you will see a response like this:  652  If this command succeeds, you will see a response like this:  719  653 OK - Started application at context path /examples 720 OK - Started application at context path /examples 721  722 654 723  Otherwise, the response will start with FAIL and include an 655  Otherwise, the response will start with FAIL and include an 724 error message. Possible causes for problems include:  656 error message. Possible causes for problems include:  725   657   726  • Encountered exception 658  • Encountered exception 727   728  An exception was encountered trying to start the web application. 659  An exception was encountered trying to start the web application. 729  Check the Tomcat logs for the details.  660  Check the Tomcat logs for the details.  730  •  661   731  • Invalid context path was specified 662  • Invalid context path was specified 732   733  The context path must start with a slash character. To reference the 663  The context path must start with a slash character. To reference the 734  ROOT web application use "/".  664  ROOT web application use "/".  735  •  665   736  • No context exists for path /foo 666  • No context exists for path /foo 737   738  There is no deployed application on the context path 667  There is no deployed application on the context path 739  that you specified.  668  that you specified.  740  •  669   741  • No context path was specified 670  • No context path was specified 742   671   743  The path parameter is required. 672  The path parameter is required. 744  •  673   745   674   746 675 747   676   748 677 749  678  750 679 751  680 http://localhost:8080/manager/text/stop?path=/examples 752 http://localhost:8080/manager/text/stop?path=/examples 753  754 681 755  Signal an existing application to make itself unavailable, but leave it 682  Signal an existing application to make itself unavailable, but leave it 756 deployed. Any request that comes in while an application is 683 deployed. Any request that comes in while an application is 758 "stopped" on a list applications command.  685 "stopped" on a list applications command.  759 686 760  If this command succeeds, you will see a response like this:  687  If this command succeeds, you will see a response like this:  761  688 OK - Stopped application at context path /examples 762 OK - Stopped application at context path /examples 763  764 689 765  Otherwise, the response will start with FAIL and include an 690  Otherwise, the response will start with FAIL and include an 766 error message. Possible causes for problems include:  691 error message. Possible causes for problems include:  767   692   768  • Encountered exception 693  • Encountered exception 769   770  An exception was encountered trying to stop the web application. 694  An exception was encountered trying to stop the web application. 771  Check the Tomcat logs for the details.  695  Check the Tomcat logs for the details.  772  •  696   773  • Invalid context path was specified 697  • Invalid context path was specified 774   775  The context path must start with a slash character. To reference the 698  The context path must start with a slash character. To reference the 776  ROOT web application use "/".  699  ROOT web application use "/".  777  •  700   778  • No context exists for path /foo 701  • No context exists for path /foo 779   780  There is no deployed application on the context path 702  There is no deployed application on the context path 781  that you specified.  703  that you specified.  782  •  704   783  • No context path was specified 705  • No context path was specified 784   785  The path parameter is required. 706  The path parameter is required. 786  •  707   787   708   788 709 789   710   791 712 792  713  793 714 794  715 http://localhost:8080/manager/text/undeploy?path=/examples 795 http://localhost:8080/manager/text/undeploy?path=/examples 796  797 716 798  WARNING - This command will delete any web 717  WARNING - This command will delete any web 799 application artifacts that exist within appBase directory 718 application artifacts that exist within appBase directory 800 (typically "webapps") for this virtual host. 719 (typically "webapps") for this virtual host. 801 This will delete the the application .WAR, if present, 720 This will delete the the application .WAR, if present, 813 /deploy command.  732 /deploy command.  814 733 815  If this command succeeds, you will see a response like this:  734  If this command succeeds, you will see a response like this:  816  735 OK - Undeployed application at context path /examples 817 OK - Undeployed application at context path /examples 818  819 736 820  Otherwise, the response will start with FAIL and include an 737  Otherwise, the response will start with FAIL and include an 821 error message. Possible causes for problems include:  738 error message. Possible causes for problems include:  822   739   823  • Encountered exception 740  • Encountered exception 824   825  An exception was encountered trying to undeploy the web application. 741  An exception was encountered trying to undeploy the web application. 826  Check the Tomcat logs for the details.  742  Check the Tomcat logs for the details.  827  •  743   828  • Invalid context path was specified 744  • Invalid context path was specified 829   830  The context path must start with a slash character. To reference the 745  The context path must start with a slash character. To reference the 831  ROOT web application use "/".  746  ROOT web application use "/".  832  •  747   833  • No context exists for path /foo 748  • No context exists for path /foo 834   835  There is no deployed application on the context path 749  There is no deployed application on the context path 836  that you specified.  750  that you specified.  837  •  751   838  • No context path was specified 752  • No context path was specified 839   840  The path parameter is required. 753  The path parameter is required. 841  •  754   842   755   843 756 844   757   845 758 846  759  847 760 848  761 http://localhost:8080/manager/text/findleaks[?statusLine=[true|false]] 849 http://localhost:8080/manager/text/findleaks[?statusLine=[true|false]] 850  851 762 852  The find leaks diagnostic triggers a full garbage collection. It 763  The find leaks diagnostic triggers a full garbage collection. It 853 should be used with extreme caution on production systems.  764 should be used with extreme caution on production systems.  866 GC, you will need to check using tools like GC logging, JConsole or similar.  777 GC, you will need to check using tools like GC logging, JConsole or similar.  867 778 868  If this command succeeds, you will see a response like this:  779  If this command succeeds, you will see a response like this:  869  780 /leaking-webapp 870 /leaking-webapp 871  872 781 873  If you wish to see a status line included in the response then include the 782  If you wish to see a status line included in the response then include the 874 statusLine query parameter in the request with a value of 783 statusLine query parameter in the request with a value of 886 795 887  796  888 797 889  798 http://localhost:8080/manager/text/sslConnectorCiphers 890 http://localhost:8080/manager/text/sslConnectorCiphers 891  892 799 893  The SSL Connector/Ciphers diagnostic lists the SSL ciphers that are currently 800  The SSL Connector/Ciphers diagnostic lists the SSL ciphers that are currently 894 configured for each connector. For BIO and NIO, the names of the individual 801 configured for each connector. For BIO and NIO, the names of the individual 895 cipher suites are listed. For APR, the value of SSLCipherSuite is returned.  802 cipher suites are listed. For APR, the value of SSLCipherSuite is returned.  896 803 897  The response will ook something like this:  804  The response will ook something like this:  898  805 OK - Connector / SSL Cipher information 899 OK - Connector / SSL Cipher information 900 Connector[HTTP/1.1-8080] 806 Connector[HTTP/1.1-8080] 901  SSL is not enabled for this connector 807  SSL is not enabled for this connector 902 Connector[HTTP/1.1-8443] 808 Connector[HTTP/1.1-8443] 904  TLS_DHE_RSA_WITH_AES_128_CBC_SHA 810  TLS_DHE_RSA_WITH_AES_128_CBC_SHA 905  TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 811  TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 906  TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 812  TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 907  ... 813  ... 908  909 814 910   815   911 816 982 <taskdef> element. Therefore, your build.xml 887 <taskdef> element. Therefore, your build.xml 983 file might look something like this:  888 file might look something like this:  984 889 985  890  986   987 <project name="My Application" default="compile" basedir="."> 988 891 989  <!-- Configure the directory into which the web application is built --> 892   990  <property name="build" value="${basedir}/build"/>                                       893                          
991                                                                                                                                                                       894
992                                                            <!-- Configure the context path for this application -->                                   895                          
993                                                            <property name="path"     value="/myapp"/>                                                 896                          
994                                                                                                                                                                       897
995                                                            <!-- Configure properties to access the Manager application -->                            898                          
996                                                            <property name="url"      value="http://localhost:8080/manager/text"/>                     899                          
997                                                            <property name="username" value="myusername"/>                                             900                          
998                                                            <property name="password" value="mypassword"/>                                             901                          
999                                                                                                                                                                       902
1000                                                           <!-- Configure the custom Ant tasks for the Manager application -->                        903                          
1001                                                           <taskdef name="deploy"    classname="org.apache.catalina.ant.DeployTask"/>                 904                          
1002                                                           <taskdef name="list"      classname="org.apache.catalina.ant.ListTask"/>                   905                          
1003                                                           <taskdef name="reload"    classname="org.apache.catalina.ant.ReloadTask"/>                 906                          
1004                                                           <taskdef name="findleaks" classname="org.apache.catalina.ant.FindLeaksTask"/>              907                          
1005                                                           <taskdef name="resources" classname="org.apache.catalina.ant.ResourcesTask"/>              908                          
1006                                                           <taskdef name="start"     classname="org.apache.catalina.ant.StartTask"/>                  909                          
1007                                                           <taskdef name="stop"      classname="org.apache.catalina.ant.StopTask"/>                   910                          
1008                                                           <taskdef name="undeploy"  classname="org.apache.catalina.ant.UndeployTask"/>               911                          
1009                                                                                                                                                                      912
1010                                                           <!-- Executable Targets -->                                                                913                          
1011                                                           <target name="compile" description="Compile web application">                              914                          
1012                                                             <!-- ... construct web application in ${build} subdirectory, and 915   1014  </target> 917   1015 918 1016  <target name="deploy" description="Install web application" 919   1018  <deploy url="${url}" username="${username}" password="${password}"                          921                          
1020                                                           </target>                                                                                  923                          
1021                                                                                                                                                                      924
1022                                                           <target name="reload" description="Reload web application"                                    925                          
1024                                                             <reload  url="${url}" username="${username}" password="${password}" 927   1026  </target> 929   1027 930 1028  <target name="undeploy" description="Remove web application"> 931   1029  <undeploy url="${url}" username="${username}" password="${password}"                        932                          
1031                                                           </target>                                                                                  934                          
1032                                                                                                                                                                      935
1033                                                         </project>                                                                                   936                          ]]>
1034                                                         
1035  1036 937 1037 

Note: The definition of the resources task above will override the resources 938 

Note: The definition of the resources task above will override the resources 1038 datatype added in Ant 1.7. If you wish to use the resources datatype you will 939 datatype added in Ant 1.7. If you wish to use the resources datatype you will 1047 consider it a security risk to include the real manager password in your 948 consider it a security risk to include the real manager password in your 1048 build.xml file's source code. To avoid this, omit the password 949 build.xml file's source code. To avoid this, omit the password 1049 property, and specify it from the command line:

950 property, and specify it from the command line:

1050 
951                          ant -Dpassword=secret deploy
1051                                                           ant -Dpassword=secret deploy
1052                                                         
1053 952 1054  953  1055 954 1059 <redirector> type attributes: 958 <redirector> type attributes: 1060 

959 

1061 960 1062  961  1063 
AttributeAttributeDescriptionDescriptionRequiredRequired
outputoutputName of a file to which to write the output. If 969 Name of a file to which to write the output. If 1072 the error stream is not also redirected to a file or property, it will 970 the error stream is not also redirected to a file or property, it will 1073 appear in this output.NoNo
errorerrorThe file to which the standard error of the 976 The file to which the standard error of the 1079 command should be redirected.NoNo
logErrorlogErrorThis attribute is used when you wish to see 982 This attribute is used when you wish to see 1085 error output in Ant's log and you are redirecting output to a 983 error output in Ant's log and you are redirecting output to a 1086 file/property. The error output will not be included in the output 984 file/property. The error output will not be included in the output 1087 file/property. If you redirect error with the error or errorProperty 985 file/property. If you redirect error with the error or errorProperty 1088 attributes, this will have no effect.NoNo
appendappendWhether output and error files should be 991 Whether output and error files should be 1094 appended to or overwritten. Defaults to false.NoNo
createemptyfilescreateemptyfilesWhether output and error files should be created 997 Whether output and error files should be created 1100 even when empty. Defaults to true.NoNo
outputpropertyoutputpropertyThe name of a property in which the output of 1003 The name of a property in which the output of 1106 the command should be stored. Unless the error stream is redirected to 1004 the command should be stored. Unless the error stream is redirected to 1107 a separate file or stream, this property will include the error output.NoNo
errorpropertyerrorpropertyThe name of a property in which the standard 1010 The name of a property in which the standard 1113 error of the command should be stored.NoNo
1064  962  1065  963  1066  964  1067  965  1068  966  1069  967  1070  968  1071  971 appear in this output. 1074  972  1075  973  1076  974  1077  975  1078  977 command should be redirected. 1080  978  1081  979  1082  980  1083  981  1084  986 attributes, this will have no effect. 1089  987  1090  988  1091  989  1092  990  1093  992 appended to or overwritten. Defaults to false. 1095  993  1096  994  1097  995  1098  996  1099  998 even when empty. Defaults to true. 1101  999  1102  1000  1103  1001  1104  1002  1105  1005 a separate file or stream, this property will include the error output. 1108  1006  1109  1007  1110  1008  1111  1009  1112  1011 error of the command should be stored. 1114  1012  1115  1013  1116  1117  1014  1118 1015 1119 

A couple of additional attributes can also be specified: 1016 

A couple of additional attributes can also be specified: 1120 

1017 

1121  1018  1122 
AttributeAttributeDescriptionDescriptionRequiredRequired
alwaysLogalwaysLogThis attribute is used when you wish to see the 1026 This attribute is used when you wish to see the 1131 output you are capturing, appearing also in the Ant's log. It must not be 1027 output you are capturing, appearing also in the Ant's log. It must not be 1132 used unless you are capturing task output. 1028 used unless you are capturing task output. 1133 Defaults to false. 1029 Defaults to false. 1134 This attribute will be supported directly by <redirector> 1030 This attribute will be supported directly by <redirector> 1135 in Ant 1.6.3NoNo
failonerrorfailonerrorThis attribute is used when you wish to avoid that 1036 This attribute is used when you wish to avoid that 1141 any manager command processing error terminates the ant execution. Defaults to true. 1037 any manager command processing error terminates the ant execution. Defaults to true. 1142 It must be set to false, if you want to capture error output, 1038 It must be set to false, if you want to capture error output, 1143 otherwise execution will terminate before anything can be captured. 1039 otherwise execution will terminate before anything can be captured. 1144 

1040 
1145 This attribute acts only on manager command execution, 1041 This attribute acts only on manager command execution, 1146 any wrong or missing command attribute will still cause Ant execution termination. 1042 any wrong or missing command attribute will still cause Ant execution termination. 1147 
NoNo
1123  1019  1124  1020  1125  1021  1126  1022  1127  1023  1128  1024  1129  1025  1130  1031 in Ant 1.6.3 1136  1032  1137  1033  1138  1034  1139  1035  1140  1043  1148  1044  1149  1045  1150  1151  1046  1152 1047 1153 

They also support the embedded <redirector> element 1048 

They also support the embedded <redirector> element 1164 can be used: 1059 can be used: 1165 

1060 

1166 1061 1167  1062 

1169                                                             <target name="manager.deploy"
1170                                                                 depends="context.status"                                                                   1063                                 depends="context.status"
1171                                                                 if="context.notInstalled">                                                              1064                                 if="context.notInstalled">
1172                                                                 <deploy url="${mgr.url}" 1065   1177  </target> 1070   1178 1071 1179  <target name="manager.deploy.war" 1072   1182  <deploy url="${mgr.url}"                                                                1075                         
1188                                                             </target>                                                                                1081                         
1189                                                                                                                                                                      1082
1190                                                             <target name="context.status">                                                           1083                         
1191                                                                 <property name="running" value="${mgr.context.path}:running"/> 1084   1192  <property name="stopped" value="${mgr.context.path}:stopped"/>                       1085                         
1193                                                                                                                                                                      1086
1194                                                                 <list url="${mgr.url}" 1087   1198  </list> 1091   1199 1092 1200  <condition property="context.running"> 1093   1201  <contains string="${ctx.status}" substring="${running}"/> 1094   1202  </condition> 1095   1203  <condition property="context.stopped"> 1096   1204  <contains string="${ctx.status}" substring="${stopped}"/> 1097   1205  </condition> 1098   1206  <condition property="context.notInstalled"> 1099   1207  <and> 1100   1208  <isfalse value="${context.running}"/>                                        1101                         
1209                                                                         <isfalse value="${context.stopped}"/> 1102   1210  </and> 1103   1211  </condition> 1104   1212  <condition property="context.deployable"> 1105   1213  <or> 1106   1214  <istrue value="${context.notInstalled}"/>                                    1107                         
1215                                                                         <and>                                                                        1108                         
1216                                                                             <istrue value="${context.running}"/> 1109   1217  <istrue value="${mgr.update}"/>                                          1110                         
1218                                                                         </and>                                                                       1111                         
1219                                                                         <and>                                                                        1112                         
1220                                                                             <istrue value="${context.stopped}"/> 1113   1221  <istrue value="${mgr.update}"/>                                          1114                         
1222                                                                         </and>                                                                       1115                         
1223                                                                     </or>                                                                            1116                         
1224                                                                 </condition>                                                                         1117                         
1225                                                                 <condition property="context.undeployable">                                          1118                         
1226                                                                     <or>                                                                             1119                         
1227                                                                         <istrue value="${context.running}"/> 1120   1228  <istrue value="${context.stopped}"/>                                         1121                         
1229                                                                     </or>                                                                            1122                         
1230                                                                 </condition>                                                                         1123                         
1231                                                             </target>                                                                                1124                             ]]>
1232                                                         
1233  1234 1125 1235 

WARNING: even if it doesn't make many sense, and is always a bad idea, 1126 

WARNING: even if it doesn't make many sense, and is always a bad idea, 1236 calling a Catalina task more than once, 1127 calling a Catalina task more than once, 1265   1156   1266 1157 1267   1158   1268  This takes the form: 1159 

This takes the form:

1269  1160 http://webserver/manager/jmxproxy/?qry=STUFF 1270 http://webserver/manager/jmxproxy/?qry=STUFF 1161 

Where STUFF is the JMX query you wish to perform. For example, 1271  1162  here are some queries you might wish to run:

1272  Where STUFF is the JMX query you wish to perform. For example, 1273  here are some queries you might wish to run: 1274 
1163 
1275 
•  1164 
•  1276  qry=*%3Atype%3DRequestProcessor%2C* --> 1165  qry=*%3Atype%3DRequestProcessor%2C* --> 1288  which look for a specific MBean by the given name. 1177  which look for a specific MBean by the given name. 1289 
•  1178   1290 
1179 
1180 

1291  You'll need to experiment with this to really understand its capabilites. 1181  You'll need to experiment with this to really understand its capabilites. 1292  If you provide no qry parameter, then all of the MBeans will 1182  If you provide no qry parameter, then all of the MBeans will 1293  be displayed. We really recommend looking at the tomcat source code and 1183  be displayed. We really recommend looking at the tomcat source code and 1294  understand the JMX spec to get a better understanding of all the queries 1184  understand the JMX spec to get a better understanding of all the queries 1295  you may run. 1185  you may run. 1186 

1296   1187   1297 1188 1298   1189   1190 

1299  The JXMProxyServlet also supports a "get" command that you can use to 1191  The JXMProxyServlet also supports a "get" command that you can use to 1300  fetch the value of a specific MBean's attribute. The general form of 1192  fetch the value of a specific MBean's attribute. The general form of 1301  the get command is: 1193  the get command is: 1194 

1302 1195 1303  1196 http://webserver/manager/jmxproxy/?get=BEANNAME&att=MYATTRIBUTE&key=MYKEY 1304 http://webserver/manager/jmxproxy/?get=BEANNAME&att=MYATTRIBUTE&key=MYKEY 1305  1306 1197 1307  You must provide the following parameters: 1198 

You must provide the following parameters:

1308 
1199 
1309 
1. get: The full bean name
2.  1200 
3. get: The full bean name
4.  1310 
5. att: The attribute you wish to fetch
6.  1201 
7. att: The attribute you wish to fetch
8.  1311 
9. key: (optional) The key into a CompositeData MBean attribute
10.  1202 
11. key: (optional) The key into a CompositeData MBean attribute
12.  1312 
1203 
1313 1204 

1314  If all goes well, then it will say OK, otherwise an error message will 1205  If all goes well, then it will say OK, otherwise an error message will 1315  be shown. For example, let's say we wish to fetch the current heap memory 1206  be shown. For example, let's say we wish to fetch the current heap memory 1316  data: 1207  data: 1208 

1317 1209 1318  1210 http://webserver/manager/jmxproxy/?get=java.lang:type=Memory&att=HeapMemoryUsage 1319 http://webserver/manager/jmxproxy/?get=java.lang:type=Memory&att=HeapMemoryUsage 1320  1321 1211 1322  Or, if you only want the "used" key: 1212 

Or, if you only want the "used" key:

1323 1213 1324  1214 http://webserver/manager/jmxproxy/ 1325 http://webserver/manager/jmxproxy/ 1215  ?get=java.lang:type=Memory&att=HeapMemoryUsage&key=used 1326  ?get=java.lang:type=Memory&att=HeapMemoryUsage&key=used 1327  1328 
1216 
1329 1217 1330   1218   1219 

1331  Now that you can query an MBean, its time to muck with Tomcat's internals! 1220  Now that you can query an MBean, its time to muck with Tomcat's internals! 1332  The general form of the set command is : 1221  The general form of the set command is : 1333  1222 

1334 http://webserver/manager/jmxproxy/?set=BEANNAME&att=MYATTRIBUTE&val=NEWVALUE 1223 http://webserver/manager/jmxproxy/?set=BEANNAME&att=MYATTRIBUTE&val=NEWVALUE 1335  1224 

So you need to provide 3 request parameters:

1336  So you need to provide 3 request parameters: 1337 
1225 
1338 
1. set: The full bean name
2.  1226 
3. set: The full bean name
4.  1339 
5. att: The attribute you wish to alter
6.  1227 
7. att: The attribute you wish to alter
8.  1340 
9. val: The new value
10.  1228 
11. val: The new value
12.  1341 
1229 
1230 

1342  If all goes ok, then it will say OK, otherwise an error message will be 1231  If all goes ok, then it will say OK, otherwise an error message will be 1343  shown. For example, lets say we wish to turn up debugging on the fly for the 1232  shown. For example, lets say we wish to turn up debugging on the fly for the 1344  ErrorReportValve. The following will set debugging to 10. 1233  ErrorReportValve. The following will set debugging to 10. 1345  1234 

1346 http://localhost:8080/manager/jmxproxy/ 1235 http://localhost:8080/manager/jmxproxy/ 1347  ?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost 1236  ?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost 1348  &att=debug&val=10 1237  &att=debug&val=10 1349  1238 

and my result is (YMMV):

1350  and my result is (YMMV): 1239 Result: ok 1351  1352 Result: ok 1353  1354 1240 1355  Here is what I see if I pass in a bad value. Here is the URL I used, 1241 

Here is what I see if I pass in a bad value. Here is the URL I used, 1356  I try set debugging equal to 'cow': 1242  I try set debugging equal to 'cow':

1357  1243 http://localhost:8080/manager/jmxproxy/ 1358 http://localhost:8080/manager/jmxproxy/ 1359  ?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost 1244  ?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost 1360  &att=debug&val=cow 1245  &att=debug&val=cow 1361  1246 

When I try that, my result is

1362  When I try that, my result is 1247 Error: java.lang.NumberFormatException: For input string: "cow" 1363  1364 Error: java.lang.NumberFormatException: For input string: "cow" 1365  1366 
1248 
1367 1249 1368   1250   1369 

The invoke command enables methods to be called on MBeans. The 1251 

The invoke command enables methods to be called on MBeans. The 1370  general form of the command is:

1252  general form of the command is:

1371  1253 http://webserver/manager/jmxproxy/ 1372 http://webserver/manager/jmxproxy/ 1254  ?invoke=BEANNAME&op=METHODNAME&ps=COMMASEPARATEDPARAMETERS 1373  ?invoke=BEANNAME&op=METHODNAME&ps=COMMASEPARATEDPARAMETERS 1374  1375 

For example, to call the findConnectors() method of the 1255 

For example, to call the findConnectors() method of the 1376  Service use:

1256  Service use:

1377  1257 http://localhost:8080/manager/jmxproxy/ 1378 http://localhost:8080/manager/jmxproxy/ 1258  ?invoke=Catalina%3Atype%3DService&op=findConnectors&ps= 1379  ?invoke=Catalina%3Atype%3DService&op=findConnectors&ps= 1380  1381 
1259 
1382  1260  1383 1261