Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2010-2012 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* http://glassfish.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.ws.rs.core;
import java.io.InputStream;
import java.lang.annotation.Annotation;
import java.net.URI;
import java.util.Date;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import javax.ws.rs.ext.MessageBodyReader;
import javax.ws.rs.ext.MessageBodyWriter;
import javax.ws.rs.ext.RuntimeDelegate;
/**
* Defines the contract between a returned instance and the runtime when
* an application needs to provide meta-data to the runtime. An application
* class can extend this class directly or can use one of the static
* methods to create an instance using a ResponseBuilder.
*
* Several methods have parameters of type URI, {@link UriBuilder} provides
* convenient methods to create such values as does {@link URI#create(java.lang.String)}.
*
* @author Paul Sandoz
* @author Marc Hadley
* @author Marek Potociar
* @see Response.ResponseBuilder
* @since 1.0
*/
public abstract class Response {
/**
* Protected constructor, use one of the static methods to obtain a
* {@link ResponseBuilder} instance and obtain a Response from that.
*/
protected Response() {
}
/**
* Get a mutable map of request-scoped properties that can be used for communication
* between different request/response processing components. May be empty, but
* MUST never be {@code null}. In the scope of a single request/response processing,
* a same property map instance is shared by the following methods:
*
* A request-scoped property is an application-defined property that may be
* added, removed or modified by any of the components (user, filter, interceptor etc.)
* that participate in a given request/response processing flow.
*
* On the client side, this property map is initialized by calling
* {@link javax.ws.rs.client.Configuration#setProperties(java.util.Map) } or
* {@link javax.ws.rs.client.Configuration#setProperty(java.lang.String, java.lang.Object) }
* on the configuration object associated with the corresponding
* {@link javax.ws.rs.client.Invocation request invocation}.
*
* On the server side, specifying the initial values is implementation-specific.
*
* If there are no initial properties set, the request-scoped property map is
* initialized to an empty map.
*
* @return a mutable request-scoped property map.
* @see javax.ws.rs.client.Configuration
*
* @since 2.0
*/
public abstract Map getProperties();
/**
* Get the status code associated with the response.
*
* @return the response status code or -1 if the status was not set.
*/
public abstract int getStatus();
/**
* Get the response status represented as a response {@link Status} enumeration
* value.
*
* @return the status type instance, or {@code null} if there is no
* mapping between the integer status code and the
* {@link javax.ws.rs.core.Response.Status response status enumeration} value.
* @since 2.0
*/
public abstract Status getStatusEnum();
/**
* Get the response message headers. This method never returns {@code null}.
*
* @return response message headers. Returned headers may be empty but never
* {@code null}.
* @see javax.ws.rs.ext.RuntimeDelegate.HeaderDelegate
*
* @since 2.0
*/
public abstract ResponseHeaders getHeaders();
/**
* Get the message entity Java instance. Returns {@code null} if the message
* does not contain an entity body.
*
* @return the message entity or {@code null} if message does not contain an
* entity body.
* @throws IllegalStateException in case the existing message entity is not
* {@link #isEntityRetrievable() retrievable} as a Java type. This is
* typically the case (on the client side) when the entity input stream
* has not been read as a Java type using one of the {@code readEntity(...)}
* methods yet.
* @throws MessageProcessingException if the entity was previously fully consumed
* as an {@link InputStream input stream}.
*
* @see #hasEntity()
* @see #isEntityRetrievable()
* @see #readEntity(java.lang.Class)
* @see #readEntity(javax.ws.rs.core.TypeLiteral)
* @see #bufferEntity()
* @see javax.ws.rs.ext.MessageBodyWriter
*/
public abstract Object getEntity() throws IllegalStateException, MessageProcessingException;
/**
* Read the message entity as an instance of specified Java type using
* a {@link javax.ws.rs.ext.MessageBodyReader} that supports mapping the
* message entity stream onto the requested type. Returns {@code null} if
* the message does not contain an entity body. Unless the supplied entity
* type is an {@link java.io.InputStream input stream}, this method automatically
* {@link #close() closes} the consumed response entity stream (if open) and
* makes the entity {@link #isEntityRetrievable() available for retrieval}.
*
* A non-null message instance returned from this method will be cached for
* subsequent retrievals via {@link #getEntity()}.
* If the message has previously been read as an instance of a different Java type,
* invoking this method will cause the cached entity instance to be serialized
* into a temporary input stream using a compatible {@link javax.ws.rs.ext.MessageBodyWriter}
* and then read again from the stream. This operation is thus potentially
* expensive and should be used with care.
*
* Note that a message entity can also be read as a raw entity
* {@link java.io.InputStream input stream}, in which case it will be fully
* consumed once the reading from the entity input stream is finished.
* Once the entity is read as an input stream, any subsequent calls to
* one of the {@code readEntity(...)} methods or {@link #getEntity()} method
* on the same message instance will result in a {@link MessageProcessingException}
* being thrown. It is up to the consumer of the entity input stream to ensure
* that consuming the stream is properly mitigated (e.g. by substituting the
* consumed response instance with a new one etc.).
*
* @param entity instance Java type.
* @param type the type of entity.
* @return the message entity or {@code null} if message does not contain an
* entity body.
* @throws MessageProcessingException if the content of the message cannot be
* mapped to an entity of the requested type or if the entity input stream
* was previously directly consumed by invoking {@code readEntity(InputStream.class)}.
* @see #hasEntity()
* @see #isEntityRetrievable()
* @see #getEntity()
* @see #readEntity(java.lang.Class, java.lang.annotation.Annotation[])
* @see #readEntity(javax.ws.rs.core.TypeLiteral)
* @see #readEntity(javax.ws.rs.core.TypeLiteral, java.lang.annotation.Annotation[])
* @see #bufferEntity()
* @see #close()
* @see javax.ws.rs.ext.MessageBodyWriter
* @see javax.ws.rs.ext.MessageBodyReader
* @since 2.0
*/
public abstract T readEntity(Class type) throws MessageProcessingException;
/**
* Read the message entity as an instance of specified (generic) Java type using
* a {@link javax.ws.rs.ext.MessageBodyReader} that supports mapping the
* message entity stream onto the requested type. Returns {@code null} if
* the message does not contain an entity body. Unless the supplied entity
* type is an {@link java.io.InputStream input stream}, this method automatically
* {@link #close() closes} the consumed response entity stream (if open) and
* makes the entity {@link #isEntityRetrievable() available for retrieval}.
*
* A non-null message instance returned from this method will be cached for
* subsequent retrievals via {@link #getEntity()}.
* If the message has previously been read as an instance of a different Java type,
* invoking this method will cause the cached entity instance to be serialized
* into a temporary input stream using a compatible {@link javax.ws.rs.ext.MessageBodyWriter}
* and then read again from the stream. This operation is thus potentially
* expensive and should be used with care.
*
* Note that a message entity can also be read as a raw entity
* {@link java.io.InputStream input stream}, in which case it will be fully
* consumed once the reading from the entity input stream is finished.
* Once the entity is read as an input stream, any subsequent calls to
* one of the {@code readEntity(...)} methods or {@link #getEntity()} method
* on the same message instance will result in a {@link MessageProcessingException}
* being thrown. It is up to the consumer of the entity input stream to ensure
* that consuming the stream is properly mitigated (e.g. by substituting the
* consumed response instance with a new one etc.).
*
* @param entity instance Java type.
* @param entityType the type of entity; may be generic.
* @return the message entity or {@code null} if message does not contain an
* entity body.
* @throws MessageProcessingException if the content of the message cannot be
* mapped to an entity of the requested type or if the entity input stream
* was previously directly consumed by invoking {@code readEntity(InputStream.class)}.
* @see #hasEntity()
* @see #isEntityRetrievable()
* @see #getEntity()
* @see #readEntity(javax.ws.rs.core.TypeLiteral, java.lang.annotation.Annotation[])
* @see #readEntity(java.lang.Class)
* @see #readEntity(java.lang.Class, java.lang.annotation.Annotation[])
* @see #bufferEntity()
* @see #close()
* @see javax.ws.rs.ext.MessageBodyWriter
* @see javax.ws.rs.ext.MessageBodyReader
* @since 2.0
*/
public abstract T readEntity(TypeLiteral entityType) throws MessageProcessingException;
/**
* Read the message entity as an instance of specified Java type using
* a {@link javax.ws.rs.ext.MessageBodyReader} that supports mapping the
* message entity stream onto the requested type. Returns {@code null} if
* the message does not contain an entity body. Unless the supplied entity
* type is an {@link java.io.InputStream input stream}, this method automatically
* {@link #close() closes} the consumed response entity stream (if open) and
* makes the entity {@link #isEntityRetrievable() available for retrieval}.
*
* A non-null message instance returned from this method will be cached for
* subsequent retrievals via {@link #getEntity()}.
* If the message has previously been read as an instance of a different Java type,
* invoking this method will cause the cached entity instance to be serialized
* into a temporary input stream using a compatible {@link javax.ws.rs.ext.MessageBodyWriter}
* and then read again from the stream. This operation is thus potentially
* expensive and should be used with care.
*
* Note that a message entity can also be read as a raw entity
* {@link java.io.InputStream input stream}, in which case it will be fully
* consumed once the reading from the entity input stream is finished.
* Once the entity is read as an input stream, any subsequent calls to
* one of the {@code readEntity(...)} methods or {@link #getEntity()} method
* on the same message instance will result in a {@link MessageProcessingException}
* being thrown. It is up to the consumer of the entity input stream to ensure
* that consuming the stream is properly mitigated (e.g. by substituting the
* consumed response instance with a new one etc.).
*
* @param entity instance Java type.
* @param type the type of entity.
* @param annotations annotations that will be passed to the {@link MessageBodyReader}.
* @return the message entity or {@code null} if message does not contain an
* entity body.
* @throws MessageProcessingException if the content of the message cannot be
* mapped to an entity of the requested type or if the entity input stream
* was previously directly consumed by invoking {@code readEntity(InputStream.class)}.
* @see #hasEntity()
* @see #isEntityRetrievable()
* @see #getEntity()
* @see #readEntity(java.lang.Class)
* @see #readEntity(javax.ws.rs.core.TypeLiteral)
* @see #readEntity(javax.ws.rs.core.TypeLiteral, java.lang.annotation.Annotation[])
* @see #bufferEntity()
* @see #close()
* @see javax.ws.rs.ext.MessageBodyWriter
* @see javax.ws.rs.ext.MessageBodyReader
* @since 2.0
*/
public abstract T readEntity(Class type, Annotation[] annotations) throws MessageProcessingException;
/**
* Read the message entity as an instance of specified (generic) Java type using
* a {@link javax.ws.rs.ext.MessageBodyReader} that supports mapping the
* message entity stream onto the requested type. Returns {@code null} if
* the message does not contain an entity body. Unless the supplied entity
* type is an {@link java.io.InputStream input stream}, this method automatically
* {@link #close() closes} the consumed response entity stream (if open) and
* makes the entity {@link #isEntityRetrievable() available for retrieval}.
*
* A non-null message instance returned from this method will be cached for
* subsequent retrievals via {@link #getEntity()}.
* If the message has previously been read as an instance of a different Java type,
* invoking this method will cause the cached entity instance to be serialized
* into a temporary input stream using a compatible {@link javax.ws.rs.ext.MessageBodyWriter}
* and then read again from the stream. This operation is thus potentially
* expensive and should be used with care.
*
* Note that a message entity can also be read as a raw entity
* {@link java.io.InputStream input stream}, in which case it will be fully
* consumed once the reading from the entity input stream is finished.
* Once the entity is read as an input stream, any subsequent calls to
* one of the {@code readEntity(...)} methods or {@link #getEntity()} method
* on the same message instance will result in a {@link MessageProcessingException}
* being thrown. It is up to the consumer of the entity input stream to ensure
* that consuming the stream is properly mitigated (e.g. by substituting the
* consumed response instance with a new one etc.).
*
* @param entity instance Java type.
* @param entityType the type of entity; may be generic.
* @param annotations annotations that will be passed to the {@link MessageBodyReader}.
* @return the message entity or {@code null} if message does not contain an
* entity body.
* @throws MessageProcessingException if the content of the message cannot be
* mapped to an entity of the requested type or if the entity input stream
* was previously directly consumed by invoking {@code readEntity(InputStream.class)}.
* @see #hasEntity()
* @see #isEntityRetrievable()
* @see #getEntity()
* @see #readEntity(javax.ws.rs.core.TypeLiteral)
* @see #readEntity(java.lang.Class)
* @see #readEntity(java.lang.Class, java.lang.annotation.Annotation[])
* @see #bufferEntity()
* @see #close()
* @see javax.ws.rs.ext.MessageBodyWriter
* @see javax.ws.rs.ext.MessageBodyReader
* @since 2.0
*/
public abstract T readEntity(TypeLiteral entityType, Annotation[] annotations) throws MessageProcessingException;
/**
* Check if there is an entity available in the response. The method returns
* {@code true} if the entity is present, returns {@code false} otherwise.
*
* In case the message contained an entity, but it was already consumed as
* an input stream via {@code readEntity(InputStream.class)}, the method
* returns {@code false}.
*
* @return {@code true} if there is an entity present in the message,
* {@code false} otherwise.
* @see #isEntityRetrievable()
* @see #getEntity()
* @see #readEntity(java.lang.Class)
* @see #readEntity(java.lang.Class, java.lang.annotation.Annotation[])
* @see #readEntity(javax.ws.rs.core.TypeLiteral)
* @see #readEntity(javax.ws.rs.core.TypeLiteral, java.lang.annotation.Annotation[])
* @since 2.0
*/
public abstract boolean hasEntity();
/**
* Check if the entity instance is {@link #hasEntity() present} and available
* for a retrieval via {@link #getEntity()}.
*
* The method returns {@code true} if the entity is retrievable, returns {@code false}
* in case there is no entity associated with the message or if the existing
* message entity is not available as a Java type. This is typically the case
* (on the client side) when the entity input stream has not been consumed
* using one of the {@code readEntity(...)} methods yet.
*
* Note that even though {@link #bufferEntity() entity buffering} closes
* the original entity input stream, the buffered entity may still not be
* retrievable, unless the buffered data was previously read using one of the
* {@code readEntity(...)} methods.
*
* @return {@code true} if there is a retrievable message entity instance
* present, {@code false} otherwise.
* @see #hasEntity()
* @see #getEntity()
* @see #readEntity(java.lang.Class)
* @see #readEntity(javax.ws.rs.core.TypeLiteral)
* @see #bufferEntity()
* @since 2.0
*/
public abstract boolean isEntityRetrievable();
/**
* Buffer the message entity.
*
* In case the message entity input stream is open, all the bytes of the
* original entity input stream are read and stored in memory. The original
* entity input stream is automatically {@link #close() closed} as part of
* the operation.
*
* This operation is idempotent, i.e. it can be invoked multiple times with
* the same effect which also means that calling the {@code bufferEntity()}
* method on an already buffered (and thus closed) message instance is legal
* and has no further effect.
*
* Note that even though entity buffering closes the original entity input
* stream, the buffered entity may still not be {@link #isEntityRetrievable()
* retrievable}, unless the buffered data was previously read using one of
* the {@code readEntity(...)} methods.
*
* @throws MessageProcessingException if there is an error buffering the
* message entity.
* @see #hasEntity()
* @see #isEntityRetrievable()
* @see #getEntity()
* @see #readEntity(java.lang.Class)
* @see #readEntity(javax.ws.rs.core.TypeLiteral)
* @see #close()
* @since 2.0
*/
public abstract void bufferEntity() throws MessageProcessingException;
/**
* Close the message entity input stream (if available and open).
*
* This operation is idempotent, i.e. it can be invoked multiple times with the
* same effect which also means that calling the {@code close()} method on an
* already closed message instance is legal and has no further effect.
*
* The {@code close()} method should be invoked on all instances that
* contain an un-consumed entity input stream to ensure the resources associated
* with the instance are properly cleaned-up and prevent potential memory leaks.
* This is typical for client-side scenarios where application layer code
* processes only the response headers and ignores the response entity.
*
* If the {@code close()} method is invoked before the message entity has been
* fully read from the input stream, any subsequent attempt to read the entity
* will result in an {@link MessageProcessingException} being thrown.
*
* Closing an instance that has already been consumed has no effect. Similarly,
* closing an instance with no entity has not effect.
*
* @throws MessageProcessingException if there is an error closing the response.
* @see #readEntity(java.lang.Class)
* @see #readEntity(javax.ws.rs.core.TypeLiteral)
* @since 2.0
*/
public abstract void close() throws MessageProcessingException;
/**
* Get metadata (headers) associated with the response as a map. The returned map
* may be subsequently modified by the JAX-RS runtime. Values will be
* serialized using a {@link javax.ws.rs.ext.RuntimeDelegate.HeaderDelegate}
* if one is available via
* {@link javax.ws.rs.ext.RuntimeDelegate#createHeaderDelegate(java.lang.Class)}
* for the class of the value or using the values {@code toString} method if a
* header delegate is not available.
*
* This method is effectively a shortcut for
* {@link #getHeaders()}.{@link ResponseHeaders#asMap() asMap()} and may be
* deprecated in the future versions of JAX-RS API.
*
* @return response metadata (headers) as a map.
*/
public abstract MultivaluedMap getMetadata();
/**
* Create a new ResponseBuilder by performing a shallow copy of an
* existing Response.
*
* The returned builder has its own {@link ResponseHeaders response headers}
* but the header values are shared with the original {@code Response} instance.
* If {@link #isEntityRetrievable() retrievable}, the original response entity
* instance is set in the new response builder.
*
* @param response a Response from which the status code, entity
* (if {@link #isEntityRetrievable() retrievable}) and response headers
* will be copied.
* @return a new ReponseBuilder.
*/
public static ResponseBuilder fromResponse(Response response) {
ResponseBuilder b = status(response.getStatus());
if (response.isEntityRetrievable()) {
b.entity(response.getEntity());
}
for (String headerName : response.getMetadata().keySet()) {
List