Define API versioning #47

Added some functions for getting the version of the request, as well as
set a Deprecation header in the response to inform the client.

Signed-off-by: Martin Lowe <martin.lowe@eclipse-foundation.org>

src/main/java/org/eclipsefoundation/marketplace/model/RequestWrapper.java

@@ -8,6 +8,7 @@ package org.eclipsefoundation.marketplace.model;
 
 import java.util.ArrayList;
 import java.util.Collections;
+import java.util.Date;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -16,9 +17,12 @@ import java.util.Optional;
 
 import javax.enterprise.context.RequestScoped;
 import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
 import javax.ws.rs.core.UriInfo;
 
 import org.apache.commons.lang3.StringUtils;
+import org.eclipsefoundation.marketplace.namespace.DeprecatedHeader;
+import org.eclipsefoundation.marketplace.namespace.RequestHeaderNames;
 import org.jboss.resteasy.core.ResteasyContext;
 
 /**
@@ -37,6 +41,7 @@ public class RequestWrapper {
 
 	private UriInfo uriInfo;
 	private HttpServletRequest request;
+	private HttpServletResponse response;
 	private UserAgent userAgent;
 
 	/**
@@ -47,6 +52,7 @@ public class RequestWrapper {
 	RequestWrapper() {
 		this.uriInfo = ResteasyContext.getContextData(UriInfo.class);
 		this.request = ResteasyContext.getContextData(HttpServletRequest.class);
+		this.response = ResteasyContext.getContextData(HttpServletResponse.class);
 		this.userAgent = null;
 	}
 
@@ -54,7 +60,7 @@ public class RequestWrapper {
 	 * Retrieves the first value set in a list from the map for a given key.
 	 * 
 	 * @param wrapper the parameter map containing the value
-	 * @param key    the key to retrieve the value for
+	 * @param key     the key to retrieve the value for
 	 * @return the first value set in the parameter map for the given key, or null
 	 *         if absent.
 	 */
@@ -74,7 +80,7 @@ public class RequestWrapper {
 	 * Retrieves the value list from the map for a given key.
 	 * 
 	 * @param wrapper the parameter map containing the values
-	 * @param key    the key to retrieve the values for
+	 * @param key     the key to retrieve the values for
 	 * @return the value list for the given key if it exists, or an empty collection
 	 *         if none exists.
 	 */
@@ -95,8 +101,8 @@ public class RequestWrapper {
 	 * exist.
 	 * 
 	 * @param wrapper map containing parameters to update
-	 * @param key    string key to add the value to, must not be null
-	 * @param value  the value to add to the key
+	 * @param key     string key to add the value to, must not be null
+	 * @param value   the value to add to the key
 	 */
 	public void addParam(String key, String value) {
 		if (StringUtils.isBlank(key)) {
@@ -155,6 +161,16 @@ public class RequestWrapper {
 		return request.getHeader(key);
 	}
 
+	/**
+	 * Retrieve the request version from the
+	 * 
+	 * @param key the headers key value
+	 * @return the version passed from the access version header
+	 */
+	public String getRequestVersion() {
+		return request.getHeader(RequestHeaderNames.ACCESS_VERSION);
+	}
+
 	/**
 	 * Get the wrapped user agent object for the current request.
 	 * 
@@ -166,7 +182,17 @@ public class RequestWrapper {
 		}
 		return this.userAgent;
 	}
-	
+
+	/**
+	 * Set the deprecation header in the response object for the client.
+	 * 
+	 * @param d   the date that the endpoint was deprecated
+	 * @param msg information about the deprecation
+	 */
+	public void setDeprecatedHeader(Date d, String msg) {
+		response.setHeader(DeprecatedHeader.NAME, DeprecatedHeader.getValue(d, msg));
+	}
+
 	@Override
 	public String toString() {
 		StringBuilder sb = new StringBuilder();

src/main/java/org/eclipsefoundation/marketplace/namespace/DeprecatedHeader.java

+/* Copyright (c) 2019 Eclipse Foundation and others.
+ * This program and the accompanying materials are made available
+ * under the terms of the Eclipse Public License 2.0
+ * which is available at http://www.eclipse.org/legal/epl-v20.html,
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.eclipsefoundation.marketplace.namespace;
+
+import java.util.Date;
+import java.util.Objects;
+
+/**
+ * Centralized location for creating the "Deprecated" header to be used when
+ * warning clients. This is designed to be used when endpoints/functionality are
+ * updated such that they diverge from previous versions.
+ * 
+ * @author Martin Lowe
+ *
+ */
+public class DeprecatedHeader {
+
+	public static final String NAME = "Deprecated";
+
+	private Date date;
+	private String message;
+
+	/**
+	 * Creates a valid deprecation header with the given values set.
+	 * 
+	 * @param date    the date that the endpoint/functionality was deprecated
+	 * @param message information about the deprecation
+	 */
+	public DeprecatedHeader(Date date, String message) {
+		this.date = Objects.requireNonNull(date);
+		this.message = Objects.requireNonNull(message);
+	}
+
+	/**
+	 * Get the value of a header that would contain the given values.
+	 * 
+	 * @param date    the date that the endpoint was deprecated
+	 * @param message information about the deprecation
+	 * @return the value for the header with given values.
+	 */
+	public static String getValue(Date date, String message) {
+		Objects.requireNonNull(date);
+		Objects.requireNonNull(message);
+
+		return date.toString() + ';' + message;
+	}
+
+	/**
+	 * Get the value of the header for the current header.
+	 * 
+	 * @return the value for this header.
+	 */
+	public String getValue() {
+		return DeprecatedHeader.getValue(this.date, this.message);
+	}
+
+	/**
+	 * @return the date
+	 */
+	public Date getDate() {
+		return date;
+	}
+
+	/**
+	 * @param date the date to set
+	 */
+	public void setDate(Date date) {
+		this.date = date;
+	}
+
+	/**
+	 * @return the message
+	 */
+	public String getMessage() {
+		return message;
+	}
+
+	/**
+	 * @param message the message to set
+	 */
+	public void setMessage(String message) {
+		this.message = message;
+	}
+
+	@Override
+	public String toString() {
+		StringBuilder builder = new StringBuilder();
+		builder.append("DeprecatedHeader [date=");
+		builder.append(date);
+		builder.append(", message=");
+		builder.append(message);
+		builder.append("]");
+		return builder.toString();
+	}
+
+}

src/main/java/org/eclipsefoundation/marketplace/namespace/RequestHeaderNames.java

@@ -14,6 +14,7 @@ package org.eclipsefoundation.marketplace.namespace;
 public class RequestHeaderNames {
 
 	public static final String ACCESS_TOKEN = "Eclipse-Access-Token";
+	public static final String ACCESS_VERSION = "Access-Version";
 	
 	private RequestHeaderNames() {}
 }