ServletsUsageFormatter.java

package server.restful.common.parameter.usage;

import com.beust.jcommander.DefaultUsageFormatter;
import com.beust.jcommander.JCommander;
import com.beust.jcommander.ParameterDescription;
import com.beust.jcommander.Parameters;
import com.beust.jcommander.internal.Lists;

import java.net.MalformedURLException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.util.*;
import java.util.stream.Collectors;

import static server.restful.common.IServletSystemProperties.JSIDPlay2Server.BASE_URL;

/**
 * Change the usage message to represent an ASCIIDOC text description for the servlets of the RESTful services.
 *
 * @author khaendel
 *
 */
@SuppressWarnings("unused")
public class ServletsUsageFormatter extends DefaultUsageFormatter {

    private final JCommander commander;

    public ServletsUsageFormatter(JCommander commander) {
        super(commander);
        this.commander = commander;
    }

    @Override
    public void appendMainLine(StringBuilder out, boolean hasOptions, boolean hasCommands, int indentCount,
                               String indent) {
        if (!hasCommands) {
            try {
                out.append("\n\n==== ").append(getBundle(commander).getString("USAGE_DESCRIPTION")).append("\n");
                appendExampleUsage(out, indentCount, indent, false, null);
                out.append("\n\n").append(getBundle(commander).getString("USAGE_LONG_DESCRIPTION")).append("\n\n");
                appendExampleUsage(out, indentCount, indent, true,
                        getBundle(commander).getString("EXAMPLE_REQUEST_PATH"));
                try {
                    String optionalUsageDescription = getBundle(commander).getString("USAGE_DESCRIPTION2");
                    out.append("\n\n==== ").append(optionalUsageDescription).append("\n");
                    appendExampleUsage(out, indentCount, indent, false, null);
                    out.append("\n\n").append(getBundle(commander).getString("USAGE_LONG_DESCRIPTION2")).append("\n\n");
                    appendExampleUsage(out, indentCount, indent, true,
                            getBundle(commander).getString("EXAMPLE_REQUEST_PATH2"));
                } catch (MissingResourceException e) {
                    // optional second usage
                }
            } catch (URISyntaxException | MalformedURLException e) {
                throw new RuntimeException(e);
            }
        }
    }

    @Override
    public void appendAllParametersDetails(StringBuilder out, int indentCount, String indent,
                                           List<ParameterDescription> sortedParameters) {
    }

    public void usage(StringBuilder out, String indent) {
        if (commander.getDescriptions() == null) {
            commander.createDescriptions();
        }
        boolean hasCommands = !commander.getCommands().isEmpty();
        boolean hasOptions = !commander.getDescriptions().isEmpty();

        // Indentation constants
        final int descriptionIndent = 6;
        final int indentCount = indent.length() + descriptionIndent;

        // Append the first line (aka main line) of the usage
        appendMainLine(out, hasOptions, hasCommands, indentCount, indent);

        // Align the descriptions at the "longestName" column
        List<ParameterDescription> sortedParameters = Lists.newArrayList();

        for (ParameterDescription pd : commander.getFields().values()) {
            if (!pd.getParameter().hidden()) {
                sortedParameters.add(pd);
            }
        }

        // Sort the options
        sortedParameters.sort(commander.getParameterDescriptionComparator());

        // Append all the parameter names and descriptions
        appendAllParametersDetails(out, indentCount, indent, sortedParameters);

        // Append commands if they were specified
        if (hasCommands) {
            appendCommands(out, indentCount, descriptionIndent, indent);
        }
    }

    public void appendCommands(StringBuilder out, int indentCount, int descriptionIndent, String indent) {
        boolean hasOnlyHiddenCommands = true;
        for (Map.Entry<JCommander.ProgramName, JCommander> commands : commander.getRawCommands().entrySet()) {
            Object arg = commands.getValue().getObjects().get(0);
            Parameters p = arg.getClass().getAnnotation(Parameters.class);

            if (p == null || !p.hidden()) {
                hasOnlyHiddenCommands = false;
                break;
            }
        }

        if (hasOnlyHiddenCommands)
            return;

        for (Map.Entry<JCommander.ProgramName, JCommander> commands : commander.getRawCommands().entrySet()) {
            Object arg = commands.getValue().getObjects().get(0);
            Parameters p = arg.getClass().getAnnotation(Parameters.class);

            if (p == null || !p.hidden()) {
                JCommander.ProgramName progName = commands.getKey();

                // Options for this command
                JCommander jc = commander.findCommandByAlias(progName.getName());

                jc.setUsageFormatter(new ServletsUsageFormatter(jc));
                jc.getUsageFormatter().usage(out, indent + s(6));
            }
        }

    }

    private void appendExampleUsage(StringBuilder out, int indentCount, String indent, boolean exampleOrUsage,
                                    String exampleRequestPath) throws MalformedURLException, URISyntaxException {
        out.append(exampleOrUsage ? "Example:\n" : "");
        out.append("\n");

        out.append(createExampleUsage(indent, exampleOrUsage, exampleRequestPath));
        out.append("\n");
        out.append("\n");
    }

    private String createExampleUsage(String indent, boolean exampleOrUsage, String exampleRequestPath)
            throws MalformedURLException, URISyntaxException {
        StringBuilder result = new StringBuilder();

        ResourceBundle bundle = getBundle(commander);

        // protocol
        StringBuilder urlAsString = new StringBuilder();

        // base URL
        urlAsString.append(BASE_URL);

        // servlet path
        urlAsString.append(bundle.getString("EXAMPLE_REQUEST_SERVLET_PATH"));

        // request path
        if (exampleOrUsage && commander.getMainParameter() != null) {
            urlAsString.append(exampleRequestPath);
        }

        // 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(),
                exampleOrUsage && queryParameters.length() > 0 ? queryParameters.toString() : "help=true",
                url.getRef());
        result.append("link:").append(uri.toASCIIString().replace("*", "%2A")).append("[").append(exampleOrUsage ? uri.toASCIIString().replace("*", "%2A") : "Usage").append("]");

        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(JCommander commander) {
        Object firstParameterObject = commander.getObjects().get(0);
        Parameters parameters = firstParameterObject.getClass().getAnnotation(Parameters.class);
        return ResourceBundle.getBundle(parameters.resourceBundle(), Locale.getDefault());
    }

    private String getParameterName(String name) {
        if (name.startsWith("--")) {
            return name.substring("--".length());
        } else if (name.startsWith("-")) {
            return name.substring("-".length());
        } else {
            return name;
        }
    }

}