ServletUsageFormatter.java
package server.restful.common.parameter.usage;
import com.beust.jcommander.*;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import server.restful.common.ContentTypeAndFileExtensions;
import server.restful.common.parameter.RequestResponseBodyParameter;
import server.restful.common.parameter.RequestResponseBodyParameter.Blob;
import server.restful.common.parameter.ServletParameterParser;
import jakarta.xml.bind.JAXBContext;
import jakarta.xml.bind.JAXBException;
import jakarta.xml.bind.Marshaller;
import java.io.StringWriter;
import java.net.MalformedURLException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.util.*;
import java.util.ResourceBundle;
import java.util.logging.Level;
import java.util.logging.Logger;
import java.util.stream.Collectors;
import static jakarta.servlet.http.HttpServletResponse.SC_INTERNAL_SERVER_ERROR;
import static jakarta.servlet.http.HttpServletResponse.SC_OK;
import static org.apache.http.HttpHeaders.ACCEPT;
import static org.apache.http.HttpHeaders.CONTENT_TYPE;
import static org.apache.tomcat.util.http.fileupload.FileUploadBase.*;
import static server.restful.common.ContentTypeAndFileExtensions.*;
import static server.restful.common.IServletSystemProperties.JSIDPlay2Server.BASE_URL;
/**
* Change the usage message to represent a servlet call usage. Servlet path is treated like a main argument and servlet
* parameters as options.
*
* @author khaendel
*
*/
public class ServletUsageFormatter extends DefaultUsageFormatter {
private static final Logger LOG = Logger.getLogger(ServletUsageFormatter.class.getName());
private final JCommander commander;
private final HttpServletRequest request;
private final HttpServletResponse response;
private Exception exception;
private final ResourceBundle bundle;
public ServletUsageFormatter(JCommander commander, HttpServletRequest request, HttpServletResponse response) {
super(commander);
this.commander = commander;
this.request = request;
this.response = response;
this.bundle = getBundle();
}
public void setException(Exception exception) {
if (this.exception == null) {
this.exception = exception;
}
}
public Exception getException() {
return exception;
}
@Override
public void appendMainLine(StringBuilder out, boolean hasOptions, boolean hasCommands, int indentCount,
String indent) {
response.setStatus(exception != null ? SC_INTERNAL_SERVER_ERROR : SC_OK);
response.setContentType(MIME_TYPE_TEXT.toString());
if (LOG.isLoggable(Level.FINEST)) {
appendCurrentRequestParameters(out, indent);
}
if (exception != null) {
appendErrorMessage(out);
}
out.append(indent).append("Usage: ").append(request.getMethod()).append(" ");
out.append(commander.getProgramDisplayName());
if (commander.getMainParameter() != null && commander.getMainParameterValue() != null) {
out.append("[<servlet path>]");
}
if (commander.getFields().values().stream().anyMatch(pd -> !pd.getParameter().hidden())) {
out.append("?[<servlet parameters>]");
}
out.append("\n");
out.append("\n");
out.append(bundle.getString("USAGE_DESCRIPTION"));
out.append("\n");
if (commander.getMainParameter() != null && commander.getMainParameterValue() != null) {
appendServletPath(out, indentCount, indent);
}
}
@Override
public void appendAllParametersDetails(StringBuilder out, int indentCount, String indent,
List<ParameterDescription> sortedParameters) {
if (!sortedParameters.isEmpty()) {
out.append("\n");
out.append(indent).append(" Servlet Parameters:\n");
}
for (ParameterDescription pd : sortedParameters) {
WrappedParameter parameter = pd.getParameter();
String description = pd.getDescription();
boolean hasDescription = !description.isEmpty();
// First line, command name
out.append(indent).append(" ").append(parameter.required() ? "* " : " ")
.append(getServletParameterNames(pd.getNames())).append("\n");
if (hasDescription) {
wrapDescription(out, indentCount, s(indentCount) + description);
}
Object def = pd.getDefault();
if (pd.isDynamicParameter()) {
String syntax = "Syntax: " + parameter.names()[0] + "key" + parameter.getAssignment() + "value";
if (hasDescription) {
out.append(newLineAndIndent(indentCount));
} else {
out.append(s(indentCount));
}
out.append(syntax);
}
if (def != null && !pd.isHelp()) {
String displayedDef = Strings.isStringEmpty(def.toString()) ? "<empty string>" : def.toString();
String defaultText = "Default: " + (parameter.password() ? "********" : displayedDef);
if (hasDescription) {
out.append(newLineAndIndent(indentCount));
} else {
out.append(s(indentCount));
}
out.append(defaultText);
}
Class<?> type = pd.getParameterized().getType();
if (type.isEnum()) {
@SuppressWarnings({"unchecked", "rawtypes"})
String valueList = EnumSet.allOf((Class<? extends Enum>) type).toString();
String possibleValues = "Possible Values: " + valueList;
// Prevent a duplicate values list, since it is set as 'Options: [values]' if the
// description
// of an enum field is empty in ParameterDescription#init(..)
if (!description.contains("Options: " + valueList)) {
if (hasDescription) {
out.append(newLineAndIndent(indentCount));
} else {
out.append(s(indentCount));
}
out.append(possibleValues);
}
}
out.append("\n");
}
try {
appendExampleUsage(out, indentCount, indent);
} catch (URISyntaxException | MalformedURLException e) {
throw new RuntimeException(e);
}
}
private void appendCurrentRequestParameters(StringBuilder out, String indent) {
String[] requestParameters = ServletParameterParser.getRequestParametersAsCommandLine(request);
if (requestParameters.length > 0) {
out.append(indent)
.append(" Internal Info: Current servlet parameters converted to command line arguments:");
out.append("\n");
out.append(Strings.join(" ", requestParameters));
out.append("\n");
out.append("\n");
}
}
private void appendErrorMessage(StringBuilder out) {
out.append(exception.getClass().getSimpleName());
out.append(":");
out.append(newLineAndIndent(2));
out.append(exception.getMessage().replaceAll("[mM]ain parameters? are", "servlet path is")
.replaceAll("[mM]ain class", "servlet").replaceAll("[mM]ain parameters?", "servlet path")
.replaceAll("[oO]ption", "servlet parameter").replaceAll("--", "").replaceAll("-", ""));
out.append("\n");
out.append("--------------------------------------------------------------------------------");
out.append("\n");
out.append("\n");
}
private void appendServletPath(StringBuilder out, int indentCount, String indent) {
out.append(newLineAndIndent(2)).append("Servlet Path:");
out.append("\n");
out.append(indent).append(" ");
out.append(commander.getMainParameterValue().getParameter().required() ? "* " : " ");
out.append(commander.getMainParameterValue().getDescription());
out.append("\n");
}
private void appendExampleUsage(StringBuilder out, int indentCount, String indent)
throws MalformedURLException, URISyntaxException {
out.append(newLineAndIndent(2)).append("Example:");
out.append("\n");
wrapDescription(out, indentCount, s(indentCount) + createExampleUsage(indent));
for (String line : createRequestResponseBodyExamples()) {
out.append("\n");
wrapDescription(out, indentCount, s(indentCount) + line);
}
out.append("\n");
out.append("\n");
}
private List<String> createRequestResponseBodyExamples() {
List<String> result = new ArrayList<>();
if ("POST".equals(request.getMethod())) {
Object firstParameterObject = commander.getObjects().get(0);
if (firstParameterObject instanceof RequestResponseBodyParameter) {
RequestResponseBodyParameter<?, ?> postMethodParameter = (RequestResponseBodyParameter<?, ?>) firstParameterObject;
Object requestBodyExample = postMethodParameter.getRequestBodyExample();
Object responseBodyExample = postMethodParameter.getResponseBodyExample();
if (requestBodyExample != null) {
result.add("");
result.add("Request:");
result.add("--------");
if (requestBodyExample instanceof Blob) {
result.add("");
result.add(CONTENT_TYPE + ": " + MIME_TYPE_FORM_URLENCODED.getMimeType());
result.add("Body:");
result.add("<Blob>");
} else {
for (ContentTypeAndFileExtensions ct : new ContentTypeAndFileExtensions[]{MIME_TYPE_JSON,
MIME_TYPE_XML, MIME_TYPE_MULTIPART}) {
createRequestBodyExample(result, ct, requestBodyExample);
}
}
}
if (responseBodyExample != null) {
result.add("");
result.add("Response:");
result.add("---------");
for (ContentTypeAndFileExtensions ct : new ContentTypeAndFileExtensions[]{
ContentTypeAndFileExtensions.MIME_TYPE_JSON, ContentTypeAndFileExtensions.MIME_TYPE_XML}) {
createResponseBodyExample(result, ct, responseBodyExample);
}
}
}
}
return result;
}
private void createRequestBodyExample(List<String> result, ContentTypeAndFileExtensions ct,
Object requestBodyExample) {
try {
switch (ct) {
case MIME_TYPE_XML: {
StringWriter xml = new StringWriter();
Marshaller marshaller = JAXBContext.newInstance(requestBodyExample.getClass()).createMarshaller();
marshaller.marshal(requestBodyExample, xml);
result.add("");
result.add(CONTENT_TYPE + ": " + ct.getMimeType());
result.add("Body:");
result.add(xml.toString());
break;
}
case MIME_TYPE_JSON: {
result.add("");
result.add(CONTENT_TYPE + ": " + ct.getMimeType());
result.add("Body:");
result.add(new ObjectMapper().writeValueAsString(requestBodyExample));
break;
}
case MIME_TYPE_MULTIPART: {
String boundary = UUID.randomUUID().toString();
result.add("");
result.add(CONTENT_TYPE + ": " + (MULTIPART + FORM_DATA + "; boundary=" + boundary));
result.add("Body:");
result.add("--" + boundary);
result.add(CONTENT_DISPOSITION + ": " + FORM_DATA + "; name=\"file\"; filename=\"filename.ext\"");
result.add(CONTENT_TYPE + ": " + MIME_TYPE_OCTET_STREAM.getMimeType());
result.add("");
result.add("54 45 53 54 (example raw binary bytes)");
result.add("--" + boundary);
break;
}
default:
break;
}
} catch (JAXBException | JsonProcessingException e) {
// skip example, if not available
}
}
private void createResponseBodyExample(List<String> result, ContentTypeAndFileExtensions ct,
Object responseBodyExample) {
try {
switch (ct) {
case MIME_TYPE_XML: {
StringWriter xml = new StringWriter();
JAXBContext.newInstance(responseBodyExample.getClass()).createMarshaller().marshal(responseBodyExample,
xml);
result.add("");
result.add(ACCEPT + ": " + ct.getMimeType());
result.add("Body:");
result.add(xml.toString());
break;
}
case MIME_TYPE_JSON: {
result.add("");
result.add(ACCEPT + ": " + ct.getMimeType());
result.add("Body:");
result.add(new ObjectMapper().writeValueAsString(responseBodyExample));
break;
}
default:
break;
}
} catch (JAXBException | JsonProcessingException e) {
// skip example, if not available
}
}
private String createExampleUsage(String indent) throws MalformedURLException, URISyntaxException {
StringBuilder result = new StringBuilder();
// protocol
result.append(indent).append("HTTP(S)-");
// request method
result.append(request.getMethod()).append(" ");
StringBuilder urlAsString = new StringBuilder();
// base URL
urlAsString.append(BASE_URL);
// servlet path
urlAsString.append(commander.getProgramDisplayName());
// request path
if (commander.getMainParameter() != null) {
urlAsString.append(bundle.getString("EXAMPLE_REQUEST_PATH"));
}
// request parameters
StringBuilder queryParameters = new StringBuilder();
Iterator<ParameterDescription> it = commander.getFields().values().stream()
.filter(pd -> !pd.getParameter().hidden() && pd.getDefault() != null)
.sorted(commander.getParameterDescriptionComparator()).collect(Collectors.toList()).iterator();
if (it.hasNext()) {
while (it.hasNext()) {
ParameterDescription def = it.next();
queryParameters.append(getExampleServletParameterName(def.getNames()));
queryParameters.append("=");
queryParameters.append(def.getParameter().password() ? "********" : String.valueOf(def.getDefault()));
if (it.hasNext()) {
queryParameters.append("&");
}
}
}
URL url = new URI(urlAsString.toString()).toURL();
URI uri = new URI(url.getProtocol(), url.getUserInfo(), url.getHost(), url.getPort(), url.getPath(),
queryParameters.length() > 0 ? queryParameters.toString() : null, url.getRef());
result.append(uri.toASCIIString());
return result.toString();
}
private String getExampleServletParameterName(String names) {
return Arrays.stream(names.split(", ")).map(this::getParameterName)
.max(Comparator.comparingInt(String::length)).orElse("");
}
private ResourceBundle getBundle() {
Object firstParameterObject = commander.getObjects().get(0);
Parameters parameters = firstParameterObject.getClass().getAnnotation(Parameters.class);
return ResourceBundle.getBundle(parameters.resourceBundle(), Locale.getDefault());
}
private String getServletParameterNames(String names) {
return Arrays.stream(names.split(", ")).map(this::getParameterName).collect(Collectors.joining(", "));
}
private String getParameterName(String name) {
if (name.startsWith("--")) {
return name.substring("--".length());
} else if (name.startsWith("-")) {
return name.substring("-".length());
} else {
return name;
}
}
/**
* Returns a new line followed by indent-many spaces.
*
* @return new line followed by indent-many spaces
*/
private static String newLineAndIndent(int indent) {
return "\n" + s(indent);
}
}