Callback interfaces and helper methods for doing boilerplating for ex…

…tracting HttpRequest and HttpResponse, processing, and properly terminating the response from an XAgent. One is specifically designed to allow population of a JSON object which will get passed back to the REST request

   /*
    * One method call to XspUtils.initialiseAndProcessResponse() does all the boilerplating for extracting the request, response and JsonJavaObject
    * and properly terminating the response. JsonJavaObject is basically the same as a Java Map. All gotchas are handled for you!
    *
    * The bit that could be new to most is that XspUtils.initialiseAndProcessResponseAsJson() takes an anonymous inner class as its method. This is just
    * a way to pass in a process() method that can interact with the request and response set up by XspUtils.initialiseAndProcessResponseAsJson()
    *
    * With Java 8 it becomes more readable with lambdas:
    *
    * XspUtils.initialiseAndProcessResponseAsJson((request, response, jsonObj) -> {
    *     // do stuff here
    * });
    */

domino/xsp/src/main/java/org/openntf/domino/xsp/IXspHttpServletJsonResponseCallback.java

@@ -0,0 +1,50 @@
+package org.openntf.domino.xsp;
+
+/*
+ 	Copyright 2018 Paul Withers 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
+	
+*/
+
+import java.io.IOException;
+
+import javax.servlet.http.HttpServletRequest;
+
+import com.ibm.commons.util.io.json.JsonJavaObject;
+import com.ibm.xsp.webapp.XspHttpServletResponse;
+
+/**
+ * This interface allows the developer to pass custom code to be run to process the HttpServletRequest and populate the
+ * XspHttpServletResponse
+ * 
+ * @author Paul Withers
+ * @since ODA 4.3.0
+ * 
+ */
+public interface IXspHttpServletJsonResponseCallback {
+
+	/**
+	 * {@linkplain Utils#initialiseAndProcessResponse(IXspHttpServletJsonResponseCallback)} will extract the HttpServletRequest and
+	 * XspHttpServletResponse, call this process() method, then terminate the response.
+	 * 
+	 * By using the callback approach custom code can be generated without needing to remember to code the boilerplate Java code that should
+	 * sit around it.
+	 * 
+	 * @param request
+	 *            HttpServletRequest
+	 * @param response
+	 *            XspHttpServletResponse that will be posted back to the browser, from which the getDelegate() method gives access to the
+	 *            HttpServletResponse, if needed
+	 * @param jsonObj
+	 *            to store JSON
+	 */
+	public void process(HttpServletRequest request, XspHttpServletResponse response, JsonJavaObject jsonObj) throws IOException;
+
+}

domino/xsp/src/main/java/org/openntf/domino/xsp/IXspHttpServletResponseCallback.java

@@ -0,0 +1,47 @@
+package org.openntf.domino.xsp;
+
+/*
+ 	Copyright 2018 Paul Withers 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
+	
+*/
+
+import java.io.IOException;
+
+import javax.servlet.http.HttpServletRequest;
+
+import com.ibm.xsp.webapp.XspHttpServletResponse;
+
+/**
+ * This interface allows the developer to pass custom code to be run to process the HttpServletRequest and populate the
+ * XspHttpServletResponse
+ * 
+ * @author Paul Withers
+ * @since ODA 4.3.0
+ * 
+ */
+public interface IXspHttpServletResponseCallback {
+
+	/**
+	 * {@linkplain Utils#initialiseAndProcessResponse(IXspHttpServletResponseCallback)} will extract the HttpServletRequest and
+	 * XspHttpServletResponse, call this process() method, then terminate the response.
+	 * 
+	 * By using the callback approach custom code can be generated without needing to remember to code the boilerplate Java code that should
+	 * sit around it.
+	 * 
+	 * @param request
+	 *            HttpServletRequest
+	 * @param response
+	 *            XspHttpServletResponse that will be posted back to the browser, from which the getDelegate() method gives access to the
+	 *            HttpServletResponse, if needed
+	 */
+	public void process(HttpServletRequest request, XspHttpServletResponse response) throws IOException;
+
+}

