Introduction

Three months ago, I wrote about a new command, twitter2stata, that imports data from Twitter’s REST API into Stata. Today, I will show you the tools we used to develop this command. Writing this command from scratch solely in Mata or ado-code would have taken several months. Fortunately, we can significantly speed up our development using an existing Java library (Twitter4J) and Stata’s Java plugins. In this post, I will discuss the basic steps of how to leverage a Java library and the Stata Java API.

Java is the most popular programming language in the world, so there are many libraries to support your development. A quick Google search should tell you if a Java library exists for what you are trying to do; this is how we found the library Twitter4J. For the rest of this blog entry, a basic understanding of programming in Java is helpful, but not necessary.

Setup

The most common way to compile Java code is to use an integrated development environment (IDE). For this article, I will use Java IDE Eclipse, version Oxygen. Even if you have a different version of Eclipse, the steps should be similar. You can download the latest version of Eclipse from the below URL if you would like to follow this example.

https://eclipse.org/downloads/

After downloading and installing Eclipse, you will need to download the Java library twitter4j to interact with Twitter’s API.

Create project and package

To start, we must create a Project in Eclipse by opening Eclipse, going to the File menu, and selecting New->Java Project. You should now see the New Java Project dialog.

I named my project test_twitter, but you can name your anything you like. Click the Finish button and you should now see your project name in the Package Explorer pane on the left-hand side of Eclipse.

Add libraries to package

Now that we have our project, we need to add the twitter4J Java library and the Stata SFI library to it so that we can interact with Twitter’s API and Stata. To do this, unzip the file you downloaded from twitter4j.org. After you unzip the file, there should be a directory, lib, that contains the libraries we need. Remember this location.

To add the twitter4J JAR files to our project, right-click on the test_twitter package name in the Package Explorer and select Properties.

In the Properties dialog, select Java Build Path and click on the Libraries tab. Then, click on the Add External JARs… button to bring up the Jar Selection dialog. Browse to the lib directory where you unzipped the twitter4J JAR files, select all JAR files in the directory, and click the Open button.

Next, we need to add the Stata Function Interface JAR file. The file sfi-api.jar is located in your Stata installation directory. Again, click on the Add External JARs… button to bring up the Jar Selection dialog. Locate your Stata installation directory and then click on the utilities/jar directory. For example, on my computer, Stata is installed in

C:\Program Files (x86)\Stata15\utilities\jar

Find the file sfi-api.jar, select it, and then click the Open button. Last, in the Properties dialog, press the Apply and close button.

Create package and class

Now that the libraries have been added to our project, let’s create a package by adding a class to the project. To add a class to the project, go to File->New->Class and you should see:

When you add a class to a project, you must also name the package where the class is stored. A Java package is just a name space. When naming your package the Java standard is to use a URL as part of your package name space, which in my case is stata.com. You can name the package anything, but try and name it something unique to avoid Java package name collisions later on. To keep things simple, I named my package com.stata.kcrow. I named my class StTwitter. Click Finish to create your package and class.

Hello world

To test that we have everything set up correctly, let’s write a simple helloWorld (member) function in our StTwitter class to test the Stata SFI. You can copy and paste the below code into Eclipse code editor and then save the project.

package com.stata.kcrow;

import com.stata.sfi.* ;

public class StTwitter {
        public static int helloWorld(String args[]) {
                SFIToolkit.error("Hello World!");
                return(0);
        }
}

Note that the method to be called must be implemented with a specific Java signature in the following form:

static int java_method_name(String[] args)

To use this function in Stata, we must export our code to a JAR file for Stata to read. To do this, again right-click on the test_twitter package name in the Package Explorer and select Export. In the Export dialog, select Java->JAR file and then click Next.

In the Jar Export dialog, we need to export the file to a directory where Stata can find it. To do this, save the JAR file along Stata’s adopath. If you don’t know what Stata’s adopath is set to on your computer, open Stata and type adopath in the Stata Command window. For example,

. adopath
  [1]  (BASE)      "C:\Program Files (x86)\Stata15\ado\base/"
  [2]  (SITE)      "C:\Program Files (x86)\Stata15\ado\site/"
  [3]              "."
  [4]  (PERSONAL)  "c:\ado\personal/"
  [5]  (PLUS)      "c:\ado\plus/"
  [6]  (OLDPLACE)  "c:\ado/"

We should save the file in the PERSONAL directory in this case. Also, make sure the check box Export generated class files and resources is checked. Click the Finish button.

Calling the class from Stata

javacall is the Stata command we use to load our plugin. The syntax is

javacall class method [varlist] [if] [in],
{jars(jar_files)|classpath(classpath)} [args(arg_list)]

For example, to call our helloWorld method from Stata, we type:

. javacall com.stata.kcrow.StTwitter helloWorld, jars(test_twitter.jar)
Hello World!

in the Stata Command window. You can also wrap the javacall command in an ado-file to make it easier to call from Stata. For example, you can save the file twitter_test.ado, which contains the below code, along your ado-path.

program define twitter_test
        javacall com.stata.kcrow.StTwitter helloWorld, jars(test_twitter.jar)
end

Now, to call our StTwitter class, we can type twitter_test in Stata.

. twitter_test
Hello World!

In my next post, I will focus on Twitter API authentication and searching tweets using twitter4j.