The java-utils project

Description

java-utils is a collection of java utility classes used in various project at the National Research Council of Canada.

Many of these classes provide functionality similar to functionality found in frameworks like Spring. In such cases, the reason why we implemented our own version of the functionality may be that our version:

• is more lightweight and easier to use
• provides some additional features
• was implemented at a time when there was no existing alternative
• or it could just be that we just did not know that there already was a usable implementation available

Java-utils is a Maven project with several sub-modules:

• java-utils-core: Modules that may be required by other modules. For example:

  • Acquiring configuration values from different sources (environment variable, java system properties, etc.)
  • Various assertion classes for JUnit testing
  • Safe deep cloning of objects
  • Various debug and introspection utilities
  • Pretty priting JSON objects
  • File manipulation, including files that may be buried inside of JARS.
  • Temporarily caputring STDOUT to string

• java-utils-data: Classes for acquiring and manipulating data, including:

  • Reading CSV files
  • Reading a stream of JSON objects from a file
  • File globbing
  • Searching the web using the Bing search API
  • Acquiring text from one or more web pages
  • Computing basic statistics (ex: Histogram)

• java-utils-elasticseach: "Streamlined" API for using Elastic Search for the purposes of Natural Language Processing

• java-utils-string: Various utility classes for processing strings

  • Joining, splitting, simple tokenization
  • Diffing strings with different costing models

• java-utils-ui: Classes for building and testing Command Line Interface (CLI) or web-based UIs

Documentation

There is no documentation per-se. However, most classes have a JUnit test case that starts with a section lableled "DOCUMENTATION TESTS".

Tests in this section provide well documented code examples that illustrate the different ways in which the class and its methods can be used.

Installing java-utils

At the moment, binary jars for java-utils are not available on any public Maven artifactory. To use java-utils in one of your projects, you must download it from GitHub and install it with maven command:

mvn clean install -DskipTests=true

You can then include any java-utils module in your project by adding an entry to your project's pom.xml file. For example, to include module java-utils-core, you would add something like this to your pom:

	<dependency>
		<groupId>ca.nrc.java-utils</groupId>
		<artifactId>java-utils-core</artifactId>
		<version>1.0.25-SNAPSHOT</version>
	</dependency>

java-utils properties

Some of the java-utils classes can be configured using properties whose names all start with ca.nrc.

You can configure those using either:

• Environment variables
• Java JRE system variables
• The ca_nrc properties file

The first two approaches are self explanatory.

For the 3rd approach (ca_nrc properties file), just create a properties file called ca_nrc.properties and define all your ca.nrc.* props in it. Then, point to this file using either an environment or JRE variable called ca_nrc.

For example:

 # Using JRE variables  
 java -Dca_nrc=/path/to/your/ca_nrc.properties etc...
 
 # Using environment variable
 export ca_nrc=/path/to/your/ca_nrc.properties; java etc...