XULRunner with Java: JavaXPCOM Tutorial 1

这篇教程更新于2008年夏天，用来集成SWT和XULRunner来在SWT里显示一个浏览器。要想获得更多信息，请参考
http://www.eclipse.org/swt/faq.php#whatisbrowser

1，简介
       这篇教程有两个目的。首先，我们能学到一些XPCOM的概念和怎么通过JavaXPCOM来在java里使用它。其次，我们学到怎么在

java程序里嵌入Firefox浏览器。
       这里的例子我们开发，编译和测试的环境是Ubuntu 8.04和JDK1.6（译注，我使用的是windows xp）。我们在windows下遇到

一个问题，用户无法在form里输入文本，虽然在例子里并不需要这点。
1.1 下载资源  
      例子的源码在相关章节的开始以及文章的最后都有下载，当然，你也可以下载所有的代码
http://ladyr.es/wiki/attachment/wiki/XPCOMGuide/complete-guide-resources-windows.zip  windows
http://ladyr.es/wiki/attachment/wiki/XPCOMGuide/complete-guide-resources-linux.zip   linux

2. 安装XULRunner
     JavaXPCOM是一个用来访问XULRunner里XPCOM组件和服务的java库。在这里我们介绍了一些方法通过java来使用XULRunner组件

和服务。JavaXPCOM也能在java程序里嵌入Gecko。JavaXPCOM需要Java1.4.2或者更新的版本。为了使用JavaXPCOM你需要下面的步骤

：
    XULRunner：你需要安装XULRunner。它在开发中并不断变化。这个教程使用的是1.9的版本，这个版本built的时间是2008-6-19.

安装XULRunner的方法：
      1. 根据自己的操作系统下载合适的安装包（译注，我在windows xp下无法使用XULRunner1.9，我使用的是
                xulrunner-1.8.1.3.en-US.win32-20080128）
   2.解压它，比如把它解压到c:/XULRunner
   3.进入这个路径
   4.卸载以前的注册
   5.注册这个版本
   （译注：注册并不是必须的，注册后可以在程序里不用知道XULRunner的路径，不注册也可以，不过程序里要知道路径）
javaxpcom.jar
MozillaInterface.jar
MozillaGlue.jar

3.在Java里使用JavaXPCOM
3.1 JavaXPCOM初始化
XPCOM（Mozilla Cross-platform Object Model）是一个机遇组件的架构。为了使用XPCOM，我们需要一些初始化和清理的代码。有

