XpressMP Java Examples

I've been looking at the examples that ship with the FICO XpressMP optimizer, specifically those using the Java API, and I ran into a bit of a conundrum. The examples live in the .../examples/solver/optimizer/java folder, which also contains a subfolder named objects. The file .../examples/solver/optimizer/index.html has a section title "Calling the library from Java" which lists the various example problems, gives a short description of what they exemplify (for instance, "Using Xpress callbacks"), and points to the corresponding source code files.

The first point of confusion for me was why the objects subfolder contained examples that in some cases seemed to duplicate what was in the parent folder.  The second point of confusion was why some example entries pointed to multiple Java files. For instance, the entry "Goal programming: Lexicographic goal programming using the Xpress multi-objective API"  points to a single file GoalProg.java, whereas the entry "The travelling salesman problem: Using Xpress callbacks" points to two files, TSP.java and TravelingSalesPerson.java. The latter is in the objects folder. So why two versions?

A kind soul at FICO cleared things up for me. The Java API is being transitioned from a "thin wrapper" around the C API (based on the XPRSprob class) to a more object oriented version (based on the XpressProblem class). The old API is not going away, but the new API is now the recommended one. Examples in the objects folder use the new API, while those in the parent folder use the old API.

One distinction between the two APIs becomes apparent when you look at the TSP examples, which employ callbacks. The distinction has to do with the standard practice of taking the user's original model and modifying it in the presolve stage. With the original API, you have access to the presolved model, and my understanding is that you can add a cut either to the original model or to the presolved model. Since those models differ substantially (including in regard to which variables they contain), if you add a cut to the presolved model you have to "crush" it (convert from original space to presolved space) yourself. In the newer API, I believe you only have access to the original model, and so you express cuts in terms of the original variables and Xpress handles the crushing ... which is fine with me. Barring some weird exigency, I'll be sticking to the new API.