Dustin's Pages

Friday, November 24, 2017

There are multiple causes of the ORA-01745 ("invalid host/bind variable name error") error when using an Oracle database. The Oracle 9i documentation on errors ORA-01500 through ORA-02098 provides more details regarding ORA-01745. It states that the "Cause" is "A colon in a bind variable or INTO specification was followed by an inappropriate name, perhaps a reserved word." It also states that the "Action" is "Change the variable name and retry the operation." In the same Oracle 12g documentation, however, there is no description of "cause" or "action" for ORA-01745, presumably because there are multiple causes and multiple corresponding actions associated with this message. In this post, I will focus on one of the perhaps less obvious causes and the corresponding action for that cause.

In addition to the causes just listed and likely in addition to other potential causes of ORA-01745, another situation that can cause the ORA-01745 error is using too many ? placeholders in a JDBC PreparedStatement with the Oracle database. I will demonstrate in this post that the number of ? placeholders in a PreparedStatement that cause this ORA-01745 is 65536 (216).

I have blogged previously on the ORA-01795 error that occurs when one attempts to include more than 1000 values in an Oracle SQL IN condition. There are multiple ways to deal with this limitation and one of the alternative approaches might be to use multiple ORs to "OR" together more than 1000 values. This will typically be implemented with a PreparedStatement and with a ? placeholder placed in the SQL statement for each value being OR-ed. This PreparedStatement-based alternate approach employing ? placeholders will only work as long as the number of vales being OR-ed together is smaller than 65536.

The code listing that follows demonstrates how a SQL query against the Oracle HR schema can be generated to make it easy to reproduce the ORA-01745 error with too many ? placeholders (full code listing is available on GitHub).

Building Up Prepared Statement with Specified Number of ? Placeholders

/**
* Constructs a query using '?' for placeholders and using
* as many of these as specified with the int parameter.
*
* @param numberPlaceholders Number of placeholders ('?')
* to include in WHERE clause of constructed query.
* @return SQL Query that has provided number of '?" placeholders.
*/
private String buildQuery(final int numberPlaceholders)
{
final StringBuilder builder = new StringBuilder();
builder.append("SELECT region_id FROM countries WHERE ");
for (int count=0; count < numberPlaceholders-1; count++)
{
builder.append("region_id = ? OR ");
}
builder.append("region_id = ?");
return builder.toString();
}

The next code listing demonstrates building a PreparedStatement based on the query constructed in the last code listing and setting its placeholders with a number of consecutive integers that match the number of ? placeholders.

The next screen snapshot shows the ORA-01745 error occurring when the number of ? placeholders applied is 65536.

This example shows that there is a maximum number of ? placeholders that can be used in an Oracle SQL statement. Fortunately, there are other ways to accomplish this type of functionality that do not have this ORA-01475 limit of 65536 ? placeholders or the 1000 IN elements limit that causes an ORA-01795 error

Wednesday, November 22, 2017

There are many things a Java developer can do to make his or her own life and the lives of others maintaining that code easier. In this post, I'm going to look at a very easy approach a developer can take to make things easier for everyone. The point of this post will likely seem obvious to everyone reading it, but I see this not done far more often than I would have expected. In short, developers should typically log the value they are switch-ing on when that value is not represented by any of the explicit case statements within that switch.

Before moving to specifics, I will add a few caveats. There are times when it may not make sense to log the value being switch-ed on that was not explicitly matched to a case. Some of these are listed here.

The value being switched on is sensitive and should not be logged for security reasons.

The value being switched on has numerous cases in which no match is expected and so the developer doesn't want to log unnecessarily.

A default can be provided that will always work well for any values that don't have matching case blocks (this seems rare).

In the cases I've seen that are the cause of this being one of my main pet peeves, none of the above caveats applied. In fact, in most of these cases, the developer has provided a logged message in the default block warning that the value was unexpected, but that same developer has failed to provide the candidate value that was not matched. A contrived example of this is shown in the next code listing.

The issue here is really a specific example of a more general issue developers should avoid: logging without sufficient context. In some cases, it might be difficult or computationally expensive to provide the type of context that makes log messages more useful. That's typically not the case with switch statements, however, where we can easily log the value that we were trying to switch on. In the above code listing, developers supporting runtime issues in deployment will only be told that an "Unexpected integer was provided." Without any context, it's difficult to know what that provided integer was and, without knowing the candidate integer, it's difficult to trace what happened or even reproduce it.

Only very small effort is required to make this default logging statement useful and this is shown in the next code listing.

