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