EntityResponseBuilder.java

package net.eusashead.hateoas.response;

/*
 * #[license]
 * spring-responseentitybuilder
 * %%
 * Copyright (C) 2013 Eusa's Head
 * %%
 * 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.
 * %[license]
 */

import java.util.Date;

import net.eusashead.hateoas.header.ETagHeaderStrategy;

import org.springframework.http.ResponseEntity;

/**
 * Create an appropriate 
 * response to a GET or HEAD request.
 * 
 * For GET, the returned {@link ResponseEntity}
 * should have status code 200, a body of type T 
 * and ETag, Last-Modified, Expires and 
 * Cache-Control headers
 * 
 * For HEAD, the returned {@link ResponseEntity}
 * should have status code 204, a null body and 
 * ETag, Last-Modified, Expires and 
 * Cache-Control headers
 *
 * @author patrickvk
 *
 * @param <T>
 */
public interface EntityResponseBuilder<T> extends ResponseBuilder<T> {
	
	/**
	 * Set the wrapped entity
	 * that this response represents
	 * @param entity
	 * @return this {@link EntityResponseBuilder}
	 */
	EntityResponseBuilder<T> entity(T entity);

	/**
	 * Create ETag header based
	 * on the best available
	 * {@link ETagStrategy}
	 * @return this {@link EntityResponseBuilder}
	 */
	EntityResponseBuilder<T> etag();
	
	/**
	 * Create ETag header based
	 * on the supplied
	 * {@link ETagStrategy}
	 * @return this {@link EntityResponseBuilder}
	 */
	EntityResponseBuilder<T> etag(ETagHeaderStrategy strategy);

	/**
	 * Create a weak ETag based
	 * on the supplied date
	 * @param date {@link Date} last modification date
	 * @return this {@link EntityResponseBuilder}
	 */
	EntityResponseBuilder<T> etag(Date date);

	/**
	 * Create a strong ETag based
	 * on the supplied version
	 * number
	 * @param version {@link Integer} version number
	* @return this {@link EntityResponseBuilder}
	 */
	EntityResponseBuilder<T> etag(Integer version);
	
	/**
	 * Create a strong ETag based
	 * on the supplied version
	 * number
	 * @param version {@link Long} version number
	 * @return this {@link EntityResponseBuilder}
	 */
	EntityResponseBuilder<T> etag(Long version);
	
	/**
	 * Set the Last-Modified header
	 * based on the supplied date
	 * @param date {@link Date} last modification date
	 * @return this {@link EntityResponseBuilder}
	 */
	EntityResponseBuilder<T> lastModified(Date date);

	
	/**
	 * Set the the Expires and
	 * Cache-Control headers
	 * based on the supplied 
	 * number of milliseconds
	 * @param millis to cache the object for
	 * @return this {@link EntityResponseBuilder}
	 */
	EntityResponseBuilder<T> expireIn(long millis);
	
}