Analisando Parâmetros da Linha de Comandos com o JCommander

Vamos começar adicionando a dependênciajcommander em nossopom.xml:

Vamos criar umHelloWorldApp simples que pega uma única entrada chamadanamee imprime uma saudação,“Hello <name>”.

ComoJCommander binds command-line arguments to fields in a Java class, primeiro definiremos uma classeHelloWorldArgs com um camponame anotado com@Parameter:

Agora, vamos usar a classeJCommander para analisar os argumentos da linha de comando e atribuir os campos em nosso objetoHelloWorldArgs:

Finalmente, vamos invocar a classe principal com os mesmos argumentos do console:

Anotando um campo com@Parameter tells JCommander to bind a matching command-line argument to it. @Parameter tem atributos para descrever o parâmetro principal, como:

Vamos configurar um parâmetrocustomerId em nosso cenário de faturamento medido:

Agora, vamos executar nosso comando com o novo parâmetro “–customer”:

Da mesma forma, podemos usar o parâmetro "-C" mais curto para obter o mesmo efeito:

Quando um parâmetro é obrigatório, o aplicativo sai lançando umParameterException se o usuário não especificá-lo:

Devemos notar que, em geral,any error in parsing the parameters results in a ParameterException no JCommander.

JCommander executa a conversão de tipo da entradaString da linha de comando para os tipos Java em nossas classes de parâmetro. The IStringConverter interface handles type conversion of a parameter from String to any arbitrary type. Portanto, todos os conversores integrados do JCommander implementam esta interface.

Pronto para uso, JCommander vem com suporte para tipos de dados comuns, comoString,Integer,Boolean,BigDecimal eEnum.

Arity refere-se ao número de parâmetros adicionais que uma opção consome. built-in parameter types have a default arity of one do JCommander, exceto paraBoolean eList. Portanto, tipos comuns comoString,Integer,BigDecimal,Long, e Enum, são tipos de aridade única.

Fields of type boolean or Boolean don’t need any additional parameter – essas opções têmarity igual a zero.

Vamos ver um exemplo. Talvez desejemos buscar as cobranças de um cliente, discriminadas por assinatura. Podemos adicionar um campobooleanitemized, que éfalse por padrão:

Nosso aplicativo retornaria cobranças agregadas comitemized definido comofalse. Quando invocamos a linha de comando com o parâmetroitemized, definimos o campo comotrue:

Isso funciona bem, a menos que tenhamos um caso de uso em que sempre desejamos cobranças discriminadas,, a menos que especificado de outra forma. Poderíamos alterar o parâmetro paranotItemized,, mas pode ser mais claro ser capaz de fornecerfalse como o valor deitemized.

Vamos apresentar esse comportamento usando um valor padrãotrue para o campo e definindo seuarity como um:

Agora, quando especificarmos a opção, o valor será definido comofalse:

Vamos supor que desejamos obter as cobranças de apenas um subconjunto das assinaturas de um cliente:

O campo não é obrigatório e o aplicativo buscará as cobranças em todas as assinaturas se o parâmetro não for fornecido. No entanto, podemos especificar várias assinaturasby using the parameter name multiple times:

Em vez de especificar a opção várias vezes, vamos tentar vincular a lista passandoString separados por vírgula:

Isso usa um único valor de parâmetro (arity = 1) para representar uma lista. O JCommander usará a classeCommaParameterSplitter para vincular oString separado por vírgula ao nossoList.

Podemos substituir o divisor padrão implementando a interfaceIParameterSplitter:

E, em seguida, mapeando a implementação para o atributosplitter em@Parameter:

Vamos experimentar:

Variable arity allows us to declarelists that can take indefinite parameters, up to the next option. Podemos definir o atributovariableArity comotrue para especificar esse comportamento.

Vamos tentar fazer isso para analisar assinaturas:

E quando executamos nosso comando:

O JCommander vincula todos os argumentos de entrada após a opção “-S” ao campo da lista, até a próxima opção ou o final do comando.

Até agora, vimos listas ilimitadas, onde podemos passar quantos itens de lista desejarmos. Às vezes, podemos querer limitar o número de itens passados ​​para um campoList. Para fazer isso, podemosspecify an integer arity value for a List field to make it bounded:

A aridade fixa força uma verificação do número de parâmetros passados ​​para uma opçãoList e lança umParameterException em caso de violação:

A mensagem de erro sugere que, como o JCommander esperava apenas dois argumentos, ele tentou analisar o parâmetro de entrada extra "subscriptionA003" como a próxima opção.

Podemos usar@Parameters para definir subcomandos. @Parameters contém o atributocommandNames para identificar um comando.

Vamos modelarsubmitefetch como subcomandos:

JCommander usa os atributos em@Parameters para configurar os subcomandos, como:

Adicionamos os subcomandos aJCommander com o métodoaddCommand:

O métodoaddCommand registra os subcomandos com seus respectivos nomes, conforme especificado no atributocommandNames da anotação@Parameters.

Para acessar a escolha de comando do usuário, devemos primeiro analisar os argumentos:

A seguir, podemos extrair o subcomando comgetParsedCommand:

Além de identificar o comando, o JCommander vincula o restante dos parâmetros da linha de comandos aos seus campos no subcomando. Agora, basta chamar o comando que queremos usar:

Podemos vincular uma opção de ajuda em nossos comandos usando um parâmetroboolean junto com o atributohelp definido comotrue:

Então, podemos detectar se “–help” foi passado nos argumentos e chamarusage:

Vejamos a saída de ajuda para nosso subcomando “submit”:

O métodousage usa os atributos@Parameter comodescription para exibir um resumo útil. Os parâmetros marcados com asterisco (*) são obrigatórios.

Podemos pegarParameterExceptione chamarusage para ajudar o usuário a entender por que sua entrada estava incorreta. ParameterException contém a instânciaJCommander para exibir a ajuda: