*! version 1.0 05jul2015

Title

jcd -- Dynamically load and call Java plugins

Syntax

jcd
class
[varlist]
[if] [in]
[, args(argument_list)]

Description

The Stata Dynamic Plugin Loader (DPL) is Stata Java plugin to dynamically load other Java plugins. It thus allows developers to quickly iterate and debug their own plugins, without having to restart Stata for each new build.

jcd is a convenience method facilitating the use of DPL. It can be used just like javacall (except for the method part, which is obsolete). That is, invoking

. jcd your.company.your.Plugin varlist if in, args(your args)

is equivalent to invoking

. javacall de.pbc.stata.PluginLoader start varlist if in , args(your.company.your.Plugin your args)

Additionally, jcd maps post-estimation scalars and macros, which aren't accessible from within Java plugins, to general use scalars and macros, which are accessible from within Java plugins.
That is, all e(X) macros and scalars are accessible as e_X, e.g. e(cmd) as e_cmd; same for r(X).

See below for how to set-up and use DPL.

Setup

In a first step, the Dynamic Plugin Loader (DPL) has to be configured. Think of it as setting up your IDE by configuring the CLASS_PATH to a 3rd party library. For this purpose, DPL expects config/dpl.xml in the current user.dir.
In the case of Stata, this is always the working directory (pwd) at the time the Java Virtual Machine (JVM) was started.

config/dpl.xml is expected to be a standard XML file as it is used by java.util.Properties. It should contain 2 properties:

CLASS_PATH: Semicolon (;) separated paths to all folders containing compiled Java .class files. The paths have to satisfy Paths.get(String, String...) naming conventions. The paths may be relative to user.dir.

JAR_PATH: Semicolon (;) separated paths to all folders containing JAR files. The paths have to satisfy Paths.get(String, String...) naming conventions. The paths may be relative to user.dir.

Conveniently, these paths can link directly to your IDE's workspace. For example, .../Eclipse/Your Project/bin for all compiled .class files in an Eclipse environment.

This is all the configuration you need to do. In order to use DPL, make sure the DPL JAR is on one of Stata's ADO paths.

Remarks

See github.com/philippbc/java-stata-dpl for more documentation and help forums.

If your plugin class is on one of the ADO paths DPL will always use this version; it will not load your class from the resource paths specified in the configuration file.
That is, versions of classes on ADO paths supersede all versions on CLASS_PATHs and JAR_PATHs.

Any uncaught exception occurring during the execution of your plugin leads to DPL returning with error code 44. The exception and its stack trace are printed to the Stata console.
This also applies to all steps in preparation of your plugin's execution (e.g., reading config/dpl.xml).

You can run DPL with Java 8 (e.g., if your plugin needs Java 8).
To do so, set java_vmpath "C:\Program Files\Java\jre1.8.0_XX\bin\server\jvm.dll" will do the trick (replace XX with your current Java 8 version). For details, see query java.

Dependencies

Stata's SFI API for error logging (http://www.stata.com/java/api/index.html)

Apache Commons IO 2.4 (https://commons.apache.org/proper/commons-io/)

The simple java.util.Properties wrapper for the configuration file (https://github.com/philippbc/java-utils-properties)