org.glassfish.jersey.message.MessageBodyWorkers Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jaxrs-ri Show documentation
Show all versions of jaxrs-ri Show documentation
A bundle project producing JAX-RS RI bundles. The primary artifact is an "all-in-one" OSGi-fied JAX-RS RI bundle
(jaxrs-ri.jar).
Attached to that are two compressed JAX-RS RI archives. The first archive (jaxrs-ri.zip) consists of binary RI bits and
contains the API jar (under "api" directory), RI libraries (under "lib" directory) as well as all external
RI dependencies (under "ext" directory). The secondary archive (jaxrs-ri-src.zip) contains buildable JAX-RS RI source
bundle and contains the API jar (under "api" directory), RI sources (under "src" directory) as well as all external
RI dependencies (under "ext" directory). The second archive also contains "build.xml" ANT script that builds the RI
sources. To build the JAX-RS RI simply unzip the archive, cd to the created jaxrs-ri directory and invoke "ant" from
the command line.
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2010-2013 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 org.glassfish.jersey.message;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.lang.annotation.Annotation;
import java.lang.reflect.Type;
import java.util.List;
import java.util.Map;
import javax.ws.rs.WebApplicationException;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.MultivaluedMap;
import javax.ws.rs.ext.MessageBodyReader;
import javax.ws.rs.ext.MessageBodyWriter;
import javax.ws.rs.ext.ReaderInterceptor;
import javax.ws.rs.ext.WriterInterceptor;
import org.glassfish.jersey.internal.PropertiesDelegate;
/**
* An injectable interface providing lookup of {@link MessageBodyReader} and
* {@link MessageBodyWriter} instances.
*
* @author Paul Sandoz
* @see javax.ws.rs.core.Context
* @see MessageBodyReader
* @see MessageBodyWriter
*/
public interface MessageBodyWorkers {
/**
* Get the map of media type to list of message body writers that are compatible with
* a media type.
*
* @param mediaType the compatible media type.
* @return the map of media type to list of message body writers.
*/
public Map> getReaders(MediaType mediaType);
/**
* Get the map of media type to list of message body writers that are compatible with
* a media type.
*
* @param mediaType the compatible media type.
* @return the map of media type to list of message body writers.
*/
public Map> getWriters(MediaType mediaType);
/**
* Convert a map media type to list of message body readers to a string.
*
* @param readers the map media type to list of message body readers
* @return the string representation.
*/
public String readersToString(Map> readers);
/**
* Convert a map media type to list of message body writers to a string.
*
* @param writers the map media type to list of message body readers
* @return the string representation.
*/
public String writersToString(Map> writers);
/**
* Get a message body reader that matches a set of criteria.
*
* @param the type of object to be read.
* @param type the class of object to be read.
* @param genericType the type of object to be produced. E.g. if the message body is
* to be converted into a method parameter, this will be the formal type of
* the method parameter as returned by
* {@code Class.getGenericParameterTypes}.
* @param annotations an array of the annotations on the declaration of the artifact
* that will be initialized with the produced instance. E.g. if the message
* body is to be converted into a method parameter, this will be the
* annotations on that parameter returned by
* {@code Class.getParameterAnnotations}.
* @param mediaType the media type of the data that will be read, this will be
* compared to the values of {@link javax.ws.rs.Consumes} for each
* candidate reader and only matching readers will be queried.
* @return a MessageBodyReader that matches the supplied criteria or null if none is
* found.
*/
MessageBodyReader getMessageBodyReader(Class type, Type genericType, Annotation annotations[], MediaType mediaType);
/**
* Get a message body reader that matches a set of criteria.
*
* @param the type of object to be read.
* @param type the class of object to be read.
* @param genericType the type of object to be produced. E.g. if the message body is
* to be converted into a method parameter, this will be the formal type of
* the method parameter as returned by
* {@code Class.getGenericParameterTypes}.
* @param annotations an array of the annotations on the declaration of the artifact
* that will be initialized with the produced instance. E.g. if the message
* body is to be converted into a method parameter, this will be the
* annotations on that parameter returned by
* {@code Class.getParameterAnnotations}.
* @param mediaType the media type of the data that will be read, this will be
* compared to the values of {@link javax.ws.rs.Consumes} for each
* candidate reader and only matching readers will be queried.
* @param propertiesDelegate request-scoped properties delegate.
* @return a MessageBodyReader that matches the supplied criteria or null if none is
* found.
*/
MessageBodyReader getMessageBodyReader(Class type, Type genericType, Annotation annotations[], MediaType mediaType,
PropertiesDelegate propertiesDelegate);
/**
* Get a message body writer that matches a set of criteria.
*
* @param the type of the object that is to be written.
* @param type the class of object that is to be written.
* @param genericType the type of object to be written. E.g. if the message body is to
* be produced from a field, this will be the declared type of the field as
* returned by {@code Field.getGenericType}.
* @param annotations an array of the annotations on the declaration of the artifact
* that will be written. E.g. if the message body is to be produced from a
* field, this will be the annotations on that field returned by
* {@code Field.getDeclaredAnnotations}.
* @param mediaType the media type of the data that will be written, this will be
* compared to the values of {@link javax.ws.rs.Produces} for each
* candidate writer and only matching writers will be queried.
* @return a MessageBodyReader that matches the supplied criteria or null if none is
* found.
*/
MessageBodyWriter getMessageBodyWriter(Class type, Type genericType, Annotation annotations[], MediaType mediaType);
/**
* Get a message body writer that matches a set of criteria.
*
* @param the type of the object that is to be written.
* @param type the class of object that is to be written.
* @param genericType the type of object to be written. E.g. if the message body is to
* be produced from a field, this will be the declared type of the field as
* returned by {@code Field.getGenericType}.
* @param annotations an array of the annotations on the declaration of the artifact
* that will be written. E.g. if the message body is to be produced from a
* field, this will be the annotations on that field returned by
* {@code Field.getDeclaredAnnotations}.
* @param mediaType the media type of the data that will be written, this will be
* compared to the values of {@link javax.ws.rs.Produces} for each
* candidate writer and only matching writers will be queried.
* @param propertiesDelegate request-scoped properties delegate.
* @return a MessageBodyReader that matches the supplied criteria or null if none is
* found.
*/
MessageBodyWriter getMessageBodyWriter(Class type, Type genericType, Annotation annotations[], MediaType mediaType,
PropertiesDelegate propertiesDelegate);
/**
* Get the list of media types supported for a Java type.
*
* @param type the class of object that is to be read.
* @param genericType the type of object to be read. E.g. if the message body is to be
* read as a method parameter, this will be the declared type of the
* parameter as returned by {@code Method.getGenericParameterTypes}.
* @param annotations an array of the annotations on the declaration of the artifact
* that will be read. E.g. if the message body is to be consumed as a
* method parameter, this will be the annotations on that parameter
* returned by {@code Method.getParameterAnnotations}.
* @return the list of supported media types, the list is ordered as follows: a/b <
* a/* < *\\/*
*/
List getMessageBodyReaderMediaTypes(Class type, Type genericType, Annotation[] annotations);
/**
* Get the list of media types supported for a Java type.
*
* @param type the class of object that is to be read.
* @return the list of supported media types, the list is ordered as follows: a/b <
* a/* < *\\/*
*/
List getMessageBodyReaderMediaTypesByType(Class type);
/**
* Get a list of {@code MessageBodyReader}s that are suitable for the given {@code type}. The list is sorted based on the
* class hierarchy (most specific readers are first).
*
* @param type the class of object readers are requested for.
* @return the list of supported {@code MessageBodyReader}s for given class.
*/
List getMessageBodyReadersForType(Class type);
/**
* Get the list of media types supported for a Java type.
*
* @param type the class of object that is to be written.
* @param genericType the type of object to be written. E.g. if the message body is to
* be produced from a field, this will be the declared type of the field as
* returned by {@code Field.getGenericType}.
* @param annotations an array of the annotations on the declaration of the artifact
* that will be written. E.g. if the message body is to be produced from a
* field, this will be the annotations on that field returned by
* {@code Field.getDeclaredAnnotations}.
* @return the list of supported media types, the list is ordered as follows: a/b <
* a/* < *\\/*
*/
List getMessageBodyWriterMediaTypes(Class type, Type genericType, Annotation[] annotations);
/**
* Get the list of media types supported for a Java type.
*
* @param type the class of object that is to be written.
* @return the list of supported media types, the list is ordered as follows: a/b <
* a/* < *\\/*
*/
List getMessageBodyWriterMediaTypesByType(Class type);
/**
* Get a list of {@code MessageBodyWriter}s that are suitable for the given {@code type}. The list is sorted based on the
* class hierarchy (most specific writers are first).
*
* @param type the class of object writers are requested for.
* @return the list of supported {@code MessageBodyWriter}s for given class.
*/
List getMessageBodyWritersForType(Class type);
/**
* Get the most acceptable media type supported for a Java type given a set of
* acceptable media types.
*
* @param type the class of object that is to be written.
* @param genericType the type of object to be written. E.g. if the message body is to
* be produced from a field, this will be the declared type of the field as
* returned by {@code Field.getGenericType}.
* @param annotations an array of the annotations on the declaration of the artifact
* that will be written. E.g. if the message body is to be produced from a
* field, this will be the annotations on that field returned by
* {@code Field.getDeclaredAnnotations}.
* @param acceptableMediaTypes the list of acceptable media types, sorted according to
* the quality with the media type of highest quality occurring first
* first.
* @return the best media types
*/
MediaType getMessageBodyWriterMediaType(Class type, Type genericType, Annotation[] annotations,
List acceptableMediaTypes);
/**
* Reads a type from the {@link InputStream entityStream} using interceptors. If the
* parameter {@code intercept} is true then {@link ReaderInterceptor reader
* interceptors} are executed before calling the {@link MessageBodyReader message
* body reader}. The appropriate {@link MessageBodyReader message body reader} is
* chosen after the interceptor execution based on parameter passed to this method
* and modified by the interceptors.
*
* @param rawType raw Java entity type.
* @param type generic Java entity type.
* @param annotations an array of the annotations on the declaration of the artifact
* that will be initialized with the produced instance. E.g. if the message
* body is to be converted into a method parameter, this will be the
* annotations on that parameter returned by
* {@code Method.getParameterAnnotations}.
* @param mediaType the media type of the HTTP entity.
* @param httpHeaders the mutable HTTP headers associated with HTTP entity.
* @param propertiesDelegate request-scoped properties delegate.
* @param entityStream the {@link InputStream} of the HTTP entity. The stream is not
* closed after reading the entity.
* @param readerInterceptors Reader interceptor that are to be used to intercept the reading of an entity. The interceptors
* will be executed in the same order as given in this parameter.
* @param translateNce if {@code true}, the {@link javax.ws.rs.core.NoContentException} thrown by a selected message body
* reader will be translated into a {@link javax.ws.rs.BadRequestException} as required by
* JAX-RS specification on the server side.
* @return the entity that was read from the {@code entityStream}.
* @throws WebApplicationException Thrown when {@link MessageBodyReader message body
* reader} fails.
* @throws IOException Thrown when reading from the {@code entityStream} fails.
*/
public Object readFrom(Class rawType,
Type type,
Annotation[] annotations,
MediaType mediaType,
MultivaluedMap httpHeaders,
PropertiesDelegate propertiesDelegate,
InputStream entityStream,
Iterable readerInterceptors,
boolean translateNce)
throws WebApplicationException, IOException;
/**
* Writers a type to the {@link OutputStream entityStream} using interceptors. If the
* parameter {@code intercept} is true then {@link WriterInterceptor writer
* interceptors} are executed before calling the {@link MessageBodyWriter message
* body writer}. The appropriate {@link MessageBodyWriter message body writer} is
* chosen after the interceptor execution based on parameter passed to this method
* and modified by the interceptors.
*
* @param entity Entity to be written to the entityStream
* @param rawType raw Java entity type.
* @param type generic Java entity type.
* @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 the mutable HTTP headers associated with HTTP entity.
* @param propertiesDelegate request-scoped properties delegate.
* @param entityStream the {@link OutputStream} for the HTTP entity.
* @param writerInterceptors Writer interceptor that are to be used to intercept the writing of an entity. The interceptors
* will be executed in the same order as given in this parameter.
* @return Outer output stream that should be closed by the caller.
* @throws WebApplicationException Thrown when {@link MessageBodyReader message body
* reader} fails.
* @throws IOException Thrown when reading from the {@code entityStream} fails.
*/
public OutputStream writeTo(Object entity, Class rawType, Type type, Annotation[] annotations, MediaType mediaType,
MultivaluedMap httpHeaders, PropertiesDelegate propertiesDelegate,
OutputStream entityStream,
Iterable writerInterceptors)
throws java.io.IOException, javax.ws.rs.WebApplicationException;
}