org.restlet.resource

## Class ClientResource

- java.lang.Object
- - org.restlet.resource.UniformResource
  - - org.restlet.resource.ClientResource

    public class ClientResource
    extends UniformResource

Client-side resource. Acts like a proxy of a target resource.
This class changes the semantics of the `UniformResource.getRequest()` and `UniformResource.getResponse()` methods. Since a clientResource may receive severals responses for a single request (in case of interim response), the `UniformResource.getResponse()` method returns the last received response object. The Request object returned by the `UniformResource.getRequest()` is actually a prototype which is cloned (except the representation) just before the `handle()` method is called.
Users must be aware that by most representations can only be read or written once. Some others, such as `StringRepresentation` stored the entity in memory which can be read several times but has the drawback to consume memory.
Concurrency note: instances of the class are not designed to be shared among several threads. If thread-safety is necessary, consider using the lower-level `Client` class instead.

Author:
  Jerome Louvel

### Constructor Summary

Constructors
`protected` `ClientResource()` Empty constructor.
`` `ClientResource(ClientResource resource)` Constructor.
`` `ClientResource(Context context, Method method, Reference reference)` Constructor.
`` `ClientResource(Context context, Method method, java.lang.String uri)` Constructor.
`` `ClientResource(Context context, Method method, java.net.URI uri)` Constructor.
`` `ClientResource(Context context, Reference reference)` Constructor.
`` `ClientResource(Context context, Request request, Response response)` Constructor.
`` `ClientResource(Context context, java.lang.String uri)` Constructor.
`` `ClientResource(Context context, java.net.URI uri)` Constructor.
`` `ClientResource(Method method, Reference reference)` Constructor.
`` `ClientResource(Method method, java.lang.String uri)` Constructor.
`` `ClientResource(Method method, java.net.URI uri)` Constructor.
`` `ClientResource(Reference reference)` Constructor.
`` `ClientResource(Request request, Response response)` Constructor.
`` `ClientResource(java.lang.String uri)` Constructor.
`` `ClientResource(java.net.URI uri)` Constructor.

### Method Summary

