Import Java Agents and Libraries in Correct Order for Compilation

[JoelProminic]

While testing with non-Imported Java agents (see #9), I got this error when importing agents:

--- Importing '/local/notesjava/workspace/domino_java_tools/../DXLExporter/import/MOO/MOOWeb_LaunchSettingsFix/code/agents/java/(router).dxl' ---
## Log:  
<?xml version='1.0'?>
<DXLImporterLog>
<warning source='NotesInputSource' line='7' column='27' id='7005'>Java compile errors:
/tmp/notes33573D/jar05927.dir/JavaAgent.java:10: error: package net.prominic does not exist
import net.prominic.DominoUtils;
                   ^
/tmp/notes33573D/jar05927.dir/JavaAgent.java:11: error: package net.prominic.log does no</warning>
</DXLImporterLog>
## End Log
Imported 1 elements

Claude identified that this was because the DominoUtils library hadn't been imported yet.

I'm planning to have DominoBlueprintImporter (#13) automatically detect these dependencies and import them in the correct order:

• Java Resources
• Script Libraries - need to import in a specific order
• Agents

[JoelProminic]

Writeup from Claude:

---

Dependency-aware import ordering for compiled design elements

Status: proposed — for issue tracking.
Target: the DominoBlueprint importer (DominoBlueprintImport), not domino_java_tools.
Land as a separate commit/issue from the DXLImport copy
(see DominoBlueprint_Import_Migration.md).

Problem

DxlImporter compiles Java agents, Java script libraries, and LotusScript at import time,
and it compiles each element in isolation against whatever already exists in the target
database. A blueprint is imported file-by-file in alphabetical path order, which does not honor
the dependency graph, so an element that is imported before its dependencies fails to compile.

Observed on the MOOWeb import (alphabetical order):

(router)   needs utils, logger, req, web.request   -> all imported later        -> FAIL
mustache   needs com.samskivert.* (jmustache jar)  -> jar in resources/, last    -> FAIL
req        needs net.prominic.web (web.request)    -> sorts after "req"          -> FAIL
req.get    needs net.prominic.DominoUtils (utils)  -> sorts after "req.get"      -> FAIL
req.post   needs net.prominic.web (web.request)    -> later                      -> FAIL
utils, web.request, logger   (no deps)                                           -> OK

These surface as DxlImporter log warnings (HCL id 7005, "Java compile errors"), not as
thrown exceptions: the design note is still created and counted as imported. The element exists
but will not run until it compiles cleanly. (The importer now prints a warning when this
happens; this issue is about preventing it.)

What the DXL gives us

• Java agents / Java script libraries: dependencies are explicit in each element's
  <javaproject> as <sharedlibraryref name="…"/>. This is a complete DAG. Example from
  MOOWeb:

  utils         -> ()
  web.request   -> ()
  logger        -> ()
  mustache      -> utils
  req           -> logger, utils, web.request
  req.post      -> req
  req.get       -> mustache, req
  (router)agent -> req.get, req.post, utils
  

  Topological order = utils, web.request, logger, mustache, req, req.post, req.get, (router).
  Referencing a library transitively pulls in its compiled classes, so a single dependency-
  ordered pass compiles everything — no fixpoint needed for the Java graph.

• LotusScript: dependencies are not in a structured tag; they appear in source as
  Use "libname" / UseLSX. Derivable, but requires parsing the script text. (In MOOWeb the
  LS agents have no Use references, so they were unaffected — but the importer should handle
  the general case.)

• .jar file resources: the Java→jar build-path link is not encoded in the element
  DXL. mustache imports com.samskivert.mustache.*, but nothing in mustache.dxl references
  jmustache-1.15.jar (no <resourceref>, no embedded archive item). So jar dependencies
  cannot be derived from the DXL — and ordering alone will not fix mustache; it needs the jar
  on the library's build path. This is an exporter fidelity gap (sibling to Item D in the
  round-trip status) and should be tracked there; the importer can only mitigate by importing
  all file resources before code.

Element-type applicability

Type	Compiled at import?	Ordering needed?	Source of deps
Java agent / Java script library	yes	yes	<sharedlibraryref> (clean DAG)
LotusScript agent / library	yes (setCompileLotusScript(true))	yes	Use / UseLSX in source
Imported-Java library	no (precompiled bytecode)	no	n/a
JavaScript / SSJS library	no	no	n/a
Formula / @formula	no	no	n/a

Proposed approach

Phased import with a dependency-ordered code phase:

1. Phase 1 — non-compiled elements first. Import everything that does not compile and that
   compiled code may depend on: file resources (incl. .jars), images, forms, views, pages,
   subforms, ACL, db properties, etc. This guarantees referenced jars and design notes exist
   before any code is compiled.

2. Phase 2 — compiled code in dependency order.

   • Build a dependency graph: Java from <sharedlibraryref>; LotusScript from parsed
     Use/UseLSX.
   • Topologically sort (e.g. Kahn's algorithm) and import in that order.
   • Handle edge cases: report cycles (shouldn't occur for valid designs) and warn on
     references to elements not present in the blueprint.

3. Fallback — multi-pass to a fixpoint. If a full graph can't be built (e.g. the jar gap,
   or LS Use parsing is incomplete), re-import the compiled elements, repeating until the
   compile-warning count stops decreasing. Each pass resolves more dependencies. With
   REPLACE_ELSE_CREATE, re-import recompiles.

4. Error escalation. During passes, compile failures are warnings (expected while deps
   aren't in yet). Compile errors that remain after the final pass are elevated to real
   errors and produce a non-zero exit. Track an "imported with compile errors" count distinct
   from "imported" so a broken element never hides inside Failed: 0.

Notes / risks

• The mustache → jmustache.jar case will likely still fail until the exporter records the
  jar build-path reference (or the jar is otherwise placed on the library's project path).
  Track that fix exporter-side; this issue should at least order resources first and surface
  the residual failure clearly.
• Keep the phase classification driven by the same element-type knowledge the exporter uses
  (DxlProcessor) so the two stay consistent — another reason this lands in the DominoBlueprint
  project rather than the role.

Testing

• Round-trip on MOOWeb: import a clean blueprint into a fresh DB (CreateDatabase), assert
  zero compile warnings after the final pass.
• Verify the (router) agent compiles and the router?openagent&req=home request runs
  (cross-check against Item C runtime error in the round-trip status).
• Unit-test the graph builder and topological sort on the MOOWeb <sharedlibraryref> set above
  (deterministic expected order).