Dear Wiki user, You have subscribed to a wiki page or wiki category on "Tomcat Wiki" for change notification.
The "HowTo" page has been changed by DomaLajos: http://wiki.apache.org/tomcat/HowTo?action=diff&rev1=111&rev2=112 ---- = Meta = - == How do I add a question to this page? == Anyone may edit this page to add their own content. That is why this page is part of a Wiki and not a hardcoded static file in the FAQ. However, ''do not'' add questions without answers to this page. If you have a question about how to do something in Tomcat which has not been addressed yet, ask the [[http://tomcat.apache.org/lists.html#tomcat-users|tomcat-user list]]. Once you've figured out how to fix your problem, come back and update the Wiki to allow the rest of us to benefit from what you've learned! == How do I contribute to Tomcat's documentation? == - Download the source bundle or grab the source XML file from [[http://tomcat.apache.org/svn.html|Subversion repository]]. If you are not familiar with Subversion, see http://www.apache.org/dev/contributors.html. The docs are in the webapps/docs subdirectory. They are in XML format and get processed into the HTML documentation as part of the Tomcat release. @@ -26, +24 @@ ---- = Installation = - == How do I set up and run Tomcat on Macintosh OS X? == See [[TomcatOnMacOS]] == How do I set up and run Tomcat on Solaris 10? == See TomcatOnSolaris10 - == How do I set up another tomcat service on Windows, sharing the same Tomcat Home ? == This script sets up a a tomcat base directory and calls tomcat5.exe to create a windows service which will use the tomcat home given for the binaries and tomcat base you create See TomcatCreateWindowsService @@ -48, +44 @@ . (!) It also makes a lot of sense to use the JavaServiceWrapper. - == How to run Tomcat without root privileges? == The best way is to use jsvc, available as part of the [[http://commons.apache.org/daemon/jsvc.html|commons-daemon]] project. @@ -99, +94 @@ {{{ sudo ipfw add 100 fwd 127.0.0.1,8080 tcp from any to any 80 in }}} - - ---- + Yet another way is to use authbind (part of Debian- and CentOS based distributions) which allows a program that would normally require superuser privileges to access privileged network services to run as a non-privileged user. The article at http://java-notes.com/index.php/installing-tomcat-with-http-port-80-on-linux discusses how to install and configure the authbind package with Tomcat 6.0 on Linux. + = Configuration = - == How do I set up multiple sites sharing the same war application/war file? == See CreateVirtualHosts @@ -256, +250 @@ 1. Now when you visit ''http://localhost:8080/admin'' you should see a page that asks for a user name and password. If you still see the "no longer loaded" error message in your browser, you must either force a full reload of the web page (in Firefox, hold down Shift key while clicking on the Reload button) or just restart your browser completely. - == How do I add JARs or classes to the common classloader without adding them to $CATALINA_HOME/lib? == - Either a) Run Tomcat with separate {{{$CATALINA_BASE}}} and {{{$CATALINA_HOME}}} (as documented in {{{RUNNING.txt}}}) and place those classes into {{{$CATALINA_BASE/lib}}}, or @@ -332, +324 @@ == How do I set up Tomcat virtual hosts in a development environment? == See TomcatDevelopmentVirtualHosts - ---- = Programming = - == How do call tomcat ant tasks to deploy webapps? == See AntDeploy @@ -385, +375 @@ p.load(is); is.close(); }}} - == How do I share sessions across web apps? == You cannot share sessions directly across web apps, as that would be a violation of the Servlet Specification. There are workarounds, including using a singleton class loaded from the common classloader repository to hold shared information, or putting some of this shared information in a database or another data store. Some of these approaches have been discussed on the [[http://tomcat.apache.org/lists.html#tomcat-users|tomcat-user mailing list]], whose archives you should search for more information. @@ -460, +449 @@ Context context = (Context) host.findChild("myContext"); Realm realm = context.getRealm(); }}} - == How do I redirect System.out and System.err to my web page? == I have met a situation where I needed to redirect a portion of standard ouput (`System.out`, STDOUT) and standard error (`System.err`, STDERR) to my web page instead of a log file. An example of such an application is a compiler research platform that our resarch team is putting online for anybody to be able to quickly compile-test their programs on line. Naturally, the compilers dump some of their stuff to STDERR or STDOUT and they are not web application `.jar`. Thus, I needed badly these streams related to the compiler output to be redirected to my web editor interface. Having found no easy instructions on how to do that lead me writing up this quick HOWTO. The HOWTO is based on Servlets, but similar arrangements can be done for JSPs. The below example shows the essentials, with most non-essentials removed. @@ -624, +612 @@ ---- = Troubleshooting = - == Tomcat crashed! What do I do now? == These steps are in no particular order ... @@ -641, +628 @@ 1. Using a database? Make sure JDBC type 4 drivers are used. Check their release notes. 1. Tweak JVM memory parameters. Setting memory too high can be as bad as having memory too low. If your memory settings are set too high, Java 1.3 JVMs may freeze while waiting for the entire garbage collection to finish. Also if the JVM has too much memory, if may be starving other resources on the machine which are needed which may be causing unforeseen exceptions. In a nutshell, throwing more memory doesn't always solve the problem! 1. Turn off the Java JIT compiler. See the Java Docs on how to do this. - == I'm encountering classloader problems when using JNI under Tomcat == The important thing to know about using JNI under Tomcat is that one cannot place the native libraries OR their JNI interfaces under the WEB-INF/lib or WEB-INF/classes directories of a web application and expect to be able to reload the webapp without restarting the server. The class that calls System.loadLibrary(String) must be loaded by a classloader that is not affected by reloading the web application itself. @@ -886, +872 @@ } } }}} - == How do I obtain a thread dump of my running webapp ? == You can only get a thread dump of the entire JVM, not just your webapp. This shouldn't be a big deal, but should be made clear: you are getting a dump of all JVM threads, not just those "for your application", whatever that means. @@ -911, +896 @@ This will produce a thread dump on standard output, but may not be possible to capture to a file. - == How do I add my own custom MBean to monitor my application within Tomcat 5/6? == - - First of all, you can read [[http://oss.wxnet.org/mbeans.html|this great tutorial]] from Christopher Blunck (ch...@wxnet.org). + First of all, you can read [[http://oss.wxnet.org/mbeans.html|this great tutorial]] from Christopher Blunck ( ch...@wxnet.org ). I will just add my comments and improvements. - I will just add my comments and improvements. + 1. Start your Tomcat and check that you have access to http://localhost:8080/manager/jmxproxy/. It means that JMX is enabled on your Tomcat configuration (if not, check if the following line is in your /conf/server.xml file : ''<Listener className="org.apache.catalina.mbeans.ServerLifecycleListener" />''. Otherwise, check the Tomcat documentation to activate it). Let this page opened to check further if your custom Mbean is detected by Tomcat.<<BR>> - 1. Start your Tomcat and check that you have access to [[http://localhost:8080/manager/jmxproxy/]]. It means that JMX is enabled on your Tomcat configuration (if not, check if the following line is in your /conf/server.xml file : - ''<Listener className="org.apache.catalina.mbeans.ServerLifecycleListener" />''. Otherwise, check the Tomcat documentation to activate it). - Let this page opened to check further if your custom Mbean is detected by Tomcat.<<BR>> - 2. Build your custom MBean by following the Christopher Blunck's example : <<BR>> + 2. Build your custom MBean by following the Christopher Blunck's example : <<BR>> '''ServerMBean.java''' : - '''ServerMBean.java''' : + {{{ package org.wxnet.mbeans; @@ -931, +911 @@ public long getUptime(); } }}} - '''Server.java''' : + '''Server.java''' : + {{{ package org.wxnet.mbeans; @@ -973, +954 @@ System.out.println("Found our MBean server"); } else { mbserver = MBeanServerFactory.createMBeanServer(); - } + } return mbserver; } @@ -984, +965 @@ public long getUptime() { return System.currentTimeMills() - _startTime; } } }}} + In this implementation, firstly notice the ''ObjectName'' representing the MBean (in the constructor) : ''name = new ObjectName("'''Application''':Name='''Server''',Type='''Server'''");'' Do not hesitate to change the domain name (the first parameter) by your own to easily find your MBean reference in the http://localhost:8080/manager/jmxproxy page.<<BR>> Secondly, take a look at your MBean constructor : <<BR>> - In this implementation, firstly notice the ''ObjectName'' representing the MBean (in the constructor) : ''name = new ObjectName("'''Application''':Name='''Server''',Type='''Server'''");'' - Do not hesitate to change the domain name (the first parameter) by your own to easily find your MBean reference in the [[http://localhost:8080/manager/jmxproxy]] page.<<BR>> - Secondly, take a look at your MBean constructor : <<BR>> - a. First step is to get a reference to the Tomcat's MBeanServer with ''MBeanServer server = getServer();''.<<BR>> - b. The ''getServer()'' method returns the default Tomcat's MBean server.<<BR>> - A good question right now could be : what happens if I decide to create my own MBeanServer? The answer is very simple : '''nothing'''.<<BR>> - After many research in the (empty) Tomcat's documentation and on the internet, after many tests, I conclued that you can't create your custom MBean server. More precisely, you can create it but Tomcat won't keep any reference to it.<<BR>> - You can replace the previous ''getServer()'' method by this one to test: {{{ + a. First step is to get a reference to the Tomcat's MBeanServer with ''MBeanServer server = getServer();''.<<BR>> b. The ''getServer()'' method returns the default Tomcat's MBean server.<<BR>> + + A good question right now could be : what happens if I decide to create my own MBeanServer? The answer is very simple : '''nothing'''.<<BR>> After many research in the (empty) Tomcat's documentation and on the internet, after many tests, I conclued that you can't create your custom MBean server. More precisely, you can create it but Tomcat won't keep any reference to it.<<BR>> You can replace the previous ''getServer()'' method by this one to test: + + {{{ private MBeanServer getServer() { MBeanServer mbserver = null; MBeanServer myMBServer = MBeanServerFactory.createMBeanServer("myMBServer"); - + ArrayList<MBeanServer> mbservers = MBeanServerFactory.findMBeanServer(null); System.out.println("****** TOMCAT'S LIST OF REGISTERED MBEANSERVERS ********** "); System.out.println(mbservers.toString()); - + System.out.println("****** TRYING TO RETRIEVE MY OWN MBEANSERVER FROM ITS AgentId ********** "); ArrayList<MBeanServer> mbservers_2 = MBeanServerFactory.findMBeanServer("myMBServer"); System.out.println(mbservers_2.toString()); - - + + if (mbservers.size() > 0) { mbserver = (MBeanServer) mbservers.get(0); } @@ -1020, +999 @@ return mbserver; } }}} + Here is a capture of the println() : https://picasaweb.google.com/lh/photo/jzVX9-NBGwF57A0m8qqv2Q?feat=directlink. Tomcat seems to register 2 Mbean server but when I try to fetch mine from its AgentId (here "myMBServer"), nothing is found. In my opinion, Tomcat might re-implement the ''MBeanServerFactory'' java class to control the server creation. Then, it doesn't keep a reference to the newly created MBean server. Moreover, if Tomcat re-implement the MBeanFactory class, there is no method to directly add MBean (see the http://tomcat.apache.org/tomcat-6.0-doc/api/index.html).<<BR>> - Here is a capture of the println() : [[https://picasaweb.google.com/lh/photo/jzVX9-NBGwF57A0m8qqv2Q?feat=directlink]]. - Tomcat seems to register 2 Mbean server but when I try to fetch mine from its AgentId (here "myMBServer"), nothing is found. - In my opinion, Tomcat might re-implement the ''MBeanServerFactory'' java class to control the server creation. Then, it doesn't keep a reference to the newly created MBean server. Moreover, if Tomcat re-implement the MBeanFactory class, there is no method to directly add MBean (see the [[http://tomcat.apache.org/tomcat-6.0-doc/api/index.html||Tomcat's javadoc]]).<<BR>> - In my application architecture, I placed the 2 MBeans files (the interface and its implementation) in a particular package (I don't think its compulsary but definitely more aesthetic). + In my application architecture, I placed the 2 MBeans files (the interface and its implementation) in a particular package (I don't think its compulsary but definitely more aesthetic). Compile those one in a jar archive and place it in the Tomcat's library folder (/lib).<<BR>> - Compile those one in a jar archive and place it in the Tomcat's library folder (/lib).<<BR>> - 3. Build your '''ContextListener''' : According to the [[[[http://tomcat.apache.org/tomcat-6.0-doc/config/listeners.html|Tomcat's documentation]], a Listener is a ''a component that performs actions when specific events occur, usually Tomcat '''starting''' or Tomcat stopping.''. + 3. Build your '''ContextListener''' : According to the [[[[http://tomcat.apache.org/tomcat-6.0-doc/config/listeners.html|Tomcat's documentation]], a Listener is a ''a component that performs actions when specific events occur, usually Tomcat '''starting''' or Tomcat stopping.''. We need to instantiate and load our MBean at Tomcat's start. So we build a ContextListener.java file which is placed wherever you want in your project architecture : - We need to instantiate and load our MBean at Tomcat's start. So we build a ContextListener.java file which is placed wherever you want in your project architecture : + {{{ package '''org.bonitasoft.context'''; @@ -1053, +1029 @@ } }}} - Take a look especially at the contextInitialized method. It just instantiates our custom MBean. Don't forget that the MBean register itself in the Tomcat's MBeanServer in its constructor. + Take a look especially at the contextInitialized method. It just instantiates our custom MBean. Don't forget that the MBean register itself in the Tomcat's MBeanServer in its constructor. DO NOT FORGET to change the ''package'' line according to your application architecture. - DO NOT FORGET to change the ''package'' line according to your application architecture. Then, you have to modify your WEB-INF/web.xml file to make Tomcat execute your ContextListener. + {{{ <?xml version="1.0" encoding="ISO-8859-1"?> @@ -1074, +1050 @@ }}} In his tutorial, Christopher Blunck suggests to compile the ContextListener.java file in a jar archive and then place it into our WEB-INF/lib folder. In my own experiments, I never found any difference without doing this.<<BR>> - 4. The '''''mbeans-descriptor.xml''''' file : The only entry in the Tomcat documentation about custom MBean is about this file. It says "''You may also add MBean descriptions for custom components in a mbeans-descriptor.xml file, located in the same package as the class files it describes.''". Unfortunately, instead of reading this file, Tomcat applied its own templates to replace my MBeans attributes and operations descriptions... + 4. The '''''mbeans-descriptor.xml''''' file : The only entry in the Tomcat documentation about custom MBean is about this file. It says "''You may also add MBean descriptions for custom components in a mbeans-descriptor.xml file, located in the same package as the class files it describes.''". Unfortunately, instead of reading this file, Tomcat applied its own templates to replace my MBeans attributes and operations descriptions... I really didn't figure out what is the correct way of using and placing this file. So I don't use it. - I really didn't figure out what is the correct way of using and placing this file. So I don't use it. - 5. The configuration should be over. You should have done those operations : + 5. The configuration should be over. You should have done those operations : - a. Build your MBean,<<BR>> - b. Compile it and place the .jar archive in the Tomcat's /lib folder,<<BR>> - c. Build your ContextListener.java,<<BR>> - d. Add a reference to your ContextListener inside your WEB-INF/web.xml file,<<BR>> + a. Build your MBean,<<BR>> b. Compile it and place the .jar archive in the Tomcat's /lib folder,<<BR>> c. Build your ContextListener.java,<<BR>> d. Add a reference to your ContextListener inside your WEB-INF/web.xml file,<<BR>> + - You can try to run your project. Open the [[http://localhost:8080/manager/jmxproxy]] page and find your custom MBean (with a simple ctrl+f). You can see its domain, name, type and its attributes and methods.<<BR>>You can now use this MBean in your application by getting a reference to the Tomcat's MBean server : + You can try to run your project. Open the http://localhost:8080/manager/jmxproxy page and find your custom MBean (with a simple ctrl+f). You can see its domain, name, type and its attributes and methods.<<BR>>You can now use this MBean in your application by getting a reference to the Tomcat's MBean server : + {{{ - MBeanServer mbs = ManagementFactory.getPlatformMBeanServer(); + MBeanServer mbs = ManagementFactory.getPlatformMBeanServer(); //call operations with invoke(...) and attributes with getAttributes(...) }}} Do not hesitate to check the ManagementFactory class javadoc. --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
