這篇文章是編寫評估命令的第四篇，它演示了如何用另一種語言（如C、C 或Java）編寫的代碼插入Stata。這種技術被稱為編寫插件，或者為Stata編寫一個動態(tài)鏈接庫（DLL）。
在這篇文章中，我在Java中編寫了一個插件，它實現(xiàn)了由mymean11.ado中mymean_work()所執(zhí)行的計算，這個內容在之前的文章中有詳細的講解。
這篇文章類似于《在Stata中編寫估計命令：編寫C語言插件》和《在Stata中編寫評估命令：編寫C 插件》，不同之處在于插件代碼是在Java而不是C或C 。
編寫hello-world JAVA插件
在進行任何計算之前，我都會演示如何編寫和編譯一個與Stata通信的Java插件。Code block 1包含myhellojava.ado的代碼，調用Java插件在Stata中顯示Hello from Java。
第2行從sfi-api.jar導入Stata函數(shù)接口（SFI），我從Stata分發(fā)的Stata/utilities/jar目錄中復制到當前目錄。您應該將安裝在Stata的版本復制到Java編譯器需要的目錄中。
第3行定義了HelloFromJava的公共類別，在myhellojava.ado的第6行中指定。
第4行定義helloJavaWork()方法，它是這個插件的入口點。入口方法的簽名必須是這種形式。該方法是public static。這個方法可以返回一個int，并且它能接受字符串數(shù)組。
Stata將返回的int視為返回碼，0意味著一切都很順利而不是識別出一個錯誤條件。如果返回的int不是0，那么Stata將退出返回int中指定的錯誤。字符串數(shù)組包含javacall傳遞給插件的參數(shù)。
第5行使用SFI方法SFIToolkit.displayln()來顯示來自Hello from Java的字符串，并附加一行返回。
第6行返回0到Stata，因此Stata不會以錯誤代碼退出。
接下來將討論如何從HelloFromJava.java創(chuàng)建JAR文件hellojavawork.jar。為了便于討論，我使用了Java命令行工具。
在包含myhellojava.ado和HelloFromJava.java的目錄中，還有從Stata/utilities/jar目錄中復制的sfi-api.jar。在我的OS X Mac上安裝了命令行開發(fā)者工具，我通過輸入javac –release 8 -classpath sfi-api.jar HelloFromJava.java，從HelloFromJava.java和sfi-api.jar中使用javac創(chuàng)建HelloFromJava.class。
在本文中，Stata與Java 8一起工作，盡管Java 9已經(jīng)發(fā)布初始版本。我必須指定-release 8，因為我的機器上的命令行工具默認使用Java 9。如果javac在您的機器上默認為Java 8，您可以省略這個選項。
要從HelloFromJava.class創(chuàng)建JAR文件hellojavawork.jar，我輸入了
jar cf hellojavawork.jar HelloFromJava.class
javac和jar的這些命令可以在所有平臺上工作，您可以將一個平臺上的jar文件分發(fā)到其他平臺上。這種跨平臺的兼容性是Java的一大優(yōu)勢。為了確保Stata命令discard刪除當前裝載到Stata的所有Java類，我也刪除了javac編譯的.class，然后再使用Java類運行ado-command。
在OS X MAC操作系統(tǒng)上，我輸入
rm HelloFromJava.class
已經(jīng)創(chuàng)建hellojavawork.jar并且刪除了HelloFromJava.class。然后可以在Stata中執(zhí)行myhellojava.ado
示例1：myhellocjava
如果我更改HelloFromJava.java，重新編譯、重制JAR文件、刪除.class文件，在運行myhellojava之前在Stata中輸入dicard，那么Stata將找到Java類的新版本。discard可以工作是因為Stata的Java插件接口使用自定義類加載器而不是Java system類加載器來加載插件的JAR文件。當您在Stata的當前工作目錄中留下您的.class文件時，就會出現(xiàn)問題，因為java-system類加載器會在Stata的自定義加載器運行之前找到并加載.class文件。這個問題避免了Stata的discard命令，這意味著您必須重啟Stata來卸載舊的類定義并加載新的版本。為了防止這個問題，在調用Java插件之前刪除.class文件（或者，您可以在Stata的當前工作目錄之外使用Java代碼，但是我更喜歡刪除.class文件，因為一旦我有了JAR文件，它們就是多余的）。
為簡單起見，我將sfi-api.jar,HelloFromjava.java, myhellojava.ado,和hellojavawork.jar放在同一個目錄中。對于大型項目，我將把.ado和.jar文件放在Stata的ADOPATH目錄中，并使用我的IDE來管理我放置sfi-api.jar和Java源文件的位置。對于本文中的示例，我使用了sfi-api.jar、所有的.ado文件、所有的Java源文件以及創(chuàng)建的.jar文件都放在一個目錄中。
在插件中訪問Stata數(shù)據(jù)
helloJavaWork()使Stata顯示插件中創(chuàng)建的內容。下一步是讓插件訪問Stata中的數(shù)據(jù)。為了說明這個過程，我將討論mylistjava.ado使用插件來列出對指定變量的觀測值。
讓我們先看看ado-code。
第6行，syntax創(chuàng)建三個本地宏。它將用戶指定的變量放入本地宏varlist中，將用戶指定的任何if條件放入本地宏if中，將用戶指定的任何in范圍放入到本地宏in中。我將max=3指定到syntax，將變量的數(shù)量限制為3。這個限制是愚蠢的，我不需要它作為Stata/Mata程序的例子，但是它可以簡化Java插件的示例。
第7行中，marksample創(chuàng)建了樣本包容變量，并將樣本包含變量的名稱放到本地宏touse中。每個被排除觀測值的樣本包含變量為0，而每個非排除觀測值的包含變量為1。marksample使用本地宏varlist中的變量、本地宏if中的if條件以及本地宏中in范圍中in來創(chuàng)建樣本包含變量（所有三個本地宏都是由syntax創(chuàng)建的）。如果本地宏varlist中的任何變量都包含一個缺失值，被本地宏if的條件排除，或者被本地宏in的范圍排除在外，則會排除一個觀測結果。如果沒有被排除的話，那么樣本包含變量就是1。
第9行，我進一步通過顯示變量的名稱來簡化Jave插件，這些變量的值是由方法插件列出的。
第10行，javacall調用了這個插件。入口點是在MyListJava類中的myListJW()方法，由JAR文件myListJW.JAR定義。因為“varlist”是指定的，SFI方法將能夠訪問本地宏varlist中包含的變量。因為if “touse”是指定的，如果touse中的樣本包含變量為0，那么SFI方法Data.isParsedIFTrue()將返回0，如果樣本包含變量為1，那么會返回1。因為“in”被指定，SFI方法Data.getObsParsedIn1()和Data.getObsParsedIn2()分別返回在范圍內指定的任何用戶的第一個和最后一個觀測值。
指定“in”不是識別用戶指定的樣本所必需的，因為if “touse”已經(jīng)指定了這個樣本包含的信息。然而，指定“in”可以極大地減少循環(huán)中對數(shù)據(jù)的觀測范圍，從而加快代碼的速度。
Code block 4中的MyListJava的代碼。在包含MyListJava.java和sfi-api.jar的目錄中，我創(chuàng)建了mylistjw.jar，在我的Mac上輸入以下三行代碼：
javac –release 8 -classpath sfi-api.jar MyListJava.java
jar cf mylistjw.jar MyListJava.class
rm MyListJava.class
解釋了MyListJava.java如何說明Stata的Java插件的結構，并且討論了代碼中使用的SFI方法。
如果Stata運行順利，myListJW.java會返回0，如果出錯，它會返回一個非零錯誤代碼。
因為所調用的方法都不能失敗，唯一的錯誤條件是遇到缺失值，這些值在第30-34行中處理。在出現(xiàn)錯誤的情況下，第32行使用SFIToolkit.errorln()來確保Stata顯示錯誤消息，并以紅色顯示。SFIToolkit.display()是代碼中其他地方使用的標準顯示方法。
Java插件使用SFI中定義的方法從或寫入Stata對象。myListJW()不會返回任何結果，所以它有一個簡單的結構。
? 使用SFI方法從Stata中指定的數(shù)據(jù)樣本中讀取數(shù)據(jù)。
? 使用標準的Java和SFI方法，使Stata顯示對指定樣本的變量的觀測，并保留了在指定樣本中有多少觀測值的計數(shù)器。
? 使用標準的Java和SFI方法來顯示樣本中的第一個觀測值、樣本中最后的觀測值，以及在指定的樣本中有多少觀測值。
現(xiàn)在我們來討論MyListJava.java部分。
第10、12和14行使用SFI Data類方法。Data.getParsedVarCount()將varlist中指定的變量數(shù)量放入nVariables中。Data.getObsParsedIn1()將in范圍指定的第一個觀測值放入firstObs。Data.getObsParsedIn2()將in范圍指定最后一個觀測值放入lastObs。如果in范圍沒有指定到javacall，那么firstObs將包含1，而lastObs將包含數(shù)據(jù)集中觀測值數(shù)量。
firstObs、lastObs和所有Stata觀測數(shù)量的Java變量都是long類型的，因為比適合int類型的Java變量，Stata數(shù)據(jù)集可以包含更多的觀測數(shù)量。
第20-22行確保我們跳過了被mylistjava.ado第10行指定的javacall的if限制排除的觀測結果。為了說明一些細節(jié)，請看示例2。
示例2：mylistjava
在第20行中，當指定給javacall的if限制的obs觀測值是1時，Data.isParsedIfTrue(obs)返回1，否則返回0。在mylistjava.ado的第10行中，我們看到傳遞給javacall的if限制是if“touse”。正如上面所討論的，對于排除變量，本地宏touse的樣本包含變量是0，對于非排除變量是1。
包含了mylistjava.ado第10行in范圍，因此，MyListJava.java第19行的觀測值循環(huán)，從in范圍內指定的開頭到結尾。在示例2中，不是循環(huán)auto數(shù)據(jù)集中所有74個觀測值，而是循環(huán)MyListJava.java第19行的第2個觀測值到第10個觀測值。
在示例2中，6個觀測值的樣本包含變量為1，而其他68個觀測值的變量為0。in 2/10的范圍不包括觀測值1和11-74的觀測值。在前10個觀測值中，2被排除在外，因為rep78缺失。排除一個觀測值，因為trunk是21。
為了進行比較，在示例3中列出了2到10之間的9個觀測值。
示例3：list
回到MyListJava，我們可以看到第28-29行說明了如何將Stata數(shù)值變量的值放入Java變量中。請注意，Data.getNum()返回所有Stata數(shù)值變量類型double。在示例2中，mpg、trunk和rep78都是Stata中的int類型。
如果一個變量中任何觀測值包含一個缺失值，那么第30-34行會導致myListJW()退出，錯誤信息為416。這些行是多余的，因為指定給javacall的touse樣本包含變量，排除包含缺失值的觀測值。我包含了這些行來說明如何安全地從插件內部排除缺失值，并重申Java代碼必須小心處理缺失值。Stata缺失的值是Java中是有效的雙精度數(shù)。如果在計算中包含Stata缺失值，就會得到錯誤的結果。
估算Java插件中的平均值
現(xiàn)在，我將討論ado命令mymeanjava，在MyCalcs類中使用myWork()方法來實現(xiàn)mymean11.ado中執(zhí)行mymeanwork()的計算。
在code block 5中，Mymeanjava的代碼來自于mymeanjava.ado。
這個程序的大概結構跟mymean10.ado和mymean11一樣，這個內容在《在Stata中編寫估計命令：編寫插件》討論過。整體來看，mymeancpp.ado可以：
? 解析用戶輸入
? 創(chuàng)建樣本包含變量
? 為保存結果的對象創(chuàng)建臨時名稱
? 調用工作程序來進行計算
? 保存工作程序返回的結果到e()中，并
? 顯示結果
Mymeanjava.ado和mymean11.ado的主要區(qū)別在于，工作程序是一個Java插件，而不是一個Mata函數(shù)。
第6行和第7行與mylistjava.ado的代碼相同。想要了解這些行是如何創(chuàng)建本地宏varlist的，在本地宏touse中樣本包含變量，本地宏in包含任何用戶指定的范圍，可以參看Getting access to the Stata data in your plugin中對mylistjava.ado的說明。
第8行將臨時名稱放入本地宏b、V和N中。我們可以使用這些名稱來計算由Java插件計算的結果，并且知道我們不會覆蓋用戶保存在全局Stata內存中的任何結果（回想Stata矩陣和標量是Stata中的全局對象）。請參閱Programming an estimation command in Stata: A first ado-command）。此外，Stata還會在mymeanjava終止時，將tempname創(chuàng)建的臨時名稱中的對象刪除。
mymeanjava中的第10行類似于mylistjava.ado中的第10行。在這種情況下，myWork()是在類MyCalcs中定義的入口方法，位于JAR文件mycalcs.jar中。上面已經(jīng)討論了varlist, if,’touse’和’in’的詳細情況。新的情況是，我們使用args（b,V,N）將臨時名稱傳遞到myWor()中。
myWork()可以：
? 執(zhí)行計算
? 將估計的方法放入一個新的Stata矩陣中，該矩陣的名稱在本地的宏b中
? 將估計方差（協(xié)方差）的估計量（VCE）放入一個新的Stata矩陣中，該矩陣的名稱在本地宏V中
? 將樣本內的觀測數(shù)量放入Stata標量中，該標量的名稱位于本地宏N中
第13-15行將變量名稱放在估計方法向量的列條紋上和VCE矩陣的行和列條紋上。第16-18行將結果保存在e()中，第19行顯示結果。
在討論myWork()的細節(jié)之前，我們先創(chuàng)建插件并運行一個示例。
在一個包含MyCalcs.java,MyCalcsW.java,MyMatrix.java,MyLong.java和sfi-api.jar的目錄中在Mac電腦中輸入以下內容創(chuàng)建了mycalcs.jar。
javac --release 8 -classpath MyCalcs.java MyCalcsW.java MyMatrix.java MyLong.java sfi-api.jar
jar cf mycalcs.jar MyCalcs.class MyCalcsW.class MyMatrix.class MyLong.class
rm MyCalcs.class MyCalcsW.class MyMatrix.class MyLong.class
創(chuàng)建完mycalcs.jar，運行示例3。
示例4：mymeanjava
現(xiàn)在討論Java代碼的一些方面，從code block 6中的MyCalcs.java開始。
MyCalcs.java只包含入口方法myWork()。綜上所述，myWork()可以執(zhí)行以下任務：
1把名稱作為參數(shù)傳遞給Java String對象的實例中，這些對象可以被傳遞到SFI方法中。
2將指定Stata變量的數(shù)量放入用于循環(huán)變量的Java變量中。
3將樣本觀測的范圍放入Java變量中，用于循環(huán)觀測值。
4創(chuàng)建MyMatrix類的bmat和vmat實例來保存樣本平均值和VCE。
5創(chuàng)建了MyLong類的nObs實例，它將保存樣本觀測值的數(shù)量。
6使用MyCalcsWmyAv()和MyCalcsWmyV()方法來計算結果并保到在bmat、vmat和nObs中。
7使用MyMatrix類的CopyCtoStataMatrix()方法來將bmat和vmat的結果復制到新的Stata矩陣。新的Stata矩陣的名稱是傳遞給myWork()的第一個和第二個參數(shù)。
8使用SFI方法Scalar.setValue()將結果從nObs復制到新的Stata標量中，該標量的名稱是傳遞給myWork()的第三個參數(shù)。
MyCalcs.java很容易讀懂，因為我把所有的細節(jié)都放到了MyMatrix、MyCalcsW和MyLong類中，下面我將對此進行討論。
如同Stata的所有Java插件一樣，myWork()使用返回碼rc來處理錯誤條件。如果一切順利，每個調用的方法都返回0，如果它不能執(zhí)行所請求的工作，它會返回一個非零錯誤代碼。如果返回的代碼不是0，myWork()會立即返回到Stata中。與錯誤條件相關聯(lián)的錯誤消息由這些方法來顯示。
在（3）中，我注意到bmat和vmat是MyMatrix類的實例。樣本平均值和VCE最好保存在矩陣中。為了事情簡單和自包含，我定義了一個簡單的矩陣類MyMatrix，它使用row-major保存，并且只使用我需要的方法。除了copyJavatoStataMatrix()方法之外，MyMatrix的代碼是標準Java，可以在code block 7中看到。
第33-58行包含copyJavatoStataMatrix()的代碼。第40和49行使用了我還沒有討論過的SFI方法。Matrix.createMatrix（字符串sname、int rows、int cols、double val）使用rows行和cols列創(chuàng)建了一個新的Stata矩陣。這個矩陣的每一個元素都被初始化為值val。sname包含這個Stata矩陣的名稱。
Matrix.storeMatrixAt（字符串sname，int i，int j，double val）將值val保存到Stata矩陣行i和列j中，該矩陣的名稱包含在sname中?；诹愕乃饕o出了行i和列j。
在（4）里，我注意到，我使用了MyLong類的一個實例來保存樣本觀測值的數(shù)量。Java中的原始類型不能通過引用傳遞，標準的包裝類型是不可變的，所以我創(chuàng)建了long counter，nObs傳遞到MycalcsW.myAve()中。當MyCalcsW.myAve()完成時，nObs包含樣本觀測值的數(shù)量。MyLong的代碼是標準Java，由code block 8中給出。
在（5）中，我注意到MyCalcsW.myAve()和MyCalcsW.myV方法計算了樣本平均值和VCE。這些方法在類MyCalcsW中，它的代碼由code block 9給出。
MyCalsW.myAve()是Mata函數(shù)MyAve()在Java中的實現(xiàn)，《在Stata中編寫估計命令：編寫插件》這篇文章中有過講解。它將樣本平均值放入MyMatrix類的bmat實例中，并將樣本中觀測的數(shù)量放入nObs中。這個方法的大部分代碼是標準Java，或者使用我已經(jīng)討論過的SFI方法。第18、34和38行值得討論。
第18行MyCalcsW.java使用MyLong的方法incrementValue()來增加保存在nObs中的觀測數(shù)量。它使nObs的當前值遞增1。
第34行使用MyMatrix方法incrementByValue()。當計算樣本均值并將其保存在向量名稱為b的jth元素中時，您需要保存b[j] value到b[j]中。換句話說，通過value，在b中增加jth元素的數(shù)量。通過value，在bmat中bmat.incrementByValue(0,var-1, value)增加元素var-1。
第38行使用MyMatrix的divideByScalar()方法。bmat.divideByScalar(z)將bmat的每個元素替換為可以除以z的元素。
MyCalsW.myV()是Mata函數(shù)MyV()在Java中的實現(xiàn)，《在Stata中編寫估計命令：編寫插件》這篇文章中有過講解。它將VCE放入MyMatrix類的vmat實例中。這個方法的大部分代碼是標準Java，或者使用我已經(jīng)討論過的方法。第72、77和85行使用MyMatrix方法storevalue()和getValue()。vmat.storeValue（i,j,z）將z值保存在MyMatrix的vmat實例中（i,j）。vmat.getValue（i，j）返回保存在MyMatrix中vmat實例中的元素（i，j）中的值。
完成和撤銷
這篇文章展示了如何實現(xiàn)一個Java插件，它可以在mymean10.ado和mymean11.ado中執(zhí)行Mata工作函數(shù)的計算。這個內容在《在Stata中編寫估計命令：編寫插件》中討論過。
