Minimal DXL Importer Project Example

[JoelProminic]

From @JustinProminic

I have poured over the DxlImporterDemo_TestSimplified.

It is fine for someone who really understands Ant, Gradle, and why both of those complex build tools are in the same project.

But it is way too complex for me to figure out when staring at it on my own... and so I suspect it will be for other people as well.

Using as a point of reference the simplicity of the build scripts and removal of all clutter I could (while still not being totally generic - so I accept that some complexity will need to be added back in) -- please use these two recent e-mails I sent with projects I simplified.

• Moonshine IDE -- ExampleJavaGradleDominoCommandLineApp -- will not work if the Notes Client is running but will if quit -- why -- please help (Nov. 20, 2021 4:55 PM CDT)
• Moonshine IDE -- ExampleCommandLineAppAccessIMOS is a more focused example that will prompt for password and work (Nov 20, 2021, 5:22 PM)

Next, please create the simplest possible example DxlImporter project.

It should not support multiple JARs or agents.

It should ideally not cause the user to deal with both Gradle and Ant.

It should be able to run from the local Mac Notes (without closing down Notes) to inject the agent into a database.

It should be able to inject into a database directly from being run in Moonshine.

It should have the fewest possible files in the project that still support the nature of DxlImporter.

It should have documentation that clearly explains what any weird files are that are in the project. In particular, there is at least one binary only fine called ScriptLibraryImportTemplate->%%source%%.jar which I find concerning and suspect others will, too.

If it is needed, then a README.md or equivalent file needs to be placed in the same directory as it that explains that that file does and why it is not suspicious.

This is related to #668. Note that DXL Importer is still in Prominic SVN, so this source is not available for external reference. This issue should be moved to the ImportDXLNSF project when we have it available. I'm including it in this repository for now because it will probably be useful in further cleaning up the template for #668 (which I was planning to do already).

Here are some ideas for implementing the above requirements:

• Remove the Ant scripts and run DXLImporter in Gradle. See JavaExec (execution, replaces build-lib.xml) and Jar (building agent JAR, replaces build-agent-*.jar)
• Create a fat JAR for ImportDXLNSF with all the dependencies included, or move the dependencies to Gradle dependencies

[JoelProminic]

I confirmed I can import an agent from the current demo with a task like this:

/**
 * Import an agent using ImportDxlNsf
 * TODO:  add parameters:
 *  - agentName
 *  - type?
 * TODO:  defaults and validation for server and dbname
 */
task importAgent(type: JavaExec) {
    // Include all of the required JARs for ImportDxlNsf
    classpath = fileTree('dxlLib') { include '*.jar' } + fileTree('dxlLib/svn') { include '*.jar' }

    main = 'com.Prominic.ImportDxlNsfForStatic'  // deprecated in later versions of Gradle - use mainClass
    //mainClass = 'com.Prominic.ImportDxlNsfForStatic'

    // need to manually set DYLD_LIBRARY_PATH, since it will not be preserved in the environment
    environment('DYLD_LIBRARY_PATH', notesInstallation)

    args '-a', 'agentProperties/agentbuild/DemoJavaAgent.properties', '-t', 'agent', '-sp', 'scriptLibraryConfig/ScriptLibraryConfig.properties', '-b', '.', '-s', "$server", '-n', "$dbName"
}

TODO:

• Build agent JAR from Bamboo (default build?) and update agentProperties to use this. For now, the JAR is still built by Ant
• Update importAgent so that it can be extended to implement different agents or script libraries. This is not strictly required for this issue, but it will make the task more generally useful.
• Additional validation on the inputs
• Require the user to select their own target database.
• Fat JAR for ImportDxlNsf. I tried this, but my previous code didn't work with the recent configuration updates.

[JoelProminic]

I have a task working for the agent Jar build. Note jarAgent needs to be defined before importAgent, or the latter will show an error on the dependency.

/**
 * Build the JAR for an individual agent, containing only the required classes.
 */
task jarAgent(type: Jar, dependsOn: classes) {
	// TODO: make this a parameter for reusability?
	String agentName = 'DemoJavaAgent'
	
	// Jar name - specify the full name for reference by DemoJavaAgent.properties
	archiveFileName = "${agentName}.jar"
	
	// Optional - only include the required class files
	from sourceSets.main.output // all class files and resources
	include ("**/${agentName}.class")
}

/**
 * Import an agent using ImportDxlNsf
 * TODO:  add parameters:
 *  - agentName
 *  - type?
 * TODO:  defaults and validation for server and dbname
 */
task importAgent(type: JavaExec, dependsOn:  tasks.getByName('jarAgent')) {
    // Include all of the required JARs for ImportDxlNsf
    classpath = fileTree('dxlLib') { include '*.jar' } + fileTree('dxlLib/svn') { include '*.jar' }

    main = 'com.Prominic.ImportDxlNsfForStatic'  // deprecated in later versions of Gradle - use mainClass
    //mainClass = 'com.Prominic.ImportDxlNsfForStatic'

    // need to manually set DYLD_LIBRARY_PATH, since it will not be preserved in the environment
    environment('DYLD_LIBRARY_PATH', notesInstallation)

    args '-a', 'agentProperties/agentbuild/DemoJavaAgent.properties', '-t', 'agent', '-sp', 'scriptLibraryConfig/ScriptLibraryConfig.properties', '-b', '.', '-s', "$server", '-n', "$dbName"
}

[JoelProminic]

I committed an initial version of the simplified project in the Prominic SVN as DxlImporterDemo_GradleMinimal.

TODO:

• Update importAgent so that it can be extended to implement different agents or script libraries. This is not strictly required for this issue, but it will make the task more generally useful.
• Additional validation on the inputs
• Require the user to select their own target database.
• Fat JAR for ImportDxlNsf. I tried this, but my previous code didn't work with the recent configuration updates.

[JoelProminic]

This issue wasn't updated for a while but I have:

• Moved the DXLImporter example to GitHub (currently private): https://github.com/Moonshine-IDE/DXLImporter-Gradle-Demo
• This was used as a basis for the Java agent generation (Generate Java Agents for Domino Visual Editor #1072) and Moonshine-Domino-CRUD

The updated project can:

• Generate default Gradle tasks for the agents and script libraries based on the properties files
• Build logic can be overridden for each agent.
• fatJar is supported, but not enabled by default.