Java-kommandolinjegrænseflader (del 2):​​args4j

I mit tidligere indlæg så jeg på parsing af kommandolinjeargumenter i Java-applikationer ved hjælp af Apache Commons CLI. I dette indlæg ser jeg på at gøre det samme ved at bruge et andet bibliotek:args4j.

args4j har en anden tilgang til at specificere, hvilke kommandolinjeargumenter Java-applikationen skal forvente end dem, der bruges af Commons CLI. Mens Commons CLI forventer, at objekter, der repræsenterer mulighederne, er individuelt og eksplicit instansieret, bruger args4j brugerdefinerede annoteringer til at lette dette "definitions"-stadium af kommandolinjeargumentbehandling. Kommandolinjeindstillinger forventes at være felter på instansniveau på klassen og er kommenteret med @org.kohsuke.args4j.Option-annotationen. Karakteristikaene for hvert kommandolinjeargument er inkluderet som attributter for denne @Option anmærkning.

Den enkle applikation, der er demonstreret i dette indlæg, ligner den, der blev brugt i mit tidligere indlæg og fokuserer på en valgfri og værdiløs -v mulighed for at angive detaljering og en påkrævet -f option, som forventer en værdi, der repræsenterer filstien og navnet. Den næste kodeliste viser brugen af ​​args4j's @Option annotation for at opsætte disse kommandolinjeargumenter som annotering på klassedatamedlemmer.

args4j Definition af kommandolinjeargumenter via @Option Annotations

@Option(name="-v", aliases="--verbose", usage="Print verbose status.")
private boolean verbose;

@Option(name="-f", aliases="--file", usage="Fully qualified path and name of file.", required=true)
private String fileName;

Som ovenstående kodeliste viser, er det nemt at angive navnet på mulighederne, deres brug og om de er påkrævet eller ej (standard er valgfri). Tilstedeværelsen af ​​private modifier ovenfor gør det indlysende, at disse er attributter defineret på et klasseniveau. Fordi der ikke er nogen static modifikator, ser vi, at disse er instansvariabler, der er blevet kommenteret.

For at parse kommandolinjeindstillingerne skal man blot instansiere en CmdLineParser og videregive kommandolinjeargumenterne til dens parseArguments(String…) metode:

Parsing af kommandolinjeargumenter i args4j

final CmdLineParser parser = new CmdLineParser(this);
try
{
   parser.parseArgument(arguments);
}
catch (CmdLineException clEx)
{
   out.println("ERROR: Unable to parse command-line options: " + clEx);
}

I den første linje i Java-koden, der lige er vist, this er referencen til den forekomst af klassen, hvori medlemsvariablerne vist ovenfor er defineret og kommenteret med @Option anmærkning. I dette tilfælde brugte jeg this fordi den samme klasse, der definerer disse muligheder, er den, der kalder denne parsingmetode. For at gøre dette i samme klasse skulle jeg have en instans (ikke-static ) metode kaldet doMain defineret i klassen og påkaldt af klassens main funktion (dette er vist i den komplette kodeliste mod slutningen af ​​dette indlæg). Kommandolinjeargumenterne som modtaget fra klassens main(final String[]) funktion er rækken af ​​strenge, der sendes til parseArguments(String[]) metode.

De næste to skærmbilleder demonstrerer anvendelsen af ​​den beskrevne kode baseret på args4j til at analysere kommandolinjeargumenterne. Det første billede viser kombinationer af de korte og lange muligheder for de to muligheder. Det andet billede viser den automatiske rapportering af sagen, hvor et påkrævet kommandolinjeargument ikke blev angivet.

En vigtig egenskab ved et kommandolinjeparsingbibliotek er evnen til at vise brugs- eller hjælpeoplysninger. Den næste kodeliste viser et eksempel på at gøre dette med args4js CmdLineParser.printUsage(OutputStream) metode.

Udskrivning af brugsoplysninger med args4j

final CmdLineParser parser = new CmdLineParser(this);
if (arguments.length < 1)
{
   parser.printUsage(out);
   System.exit(-1);
}

Brugsoplysningerne, der som standard udskrives af args4j, er afbildet i det næste skærmbillede.

