This is a Java(TM) library that is used in-house at QCI in the development of Java programs. It is a collection of classes/routines we find ourselves using/recreating frequently. In order to make our code and our programs behaviors more consistent and to save work for ourselves in the future, we have cleaned up, documented, and packaged this code for internal and external reuse.
this particular library is also a testcase for standard building, testing, and packaging procedures for all of our java projects.
At the moment, this project contains utilities for assertion (precondition, postcondition, invariant, unexpected exception) testing in Java code, classes for standards-compliant command-line option processing, and a logging API. There exists a package of SQL/JDBC utilities and a package containing a generic data storage extraction layer as well, which have been split out into their own project trees available from the same web site (qjsql and dbframework respectively). More classes and features will be added to this package over time along with the inevitable bug fixes, but we will avoid changes that break existing code since we have active projects which are using this API.
A regression test suite is included to verify that the package is working with your VM. See the Maintainer's README file for information on running the regression tests and the section on Portability, below, for a list of the platforms on which we run the tests.
First of all, this product is designed and that design is evolving. This, in and of itself, may take some getting used to when using this product. An effort has been made to clearly identify and fully specify the design and the associated tradeoffs in the documentation. You may not agree with our rationale, but at least it is not hidden so you can argue with us or decide that the product will work for you- before you use it. If you don't like something, tell us. If you think we can do something better, tell us. We may not agree with you, but we will both probably learn something in the exchange.
This product is not intended to be an end-all and be-all library. The development priorities are as follows:
Thus, you will find the code littered with assertions, but little optimization, and relatively spare interfaces. Methods and classes tend to be declared final until it is determined that they can be safely overridden without breaking other classes. We try to keep the code reasonably portable, but not at the expense of maintainability or correctness. This choice of priorities is based on the application of several principles:
Therefore, you will quite likely find that some of these components don't do exactly what you want quite as quickly as you want, on all the platform/VM combinations that you would like it to. But you may find that by having all of these components available in the early stages, you will have the opportunity to customize and/or replace the few that really don't meet your needs later on. The methodical use of assertions and class invariants will make it easier to replace pieces selectively and be confident that your design is still valid.
This package is not GPLed, and therefore can be used in commercial packages. This was very important to us (see LICENSE.txt for info).
To install the package under a JDK 1.2+ VM, simply copy the jar(s) to your extensions directory as described in your VM documentation. Otherwise, put the jars somewhere convenient and make sure they are listed in your class path. On our workstations, we have our Jars available on a network server, so they are found in '/netpkg-noarch/javalib/'. Most of our dependent projects (e.g.: other subprojects on this site, also QAT) look there first, but they all provide a means of telling them to look somewhere else.
The main Java Utilities project comes with two jars, qciutil.jar and qciutil-test.jar. qciutil.jar contains the classes you need to use this project. qciutil-test.jar contains the test suite. The test suite jar, in addition to the test cases themselves, contains abstract test classes, stubs and other minor test utilities which may be useful for testing classes which use this library's facilities.
At this time, we fully expect the packages to run on any compliant 1.2.x, 1.3.x or 1.4.x VM. Compatibility with 1.x JDKs has been largely dropped. Given a pressing need, we could backport critical parts of the library to 1.x, but it is no longer an official requirement to remain portable to 1.1.x JDKs. We do have a requirement to remain compatible with 1.2.x and will probably maintain that requirement until at least 4Q2002. We have recently made changes to ensure portability to JDK 1.4 (e.g.: dealt with the fact that "assert" is now a reserved word.
Now that JDK standardization seems to have improved markedly, we are no longer testing major releases on as large a variety of JDKs/platforms. One can be reasonably certain that we or other contributors are running on at least Linux and Windows plus one or two other platforms which are being used in active projects (e.g. Solaris, SGI). We have an in-house portability lab, so we have access to different machines and configurations for dealing with problems as they are encountered. If you encounter problems on a particular platform/VM, let us know and we will try to duplicate it. If you are actively using this library on a less common platform, let us know and we will consider adding it to our test cycle.
Javadoc is available for all packages from the project web site. It can also be downloaded from the file/release manager or built from source. In addition to the raw class documentation, overview and package summary pages plus a few example classes are included.
We could say (and would mean) all of the usual things about giving back to the community, creating goodwill, etc. QCI uses Linux and other open-source software heavily for internal development (though we sometimes can't deliver them to our clients) and these tools have saved uncounted programmer-hours and software purchase dollars.
However, when it gets down to it, we have four "practical" reasons:
Download it, try it, send us fixes and improvements. We'll incorporate what we can and make new releases. Be aware that we (and others) have deployed software based on this package, so backwards compatibility is a concern.
We have a coding standard that is used in this package. It also contains generic advice for writing good code that was mainly learned the hard way and therefore may be interesting. Please look through it. We won't reject fixes or improvements that don't fit in with our scheme of things, but they may take longer to incorporate.
When sending in bug reports, fixes, comments, suggestions, please tell us what platform, VM, compiler, etc., you are using. We don't have the resources to track down bugs from incomplete reports.
We would be most appreciative if people with highly unusual portability concerns would let us access hardware for testing/diagnostic purposes. The hardware does not have to be fast, recent, etc., but just capable of running the correct software and available for network login.
http://qcijutils.sourceforge.net/ is the primary site. Binary releases are made at significant points. The most recent source code can be obtained from CVS (module "jutils1" contains the 1.0 baseline. "jutils" contains the old 0.90 project baseline).
The Sourceforge Site provides bug tracking, discussion forums, and contact information off of the Summary Page
We use a cross-platform build process based on ant. See the Maintainer's README in the source distribution for details.
Precompiled jars for the last full release are also available from the project page.