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