Introduction

The PUT method requests that the enclosed entity be stored under the supplied URL. If the URL refers to an already existing resource, the enclosed entity should be considered as a modified version of the one residing on the origin server. If the URL does not point to an existing resource, and that URL is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URL.

If the request passes through a cache and the URL identifies one or more currently cached entities, those entries should be treated as stale. Responses to this method are not cacheable.

The fundamental difference between POST and PUT requests is reflected in the different meaning of the request URL. The URL in a POST request identifies the resource that will handle the enclosed entity. That resource might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URL in a PUT request identifies the entity enclosed with the request -- the user agent knows what URL is intended and the server must not attempt to apply the request to some other resource.

Unless otherwise specified for a particular entity-header, the entity-headers in the PUT request should be applied to the resource created or modified by the PUT.

Typical Usage

The put method is very simple, it takes a URL to put to and requires that the body of the request method be set to the data to upload. The body can be set with an input stream or a string.

        PutMethod put = new PutMethod("http://jakarta.apache.org");
        put.setRequestBody(new FileInputStream("UploadMe.gif"));
        // execute the method and handle any error responses.
        ...
        // Handle the response.  Note that a successful response may not be
        // 200, but may also be 201 Created, 204 No Content or any of the other
        // 2xx range responses.
      
      

Common Problems

The PUT method is not widely supported on public servers due to security concerns and generally FTP is used to upload new and modified files to the webserver. Before executing a PUT method on a URL, it may be worth checking that PUT is supported using the OPTIONS method.

RFC Section

The put method is defined in section 9.6 of RFC2616.