How do I compile Java plugins for Stata?

[Michael Anbar]

I followed the instructions in -help java- to create an example file, "test.java" with Stata's example code. Now, I'm trying to compile "test.java" to a JAR file from the Windows command line, using javac:

javac -classpath "C:\Program Files (x86)\Stata14\ado\base\jar" test.java

This throws numerous errors, the first of which is

test.java:3: error: package com.stata.sfi does not exist
    import com.stata.sfi.*;
    ^

I'm guessing this is because the Java compiler isn't finding Stata's packages, although the directory I added to the classpath contains "stata-sfi.jar", "libdeps-core.jar", and "libstata-core.jar". I'm using a Windows 7 x64 system, Stata 14 MP, and the 64-bit JDK v 1.8.0_66.

What am I doing wrong? How do I compile a Java plugin for Stata?

Thank you!

[James Hassell (StataCorp)]

Michael,

You will need to add jar files specifically to your classpath. The com.stata.sfi package is located in the stata-sfi.jar file. The other jar files from that directory can be ignored, as they are there to be used by Stata.

 
 javac -classpath "C:\Program Files (x86)\Stata14\ado\base\jar\stata-sfi.jar" test.java

You can also copy stata-sfi.jar to your project directory or other convenient path relative to your project, so that specifying the classpath will be easier.

Hope this helps.
-- James

[wbuchanan]

Another option that I've found helpful is to install the Java API jar to your local Maven and then use Maven to add it to your project as a dependency. Depending on what you're doing you may find: https://github.com/wbuchanan/StataJavaUtilities helpful, and should be able to reference it from Maven as well.

[Michael Anbar]

Michael,

You will need to add jar files specifically to your classpath. The com.stata.sfi package is located in the stata-sfi.jar file. The other jar files from that directory can be ignored, as they are there to be used by Stata.

Thanks, this is what I was looking for. Should I be worried that the example in the Stata documentation (under -help java-) uses methods that are deprecated according to the Stata-Java documentation, e.g. getParsedIn1()? The example itself doesn't mention that those functions are deprecated, which seems misleading.

[Michael Anbar]

Another option that I've found helpful is to install the Java API jar to your local Maven and then use Maven to add it to your project as a dependency. Depending on what you're doing you may find: https://github.com/wbuchanan/StataJavaUtilities helpful, and should be able to reference it from Maven as well.

I'll look into this. It's been years since I've used Maven, and (as you can probably tell) even longer since I've used Java, but this sounds helpful.

[James Hassell (StataCorp)]

Should I be worried that the example in the Stata documentation (under -help java-) uses methods that are deprecated according to the Stata-Java documentation, e.g. getParsedIn1()? The example itself doesn't mention that those functions are deprecated, which seems misleading.

No you don't need to be worried, but I think an explanation will help. New to Stata14, Stata/MP can hold more than 2 billion observations. To support that feature new methods were added to the Java classes that accept and return a long data type for observation numbers. We deprecated the old methods (int data type) to encourage use of the new methods, although we really have no plans to remove the old methods. We will get the documentation updated to use the new methods as soon as we can.

[wbuchanan]

Michael Anbar this is what I've used (I work on a Mac 99.9% of the time so you'll likely need to adjust the path) :

mvn install:install-file -Dfile=/Applications/Stata/ado/base/jar/stata-sfi.jar -DgroupId=com.stata -DartifactId=sfi -Dversion=14 -Dpackaging=jar

Then, if you're using NetBeans, Eclipse, or IntelliJ (which all have Maven support either natively or pretty close to it), you can add:

<dependencies>
  <dependency>
     <groupId>com.stata</groupId>
     <artifactId>sfi</artifactId>
     <version>14</version>
     <type>jar</type>
     <scope>provided</scope>
  </dependency>
</dependencies>

to your pom.xml file and you'll be good to go (just remember to still add the import com.stata.sfi.*; at the beginning of your code). Assuming you have the necessary Maven plugins, you can compile and package your code into a jar in a single step. I messed around with NetBeans a little bit, but I've started to grow pretty fond of IntelliJ since it has some nice features that make it a bit easier to test your Java plugins (e.g., you can access a terminal within the program, issue the Maven command to compile/build your plugin, start Stata in batch mode, and test away).

[Diogo Pereira]

It would be great if StataCorp would publish stata-sfi.jar in a public Maven repository with proper versioning.

[wbuchanan]

Diogo Pereira other than saving the single step of a manual installation from my example above, what value would there be in publishing the jar on Maven central or other repositories? Without having an installation of Stata available the Jar serves no purpose to the broader developer community and while I've not checked, I'd be willing to guess that there may only be a handful (if that) libraries published to one of the maven repositories that have been developed by Stata users (including the one or two examples I've pushed to the sonatype repo).

[Diogo Pereira]

Diogo Pereira other than saving the single step of a manual installation from my example above, what value would there be in publishing the jar on Maven central or other repositories?

It's not a single step if you don't have Maven installed. I use Gradle and had to waste a couple of hours trying to figure out the repository structure and manually editing XML files. Not fun.

Anyone should be able to clone my GitHub repository, run "gradlew build" and be on his way without first having to muck around with a local Maven repository.

[wbuchanan]

So you want the jar published in a Maven repository so you can use a different build tool for your project? I've never used Gradle so am not sure how it handles dependency management, but it seems odd that it requires so much effort. Since there might be other users interested in using Gradle, why not post the solution you came up with so others won't have to spend as much time going through the same issues?

[Diogo Pereira]

AFAIK, most build tools for JVM languages (Maven, Gradle, sbt, leiningen ...) handle dependency management in the same way, using Maven metadata. The "solution" I came up with is the same as yours. It is not a good solution because it has to be repeated by everyone who wants to build a plugin, on every machine he wants to use. And if I want to set up CI builds on Travis, where are am I going to get the JAR from?

There is a reason why everyone publishes JVM libraries in Maven repositories.

[wbuchanan]

Travis supporting Stata now? One line of code to install the binary locally isn't really that big of a step to ask for. More importantly, the dependency should be referencing it as provided since the assumption is that users have Stata available if they are using a Java plugin for it. If the Java API acted as a controller for Stata I could see some additional value for it. You could also add the jar to the class/build path as well, so while there would definitely be some convenience from using Maven references I don't see what benefit it would have for Stata and think it could make things more confusing in the long term (e.g., having to remember that version 1.x.x refers to the Stata 13 Java API, etc...).

[Diogo Pereira]

One line of code to install the binary locally isn't really that big of a step to ask for.

Well, and is publishing it in a public repository that big of a step to ask for? Either StataCorp does it once and everyone benefits, or I have to do it, you have to do it, Michael has to do it, and everyone else who wants to write or build a plugin has to do it. A waste of everyone's time.

Versions could (and should) be 13, 14, etc. just like you did.

[wbuchanan]

Installing it locally is just a matter of convenience when working with the IDE I use. I could just as easily add the binary to the build/classpath, but aside from the one line of code it takes to install the Java binary locally it wouldn't be saving end users that much time (at least with Maven). If Gradle, Ant, or and of the other build tools that exist require more extensive settings to set things up, it might just be easier to share the set up instructions or make some type of official recommendation to use one vs the other build tool. It is possible that there are also some legal issues related to the IP rights that would make publishing to Maven difficult for Stata. If the folks at StataCorp see more users developing Java-based solutions I would assume there would be much more willingness to do things like this, but its probably like the the C API that was rarely used (so as much as possible if you can publish your own work so other users can use it it would likely help things).