javax.ws.rs.ext.MessageBodyWriter Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of ehcache Show documentation
Show all versions of ehcache Show documentation
Ehcache is an open source, standards-based cache used to boost performance,
offload the database and simplify scalability. Ehcache is robust, proven and full-featured and
this has made it the most widely-used Java-based cache.
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the "License"). You may not use this file except
* in compliance with the License.
*
* You can obtain a copy of the license at
* http://www.opensource.org/licenses/cddl1.php
* See the License for the specific language governing
* permissions and limitations under the License.
*/
/*
* MessageBodyWriter.java
*
* Created on November 8, 2007, 3:57 PM
*
*/
package javax.ws.rs.ext;
import java.io.IOException;
import java.io.OutputStream;
import java.lang.annotation.Annotation;
import java.lang.reflect.Type;
import javax.ws.rs.WebApplicationException;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.MultivaluedMap;
/**
* Contract for a provider that supports the conversion of a Java type to a
* stream. To add a MessageBodyWriter implementation, annotate the
* implementation class with @Provider.
*
* A MessageBodyWriter implementation may be annotated
* with {@link javax.ws.rs.Produces} to restrict the media types for which it will
* be considered suitable.
*
* @param T the type that can be written
* @see Provider
* @see javax.ws.rs.Produces
*/
public interface MessageBodyWriter {
/**
* Ascertain if the MessageBodyWriter supports a particular type.
*
* @param type the class of object that is to be written.
* @param genericType the type of object to be written, obtained either
* by reflection of a resource method return type or via inspection
* of the returned instance. {@link javax.ws.rs.core.GenericEntity}
* provides a way to specify this information at runtime.
* @param annotations an array of the annotations on the resource
* method that returns the object.
* @param mediaType the media type of the HTTP entity.
* @return true if the type is supported, otherwise false.
*/
boolean isWriteable(Class type, Type genericType,
Annotation annotations[], MediaType mediaType);
/**
* Called before writeTo to ascertain the length in bytes of
* the serialized form of t. A non-negative return value is
* used in a HTTP Content-Length header.
* @param t the instance to write
* @param type the class of object that is to be written.
* @param genericType the type of object to be written, obtained either
* by reflection of a resource method return type or by inspection
* of the returned instance. {@link javax.ws.rs.core.GenericEntity}
* provides a way to specify this information at runtime.
* @param annotations an array of the annotations on the resource
* method that returns the object.
* @param mediaType the media type of the HTTP entity.
* @return length in bytes or -1 if the length cannot be determined in
* advance
*/
long getSize(T t, Class type, Type genericType, Annotation annotations[],
MediaType mediaType);
/**
* Write a type to an HTTP response. The response header map is mutable
* but any changes must be made before writing to the output stream since
* the headers will be flushed prior to writing the response body.
*
* @param t the instance to write.
* @param type the class of object that is to be written.
* @param genericType the type of object to be written, obtained either
* by reflection of a resource method return type or by inspection
* of the returned instance. {@link javax.ws.rs.core.GenericEntity}
* provides a way to specify this information at runtime.
* @param annotations an array of the annotations on the resource
* method that returns the object.
* @param mediaType the media type of the HTTP entity.
* @param httpHeaders a mutable map of the HTTP response headers.
* @param entityStream the {@link OutputStream} for the HTTP entity. The
* implementation should not close the output stream.
* @throws java.io.IOException if an IO error arises
* @throws javax.ws.rs.WebApplicationException if a specific
* HTTP error response needs to be produced. Only effective if thrown prior
* to the response being committed.
*/
void writeTo(T t, Class type, Type genericType, Annotation annotations[],
MediaType mediaType,
MultivaluedMap httpHeaders,
OutputStream entityStream) throws IOException, WebApplicationException;
}