两种方法来使用它，请看下面注释过的代码：
首先我们可以使用initXPCOM方法
package es.ladyr.javaxpcom.test; import java.io.File; import java.io.FileNotFoundException; import java.util.Properties; import org.mozilla.xpcom.GREVersionRange; import org.mozilla.xpcom.Mozilla; public class SimplestInitializationCode { public static void main(String[] args) { // JavaXPCOM initialization GREVersionRange[] range = new GREVersionRange[1]; range[0] = new GREVersionRange("1.8", true, "1.9+", true); Properties props = null; File grePath = null; try { grePath = Mozilla.getGREPathWithProperties(range, props); } catch (FileNotFoundException e) { System.out.println("XULRunner not found. It is possible that it be wrong installed"); return; } Mozilla mozilla = Mozilla.getInstance(); mozilla.initialize(grePath); try { mozilla.initXPCOM(grePath, null); } catch (Throwable t) { System.out.println("initXPCOM failed"); t.printStackTrace(); return; } // From this line, we can use JavaXPCOM System.out.println("/n--> initialized/n"); // ... your application code ... // JavaXPOM finalization mozilla.shutdownXPCOM(null); } }

为了嵌入，你应该使用 initEmbedding 方法。这个方法需要实现 IAppFileLocProvider 的类。我们使用包

org.eclipse.atf.mozilla.ide.core里的一个类LocationProvider 。它的代码如下： /******************************************************************* * * Licensed Materials - Property of IBM * * AJAX Toolkit Framework 6-28-496-8128 * * (c) Copyright IBM Corp. 2006 All Rights Reserved. * * U.S. Government Users Restricted Rights - Use, duplication or * disclosure restricted by GSA ADP Schedule Contract with IBM Corp. * *******************************************************************/ package org.eclipse.atf.mozilla.ide.core; import java.io.File; import java.io.FileNotFoundException; import java.io.IOException; import org.mozilla.xpcom.IAppFileLocProvider; public class LocationProvider implements IAppFileLocProvider { private File libXULPath; private File profile; private File history; public LocationProvider(File aBinPath, File aProfileDir) throws IOException { libXULPath = aBinPath; profile = aProfileDir; if (!libXULPath.exists() || !libXULPath.isDirectory()) { throw new FileNotFoundException("libxul directory specified is not valid: " + libXULPath.getAbsolutePath()); } if (profile != null && (!profile.exists() || !profile.isDirectory())) { throw new FileNotFoundException("profile directory specified is not valid: " + profile.getAbsolutePath()); } // create history file if (profile != null) { setupProfile(); } } private void setupProfile() throws IOException { history = new File(profile, "history.dat"); if (!history.exists()) { history.createNewFile(); } } public File getFile(String aProp, boolean[] aPersistent) { File file = null; if (aProp.equals("GreD") || aProp.equals("GreComsD")) { //$NON-NLS-1$ // file = new File(grePath); file = libXULPath; if (aProp.equals("GreComsD")) { //$NON-NLS-1$ file = new File(file, "components"); //$NON-NLS-1$ } } else if (aProp.equals("MozBinD") || //$NON-NLS-1$ aProp.equals("CurProcD") || //$NON-NLS-1$ aProp.equals("ComsD")) //$NON-NLS-1$ { file = libXULPath; if (aProp.equals("ComsD")) { //$NON-NLS-1$ file = new File(file, "components"); //$NON-NLS-1$ } } else if (aProp.equals("ProfD")) { //$NON-NLS-1$ return profile; } else if (aProp.equals("UHist")) { //$NON-NLS-1$ return history; } // else { // System.err.println("LocationProvider::getFile() => unhandled property = " + aProp); // } return file; } public File[] getFiles(String aProp) { File[] files = null; if (aProp.equals("APluginsDL")) { //$NON-NLS-1$ files = new File[1]; files[0] = new File(libXULPath, "plugins"); // } else { // System.err.println("LocationProvider::getFiles() => unhandled property = " + aProp); } return files; } }


关于更多ATF的信息,请访问http://www.eclipse.org/atf/
 
为了嵌入而初始JavaXPCOM的代码如下：

package es.ladyr.javaxpcom.test; import java.io.File; import java.io.FileNotFoundException; import java.io.IOException; import java.util.Properties; import org.eclipse.atf.mozilla.ide.core.LocationProvider; import org.mozilla.xpcom.GREVersionRange; import org.mozilla.xpcom.Mozilla; import org.mozilla.xpcom.XPCOMException; public class EmbeddingInitializationCode { public static void main(String[] args) { // JavaXPCOM initialization GREVersionRange[] range = new GREVersionRange[1]; range[0] = new GREVersionRange("1.8", true, "1.9+", true); Properties props = null; File grePath = null; try { grePath = Mozilla.getGREPathWithProperties (range, props); } catch (FileNotFoundException e) { System.out.println("XULRunner not found. It is possible that it be wrong installed"); return; } Mozilla mozilla = Mozilla.getInstance(); mozilla.initialize(grePath); LocationProvider locProvider; try { locProvider = new LocationProvider(grePath, grePath); } catch (IOException e) { System.out.println("XULRunner not found. It is possible that it be wrong installed"); return; } mozilla.initEmbedding(grePath, grePath, locProvider); // From this line, we can use JavaXPCOM System.out.println("/n--> initialized/n"); // ... your application code ... // JavaXPOM finalization try { mozilla.termEmbedding(); } catch (XPCOMException e) { // this exception is thrown if termEmbedding failed } } }

3.2 XPCOM组件和接口的基本概念
   XPCOM(Mozilla Cross-platform Object Model)如它名字，是一个基于组件的架构。XPCOM的组件一般是本地实现的。XPCOM系统

里的所有组件都有一个唯一的标识。XPCOM组件实现许多接口，这些接口提供各种功能。同一个组件可能实现不同的接口，同样，一

个接口可能北不同的组件实现。因为接口必需有一个具体的实现才能使用，我们将讨论组件和接口。在后面，我们把组件看成一段实

现了一个或多个接口的代码。
   在XULRunner里，接口名总是以nsI开头。在JavaXPCOM里，每个XPCOM接口都有一个对应的java接口。它们的名字以nsI开头，它们

位于org.mozilla.xpcom里，被放在MozillaInterfaces.jar包里面。这些接口的javaDoc在MozillaInterfaces-src.jar里。你可以在

https://developer.mozilla.org/En浏览所有的XPCOM接口，MDC是一个与语言无关的文档，并不是Java的。
   在JavaXPCOM里没有XPCOM组件的代码。后面你将看到怎么在JavaXPCOM里初始化和使用组件。因为没有java代码，所有也没有

JavaDoc。http://developer.mozilla.org/En里包含了XPCOM组件的完整文档。
   我们可以如下的步骤使用XPCOM组件：
      得到组件
      得到实现了我们想使用的接口的组件
      调用它
   组件使用URI来命名，例如，@mozilla.org/file/local;1。Mozilla的组件以@mozilla.org开头。这个URI是contractID，每个组

件也有一个组件标识符(CID)。同样，每一个接口也有一个接口标识符(IID)。IID总能使用一个static的final的属性来获取。组件可

能存在一个对象实例或者单例的服务。通常，服务包含单词Service或者Manager

3.3 使用JavaXPCOM： 与用JavaScript来使用XPCOM的不同点与相同点
   在XPCOM里，所有的接口都继承了nsISupports，它有一个函数叫做QueryInterface，这个函数返回一个组件的一个接口，如果这

个组件没有实现这个接口，那么将返回异常。在JavaXPCOM里，接口nsISupports提供了QueryInterface来返回一个nsISupports对象
。为了属于谋个接口的方法，你首先需要使用QueryInterface方法确定这个接口。

   比如，你可以使用下面的JavaScript来调用XPCOM来创建一个本地文件组件：
// Get the component
var aFile = Components.classes["@mozilla.org/file/local;1"].createInstance();

// Get the part of the component corresponding to the interface that we want to use
var aLocalFile = aFile.QueryInterface(Components.interfaces.nsILocalFile);

// Call the function (one or more than one)
aLocalFile.initWithPath("/mozilla/testfile.txt");


上面需要两行JavaScript代码来创建组件和获得接口。可以简化的代码：
// Get the component and directly the part of the component corresponding to the interface that we want to use
var aLocalFile = Components.classes["@mozilla.org/file/local;1"].createInstance(Components.interfaces.nsILocalFile);

// Call the function (one or more than one)
aLocalFile.initWithPath("/mozilla/testfile.txt");

在JavaXPCOM里，为了得到XPCOM组件相对应的JavaXPCOM的实例，我们必须访问ComponentManager对象，这个对象允许在运行时访问

和使用。它能够通过单例类Mozilla的getComponentManager()访问。每次我们用这种方法实例化，我们创建了一个XPCOM组件。有两

种方法来创建XPCOM组件的实例：
   使用组件ID(CID):
// Get the component manager
ComponentManager cm = Mozilla.getInstance().getComponentManager();

// Get the part of the component corresponding to the interface that we want to use
nsISupports obj = cm.createInstance("{6ddb050c-0d04-11d4-986e-00c04fa0cf4a}", null, nsISupports.NS_ISUPPORTS_IID);

// Get the part of the component corresponding to the interface that we want to use
nsIInputStreamChannel isc = obj.queryInterface(nsIInputStreamChannel.NS_IINPUTSTREAMCHANNEL_IID);

// Call the method (one or more than one)
System.out.println("Content-Length: " + isc.getContentLength());

我们可以简化一下：
// Get the component manager
ComponentManager cm = Mozilla.getInstance().getComponentManager();

// Get the part of the component corresponding to the interface that we want to use
nsIInputStreamChannel isc = (nsIInputStreamChannel)
         cm.createInstance("{6ddb050c-0d04-11d4-986e-00c04fa0cf4a}", null,

nsIInputStreamChannel.NS_IINPUTSTREAMCHANNEL_IID);

// Call the method (one or more than one)
System.out.println("Content-Length: " + isc.getContentLength());

也可以通过contractID来访问：
// Get the component manager
ComponentManager cm = Mozilla.getInstance().getComponentManager();

// Get the part of the component corresponding to the interface that we want to use
nsISupports obj = cm.createInstanceByContractID("@ mozilla.org/file/local;1", null, nsISupports.NS_ISUPPORTS_IID);

// Get the part of the component corresponding to the interface that we want to use
nsILocalFile file = obj.queryInterface(nsILocalFile.NS_ILOCALFILE_IID);

// Call the method (one or more than one)
file.initWithPath("/home/alpgarcia/xpcom-file-test.txt");

简化形式：
// Get the component manager
ComponentManager cm = Mozilla.getInstance().getComponentManager();

// Get the part of the component corresponding to the interface that we want to use
nsILocalFile file = (nsILocalFile)cm.createInstanceByContractID("@ mozilla.org/file/local;1", null,

nsILocalFile.NS_ILOCALFILE_IID);

// Call the method (one or more than one)
file.initWithPath("/home/alpgarcia/xpcom-file-test.txt");

在JavaScript里，我们通过调用instanceOf来检查一个组件是否实现了一个接口：

var aFile = Components.classes["@mozilla.org/file/local;1"].createInstance();
if (aFile instanceOf Components.interfaces.nsILocalFile){
   var aLocalFile = aFile.QueryInterface(Components.interfaces.nsILocalFile);
   ...
}


在java里，instanceof运算符是其它的含义。在java里只能通过QueryInterface来判断。如果调用失败，那么这个组件就没有实现特

定的接口。如果我们还是用JavaScript的写法，那么就会得到不同的结果(错误的)。试试下面的代码：

package es.ladyr.javaxpcom.test; import java.io.File; import java.io.FileNotFoundException; import java.util.Properties; import org.mozilla.xpcom.GREVersionRange; import org.mozilla.xpcom.Mozilla; import org.mozilla.xpcom.XPCOMException; import org.mozilla.interfaces.nsIComponentManager; import org.mozilla.interfaces.nsILocalFile; import org.mozilla.interfaces.nsIMutableArray; import org.mozilla.interfaces.nsISupports; public class InstanceOfTest { public static void main(String[] args) { // JavaXPCOM initialization GREVersionRange[] range = new GREVersionRange[1]; range[0] = new GREVersionRange("1.8", true, "1.9+", true); Properties props = null; File grePath = null; try { grePath = Mozilla.getGREPathWithProperties(range, props); } catch (FileNotFoundException e) { System.out .println("XULRunner not found. It is possible that it be wrong installed"); return; } Mozilla mozilla = Mozilla.getInstance(); mozilla.initialize(grePath); try { mozilla.initXPCOM(grePath, null); } catch (Throwable t) { System.out.println("initXPCOM failed"); t.printStackTrace(); return; } // From this line, we can use JavaXPCOM // Get the component manager nsIComponentManager cm = Mozilla.getInstance().getComponentManager(); // We will not be able to know if that component implements a given // interface using instanceof in Java nsISupports aFile = cm .createInstanceByContractID("@mozilla.org/file/local;1", null, nsISupports.NS_ISUPPORTS_IID); if (aFile instanceof nsILocalFile) { // The execution flow never come this way because instanceof // semantics are diferent in JavaScript and Java // (nsILocalFile is a chid class of nsISupports and not // the other way round) nsILocalFile aLocalFile = (nsILocalFile) aFile .queryInterface(nsILocalFile.NS_ILOCALFILE_IID); System.out.println("This message will never be printed."); } try { nsILocalFile aLocalFile = (nsILocalFile) aFile .queryInterface(nsILocalFile.NS_ILOCALFILE_IID); // The next sentences are executed if aFile component implements // nsILocalFile interface System.out .println("nsILocalFile interface implemented by this component."); // Try to get an exception caused by a non implemented interface nsIMutableArray arr = (nsIMutableArray) aFile .queryInterface(nsIMutableArray.NS_IMUTABLEARRAY_IID); System.out.println("This message will never be printed."); } catch (XPCOMException ex) { // The next sentences are executed if aFile component don't // implement nsILocalFile interface System.err .println("Interface not supported. See the following exception: "); ex.printStackTrace(); System.err.flush(); } // The inverse case matchs with the semantics of Java instanceof // operator nsILocalFile aLocalFile = (nsILocalFile) aFile .queryInterface(nsILocalFile.NS_ILOCALFILE_IID); if (aLocalFile instanceof nsISupports) { // The next sentence will be executed System.out.println("aLocalFile instance of nsISupports"); } // JavaXPOM finalization mozilla.shutdownXPCOM(null); } }

JavaScript和Java的主要区别是，在JavaXPCOM里没有一个特定的对象与XPCOM组件对应。
另外，我们可以使用另一类组件，叫做services。前面我们说过，Service作为一个单例存在，换句话说，你只能初始化一次。

Services被用来get和set全局的数据或者对其它对象进行操作。创建Service与创建组件类似，把getInstance()改成getService()就

行了。在JavaXPCOM里，我们需要nsIServiceManager对象来初始化一个Service。然后你需要调用getService或者

getServiceByContractID来得到service组件的引用。

在JavaScript里的代码：
// get the dns service component in JavaScript
var dnsservice = Components.classes["@mozilla.org/network/dns-service;1"].getService();
dnsservice.QueryInterface(Components.interfaces.nsIDNSService);

JavaXPCOM的代码：
//Now, we will try to use a service, for example, dns service
nsIServiceManager sm = mozilla.getServiceManager();
                               
nsIDNSService dns = (nsIDNSService) sm.getServiceByContractID(
        "@mozilla.org/network/dns-service;1", nsIDNSService.NS_IDNSSERVICE_IID);


3.4 在JavaXPCOM里使用组件和Services的完整例子
在第一个例子里我们将要创建一个本地的文件并写入一些文本。
package es.ladyr.javaxpcom.test;

import java.io.File; import java.io.FileNotFoundException; import java.util.Properties; import org.mozilla.xpcom.GREVersionRange; import org.mozilla.xpcom.Mozilla; import org.mozilla.interfaces.nsIComponentManager; import org.mozilla.interfaces.nsIFileInputStream; import org.mozilla.interfaces.nsIFileOutputStream; //import org.mozilla.interfaces.nsILineInputStream; import org.mozilla.interfaces.nsILocalFile; import org.mozilla.interfaces.nsISeekableStream; import org.mozilla.interfaces.nsISupports; public class FileTest { public static void main(String[] args) { // JavaXPCOM initialization GREVersionRange[] range = new GREVersionRange[1]; range[0] = new GREVersionRange("1.8", true, "1.9+", true); Properties props = null; File grePath = null; try { grePath = Mozilla.getGREPathWithProperties(range, props); } catch (FileNotFoundException e) { System.out .println("XULRunner not found. It is possible that it be wrong installed"); return; } Mozilla mozilla = Mozilla.getInstance(); mozilla.initialize(grePath); try { mozilla.initXPCOM(grePath, null); } catch (Throwable t) { System.out.println("initXPCOM failed"); t.printStackTrace(); return; } // From this line, we can use JavaXPCOM // First, we will create an empty file // A file is a component, we use the component manager to create an // instance // of local file component nsIComponentManager cm = mozilla.getComponentManager(); // Here we create directly a component and use its nsILocalFile // interface nsILocalFile file = (nsILocalFile) cm.createInstanceByContractID( "@mozilla.org/file/local;1", null, nsILocalFile.NS_ILOCALFILE_IID); file.initWithPath("/home/sevi/xpcom-file-test.txt"); // Check file existence because if the file already exists in filesystem // and // we try to create another one with the same path, an exception will be // thrown by XPCOM // (something like "The function "create" returned an error condition // (0x80520008)") if (!file.exists()) { file.create(nsILocalFile.NORMAL_FILE_TYPE, 0600); } // We can create a stream to write the file nsIFileOutputStream os = (nsIFileOutputStream) cm .createInstanceByContractID( "@mozilla.org/network/file-output-stream;1", null, nsIFileOutputStream.NS_IFILEOUTPUTSTREAM_IID); os.init(file, nsISeekableStream.NS_SEEK_END, 0, 0); os.write("Hello World!/n", 13); os.flush(); os.close(); // And now we will use an input stream to read the file // The @mozilla.org/network/file-input-stream;1 component implements the // following interfaces: // * nsIFileInputStream // * nsIInputStream // * nsILineInputStream // * nsISeekableStream // * nsISupports // First create a parent component (top parent component). We could use // another component // implemented interface as well. nsISupports is = cm.createInstanceByContractID( "@mozilla.org/network/file-input-stream;1", null, nsISupports.NS_ISUPPORTS_IID); // We will use the file input stream interface to associate a local file // with the stream nsIFileInputStream fis = (nsIFileInputStream) is .queryInterface(nsIFileInputStream.NS_IFILEINPUTSTREAM_IID); fis.init(file, nsIFileInputStream.REOPEN_ON_REWIND, 0, 0); System.out.println("The file contains " + fis.available() + " bytes of data."); fis.close(); // JavaXPOM finalization mozilla.shutdownXPCOM(null); System.out.println("Finish!"); } }


下面是一个关于域名的例子：
package es.ladyr.javaxpcom.test; import java.io.File; import java.io.FileNotFoundException; import java.util.Properties; import org.mozilla.xpcom.GREVersionRange; import org.mozilla.xpcom.Mozilla; import org.mozilla.interfaces.*; public class ServiceTest { public static void main(String[] args) { // JavaXPCOM initialization GREVersionRange[] range = new GREVersionRange[1]; range[0] = new GREVersionRange("1.8", true, "1.9+", true); Properties props = null; File grePath = null; try { grePath = Mozilla.getGREPathWithProperties(range, props); } catch (FileNotFoundException e) { System.out .println("XULRunner not found. It is possible that it be wrong installed"); return; } Mozilla mozilla = Mozilla.getInstance(); mozilla.initialize(grePath); try { mozilla.initXPCOM(grePath, null); } catch (Throwable t) { System.out.println("initXPCOM failed"); t.printStackTrace(); return; } // From this line, we can use JavaXPCOM // Now, we will try to use a service, for instance, dns service nsIServiceManager sm = mozilla.getServiceManager(); nsIDNSService dns = (nsIDNSService) sm.getServiceByContractID( "@mozilla.org/network/dns-service;1", nsIDNSService.NS_IDNSSERVICE_IID); System.out.println("Hostname: " + dns.getMyHostName()); nsIDNSRecord dnsRecord = dns.resolve("www.google.es", nsIDNSService.RESOLVE_CANONICAL_NAME | nsIDNSService.RESOLVE_BYPASS_CACHE); System.out.println("Canonical Name: " + dnsRecord.getCanonicalName() + " -- Next Address: " + dnsRecord.getNextAddrAsString()); // JavaXPOM finalization mozilla.shutdownXPCOM(null); System.out.println("Finish!"); } }