Methods
`static <T> T` `create(Context context, Reference reference, java.lang.Class<? extends T> resourceInterface)` Creates a client resource that proxy calls to the given Java interface into Restlet method calls.
`static <T> T` `create(Reference reference, java.lang.Class<? extends T> resourceInterface)` Creates a client resource that proxy calls to the given Java interface into Restlet method calls.
`static <T> T` `create(java.lang.String uri, java.lang.Class<? extends T> resourceInterface)` Creates a client resource that proxy calls to the given Java interface into Restlet method calls.
`protected Uniform` `createNext()` Creates a next Restlet is no one is set.
`protected Request` `createRequest(Request prototype)` Creates a new request by cloning the given one.
`protected Response` `createResponse(Request request)` Creates a new response for the given request.
`Representation` `delete()` Deletes the target resource and all its representations.
`<T> T` `delete(java.lang.Class<T> resultClass)` Deletes the target resource and all its representations.
`Representation` `delete(MediaType mediaType)` Deletes the target resource and all its representations.
`protected void` `doRelease()` Releases the resource by stopping any connector automatically created and associated to the "next" property (see `getNext()` method.
`protected void` `finalize()` Attempts to `UniformResource.release()` the resource.
`Representation` `get()` Represents the resource using content negotiation to select the best variant based on the client preferences.
`<T> T` `get(java.lang.Class<T> resultClass)` Represents the resource in the given object class.
`Representation` `get(MediaType mediaType)` Represents the resource using a given media type.
`ClientResource` `getChild(Reference relativeRef)` Returns the child resource defined by its URI relatively to the current resource.
`<T> T` `getChild(Reference relativeRef, java.lang.Class<? extends T> resourceInterface)` Wraps the child client resource to proxy calls to the given Java interface into Restlet method calls.
`ClientResource` `getChild(java.lang.String relativeUri)` Returns the child resource defined by its URI relatively to the current resource.
`<T> T` `getChild(java.lang.String relativeUri, java.lang.Class<? extends T> resourceInterface)` Wraps the child client resource to proxy calls to the given Java interface into Restlet method calls.
`Uniform` `getNext()` Returns the next Restlet.
`Uniform` `getOnResponse()` Returns the callback invoked on response reception.
`Uniform` `getOnSent()` Returns the callback invoked after sending the request.
`ClientResource` `getParent()` Returns the parent resource.
`<T> T` `getParent(java.lang.Class<? extends T> resourceInterface)` Wraps the parent client resource to proxy calls to the given Java interface into Restlet method calls.
`int` `getRetryAttempts()` Returns the number of retry attempts before reporting an error.
`long` `getRetryDelay()` Returns the delay in milliseconds between two retry attempts.
`Representation` `handle()` Handles the call by invoking the next handler.
`boolean` `hasNext()` Indicates if there is a next Restlet.
`Representation` `head()` Represents the resource using content negotiation to select the best variant based on the client preferences.
`Representation` `head(MediaType mediaType)` Represents the resource using a given media type.
`boolean` `isFollowingRedirects()` Indicates if redirections are followed.
`boolean` `isRetryOnError()` Indicates if idempotent requests should be retried on error.
`Representation` `options()` Describes the resource using content negotiation to select the best variant based on the client preferences.
`<T> T` `options(java.lang.Class<T> resultClass)` Describes the resource using a given media type.
`Representation` `options(MediaType mediaType)` Describes the resource using a given media type.
`Representation` `post(java.lang.Object entity)` Posts an object entity.
`<T> T` `post(java.lang.Object entity, java.lang.Class<T> resultClass)` Posts an object entity.
`Representation` `post(java.lang.Object entity, MediaType mediaType)` Posts an object entity.
`Representation` `post(Representation entity)` Posts a representation.
`Representation` `put(java.lang.Object entity)` Puts an object entity.
`<T> T` `put(java.lang.Object entity, java.lang.Class<T> resultClass)` Puts an object entity.
`Representation` `put(java.lang.Object entity, MediaType mediaType)` Puts an object entity.
`Representation` `put(Representation entity)` Creates or updates a resource with the given representation as new state to be stored.
`void` `setChallengeResponse(ChallengeResponse challengeResponse)` Sets the authentication response sent by a client to an origin server.
`void` `setChallengeResponse(ChallengeScheme scheme, java.lang.String identifier, java.lang.String secret)` Sets the authentication response sent by a client to an origin server given a scheme, identifier and secret.
`void` `setClientInfo(ClientInfo clientInfo)` Sets the client-specific information.
`void` `setConditions(Conditions conditions)` Sets the conditions applying to this request.
`void` `setCookies(Series<Cookie> cookies)` Sets the cookies provided by the client.
`void` `setFollowingRedirects(boolean followingRedirects)` Indicates if redirections are followed.
`void` `setHostRef(Reference hostRef)` Sets the host reference.
`void` `setHostRef(java.lang.String hostUri)` Sets the host reference using an URI string.
`void` `setMethod(Method method)` Sets the method called.
`void` `setNext(Uniform next)` Sets the next handler such as a Restlet or a Filter.
`void` `setOnResponse(Uniform onResponseCallback)` Sets the callback invoked on response reception.
`void` `setOnSent(Uniform onSentCallback)` Sets the callback invoked after sending the request.
`void` `setOriginalRef(Reference originalRef)` Sets the original reference requested by the client.
`void` `setProtocol(Protocol protocol)` Sets the protocol used or to be used.
`void` `setRanges(java.util.List<Range> ranges)` Sets the ranges to return from the target resource's representation.
`void` `setReference(Reference reference)` Sets the resource's reference.
`void` `setReference(java.lang.String uri)` Sets the resource's reference using an URI string.
`void` `setReferrerRef(Reference referrerRef)` Sets the referrer reference if available.
`void` `setReferrerRef(java.lang.String referrerUri)` Sets the referrer reference if available using an URI string.
`void` `setRetryAttempts(int retryAttempts)` Sets the number of retry attempts before reporting an error.
`void` `setRetryDelay(long retryDelay)` Sets the delay in milliseconds between two retry attempts.
`void` `setRetryOnError(boolean retryOnError)` Indicates if idempotent requests should be retried on error.
`<T> T` `wrap(java.lang.Class<? extends T> resourceInterface)` Wraps the client resource to proxy calls to the given Java interface into Restlet method calls.

### Methods inherited from class org.restlet.resource.UniformResource

`doCatch, doInit, getAllowedMethods, getApplication, getChallengeRequests, getChallengeResponse, getClientInfo, getConditions, getContext, getConverterService, getCookies, getCookieSettings, getDimensions, getHostRef, getLocationRef, getLogger, getMatrix, getMaxForwards, getMetadataService, getMethod, getOriginalRef, getProtocol, getQuery, getRanges, getReference, getReferrerRef, getRequest, getRequestAttributes, getRequestEntity, getResponse, getResponseAttributes, getResponseEntity, getRootRef, getServerInfo, getStatus, getStatusService, init, isConfidential, release, setRequest, setResponse, toObject, toRepresentation`

### Methods inherited from class java.lang.Object

`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### ClientResource

    protected ClientResource()

Empty constructor.

#### ClientResource

    public ClientResource(ClientResource resource)

Constructor.

Parameters:
  `resource` - The client resource to copy.

#### ClientResource

    public ClientResource(Context context,
                  java.net.URI uri)

Constructor.

Parameters:
  `context` - The context.
  `uri` - The target URI.

#### ClientResource

    public ClientResource(Context context,
                  Method method,
                  java.net.URI uri)

Constructor.

Parameters:
  `context` - The context.
  `method` - The method to call.
  `uri` - The target URI.

#### ClientResource

    public ClientResource(Context context,
                  Method method,
                  Reference reference)

Constructor.

Parameters:
  `context` - The context.
  `method` - The method to call.
  `reference` - The target reference.

#### ClientResource

    public ClientResource(Context context,
                  Method method,
                  java.lang.String uri)

Constructor.

Parameters:
  `context` - The context.
  `method` - The method to call.
  `uri` - The target URI.

#### ClientResource

    public ClientResource(Context context,
                  Reference reference)

Constructor.

Parameters:
  `context` - The context.
  `reference` - The target reference.

#### ClientResource

    public ClientResource(Context context,
                  Request request,
                  Response response)

Constructor.

Parameters:
  `context` - The current context.
  `request` - The handled request.
  `response` - The handled response.

#### ClientResource

    public ClientResource(Context context,
                  java.lang.String uri)

Constructor.

Parameters:
  `context` - The context.
  `uri` - The target URI.

#### ClientResource

    public ClientResource(java.net.URI uri)

Constructor.

Parameters:
  `uri` - The target URI.

#### ClientResource

    public ClientResource(Method method,
                  java.net.URI uri)

Constructor.

Parameters:
  `method` - The method to call.
  `uri` - The target URI.

#### ClientResource

    public ClientResource(Method method,
                  Reference reference)

Constructor.

Parameters:
  `method` - The method to call.
  `reference` - The target reference.

#### ClientResource

    public ClientResource(Method method,
                  java.lang.String uri)

Constructor.

Parameters:
  `method` - The method to call.
  `uri` - The target URI.

#### ClientResource

    public ClientResource(Reference reference)

Constructor.

Parameters:
  `reference` - The target reference.

#### ClientResource

    public ClientResource(Request request,
                  Response response)

Constructor.

Parameters:
  `request` - The handled request.
  `response` - The handled response.

#### ClientResource

    public ClientResource(java.lang.String uri)

Constructor.

Parameters:
  `uri` - The target URI.

### Method Detail

#### create

    public static <T> T create(Context context,
               Reference reference,
               java.lang.Class<? extends T> resourceInterface)

Creates a client resource that proxy calls to the given Java interface into Restlet method calls. It basically creates a new instance of `ClientResource` and invokes the `wrap(Class)` method.

Type Parameters:
  `T` -
Parameters:
  `context` - The context.
  `reference` - The target reference.
  `resourceInterface` - The annotated resource interface class to proxy.
Returns:
  The proxy instance.

#### create

    public static <T> T create(Reference reference,
               java.lang.Class<? extends T> resourceInterface)

Creates a client resource that proxy calls to the given Java interface into Restlet method calls. It basically creates a new instance of `ClientResource` and invokes the `wrap(Class)` method.

Type Parameters:
  `T` -
Parameters:
  `resourceInterface` - The annotated resource interface class to proxy.
Returns:
  The proxy instance.

#### create

    public static <T> T create(java.lang.String uri,
               java.lang.Class<? extends T> resourceInterface)

Creates a client resource that proxy calls to the given Java interface into Restlet method calls. It basically creates a new instance of `ClientResource` and invokes the `wrap(Class)` method.

Type Parameters:
  `T` -
Parameters:
  `uri` - The target URI.
  `resourceInterface` - The annotated resource interface class to proxy.
Returns:
  The proxy instance.

#### createNext

    protected Uniform createNext()

Creates a next Restlet is no one is set. By default, it creates a new `Client` based on the protocol of the resource's URI reference.

Returns:
  The created next Restlet or null.

#### createRequest

    protected Request createRequest(Request prototype)

Creates a new request by cloning the given one.

Parameters:
  `prototype` - The prototype request.
Returns:
  The new response.

#### createResponse

    protected Response createResponse(Request request)

Creates a new response for the given request.

Parameters:
  `request` - The associated request.
Returns:
  The new response.

#### delete

    public Representation delete()
                          throws ResourceException

Deletes the target resource and all its representations. If a success status is not returned, then a resource exception is thrown.

Returns:
  The optional response entity.
Throws:
  `ResourceException`
See Also:
  HTTP DELETE method

#### delete

    public <T> T delete(java.lang.Class<T> resultClass)
             throws ResourceException

Deletes the target resource and all its representations. If a success status is not returned, then a resource exception is thrown.

Type Parameters:
  `T` - The expected type for the response entity.
Parameters:
  `resultClass` - The expected class for the response entity object.
Returns:
  The response entity object.
Throws:
  `ResourceException`
See Also:
  HTTP DELETE method

#### delete

    public Representation delete(MediaType mediaType)
                          throws ResourceException

Deletes the target resource and all its representations. If a success status is not returned, then a resource exception is thrown.

Parameters:
  `mediaType` - The media type of the representation to retrieve.
Returns:
  The representation matching the given media type.
Throws:
  `ResourceException`
See Also:
  HTTP DELETE method

#### doRelease

    protected void doRelease()
                      throws ResourceException

Releases the resource by stopping any connector automatically created and associated to the "next" property (see `getNext()` method.

Overrides:
  `doRelease` in class `UniformResource`
Throws:
  `ResourceException`
See Also:
  `UniformResource.release()`

#### finalize

    protected void finalize()
                     throws java.lang.Throwable

Attempts to `UniformResource.release()` the resource.

Overrides:
  `finalize` in class `java.lang.Object`
Throws:
  `java.lang.Throwable`

#### get

    public Representation get()
                       throws ResourceException

Represents the resource using content negotiation to select the best variant based on the client preferences. Note that the client preferences will be automatically adjusted, but only for this request. If you want to change them once for all, you can use the `UniformResource.getClientInfo()` method.
If a success status is not returned, then a resource exception is thrown.

Returns:
  The best representation.
Throws:
  `ResourceException`
See Also:
  HTTP GET method

#### get

    public <T> T get(java.lang.Class<T> resultClass)
          throws ResourceException

Represents the resource in the given object class. Note that the client preferences will be automatically adjusted, but only for this request. If you want to change them once for all, you can use the `UniformResource.getClientInfo()` method.
If a success status is not returned, then a resource exception is thrown.

Type Parameters:
  `T` - The expected type for the response entity.
Parameters:
  `resultClass` - The expected class for the response entity object.
Returns:
  The response entity object.
Throws:
  `ResourceException`
See Also:
  HTTP GET method

#### get

    public Representation get(MediaType mediaType)
                       throws ResourceException

Represents the resource using a given media type. Note that the client preferences will be automatically adjusted, but only for this request. If you want to change them once for all, you can use the `UniformResource.getClientInfo()` method.
If a success status is not returned, then a resource exception is thrown.

Parameters:
  `mediaType` - The media type of the representation to retrieve.
Returns:
  The representation matching the given media type.
Throws:
  `ResourceException`
See Also:
  HTTP GET method

#### getChild

    public ClientResource getChild(Reference relativeRef)
                            throws ResourceException

Returns the child resource defined by its URI relatively to the current resource. The child resource is defined in the sense of hierarchical URIs. If the resource URI is not hierarchical, then an exception is thrown.

Parameters:
  `relativeRef` - The URI reference of the child resource relatively to the current resource seen as the parent resource.
Returns:
  The child resource.
Throws:
  `ResourceException`

#### getChild

    public <T> T getChild(Reference relativeRef,
                 java.lang.Class<? extends T> resourceInterface)
               throws ResourceException

Wraps the child client resource to proxy calls to the given Java interface into Restlet method calls. The child resource is defined in the sense of hierarchical URIs. If the resource URI is not hierarchical, then an exception is thrown.

Type Parameters:
  `T` -
Parameters:
  `relativeRef` - The URI reference of the child resource relatively to the current resource seen as the parent resource.
  `resourceInterface` - The annotated resource interface class to proxy.
Returns:
  The proxy instance.
Throws:
  `ResourceException`

#### getChild

    public ClientResource getChild(java.lang.String relativeUri)
                            throws ResourceException

Returns the child resource defined by its URI relatively to the current resource. The child resource is defined in the sense of hierarchical URIs. If the resource URI is not hierarchical, then an exception is thrown.

Parameters:
  `relativeUri` - The URI of the child resource relatively to the current resource seen as the parent resource.
Returns:
  The child resource.
Throws:
  `ResourceException`

#### getChild

    public <T> T getChild(java.lang.String relativeUri,
                 java.lang.Class<? extends T> resourceInterface)
               throws ResourceException

Wraps the child client resource to proxy calls to the given Java interface into Restlet method calls. The child resource is defined in the sense of hierarchical URIs. If the resource URI is not hierarchical, then an exception is thrown.

Type Parameters:
  `T` -
Parameters:
  `relativeUri` - The URI of the child resource relatively to the current resource seen as the parent resource.
  `resourceInterface` - The annotated resource interface class to proxy.
Returns:
  The proxy instance.
Throws:
  `ResourceException`

#### getNext

    public Uniform getNext()

Returns the next Restlet. By default, it is the client dispatcher if a context is available.

Returns:
  The next Restlet or null.

#### getOnResponse

    public Uniform getOnResponse()

Returns the callback invoked on response reception. If the value is not null, then the associated request will be executed asynchronously.

Returns:
  The callback invoked on response reception.

#### getOnSent

    public Uniform getOnSent()

Returns the callback invoked after sending the request.

Returns:
  The callback invoked after sending the request.

#### getParent

    public ClientResource getParent()
                             throws ResourceException

Returns the parent resource. The parent resource is defined in the sense of hierarchical URIs. If the resource URI is not hierarchical, then an exception is thrown.

Returns:
  The parent resource.
Throws:
  `ResourceException`

#### getParent

    public <T> T getParent(java.lang.Class<? extends T> resourceInterface)
                throws ResourceException

Wraps the parent client resource to proxy calls to the given Java interface into Restlet method calls. The parent resource is defined in the sense of hierarchical URIs. If the resource URI is not hierarchical, then an exception is thrown.

Type Parameters:
  `T` -
Parameters:
  `resourceInterface` - The annotated resource interface class to proxy.
Returns:
  The proxy instance.
Throws:
  `ResourceException`

#### getRetryAttempts

    public int getRetryAttempts()

Returns the number of retry attempts before reporting an error. Default value is 2.

Returns:
  The number of retry attempts before reporting an error.

#### getRetryDelay

    public long getRetryDelay()

Returns the delay in milliseconds between two retry attempts. Default value is 2 seconds.

Returns:
  The delay in milliseconds between two retry attempts.

#### handle

    public Representation handle()

Handles the call by invoking the next handler. The prototype request is retrieved via `UniformResource.getRequest()` and cloned and the response is set as the latest with `UniformResource.setResponse(Response)`. If necessary the `setNext(Uniform)` method is called as well with a `Client` instance matching the request protocol.

Specified by:
  `handle` in class `UniformResource`
Returns:
  The optional response entity.
See Also:
  `getNext()`

#### hasNext

    public boolean hasNext()

Indicates if there is a next Restlet.

Returns:
  True if there is a next Restlet.

#### head

    public Representation head()
                        throws ResourceException

Represents the resource using content negotiation to select the best variant based on the client preferences. This method is identical to `get()` but doesn't return the actual content of the representation, only its metadata.
Note that the client preferences will be automatically adjusted, but only for this request. If you want to change them once for all, you can use the `UniformResource.getClientInfo()` method.
If a success status is not returned, then a resource exception is thrown.

Returns:
  The best representation.
Throws:
  `ResourceException`
See Also:
  HTTP HEAD method

#### head

    public Representation head(MediaType mediaType)
                        throws ResourceException

Represents the resource using a given media type. This method is identical to `get(MediaType)` but doesn't return the actual content of the representation, only its metadata.
Note that the client preferences will be automatically adjusted, but only for this request. If you want to change them once for all, you can use the `UniformResource.getClientInfo()` method.
If a success status is not returned, then a resource exception is thrown.

Parameters:
  `mediaType` - The media type of the representation to retrieve.
Returns:
  The representation matching the given media type.
Throws:
  `ResourceException`
See Also:
  HTTP HEAD method

#### isFollowingRedirects

    public boolean isFollowingRedirects()

Indicates if redirections are followed.

Returns:
  True if redirections are followed.

#### isRetryOnError

    public boolean isRetryOnError()

Indicates if idempotent requests should be retried on error. Default value is true.

Returns:
  True if idempotent requests should be retried on error.

#### options

    public Representation options()
                           throws ResourceException

Describes the resource using content negotiation to select the best variant based on the client preferences. If a success status is not returned, then a resource exception is thrown.

Returns:
  The best description.
Throws:
  `ResourceException`
See Also:
  HTTP OPTIONS method

#### options

    public <T> T options(java.lang.Class<T> resultClass)
              throws ResourceException

Describes the resource using a given media type. If a success status is not returned, then a resource exception is thrown.

Type Parameters:
  `T` - The expected type for the response entity.
Parameters:
  `resultClass` - The expected class for the response entity object.
Returns:
  The response entity object.
Throws:
  `ResourceException`
See Also:
  HTTP OPTIONS method

#### options

    public Representation options(MediaType mediaType)
                           throws ResourceException

Describes the resource using a given media type. If a success status is not returned, then a resource exception is thrown.

Parameters:
  `mediaType` - The media type of the representation to retrieve.
Returns:
  The matched description or null.
Throws:
  `ResourceException`
See Also:
  HTTP OPTIONS method

#### post

    public Representation post(java.lang.Object entity)
                        throws ResourceException

Posts an object entity. Automatically serializes the object using the `ConverterService`.

Parameters:
  `entity` - The object entity to post.
Returns:
  The optional result entity.
Throws:
  `ResourceException`
See Also:
  HTTP POST method

#### post

    public <T> T post(java.lang.Object entity,
             java.lang.Class<T> resultClass)
           throws ResourceException

Posts an object entity. Automatically serializes the object using the `ConverterService`.

Parameters:
  `entity` - The object entity to post.
  `resultClass` - The class of the response entity.
Returns:
  The response object entity.
Throws:
  `ResourceException`
See Also:
  HTTP POST method

#### post

    public Representation post(java.lang.Object entity,
                      MediaType mediaType)
                        throws ResourceException

Posts an object entity. Automatically serializes the object using the `ConverterService`.

Parameters:
  `entity` - The object entity to post.
  `mediaType` - The media type of the representation to retrieve.
Returns:
  The response object entity.
Throws:
  `ResourceException`
See Also:
  HTTP POST method

#### post

    public Representation post(Representation entity)
                        throws ResourceException

Posts a representation. If a success status is not returned, then a resource exception is thrown.

Parameters:
  `entity` - The posted entity.
Returns:
  The optional result entity.
Throws:
  `ResourceException`
See Also:
  HTTP POST method

#### put

    public Representation put(java.lang.Object entity)
                       throws ResourceException

Puts an object entity. Automatically serializes the object using the `ConverterService`.

Parameters:
  `entity` - The object entity to put.
Returns:
  The optional result entity.
Throws:
  `ResourceException`
See Also:
  HTTP PUT method

#### put

    public <T> T put(java.lang.Object entity,
            java.lang.Class<T> resultClass)
          throws ResourceException

Puts an object entity. Automatically serializes the object using the `ConverterService`.

Parameters:
  `entity` - The object entity to put.
  `resultClass` - The class of the response entity.
Returns:
  The response object entity.
Throws:
  `ResourceException`
See Also:
  HTTP PUT method

#### put

    public Representation put(java.lang.Object entity,
                     MediaType mediaType)
                       throws ResourceException

Puts an object entity. Automatically serializes the object using the `ConverterService`.

Parameters:
  `entity` - The object entity to post.
  `mediaType` - The media type of the representation to retrieve.
Returns:
  The response object entity.
Throws:
  `ResourceException`
See Also:
  HTTP PUT method

#### put

    public Representation put(Representation entity)
                       throws ResourceException

Creates or updates a resource with the given representation as new state to be stored. If a success status is not returned, then a resource exception is thrown.

Parameters:
  `entity` - The request entity to store.
Returns:
  The optional result entity.
Throws:
  `ResourceException`
See Also:
  HTTP PUT method

#### setChallengeResponse

    public void setChallengeResponse(ChallengeResponse challengeResponse)

Sets the authentication response sent by a client to an origin server.

Parameters:
  `challengeResponse` - The authentication response sent by a client to an origin server.
See Also:
  `Request.setChallengeResponse(ChallengeResponse)`

#### setChallengeResponse

    public void setChallengeResponse(ChallengeScheme scheme,
                            java.lang.String identifier,
                            java.lang.String secret)

Sets the authentication response sent by a client to an origin server given a scheme, identifier and secret.

Parameters:
  `scheme` - The challenge scheme.
  `identifier` - The user identifier, such as a login name or an access key.
  `secret` - The user secret, such as a password or a secret key.

#### setClientInfo

    public void setClientInfo(ClientInfo clientInfo)

Sets the client-specific information.

Parameters:
  `clientInfo` - The client-specific information.
See Also:
  `Request.setClientInfo(ClientInfo)`

#### setConditions

    public void setConditions(Conditions conditions)

Sets the conditions applying to this request.

Parameters:
  `conditions` - The conditions applying to this request.
See Also:
  `Request.setConditions(Conditions)`

#### setCookies

    public void setCookies(Series<Cookie> cookies)

Sets the cookies provided by the client.

Parameters:
  `cookies` - The cookies provided by the client.
See Also:
  `Request.setCookies(Series)`

#### setFollowingRedirects

    public void setFollowingRedirects(boolean followingRedirects)

Indicates if redirections are followed.

Parameters:
  `followingRedirects` - True if redirections are followed.

#### setHostRef

    public void setHostRef(Reference hostRef)

Sets the host reference.

Parameters:
  `hostRef` - The host reference.
See Also:
  `Request.setHostRef(Reference)`

#### setHostRef

    public void setHostRef(java.lang.String hostUri)

Sets the host reference using an URI string.

Parameters:
  `hostUri` - The host URI.
See Also:
  `Request.setHostRef(String)`

#### setMethod

    public void setMethod(Method method)

Sets the method called.

Parameters:
  `method` - The method called.
See Also:
  `Request.setMethod(Method)`

#### setNext

    public void setNext(Uniform next)

Sets the next handler such as a Restlet or a Filter. In addition, this method will set the context of the next Restlet if it is null by passing a reference to its own context.

Parameters:
  `next` - The next handler.

#### setOnResponse

    public void setOnResponse(Uniform onResponseCallback)

Sets the callback invoked on response reception. If the value is not null, then the associated request will be executed asynchronously.

Parameters:
  `onResponseCallback` - The callback invoked on response reception.

#### setOnSent

    public void setOnSent(Uniform onSentCallback)

Sets the callback invoked after sending the request.

Parameters:
  `onSentCallback` - The callback invoked after sending the request.

#### setOriginalRef

    public void setOriginalRef(Reference originalRef)

Sets the original reference requested by the client.

Parameters:
  `originalRef` - The original reference.
See Also:
  `Request.setOriginalRef(Reference)`

#### setProtocol

    public void setProtocol(Protocol protocol)

Sets the protocol used or to be used.

Parameters:
  `protocol` - The protocol used or to be used.

#### setRanges

    public void setRanges(java.util.List<Range> ranges)

Sets the ranges to return from the target resource's representation.

Parameters:
  `ranges` - The ranges.
See Also:
  `Request.setRanges(List)`

#### setReference

    public void setReference(Reference reference)

Sets the resource's reference. If the reference is relative, it will be resolved as an absolute reference. Also, the context's base reference will be reset. Finally, the reference will be normalized to ensure a consistent handling of the call.

Parameters:
  `reference` - The resource reference.
See Also:
  `Request.setResourceRef(Reference)`

#### setReference

    public void setReference(java.lang.String uri)

Sets the resource's reference using an URI string. Note that the URI can be either absolute or relative to the context's base reference.

Parameters:
  `uri` - The resource URI.
See Also:
  `Request.setResourceRef(String)`

#### setReferrerRef

    public void setReferrerRef(Reference referrerRef)

Sets the referrer reference if available.

Parameters:
  `referrerRef` - The referrer reference.
See Also:
  `Request.setReferrerRef(Reference)`

#### setReferrerRef

    public void setReferrerRef(java.lang.String referrerUri)

Sets the referrer reference if available using an URI string.

Parameters:
  `referrerUri` - The referrer URI.
See Also:
  `Request.setReferrerRef(String)`

#### setRetryAttempts

    public void setRetryAttempts(int retryAttempts)

Sets the number of retry attempts before reporting an error.

Parameters:
  `retryAttempts` - The number of retry attempts before reporting an error.

#### setRetryDelay

    public void setRetryDelay(long retryDelay)

Sets the delay in milliseconds between two retry attempts. The default value is two seconds.

Parameters:
  `retryDelay` - The delay in milliseconds between two retry attempts.

#### setRetryOnError

    public void setRetryOnError(boolean retryOnError)

Indicates if idempotent requests should be retried on error.

Parameters:
  `retryOnError` - True if idempotent requests should be retried on error.

#### wrap

    public <T> T wrap(java.lang.Class<? extends T> resourceInterface)

Wraps the client resource to proxy calls to the given Java interface into Restlet method calls.

Type Parameters:
  `T` -
Parameters:
  `resourceInterface` - The annotated resource interface class to proxy.
Returns:
  The proxy instance.