The "enhanced" log message indicates which integer was being switched on and adds what is being returned because of that not being an expected integer. The second part is not as necessary for the developer because the static code will show the developer what is returned in that "default" case. However, the logging of the integer that was being switched on is highly valuable because there's no good way to access this information later unless a different log message somewhere else made it clear that's what was being switched on.

I have been the victim numerous times of developers not providing this simple context. It has made what would have likely been an easy diagnosis much more difficult. In extreme cases, I've had to add this context to the log message and wait for it to be encountered again. Had the developer added that simple context information at the time of writing of the code, the issue could have been resolved much more readily.

I like to take this concept a little further when writing my own switch statements. I typically add a default block even when my switch covers all possible (current) cases explicitly. This default block is unnecessary at the time of writing and will "never be called," but I add it to future-proof the switch statement (unit tests can be used to implement similar protections). I add the logging of the unexpected candidate value provided to the switch statement so that if another case is added "upstream" in the code, my switch will quickly tell me when it runs into an unexpected value and tell me what that unexpected value is.

It often turns out that having a candidate value for a switch statement without matching case is an exceptional circumstance. In such cases, it's likely more appropriate to thrown an exception than to simply log the exceptional situation. A standard exception such as IllegalArgumentException works well for this (it is, in a way, an illegal argument to the switch statement), but I have occasionally also written a custom exception to help with this. When I've decided to implement and use this custom exception, part of the reason for making that decision is that throwing of that exception encourages developers to provide the object being switched upon as part of the exception's constructor. A representative example of this type of custom exception is shown next (source code is also available on GitHub).

Whether the developer is simply logging the switch candidate not being found or throws an exception is response to that, the value being switched on should typically be logged or included in the exception to make it easier to diagnose the issue. The custom exception above will provide that message automatically regardless of the constructor used as long as the developer provides the switched-on object. A developer would have to go out of his or her way to not provide that object in this case rather than simply neglecting or forgetting to include it.

After ruling out cases where it's not appropriate to log or write out the value being switched on that has no match, the mostly likely reason a developer fails to indicate the value is simply not thinking about it. It can be "obvious" to the developer at time of writing the code that any unexpected case "will never happen" or that it would be obvious what the value was if it did happen. Another likely reason for not including context in these types of messages (or any log messages for that matter) is being rushed or being lazy. A developer might know that it would be best to provide these details, but doesn't want to take the time to do it. It's this latter reason that sometimes encourages me to write a custom exception like that shown above.

Debugging and maintaining production software is a valuable experience for developers because it helps them to better understand how their actions (or lack thereof) make others' jobs more difficult in the future. In general, the conscientious developer can help others (and possibly himself or herself) by providing context information in logged messages, especially for warning, error, and exception conditions. In particular,
adding the context of what value was being switch-ed on when no match is found is easy to do and could save yourself, other developers, and customers quite a bit of time in the future.

The third edition is anticipated to have significant new and updated content given the changes to the language with Java 7, Java 8, and Java 9. The Table of Contents available on the Pearson page does not yet show the individual items in each chapter, but it does show that the third edition of Effective Java will have an entire new chapter on and called "Lambdas and Streams." This new chapter will be the seventh of twelve chapters in the book and will immediately follow the two chapters on significant features introduced in Java 5 (enums, annotations, and generics).

I imagine there will be new items and updated items in the other eleven chapters that previously existed in the first two editions as later versions of Java will impact many of those chapters. In fact, both the Pearson page and the Amazon page provide the same list of some of the "new coverage" items in this book and many of these will likely fall into one of the chapters other than the one on lambdas and streams.

I have never purchased three editions of the same book before and the ~$50 USD is not cheap, but I'll likely be purchasing the third edition of Effective Java as a Christmas gift for myself.

The Humble Book Bundle: Java is presented by O'Reilly Media and is available for a little less than two weeks from publication of this post. Purchasers of the bundle can select which "level" of bundle they'd like to purchase. The smallest bundle requires a minimum payment of $1, the middle bundle requires a minimum payment of $8, and the largest bundle requires a minimum payment of $15 (all currencies expressed here in U.S. dollars). These bundles are of Java-oriented electronic books published by O'Reilly and include some impressive titles. Portions of the proceeds go to charity, the electronic books are DRM-free, and the electronic books are available in multiple formats (PDF, EPUB, MOBI).