domino/xsp/src/main/java/org/openntf/domino/xsp/helpers/XspUtils.java

@@ -3,14 +3,27 @@
  */
 package org.openntf.domino.xsp.helpers;
 
+import java.io.IOException;
+import java.io.PrintWriter;
 import java.util.logging.Logger;
 
+import javax.faces.context.ExternalContext;
+import javax.faces.context.FacesContext;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
 import org.openntf.domino.Document;
 import org.openntf.domino.utils.DominoUtils;
 import org.openntf.domino.utils.XSPUtil;
+import org.openntf.domino.xsp.IXspHttpServletJsonResponseCallback;
+import org.openntf.domino.xsp.IXspHttpServletResponseCallback;
 import org.openntf.domino.xsp.ODAPlatform;
 
+import com.ibm.commons.util.io.json.JsonException;
+import com.ibm.commons.util.io.json.JsonJavaObject;
+import com.ibm.domino.services.HttpServiceConstants;
 import com.ibm.xsp.model.domino.wrapped.DominoDocument;
+import com.ibm.xsp.webapp.XspHttpServletResponse;
 
 /**
  * @author Nathan T. Freeman
@@ -55,4 +68,59 @@ public static Document getBEDoc(final DominoDocument doc) {
 		return beDoc;
 	}
 
+	/**
+	 * A generic method that performs boilerplate code to extract XspHttpServletRequest and HttpServletResponse; triggers a callback method
+	 * passed in giving it access to the request, response and a JsonJavaObject; then closes everything down successfully
+	 * 
+	 * @param callback
+	 *            anonymous inner class callback that implements IXspHttpServletResponse, so has a process() method that can be called from
+	 *            here
+	 * @throws IOException
+	 *             that may be caused by manipulating the response
+	 * @throws JsonException
+	 *             caused by malformed JSON, shouldn't happen
+	 * @since ODA 4.3.0
+	 */
+	public static void initialiseAndProcessResponseAsJson(final IXspHttpServletJsonResponseCallback callback)
+			throws IOException, JsonException {
+		FacesContext ctx = FacesContext.getCurrentInstance();
+		ExternalContext ext = ctx.getExternalContext();
+		XspHttpServletResponse response = (XspHttpServletResponse) ext.getResponse();
+		response.setContentType(HttpServiceConstants.CONTENTTYPE_APPLICATION_JSON);
+		response.setHeader("Cache-Control", "no-cache");
+		JsonJavaObject result = new JsonJavaObject();
+		callback.process((HttpServletRequest) ext.getRequest(), response, result);
+		if (!response.isStatusSet()) {
+			response.setStatus(HttpServletResponse.SC_OK);
+		}
+		PrintWriter writer = response.getWriter();
+		writer.write(result.toString());
+		//  Terminate the request processing lifecycle.
+		FacesContext.getCurrentInstance().responseComplete();
+	}
+
+	/**
+	 * A more basic generic method that performs boilerplate code to extract XspHttpServletRequest and HttpServletResponse; triggers a
+	 * callback method passed in, passing it the request and response; then terminates the response
+	 * 
+	 * It's down to you to handle printing something to the response
+	 * 
+	 * @param callback
+	 *            anonymous inner class callback that implements IXspHttpServletResponse, so has a process() method that can be called from
+	 *            here
+	 * @throws IOException
+	 *             that may be caused by manipulating the response
+	 * @since ODA 4.3.0
+	 */
+	public static void initialiseAndProcessResponse(final IXspHttpServletResponseCallback callback) throws IOException {
+		FacesContext ctx = FacesContext.getCurrentInstance();
+		ExternalContext ext = ctx.getExternalContext();
+		XspHttpServletResponse response = (XspHttpServletResponse) ext.getResponse();
+		response.setContentType(HttpServiceConstants.CONTENTTYPE_APPLICATION_JSON);
+		response.setHeader("Cache-Control", "no-cache");
+		callback.process((HttpServletRequest) ext.getRequest(), response);
+		//  Terminate the request processing lifecycle.
+		FacesContext.getCurrentInstance().responseComplete();
+	}
+
 }