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);
    }

}