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.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.RuntimeDelegate;
/**
* Defines the contract between a returned instance and the runtime when
* an application needs to provide metadata 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
* available as a Java type. This is typically the case when the entity
* input stream has not been converted into a Java type using one of the
* {@code readEntity(...)} methods yet (client side).
* @throws MessageProcessingException if the entity was previously fully consumed
* as an {@link InputStream input stream}.
*
* @see #hasEntity()
* @see #readEntity(java.lang.Class)
* @see #readEntity(javax.ws.rs.core.TypeLiteral)
* @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 requested entity
* type is an {@link java.io.InputStream input stream}, this method automatically
* {@link #close() closes} the consumed response entity stream (if open).
*
* 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 #getEntity()
* @see #readEntity(javax.ws.rs.core.TypeLiteral)
* @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 requested entity
* type is an {@link java.io.InputStream input stream}, this method automatically
* {@link #close() closes} the consumed response entity stream (if open).
*
* 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 #getEntity()
* @see #readEntity(java.lang.Class)
* @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;
/**
* 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 response 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 response, {@code false}
* otherwise.
* @see #getEntity()
* @see #readEntity(java.lang.Class)
* @see #readEntity(javax.ws.rs.core.TypeLiteral)
* @since 2.0
*/
public abstract boolean hasEntity();
/**
* Buffer the entity.
*
* All the bytes of the original entity input stream will be read and stored
* in memory. The original entity input stream will then be closed.
*
* @throws MessageProcessingException if there is an error processing the response.
* @since 2.0
*/
public abstract void bufferEntity() throws MessageProcessingException;
/**
* Close the response entity input stream (if available and open) as well as
* any other resources associated with the response.
* 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 response instance is legal and has no further effect.
*
* The {@code close()} method should be invoked on all response 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.
*
* Closing a response that has already been consumed has no effect. Similarly,
* closing a response 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 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()}.
*
* @return response metadata 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 metadata map but
* entries are simply references to the keys and values contained in the
* supplied Response metadata map.
*
* @param response a Response from which the status code, entity and metadata
* will be copied
* @return a new ReponseBuilder
*/
public static ResponseBuilder fromResponse(Response response) {
ResponseBuilder b = status(response.getStatus());
b.entity(response.getEntity());
for (String headerName : response.getMetadata().keySet()) {
List