Dette indlæg har demonstreret brugen af ​​arg4j til at opnå nogle af de mest almindelige funktioner relateret til kommandolinjeparsing i Java-applikationer, herunder mulighed "definition", kommandolinjeargumenter "parsing", "interrogation" af de parsede kommandolinjeargumenter og hjælp /brugsdetaljer relateret til kommandolinjeargumenterne. Den fulde kodeliste for klassen, der delvist er repræsenteret ovenfor i kodelister, vises nu.

Fuld kodeliste for args4j Demonstration Main.java

package examples.dustin.commandline.args4j;

import static java.lang.System.out;

import org.kohsuke.args4j.CmdLineException;
import org.kohsuke.args4j.CmdLineParser;
import org.kohsuke.args4j.Option;

import java.io.IOException;

/**
 * Demonstrate args4j.
 */
public class Main
{
   @Option(name="-v", aliases="--verbose", usage="Print verbose status.")
   private boolean verbose;

   @Option(name="-f", aliases="--file", usage="Fully qualified path and name of file.", required=true)
   private String fileName;

   private void doMain(final String[] arguments) throws IOException
   {
      final CmdLineParser parser = new CmdLineParser(this);
      if (arguments.length < 1)
      {
         parser.printUsage(out);
         System.exit(-1);
      }
      try
      {
         parser.parseArgument(arguments);
      }
      catch (CmdLineException clEx)
      {
         out.println("ERROR: Unable to parse command-line options: " + clEx);
      }
      out.println("The file '" + fileName + "' was provided and verbosity is set to '" + verbose + "'.");
   }

   /**
    * Executable function demonstrating Args4j command-line processing.
    *
    * @param arguments Command-line arguments to be processed with Args4j.
    */
   public static void main(final String[] arguments)
   {
      final Main instance = new Main();
      try
      {
         instance.doMain(arguments);
      }
      catch (IOException ioEx)
      {
         out.println("ERROR: I/O Exception encountered: " + ioEx);
      }
   }
}

Her er nogle yderligere egenskaber ved args4j at overveje, når du vælger en ramme eller et bibliotek for at hjælpe med kommandolinjeparsing i Java.

• args4j er open source og licenseret med MIT-licensen.
• Nuværende version af args4j (2.33) kræver J2SE 5.
• args4j kræver ikke, at nogen tredjepartsbiblioteker downloades eller refereres separat.
• Args4j 2.33 main JAR (args4j-2.33.jar ) er cirka 152 KB i størrelse.
• Maven Repository viser 376 afhængigheder af args4j inklusive OpenJDK's JMH Core og Jenkins (ikke overraskende i betragtning af Kohsuke Kawaguchis involvering i begge).
• args4j har eksisteret i et stykke tid; dens 2.0.3-udgivelse var i januar 2006, og den har eksisteret i en eller anden form siden mindst 2003.
• args4j tillader, at en kommandolinjeparameter udelukkes fra brugsoutputtet via "skjult" på @Option anmærkning.
• args4j gør det muligt at specificere og håndhæve relationer mellem kommandolinjeargumenter. Dette inkluderer muligheden for at specificere, hvornår to argumenter ikke kan leveres på samme tid ("forbyder"), og når tilstedeværelsen af ​​et argument kun giver mening, når et andet argument også er angivet ("afhænger").
• args4j understøtter brugen af ​​enum-typede klasseattributter i tilfælde, hvor et begrænset sæt værdier er anvendeligt for optionen. @Option-dokumentationen beskriver, hvordan du gør dette under afsnittet "Enum Switch".
• args4j giver mulighed for udvidelse og tilpasning af kommandolinjeargumenter, der parser via dens OptionHandler-klasse.

Args4j-biblioteket er nemt at bruge og giver mulighed for meget læsbar kode. Måske den største overvejelse, når man beslutter sig for, om man skal bruge args4j, er at beslutte, hvor komfortabel man er med at bruge annoteringer til at specificere kommandolinjeparametrenes definitioner.

Yderligere referencer

• args4j
• args4j Download
• args4j kildekode (GitHub)
• args4j API-dokumentation
• args4j Sample Main