Answers to the most frequently asked
Below you'll find questions and answers
to the most frequently asked questions about the com.oreilly.servlet
library, especially the file upload components.
If you have other questions, write to firstname.lastname@example.org.
What is the com.oreilly.servlet package?
The com.oreilly.servlet package is a "must
have" class library for servlet developers. There are classes
to help servlets handle file uploads, generate multipart responses
(server push), parse parameters, negotiate locales for internationalization,
return files, manage socket connections, and act as RMI servers,
as well as a class to help applets communicate with servlets. Since
the first release, there are also new classes to help servlets send
email messages, cache responses, and auto-detect servlet API support.
The latest version is available online (with javadoc documentation)
for download from http://www.servlets.com.
How do I install the com.oreilly.servlet package?
Unzip the com.oreilly.servlets distribution file
using a unzip utility like WinZip or jar. Inside you'll find a file
cos.jar. Place this where your server will find it, such as the
WEB-INF/lib directory for your web application. For server-wide
availability you can also place it into the CLASSPATH used by your
server. That's it!
For more information on the WEB-INF directory see
"Java Servlet Programming, 2nd Edition" and for more information
on CLASSPATH entries see any introductory Java book.
What's the difference between MultipartRequest
MultipartRequest is an API for easyhandling
of multipart/form-data requests (commonly known as file uploads).
MultipartParser is an API for experts who want more control in handling
these requests. MultipartRequest handles the entire request and
then exposes the results while MultipartParser lets you walk the
request piece-by-piece and deal with each piece as it comes. MultipartRequest
is actually written as a thin facade on MultipartParser.
OK, so what's MultipartWrapper?
MultipartWrapper takes advantage of the filtering
capability introduced in Servlet API 2.3 to make handling file uploads
practically automatic. It can automatically wrap any request to
invisibly handle multipart/form-data requests. For more information,
see my filters
article at JavaWorld.
Why doesn't MultipartRequest implement the HttpServletRequest
It's an issue of forward compatibility. If MultipartRequest
had implemented HttpServletRequest back when
servlets were at API 2.0, then when API 2.1 came out and introduced
new methods into the request interface, all deployments of MultipartRequest
would have failed because MultipartRequest would no longer fully
implement the new HttpServletRequest. The same would have happened
with API 2.1 and 2.2. Now happily with API 2.3 there's an HttpServletRequestWrapper
class which protects against forward compatibility concerns, and
so MultipartWrapper does fully implement the HttpServletRequest
Why when using com.oreilly.servlet.MultipartRequest
or MultipartParser do large uploads fail?
The classes themselves were specifically designed
to have no maximumupload size limit (unlike
most other file upload utilities), but for your server's protection
the constructor allows you to set a maximum POST size to accept.
Anything upload larger than the limit is halted. The default maximum
is 1 Meg. For a discussion of the difficulties a server has in notifying
a client of the error, see the discussion in Java Servlet Programming,
2nd Edition, page 119.
How can I configure a maximum upload size for
a single file but have no limit for the entire post?
The protocol doesn't make this easy. The only information
given to the server up front is the size of the entire POST. After
that, each file comes piece by piece with only a separator between
them. If you want to have a maximum file size, your best bet is
probably to use MultipartParser to walk the request piece by piece
and when writing any file keep track of how much is written and
if it exceeds your maximum you can remove the file and (if you like)
halt the upload. If you want to continue the upload, you'll need
to continue reading until the file it done before you can receive
the next file however.
How can I select a directory for the uploaded
files based on some information sent in the upload request?
Again, the protocol doesn't make this easy. In
fact, there's no guarantee the browser will send the parameter information
before the files. The safest approach is to create a temporary directory,
upload the files into there, then after the upload move the files
and/or the directory into the proper location.
Why when using com.oreilly.servlet.MultipartRequest
or MultipartParser am I getting an IOException saying "Corrupt
form data: premature ending" or "Separation boundary was
This indicates there was a problem parsing the
POST request submitted by the client. There can be many causes for
the problem: a bug in the web form, a bug in the servlet, a bug
in the web server, a bug in the browser, or a bug in your web.xml
configuration. Some rare times it's
a bug in the com.oreilly.servlet library itself. History has shown
the web server to be the most frequent cause of problems probably
because there are so many different servers and few vendors appear
to test their binary upload capability. Another cause people have
reported is having a web.xml with the multipart filter covered by two
different filter rules mathing the same URL, and then on the second invocation the
filter tries to process the request and it results in "Corrupt form data: premature ending".
To investigate the issue, first, check if your problem is already posted
on the "Servlet bugs you need
to know about" resource on this site. If it's not well
known, then you get to be among the first to learn about it! And
you can share your discovery with us here!
Second, see if the upload works using the provided
upload.html form and DemoRequestUploadServlet.java class. Some people
have found bugs in their form that caused problems. Testing this
combination will see if that's the case. It will also check
if it's a web.xml filter configuration issue.
If it still fails, the best way to isolate the
problem is to treat it like a hardware problem and swap out components
until things work, then use that knowledge to see what product has
the bug, or what interaction between products causes a bug. Try
swapping browsers first. You probably have multiple browsers available
to you so this should be easy. If one browser fails while others
work, it's likely an issue with that browser or how that browser
interacts with the server. Try uploading different files too, since
some files (especially binary files or files with long lines like
.doc files) could be triggering bugs. You can also test against
the Servlets.com upload demo at http://www.servlets.com/jservlet2/examples/ch04/index.html#ex04_21.
If your browser fails against that page, it's very likely the fault
of the browser because that page has been successful for many others.
If it looks like everything works on the demo site but not on your
server, it's very likely a server bug. Try installing a different
server to make sure, and if you isolate the problem report it to
your server vendor. Also please report it to us at email@example.com
so we can track it and help others.
I want to comply with your license, but I'd
like something simpler. Can I negotiate a different license?
Sure, contact firstname.lastname@example.org.
Site-wide and company-wide licensing options are available, as well
as licenses for redistribution.
I want an applet client so I can upload a full
directory of files (or some such thing). Where can I find that?
Yes, see http://www.infomentum.com/appletfile/.
It's loaded with features like directory-at-a-time uploading. Tell
them Servlets.com sent you!