org.mattressframework.api.HttpEntityWriter Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of mattress-api Show documentation
Public API to the Mattress framework. This is essentially what JSR 311 should be.
The newest version!
/*
 * Copyright 2007-2008, Josh Devins.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.mattressframework.api;

import java.io.IOException;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.util.Map;

import org.mattressframework.api.annotations.SupportsMediaTypes;
import org.mattressframework.api.http.Header;
import org.mattressframework.api.http.MediaType;

/**
 * Contract for a provider that supports the conversion of a Java type to a
 * stream.
 * 
 * 
 * Implementing classes should be annotated with {@link SupportsMediaTypes} to
 * show what type of media they support. Once a bean of this type has been added
 * to the Spring context, the framework will pick it up automatically, no extra
 * annotations are needed.
 * 
 * 
 * 
 * This differs from the JSR 311 MessageBodyWriter in that it uses
 * the framework's {@link MediaType}.
 * 
 */
public interface HttpEntityWriter extends Provider {

    /**
     * Called before {@link #writeTo(Object, MediaType, Map, OutputStream)} to
     * ascertain the length in bytes of the serialized form of
     * entity. A non-negative return value is used in a HTTP
     * Content-Length header.
     * 
     * @param entity
     *            The entity instance that is to be written to the entity
     *            stream.
     * 
     * @return Length in bytes or -1 if the length cannot be determined in
     *         advance.
     * @deprecated This method does not have enough information (i.e. encoding)
     *             to determine the size of the entity.
     */
    @Deprecated
    int getSize(Object entity);

    /**
     * Write a type to an HTTP response. Implementations should
     * NOT call {@link OutputStream#flush()} after writing to
     * the {@link OutputStream}. The framework will be responsible for doing
     * this.
     * 
     * @param entity
     *            The entity instance that is to be written to the entity
     *            stream.
     * @param mediaType
     *            The media type of the HTTP entity.
     * @param httpHeaders
     *            The HTTP headers associated with HTTP entity.
     * @param entityStream
     *            The {@link OutputStream} of the HTTP entity.
     * 
     * @throws java.io.IOException
     *             If an IO error arises.
     * @deprecated Use
     *             {@link #writeTo(Object, MediaType, Map, OutputStreamWriter)}
     *             to provide an OutputStreamWriter with encoding specified.
     */
    @Deprecated
    void writeTo(Object entity, MediaType mediaType,
            Map httpHeaders, OutputStream entityStream)
            throws IOException;

    /**
     * Write a type to an HTTP response. Implementations should
     * NOT call {@link OutputStream#flush()} after writing to
     * the {@link OutputStreamWriter}. The framework will be responsible for
     * doing this.
     * 
     * @param entity
     *            The entity instance that is to be written to the entity
     *            stream.
     * @param mediaType
     *            The media type of the HTTP entity.
     * @param httpHeaders
     *            The HTTP headers associated with HTTP entity.
     * @param entityWriter
     *            The {@link OutputStreamWriter} of the HTTP entity. If the
     *            character encoding is needed during processing, it can be
     *            retrieved from {@link OutputStreamWriter#getEncoding()}
     * 
     * @throws java.io.IOException
     *             If an IO error arises.
     */
    void writeTo(Object entity, MediaType mediaType,
            Map httpHeaders, OutputStreamWriter entityWriter)
            throws IOException;
}