Java: June 2009 Archives

JavaDocs are great. They're the standard for api documentation, but as good as they are they have one big problem: all classes and all methods are created equal. This can be a problem especially in the quite verbose Java language. Sometimes one class or method is much better than another one. Sometimes you get overwhelmed by the options and have no idea where to even start looking.

Someone has come up with a solution and it's pretty good! It's called Jadeite and it was written four smart guys at CMU. They've even run it on the two common api docs already.

• Java 6 Jadeite API documentation
• JavaMail Jadeite API documentation

It introduces a few useful features.

• It weights classes based on usage. java.lang.Date is huge, java.sql.Date is not as big. This is a huge help when dealing with two similar looking classes that have very critical differences.
• Examples (only for constructors so far) that have been scavenged off of the Internet.
• Users can annotate the documentation as they use it with placeholders. This is a combination wishlist / alternative finder.

It's a huge time saver already. The features have added the best part of php.net's comments without all the noise. If you're doing Java or Groovy development, go check it out.

Most of the time we want web servers to run as fast as they can. There is one time we don't want this to be true: when there are stability issues on a back end service. For example, we're using a web service or database that crashes under load and we can't either throttle the use of this service or improve its ability to accept load. It's better to be up and slow than up and down. To solve this problem you can detune the connector configuration in Tomcat to reduce the number of threads processing requests.

1. Edit tomcat/conf/server.xml
2. Find the configuration for your connector. It will be in an element named Connector
3. Set the maxThreads attribute to a smaller value. I used 50. This limits the number of requests that will be processed simultaneously and in turn reduces down stream load.
4. Add an attribute for acceptCount if it is not already defined. I set this to 1000. This is the number of requests that we will allow to wait for a thread to free up. Tomcat will drop requests once this queue is full.

My Connector configuration looked like this in the end:

<Connector port="8080" maxHttpHeaderSize="8192"
               maxThreads="50" minSpareThreads="20" maxSpareThreads="40"
               enableLookups="false" redirectPort="8443" acceptCount="1000"
               connectionTimeout="20000" disableUploadTimeout="true" 
               compression="on" compressionMinSize="2048" noCompressionUserAgents="gozilla, traviata"
               compressableMimeType="text/html,text/xml,text/plain,text/css,text/javascript,application/x-javascript,application/javascript"/>