Dear Wiki user, You have subscribed to a wiki page or wiki category on "Jakarta-httpclient Wiki" for change notification.
The following page has been changed by RolandWeber: http://wiki.apache.org/jakarta-httpclient/FrequentlyAskedApplicationDesignQuestions New page: #pragma section-numbers 2 = Application Design FAQ = This document addresses questions about application design which have been raised repeatedly on the HttpClient and HttpComponents mailing lists. As it addresses design issues rather than API or other HttpClient or HttpComponents specific problems, much of the information presented is equally applicable for HttpURLConnection or non-Java APIs. If you are just getting your feet wet and want to understand the basics of client HTTP programming rather than read about application design alternatives, check out our [wiki:Self:ForAbsoluteBeginners primer]. ---- [[TableOfContents]] ---- == Sending Parameters and Uploading Files == A question that is asked on a regular basis is: ''How do I upload a file along with some parameters?'' This section presents different ways to upload parameters, files, and both. It assumes that you are implementing both a client application and a server application to which the client application connects. The client application might be a Java program using HttpClient, while the server application is assumed to be a [http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/http/HttpServlet.html Servlet]. Parameters are name/value pairs, where both name and value are strings. Names should always be in US-ASCII, values may use other character encodings, depending on the technique used for sending the parameters. Files or rather file parameters are name/value pairs, where the name is a string and the value is binary data read from a file. Binary values from other sources can be handled similar to files from a design perspective, though the details of the API will vary. === GET with Query === The simplest way to transfer parameters to the server is the query string of the URL. That's the part after the question mark, for example in: http:''''''//my.server.name/my/servlet'''?param1=value1¶m2=value2''' Query strings can be used with any HTTP method, but they are most frequently used with the GET method. A query string is also the only way to send parameters with a GET method. (Unless your application encodes parameters into the URL path.) Query strings works only for string values. Special characters like = & % and the space character need to be escaped as a % character followed by two hex digits specifying the ASCII value of the character. The encoding of special characters is automatically handled for example by the [http://java.sun.com/j2se/1.5.0/docs/api/java/net/URI.html#URI(java.lang.String,%20java.lang.String,%20java.lang.String,%20int,%20java.lang.String,%20java.lang.String,%20java.lang.String) java.net.URI] and [http://jakarta.apache.org/commons/httpclient/apidocs/org/apache/commons/httpclient/URI.html#setRawQuery(char%5b%5d) org.apache.commons.httpclient.URI] classes. URLs are confined to using ASCII characters exclusively. Only ASCII values can reliably be transferred in a query string. However, some browsers handle non-ASCII input in HTML forms by encoding those characters, for example in UTF-8, and escaping the non-ASCII bytes as %xx sequences. It is strongly discouraged to send non-ASCII values in the query string. On the server, name/value pairs sent in a query string are available as parameters of the [http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/ServletRequest.html#getParameter(java.lang.String) ServletRequest]. %xx escape sequences are automatically decoded by the Servlet API. If non-ASCII values are sent in the query string, the outcome depends on the implementation of the Servlet API and possibly also on configuration parameters, such as the JVM default character set. That's why it is strongly discouraged to send non-ASCII values in the query string. === POST with URL-encoded Form Data === Unlike the GET method, a POST method has a message body or entity which can hold any kind of binary or non-binary data. A simple way to send parameters with string values to the server is to put the query string into the message body instead of the URL. This avoids URL length restrictions, problems with parameters being logged where they shouldn't, and it also allows for non-ASCII characters in the values. While a URL is confined to ASCII characters, the message body is not. The character set can be specified in a header field. The encoding of special characters is automatically handled by HttpClient's [http://jakarta.apache.org/commons/httpclient/apidocs/org/apache/commons/httpclient/methods/PostMethod.html PostMethod]. On the server, name/value pairs sent in a message body with content type "application/x-www-form-urlencoded" are available as parameters of the [http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/ServletRequest.html#getParameter(java.lang.String) ServletRequest]. If there are parameters in both the message body and the query string, all of them are available in the !ServletRequest. === POST with Multipart Form Data === In order to upload binary data such as files, the data can be encoded as multipart [http://www.ietf.org/rfc/rfc1521.txt MIME]. That's the same format which is used for sending email attachments. HTML forms for uploading files have to specify the content type "multipart/form-data" so the browser knows that the multipart MIME encoding must be applied. That content type is also sent to the server. HttpClient provides the [http://jakarta.apache.org/commons/httpclient/apidocs/org/apache/commons/httpclient/methods/multipart/MultipartRequestEntity.html MultipartRequestEntity] class to perform multipart MIME encoding. On the server, parameters sent as multipart MIME are ''not'' available as parameters of the [http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/ServletRequest.html#getParameter(java.lang.String) ServletRequest]. The servlet has to read and interpret the message body explicitly. There are libraries for parsing multipart MIME data, for example [http://jakarta.apache.org/commons/fileupload/ Commons FileUpload]. It should also be possible to parse multipart/form-data using the [http://java.sun.com/products/javamail/FAQ.html#attach JavaMail API]. If there are parameters in both the message body and the query string, only those from the query string are available in the !ServletRequest. === POST with Query and Data === In the special case that you need to upload only parameters with ASCII string values and a single file, there is another option. You can send the parameters in a query string and the file contents as the message body. This does not require special encoding or decoding of the binary data. This kind of request can not be generated by an HTML form. [[BR]] With this approach, the file is not sent as a name/value pair. Only the value, that is the file contents, will be transferred. The servlet has to know what to do with the file based only on the information in the URL (and HTTP headers). The information in the URL can come from the query string (?name=!MyImage.png), from the URL path (/my/servlet/save), or both. [[BR]] You should specify a content type that indicates the type of data you are sending in the message body, such as "application/octet-stream" or "image/png" or whatever else is appropriate for the file you are uploading. If you are uploading a text file, you should also specify the character set as part of the content type. On the server, the parameters sent in the query string are available as parameters of the [http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/ServletRequest.html#getParameter(java.lang.String) ServletRequest]. The file contents is available as from the !ServletRequest as either [http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/ServletRequest.html#getInputStream() binary] or [http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/ServletRequest.html#getReader() character] data. === Further Reading === [http://java.sun.com/j2se/1.5.0/docs/api/java/net/HttpURLConnection.html Java Standard Edition 5.0, HttpURLConnection] [http://www.iana.org/assignments/media-types/ IANA: Registered MIME Media Types] [http://java.sun.com/products/servlet/docs.html Sun: Java Servlet Technology Documentation] [http://java.sun.com/products/servlet/2.3/javadoc/ Servlet API 2.3] [http://java.sun.com/javaee/5/docs/api/javax/servlet/package-summary.html Java Enterprise Edition 5.0, Servlet API 2.4] [http://java.sun.com/products/javamail/reference/index.html JavaMail] [http://java.sun.com/javaee/5/docs/api/javax/mail/package-summary.html Java Enterprise Edition 5.0, JavaMail API] --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