I already have the printed editions of some of these books and they are excellent. There is also a nice mix of books here with some designed for beginners (such as Think Java and Learning Java), some designed for more experienced Java developers (such as Java Generics and Collections and Java Performance: The Definitive Guide), some designed for general Java (such as Java Cookbook and Java in a Nutshell) and some designed with focus on recent Java (such as Java 8 Lambdas).

It could be argued that any one or two of these electronic books are worth $15 USD, but getting all 15 electronic books for that price is a great deal. When one considers that these electronic books are DRM-free and come in multiple formats and that a portion of the proceeds goes to charity, it's even better. This Humble Book Bundle: Java is a good opportunity to acquire these titles.

Monday, November 20, 2017

The primary types/objects used for decimal numbers in Java are float/Float, double/Double, and BigDecimal. Each of these has cases in which its "default" string representation is "computerized scientific notation." This post demonstrates some simple approaches to provide a string representation of the decimal number in these cases without scientific notation.

Examples in this post will demonstrate the "default" scientific notation String representations of these Java numeric types using a range of numbers for each type that demonstrate approximately where the "default" representation for each type becomes scientific notation. The next three code listings show the code for constructing general ranges for floats, doubles, and BigDecimals. The full source code listing for these examples is available on GitHub.

The three methods shown above can be called with ranges specified to demonstrate when scientific notation is automatically employed for String representations of the Java decimal types. The output from running the above with "default" format for each numeric type is shown in the next three output listings.

The default representation of very small and very large floats does include scientific notation for the smallest numbers shown and for the largest numbers shown. These numbers demonstrate what is discussed in the Float.toString(Float) documentation: numbers "less than 10-3 or greater than or equal to 107" are "represented in so-called 'computerized scientific notation.'"

The default representation of very small and very large doubles does include scientific notation for the smallest numbers shown and for the largest numbers shown. These numbers demonstrate what is discussed in the Javadoc documentation for Double.toString(double): numbers "less than 10-3 or greater than or equal to 107" are "represented in so-called 'computerized scientific notation.'"

While float and double had their smallest and largest numbers expressed in scientific notation, BigDecimal only does this by default for smaller numbers. This is described in the BigDecimal.toString() Javadoc documentation: "If the scale is greater than or equal to zero and the adjusted exponent is greater than or equal to -6, the number will be converted to a character form without using exponential notation. ... if ... the adjusted exponent is less than -6, the number will be converted to a character form using exponential notation."

The representation of very small and very large numbers in the code above can be presented in default format or in a format the precludes use of scientific notation. The code listing for the Format enum is shown next and this enum demonstrates approaches that can be used with float, double, and BigDecimal to render them without scientific notation.

The Format enum uses an instance of NumberFormat with grouping disabled and with the maximum fraction digits set to Integer.MAX_VALUE to ensure that floats and doubles are rendered without scientific notation. It's even easier to accomplish this with BigDecimal using its toPlainString() method.

