An Object Oriented API for Linkage Checks

Object Oriented programming is more than using classes as structs to decompose an algorithm. Indeed object oriented programs do not model algorithms. They model entities in the problem domain. Algorithms and data structures are implementation details that can be changed without affecting the public surface. If an API exposes a particular algorithm, then the model is incomplete.

In the linkage checker and enforcer rule, we model a Java classpath. More specifically, these are the entities in play:

• Classpaths
• Classpath entries
• Jar files
• .class files
• Maven artifacts
• Maven dependencies
• Maven dependency graph

There are a few things that might be added. For example, it's easy to imagine a classpath entry that has a directory of compiled .class files rather than a jar file, though as yet we haven't needed that. But this is the basic list.

There is a certain containment hierarchy here that should be reflected in our classes. In particular:

• A Classpath has classpath entries, in order.
• A classpath entry has:
  • a JAR file
  • a Maven artifact
  • .class files
  • resources
  • a Manifest
  • etc.
• A .class file has
  • byte code
  • symbols it defines
  • a binary name
  • a fully package qualified source name
  • symbols it references (derived from the byte code)

Now we might not need to model all this. For instance, the Manifest has not mattered up till now so it's omitted completely. We preprocess the byte code in a .class file to extract symbols we care about and throw the rest away.

Linkage error is left out of this list. Arguably it should be a type, but equally likely it is a property of a symbol reference of a .class file. I.e. valid or invalid, found or not found. Then again, whether it's valid depends on the classpath so perhaps it has an independent existence.

Things that don't appear here: linkage checker, class dumpers, or anything else that is a verb masquerading as a noun. At most these are methods on the relevant classes, or better yet internal implementation details. In an object oriented system, you don't check a classpath for linkage errors. Instead you ask the classpath to tell you its linkage errors.

Also missing: maps, multimaps, immutable sorted sets of lists of maps, and so forth. Each class can be queried directly for its information.