The output from running the code with the Format.NO_EXPONENT is shown next (and there's no exponents or scientific notation in sight).

The standard Java floating types and BigDecimal class render some numbers in scientific notation, but it's easy to ensure that this default presentation of scientific notation is not used when it is not desired.

Saturday, November 4, 2017

This series on parsing command line arguments in Java has consisted of 29 posts published over four months and covering 28 distinct open source libraries available for parsing command line arguments in Java. This post collects some observations that can be made from the first 29 posts in this series and provides some general considerations to make when selecting one of the 28 libraries or deciding to roll one's own command-line argument parsing code. Although no one library will be the best fit for every situation, this post will also look at how some libraries may be a better fit than others for specific situations. The post will end with a subset of the original 28 libraries that may be the most generally appealing of the covered libraries based on some criteria covered in the post.

The plethora of Java-based libraries for parsing command line arguments in indicative of the vastness of the Java ecosystem.

The fact that all 28 covered libraries are open source is a reminder of how fundamental open source is in the Java culture.

There are some interesting differences between the libraries covered in this series and the various different approaches are a reminder that there's often more than one way to implement even relatively minor functionality in Java.

The large number of libraries for parsing command line arguments in Java, many of which are associated with author statements saying something about the existing libraries not satisfying their needs, is evidence that it's unlikely there will ever be a single language, framework, or library that will be "best" to everyone. If something as simple as a command line parsing library cannot be written to be everyone's favorite, it seems impossible to ever have a larger library, a framework, or a programming language be everyone's favorite. "One size doesn't fit all" when it comes to libraries, frameworks, and programming languages.

It's not just technical strength that must be considered when evaluating and selecting a library; its license, distribution mechanism, currency, provider support, and community support also all weigh in on the decision. Even the version of Java it will run on plays a role in the decision.

Evaluation Criteria

These are several criteria that may be important to a Java developer when selecting between so many libraries and when weighing whether to use a library or implement one's own command line argument functionality.

Is it open source?

My simple definition of open source in this context is "source code can be legally viewed by developers using the library." Wikipedia articulates a similar but slightly stricter definition, "[open source code] is source code [that is] made available with a license in which the copyright holder provides the rights to study, change, and distribute the software to anyone and for any purpose."

All 28 libraries covered in this series make source code available to developers using the library and so are "open source" by my simple definition and also generally meet the slightly stricter definition on Wikipedia.

What is its license?

The license under which each library is issued can be significant in determining whether to choose that library. Most users will be most comfortable with open source licenses that are clearly defined and that are most liberal in what they allow.

Many of the libraries covered in the series are released under liberal open source licenses, but some are released under less liberal licenses or do not have an explicitly specified license at all.

What is its size?

Use of a library typically means an additional JAR on the classpath and it may be important in some situations to keep the size of these additional libraries as small as possible for a particular deployment environment.

None of these command line parsing libraries are large when compared to libraries such as Spring and Hibernate, but the relative differences in size among these libraries can be large.

Are there third-party dependencies?

Third-party libraries add to the overall increase in library size and mean more dependencies to manage.

Most of the libraries covered in this series do not have additional dependencies, but some of them do.

What is the distribution mechanism?

Availability as a single JAR via Maven repository is probably the easiest mechanism for most Java developers to acquire a library.

There are JARs available in the Maven repository for many of the covered libraries, but some of the libraries require downloading the JAR from a project site or associated article site.

The 28 libraries covered in this series tend to be distributed via Maven repository, via project page download (GitHub, SourceForge, library author's site, etc.), and even copy-and-paste in a couple of cases where the "library is a single Java source code file.

Documentation

The libraries covered in this series are documented in a variety of ways including project documentation, Javadoc documentation, unit tests, and in-code comments.

Many of the libraries have the equivalent of a "Quick Start" tutorial, but some have relatively little documentation other than that. Some have no or very few Javadoc comments and others have significant Javadoc-based API documentation. Many of the libraries make their Javadoc-generated documentation available online, but some require downloading the library to see its Javadoc-based documentation.

Community

With open source projects, it's often advantageous to have a large community that uses the product because a large community means more implicit testing and potentially more blog posts, articles, and forum messages on how to use that project.

The sizes of the communities of the libraries covered in this series vary dramatically and it can be difficult to ascertain the size of any given community. However, the number of libraries dependent on a given library and the number of online resources talking about a given library give us an idea of community involvement.

Age of Library / Most Recent Update

Newer is not always better, but it generally is more compelling to use an open source product that receives current and recent updates than to use a product that has not been updated or changed in many years. It's a bit less of a concern with a small and simple library such as a command line parsing library, but currently supported libraries are still advantageous over potentially abandoned projects.

What features does it offer?

This is where the libraries covered in the series really differentiate themselves, but it's the criterion that is most difficult to compare between libraries as it really depends on which particular feature is desired.

Most of the covered libraries provided most of the features covered in the simple examples in this series. However, some of the libraries provided significant features that were beyond those used in each library's example.

For the simple examples used throughout this series, the ease of use of the API provided by the parsing library was probably as important of a feature as any.

The CLI Comparison page on the picocli GitHub page compares and contrasts many of the libraries covered in this series and some libraries not covered in this series. The page compares the libraries in table format by listing each library's respective attributes such as license, minimum Java version supported, style of API, and parsing options supported.

This series has covered 28 different libraries for parsing command line arguments from Java. It's impossible to designate any one of these as the "best" library for this purpose for all people in all situations. Each library is an investment of time and effort by its developer (or developers), but I attempt here to narrow down the list of libraries to the subset that I believe is most likely to appeal to general situations and developers.

Voted Most Likely to Succeed

The following libraries are listed in alphabetical order rather than in my order of preference.

Apache Commons CLI

In my opinion, Apache Commons CLI offers the least aesthetically appealing API of this narrowed down subset of recommended libraries.

Apache Commons CLI benefits from name recognition, from being frequently used by other libraries and products, and from being around for a long time.

In environments where it is difficult to justify installation of new libraries, there is better chance of having Apache Commons CLI already available than most of the other libraries.

Apache Commons CLI is built into Groovy and so is especially easy for someone to use moving between Groovy and Java.

Quality documentation.

The Apache License, Version 2, is a well-known, liberal, and corporation-friendly license.

args4j

args4j offers numerous features and is highly extensible.

Command-line arguments are typed.

Quality documentation.

args4j is currently supported by a familiar name in the open source Java community.

The MIT license is a well-known, liberal, and corporation-friendly license.

JCommander

API consists of easy-to-use combination of annotations and builders.

Command-line arguments are typed.

Quality documentation.

JCommander is currently supported by a familiar name in the open source Java community.

The Apache License, Version 2, is a well-known, liberal, and corporation-friendly license.

JewelCli

The annotated interface approach of JewelCli appeals to me.

Command-line arguments are typed.

Quality documentation.

The Apache License, Version 2, is a well-known, liberal, and corporation-friendly license.

picocli

Highly readable annotation-based API.

Quality documentation.

Command-line arguments are typed.

One of the more feature-rich libraries covered in this series.

Currently supported (has been enhanced with several new features since I started this series of posts).

The Apache License, Version 2, is a well-known, liberal, and corporation-friendly license.

Although I listed a subset of five libraries out of the 28 covered libraries, there are reasons that a developer might choose to use one of the 23 libraries not on this narrowed-down list. Several of the libraries not on this list offer unique features that, if important enough to the Java developer, would make those libraries preferable to the 5 listed above.

The next listing associates some of the covered libraries with some of their relatively unique strengths. One of these might be selected, even if it's not in the list of five I just highlighted, if it is something that it's particularly and uniquely strong in and is one of the most important considerations for the relevant application. Many of the listed "traits" are a matter of preference or taste, meaning a library having the listed trait may be seen as a positive by one developer and as a negative by another developer.

There are numerous other characteristics that one might desire in a Java-based command-line parsing library that might narrow down the number of appropriate candidates. These include flexibility of command styles (long and/or short names, styles [GNU, POSIX, Java, etc.]), applicable license, availability of current support, new releases and updates, size of user community, and minimum version of Java that is supported. The tables provided in the previously referenced Java Command Line Parsers Comparison make it easy to compare some of these characteristics for most of the libraries covered in this series.

This series on parsing command line arguments with Java has demonstrated 28 libraries and there are several more publicly available libraries not yet covered in this series. With over 30 libraries available, most developers should be able to find an external library to meet one's needs.

Thursday, October 26, 2017

This series on parsing command line arguments from Java has briefly introduced 28 open source libraries that can be used to process command-line arguments from Java code. Even with these 28 libraries covered, the series has not covered all available open source libraries for parsing command line options from Java. For example, this series has not covered docopt, dolphin getopt, DPML CLI, the "other" JArgP, java-getopt, ritopt, cli-args, clio, TE-CODE Command, and likely many other libraries I'm not aware of. This post looks at considerations one might make when attempting to decide whether to roll one's own command line argument parsing code in Java versus using one of the plethora of command line parsing libraries that is already available.

At first glance, it would be easy to say that someone developer their own command-line parsing code in Java might be suffering from Not Invented Here Syndrome. However, I still occasionally write my own simple command line processing code and will outline the situations in which I do this.

Many of the libraries covered in this series are small. However, for cases where the command line parsing is very simple, even these smaller libraries may be heavier than what is needed for the job at hand. The examples I show in this post are the type that might fit this category. The likelihood of a developer developing custom command line processing code likely increases as the complexity of required command line parsing increases and as the difficultly of introducing new libraries to one's deployment environment decreases. Process can also influence the decision as some developers may choose to implement their own command line processing code rather than wait for requisite approvals to use the identified library.

The easiest situation to choose to not use a command-line parsing library for Java is obviously those situations in which command line arguments are not necessary. In fact, it is likely that far more Java developers never or rarely use command-line options given that so many use web servers, application servers, or other containers (such as Spring) to run that they don't think about command-line parsing for their application. Even some simple command-line-based applications may be able to assume values or read values from an assumed location and don't need arguments passed to them.

If I only have a single argument to read from the command line, I'll write that simple code myself. The Java Tutorials feature a section on Command-Line Arguments that introduces basic handling of command line arguments in Java. The zero to many strings on the command line following the Java executable application's name are provided to the Java application via the String[] or String... arguments to the classic "public static void main" function. The simple code listing below indicates how a single expected command-line argument might be processed.

The above code was easy to write because there was one command line option, it did not have an argument to go with the option, and it was required. With all of these assumptions in place, it is relatively easy to write command line parsing code.

If the application requires two arguments, it is still pretty straightforward to handle this directly in Java without a third-party library. This is demonstrated in the next code listing that simulates an application that accepts the name/path of an XML file to be validated and the name/path of the XSD against which that XML is to be validated.

In the posts in this series, I've used examples that expect a required option specifying file path/name and an optional option expressing enabled verbosity. In all of those examples, the file path/name option was a flag name (-f and/or --file) followed by a an "argument" or "value" for that option. For those examples, the verbosity option did not have an argument or value associated with it and the existence of -v or --verbose implied enabled verbosity. This is particularly easy to accomplish directory in Java without a library if I'm willing to change the approach slightly and assume the the first command line option is the file path/name and to assume that the verbosity flag, if provided, occurs after the file path/name. The other assumption that makes this easy is to assume that because the file path/name is first, I don't need to actually use a flag such as -file or -f. With all of these assumptions in place, the code example is shown next.

I've had relatively easy command-line parsing options so far because of these characteristics of these examples:

Order of command line arguments was assumed and unchangeable.

Never had more than one optional command line argument and the optional argument was expected last.

Never needed a command line argument that consisted of flag and value associated with that flag.

No option had a dependency on any other option.

The just-mentioned characteristics made for easier parsing of command line options from Java because the number of permutations and combinations to be prepared for were significantly reduced by requiring the ordering of the options, by not allowing for flags with associated values that must be handled together (each string in the provided String[] is independent of all other strings in that array), and by only allowing one optional argument at most (and requiring it to be last).

As the command-line arguments situation gets more complicated, my desire to use a third-party library increases. If I want to have multiple optional arguments or want to have options that consist of flags with associated values, I'm more likely to make the jump to the third-party libraries for parsing command-line arguments in Java. Using most of the third-party libraries covered in this series removes the need for me to worry about option ordering and option name/flag associations.

One situation in which it might be desirable to roll one's own command-line parsing code in Java is when those parsing needs are highly specific to a particular situation that is not handled well by the existing libraries or when none of the existing libraries adequately meet one's needs. However, with 30+ libraries available, I doubt this would occur very frequently for most people.

When developing one's own command-line parsing code in Java, other options besides writing it from scratch include forking and extending one of the open source libraries or building one's code on a framework such as that introduced in the article "Parsing Command Line Arguments with Java: Using an effective Java framework to write command line tools" (pages 20 and 22 of this Java Developer's Journal).

For small Java-based tools, the simple command-line parsing approaches shown in this post are often sufficient, especially if I'm the only one likely to use the tool. However, as the potential user base increases for the Java application, the requirements outlined in this post can become onerous and the use of third-party libraries covered in this series of posts can be helpful in creating a more user-friendly command-line argument experience. For the simplest of Java-based tools and applications, I may be able to get away with my own homemade command-line parsing code. However, for most Java applications of significance, a third-party library will make more sense because it offers significantly greater flexibility and ease of use for the end users.

Wednesday, October 25, 2017

The page for getopt4j describes this as "a library to parse command line arguments according to the GNU style." The page then introduces getopt4j: "The 'getopt4j' library is designed to parse the command line options in the same manner as the C getopt() function in glibc (the GNU C runtime library). It attempts to do this in a simpler, more Java-centric manner than the original product." This post describes use of getopt4j to parse command line options in the same manner as was done for the libraries covered in the earlier 27 posts in this series.

The "definition" stage is accomplished in getopt4j via instances of CLOptionDescriptor as demonstrated in the next code listing (full source code is available on GitHub).

As shown in the above code, the instances of CLOptionDescriptor are placed in an array to be presented to the getopt4j parser.

The "parsing" stage is achieved in getopt4j via instantiation of the CLArgsParser class. The constructor of that class accepts the command line arguments in the String[] array and the array of CLOptionDescriptor
instances representing the options' definitions. This is shown in the next code listing.

The "interrogation" stage in getopt4j is accomplished by retrieving a List<CLOption> via invocation of the method getArguments() on the CLArgsParser instance. Each instance of CLOption can be queried by its getId() method to acquire the parsed parameter by its "short"
name ('f' or 'v' in this example). Once the appropriate instance of CLOption has been found via its getId() method,
that same instance of CLOption will provide the value associated on the command line with that option via a call to the CLOption's method getArgument() method. This "interrogation" process is demonstrated in the next code listing.

The getopt4j library makes it easy to request usage/help information by passing the array of CLOptionDescriptor instances to the static method CLUtil.describeOptions(CLOptionDescriptor[]). This is demonstrated in the next code listing, a couple of lines of code called when it is detected that the file path/name has not been provided.

"Usage" Statement with getopt4j

if (filePathAndName == null)
{
out.println("ERROR: The file path/name option is required but was not provided.\n\n"
+ CLUtil.describeOptions(optionsDefinitions));
}

The first of the next two screen snapshots depicts the automatically generated "usage" statement that the code is able to invoke when the required "file option is not specified. The second image depicts various combinations of the "file" and "verbose" long and short option names being used.

There are characteristics of getopt4j to consider when selecting a framework or library to help with command-line parsing in Java.

Tuesday, October 24, 2017

CLI Parser, originally hosted on and now archived on Google Code, is now available on GitHub. The archive Google Code project page describes CLI Parser as a "very simple to use, very small dependency" that uses annotations to "make very succinct main methods that don't need to know how to parse command line arguments with either fields, properties, or method based injection." The current GitHub project page describes CLI Parser as "a tiny ..., super easy to use library for parsing various kinds of command line arguments or property lists."

CLI Parser expects the "definition" stage to be implemented via the @Argument annotation. This is demonstrated in the next code listing, which provides a simple example defining "file" and "verbose" options as has been done in previous posts in this series. The complete code listing is available on GitHub.

The code shown above defines two options. Each option can be specified with a name matching the field name (file or verbose) or with the specified alias (f or v). With CLI Parser, either case (full field name or alias) is expressed on the command-line with a single hyphen. As shown in the code example, an option can be specified as "required" and description text can be provided to be used in help/usage statements.

The "parsing" stage is accomplished in CLI Parser via static functions on its Args class. In this case,
I'm using the Args.parseOrExit(Class, String[]) function as shown in the next code listing.

"Parsing" Stage with CLI Parser

final List<String> unparsed = Args.parseOrExit(instance, arguments);

The "interrogation" stage is accomplished by accessing the fields annotated with @Argument as demonstrated in the next code listing.

The "definition" code defined the "file" option as "required." If this option is not specified on the command line, CLI Parser automatically prints out a usage statement using the "description" values provided in the respective @Argument annotations. This is shown in the next screen snapshot, which is followed by another screen snapshot indicating combinations of the -file/-f and -verbose/-v options.

There are characteristics of CLI Parser to consider when selecting a framework or library to help with command-line parsing in Java.

CLI Parser is open source and available under the Apache License, Version 2.

CLI Parser is a small, lightweight library with the cli-parser-1.1.2.jar being approximately 15 KB and having no third-party dependencies.

CLI Parser is, as advertised, a "tiny" and "super easy to use library for parsing various kinds of command line arguments." It's liberal open source Apache license makes it easy for most organizations to acquire and use it.

Monday, October 23, 2017

I became aware of the twenty-sixth featured Java-based library in this series on parsing command line arguments because of a Tweet. CmdOption is described on its main GitHub page as "a simple annotation-driven command line parser toolkit for Java 5+ applications that is configured through annotations." The project's subtitle is, "Command line parsing has never been easier."

The annotation @CmdOption is used to annotate fields (or methods) that will contain the parsed command-line arguments. In other words, it is with the @CmdOption annotation that the "definition" stage is accomplished with CmdOption. This is shown in the next code listing.

As with other posts in this series, the examples used in this post are of options specifying file path and name and a verbosity level. The full source code listing for the example code listings in this post is available on GitHub. As the above code listing shows, the "long" (with double hyphen) and "short" (with single hyphen) option names can be specified with the @CmdOption annotation's names element. The minCount element is used to specify that a particular option must have an argument passed to it and the args element lists the string reference to the argument of an option that will be rendered in the help/usage display. The maxCount element is set to 0 for the verbosity option because no arguments should be provided for that option (presence of -v or --verbose is enough).

The "parsing" stage is accomplished in CmdOption by passing an instance of the class with @CmdOption-annotated fields (or methods) to the constructor of the CmdOption's CmdlineParser class and then passing the String[] representing the command-line arguments to the parse(String[]) method of that instantiated CmdlineParser class.

"Parsing" Stage with CmdOption

final Main instance = new Main();
final CmdlineParser parser = new CmdlineParser(instance);
parser.parse(arguments);

The "interrogation" stage in CmdOption consists simply of accessing the @CmdOption-annotated fields (or methods) on the instance of their containing class that was passed to the CmdlineParser constructor.

CmdOption provides mechanisms to make generation of "help" or "usage" statements easier. If the @CmdOption annotation includes the element isHelp=true, CmdOption won't validate the command-line arguments when the option associated with isHelp=true is specified on the command line. This prevents error messages about missing required options or arguments from being displayed and then the method CmdlineParser.usage() can be invoked to have CmdOption print out usage/help information. A portion of code demonstrating this is shown next.

The following three screen snapshots show the above code in action and using CmdOption. The first image depicts two error messages, one when no options are specified (-f/--file is required) and one when the "file" option is specified without an argument. The second image depicts the combinations of short and long option names. The third image shows the usage that is printed when the -h or --help option is specified.

There are characteristics of CmdOption to consider when selecting a framework or library to help with command-line parsing in Java.

The de.tototec.cmdoption-0.5.0.jar is approximately 82 KB in size and requires no third-party dependencies.

CmdOption 0.5.0 is compiled with "major version: 49", meaning that it's compatible with J2SE 5 applications. Although there are multiple libraries covered in this series that have similar annotations to CmdOption's, this ability to work with an older version of Java may be a differentiator in some cases.

CmdOption is still being supported; the version covered in this post (0.5.0) was updated earlier this month (9 October 2017).

CmdOption is an easy-to-use library for parsing command-line options in Java. It comes with a liberal open source license and has received recent updates.

Because JCommando uses XML to specify command line options to be parsed, the "definition" stage with JCommando is accomplished via XML specification. As with the previous posts in this series, the examples in this post are based on command line options for file path and name and verbosity and their definition in JCommando-compliant XML is shown in the next code listing (options.xml).

JCommando uses the XML file an input and, based on that XML, generates a Java source code file that parses the options specified in the XML. There are two ways to instruct JCommando to parse this XML and use the details to generate Java source code. One way is to use the executable jcomgen executable provided with the JCommando distribution (in its bin directory). The second approach for generating a Java class from the XML is the approach shown here: using Apache Ant and a JCommando-provided Ant task. This is demonstrated in the next XML/Ant listing.

The above Ant target shows how JCommando allows the input XML file (options.xml) to be specified as the "inputfile" and that the generated Java source code file will be placed in the src directory in a subdirectory structure matching the designated package "examples.dustin.commandline.jcommando". The execution of the Ant target and source code generation is shown in the next screen snapshot.

The result of this Ant target is the generated Java source class MainParser.java whose listing is shown next.

With the Java source code generated, we now have our options definitions. A custom class is written to extend the generated MainParser and to access its parent for parsing. This is demonstrated in the next code listing of the custom written Main class that extends the generated MainParser class.

As shown in the custom Main.java source code shown above, the "parsing" stage is accomplished in JCommando via execution of the parse(String[]) method inherited from the class that JCommando generated based on the configuration XML (and that generated class gets its definition of that parse method from its parent JCommandParser class).

The custom class that extends the generated class needed to have the "set" methods for the options implemented. With these properly implemented, the "interrogation" stage in JCommando-based applications is as simple as accessing the fields set by those custom implemented "set"
methods. This was demonstrated in the doExecute() method shown in the last code listing. That doExecute method was generated as an abstract method in the generated parent class because of the specification of the <commandless>
element with id of "execute" in the configuration XML.

The JCommandParser class that the custom class ultimately extends has a method printUsage() that can be used to write "help"/"usage" output to standard output. This can be seen in the source code for Main.javaavailable on GitHub.

The next two screen snapshots demonstrate execution of the sample code discussed in this post. The first screen snapshot shows the "usage information that can be automatically printed, in this case when the required "file" option was not specified. The second screen snapshot demonstrates the combinations of long and short option names for the "vile" and "verbose" options.

The steps involved with using JCommando that have been discussed in this blog post are summarized here.

Define options in XML file.

Generate Java parser source code from XML using one of two approaches.

Use jcomgen tool provided in JCommando's bin directory.

Use Ant target with JCommand-provided Ant task as demonstrated in this post.

Write Java class that extends generated parser class.

There are characteristics of JCommando to consider when selecting a framework or library to help with command-line parsing in Java.

The jcommando.jar JAR is approximately 27 KB in size and there is no third-party dependency.

Defining options in JCommando via XML is a different approach than the other libraries covered in this series, but what I find more interesting about JCommando's options definition is the easy ability to express relationships between options such as "and", "or", "xor", and nested combinations of these.

JCommando implements some novel concepts in terms of Java-based command line options parsing. It requires XML configuration of the potential command line options, but makes it easy to establish relationships between those options. JCommando generates Java source from the XML options configuration and a custom parsing class extends that generated class. JCommando is also the first of the libraries covered in this series to use the Zlib license.