* You would use to class to find a XULRunner installation, setup a profile (if * necessary), and initialize embedding. A typical scenario would look like * this: *
* Mozilla mozilla = Mozilla.getInstance();
* GREVersionRange[] range = new GREVersionRange[1];
* range[0] = new GREVersionRange("1.8.0.*", false, "1.8.1.*", true);
* try {
* File grePath = Mozilla.getGREPathWithProperties(range, null);
* mozilla.initialize(grePath);
* profLock = mozilla.lockProfileDirectory(profileDir);
* // LocationProvider is a user class that implements IAppFileLocProvider
* LocationProvider locProvider = new LocationProvider(grePath, profileDir);
* mozilla.initEmbedding(grePath, grePath, locProvider);
* mozilla.notifyProfile();
* } catch (XPCOMInitializationException xie) {
* // handle exception
* } catch (XPCOMException xe) {
* // handle exception
* }
*
*
* @see http://www.mozilla.org/projects/embedding/GRE.html
*/
public class Mozilla implements IMozilla, IGRE, IXPCOM, IJavaXPCOMUtils,
IXPCOMError {
private static Mozilla mozillaInstance = new Mozilla();
private static final String JAVAXPCOM_JAR = "javaxpcom.jar";
private IMozilla mozilla = null;
private IGRE gre = null;
private IXPCOM xpcom = null;
private IJavaXPCOMUtils jxutils = null;
/**
* @return
*/
public static Mozilla getInstance() {
return mozillaInstance;
}
/**
*
*/
private Mozilla() {
}
/**
* Locates the path of a GRE with the specified properties. This method
* will only return GREs that support Java embedding (looks for the
* presence of "javaxpcom.jar").
*
* Currently this uses a "first-fit" algorithm, it does not select
* the newest available GRE.
*
* @param aVersions An array of version ranges: if any version range
* matches, the GRE is considered acceptable.
* @param aProperties A list of GRE property/value pairs which must
* all be satisfied. This parameter is ignored on
* Macintosh, because of the manner in which the
* XUL frameworks are installed.
*
* @return A file object of the appropriate path. If
* the "local" GRE is specified (via the USE_LOCAL_GRE
* environment variable, for example), returns
*
* NOTE: This function must be called from the "main" thread.
*
* NOTE: At the present time, this function may only be called once in
* a given process. Use
* NOTE: Release any references to XPCOM objects that you may be holding
* before calling this function.
*
* @throws XPCOMInitializationException if Mozilla was not properly
* initialized
*/
public void termEmbedding() {
try {
gre.termEmbedding();
} catch (NullPointerException e) {
throw new XPCOMInitializationException("Must call " +
"Mozilla.getInstance().initialize() before using this method", e);
} finally {
mozilla = null;
gre = null;
xpcom = null;
}
}
/**
* Lock a profile directory using platform-specific semantics.
*
* @param aDirectory The profile directory to lock.
*
* @return A lock object. The directory will remain locked until the lock is
* released by invoking the
* Normally the embedder should call
* NOTE: There are two possibilities for selecting a profile:
* null.
*
* @throws FileNotFoundException if an appropriate GRE could not be found
*/
public static File getGREPathWithProperties(GREVersionRange[] aVersions,
Properties aProperties) throws FileNotFoundException {
File grePath = null;
// if GRE_HOME is in the environment, use that GRE
String env = System.getProperty("GRE_HOME");
if (env != null) {
try {
grePath = new File(env).getCanonicalFile();
} catch (IOException e) {
throw new FileNotFoundException("cannot access GRE_HOME");
}
if (!grePath.exists()) {
throw new FileNotFoundException("GRE_HOME doesn't exist");
}
return grePath;
}
// the Gecko bits that sit next to the application or in the PATH
env = System.getProperty("USE_LOCAL_GRE");
if (env != null) {
return null;
}
// Search for GRE in platform specific locations. We want a GRE that
// supports Java, so we look for the "javaxpcom" property by default.
if (aProperties == null) {
aProperties = new Properties();
}
aProperties.setProperty("javaxpcom", "1");
String osName = System.getProperty("os.name").toLowerCase();
if (osName.startsWith("mac os x")) {
grePath = getGREPathMacOSX(aVersions);
} else if (osName.startsWith("windows")) {
grePath = getGREPathWindows(aVersions, aProperties);
} else {
// assume everything else is Unix/Linux
grePath = getGREPathUnix(aVersions, aProperties);
}
if (grePath == null) {
throw new FileNotFoundException("GRE not found");
}
return grePath;
}
/**
* @param aVersions
* @return
*/
private static File getGREPathMacOSX(GREVersionRange[] aVersions) {
/*
* Check the application bundle first, for
* termEmbedding to clean up and free
* resources allocated by initEmbedding.
*
* @param aLibXULDirectory The directory in which the libXUL shared library
* was found.
* @param aAppDirectory The directory in which the application components
* and resources can be found. This will map to
* the "resource:app" directory service key.
* @param aAppDirProvider A directory provider for the application. This
* provider will be aggregated by a libXUL provider
* which will provide the base required GRE keys.
*
* @throws XPCOMException if a failure occurred during initialization
* @throws XPCOMInitializationException if Mozilla was not properly
* initialized
*/
public void initEmbedding(File aLibXULDirectory, File aAppDirectory,
IAppFileLocProvider aAppDirProvider) throws XPCOMException {
try {
gre.initEmbedding(aLibXULDirectory, aAppDirectory, aAppDirProvider);
} catch (NullPointerException e) {
throw new XPCOMInitializationException("Must call " +
"Mozilla.getInstance().initialize() before using this method", e);
}
}
/**
* Terminates libXUL embedding.
* release method, or by the
* termination of the JVM, whichever comes first.
*
* @throws XPCOMException if profile is already locked (with
* errorcode == NS_ERROR_FILE_ACCESS_DENIED);
* or if a failure occurred
* @throws XPCOMInitializationException if Mozilla was not properly
* initialized
*/
public ProfileLock lockProfileDirectory(File aDirectory)
throws XPCOMException {
try {
return gre.lockProfileDirectory(aDirectory);
} catch (NullPointerException e) {
throw new XPCOMInitializationException("Must call " +
"Mozilla.getInstance().initialize() before using this method", e);
}
}
/**
* Fire notifications to inform the toolkit about a new profile. This
* method should be called after initEmbedding if the
* embedder wishes to run with a profile.
* lockProfileDirectory
* to lock the directory before calling this method.
*
*
*
* @throws XPCOMInitializationException if Mozilla was not properly
* initialized
*/
public void notifyProfile() {
try {
gre.notifyProfile();
} catch (NullPointerException e) {
throw new XPCOMInitializationException("Must call " +
"Mozilla.getInstance().initialize() before using this method", e);
}
}
/**
* Initializes XPCOM. You must call this method before proceeding
* to use XPCOM.
*
* @param aMozBinDirectory The directory containing the component
* registry and runtime libraries;
* or use initEmbedding.
* The aAppDirProvider object passed to initEmbedding
* should provide the NS_APP_USER_PROFILE_50_DIR key, and
* may also provide the following keys:
*
*
* In this scenario notifyProfile should be called
* immediately after initEmbedding. Component
* registration information will be stored in the profile and
* JS components may be stored in the fastload cache.
* initEmbedding.
* In this case the embedder must install a directory service
* provider which provides NS_APP_USER_PROFILE_50_DIR and optionally
* NS_APP_USER_PROFILE_LOCAL_50_DIR. Component registration information
* will be stored in the application directory and JS components will not
* fastload.
* null to use the working
* directory.
*
* @param aAppFileLocProvider The object to be used by Gecko that specifies
* to Gecko where to find profiles, the component
* registry preferences and so on; or use
* null for the default behaviour.
*
* @return the service manager
*
* @throws XPCOMException
*
* @throws XPCOMInitializationException if Mozilla was not properly
* initialized
*/
public nsIServiceManager initXPCOM(File aMozBinDirectory,
IAppFileLocProvider aAppFileLocProvider) throws XPCOMException {
try {
return xpcom.initXPCOM(aMozBinDirectory, aAppFileLocProvider);
} catch (NullPointerException e) {
throw new XPCOMInitializationException("Must call " +
"Mozilla.getInstance().initialize() before using this method", e);
}
}
/**
* Shutdown XPCOM. You must call this method after you are finished
* using xpcom.
*
* @param aServMgr The service manager which was returned by initXPCOM.
* This will release servMgr.
*
* @throws XPCOMException if a failure occurred during termination
* @throws XPCOMInitializationException if Mozilla was not properly
* initialized
*/
public void shutdownXPCOM(nsIServiceManager aServMgr) throws XPCOMException {
try {
xpcom.shutdownXPCOM(aServMgr);
} catch (NullPointerException e) {
throw new XPCOMInitializationException("Must call " +
"Mozilla.getInstance().initialize() before using this method", e);
} finally {
mozilla = null;
gre = null;
xpcom = null;
}
}
/**
* Public Method to access to the service manager.
*
* @return the service manager
*
* @throws XPCOMException if a failure occurred
* @throws XPCOMInitializationException if Mozilla was not properly
* initialized
*/
public nsIServiceManager getServiceManager() throws XPCOMException {
try {
return xpcom.getServiceManager();
} catch (NullPointerException e) {
throw new XPCOMInitializationException("Must call " +
"Mozilla.getInstance().initialize() before using this method", e);
}
}
/**
* Public Method to access to the component manager.
*
* @return the component manager
*
* @throws XPCOMException if a failure occurred
* @throws XPCOMInitializationException if Mozilla was not properly
* initialized
*/
public nsIComponentManager getComponentManager() throws XPCOMException {
try {
return xpcom.getComponentManager();
} catch (NullPointerException e) {
throw new XPCOMInitializationException("Must call " +
"Mozilla.getInstance().initialize() before using this method", e);
}
}
/**
* Public Method to access to the component registration manager.
*
* @return the component registration manager
*
* @throws XPCOMException if a failure occurred
* @throws XPCOMInitializationException if Mozilla was not properly
* initialized
*/
public nsIComponentRegistrar getComponentRegistrar() throws XPCOMException {
try {
return xpcom.getComponentRegistrar();
} catch (NullPointerException e) {
throw new XPCOMInitializationException("Must call " +
"Mozilla.getInstance().initialize() before using this method", e);
}
}
/**
* Public Method to create an instance of a nsILocalFile.
*
* @param aPath A string which specifies a full file path to a
* location. Relative paths will be treated as an
* error (NS_ERROR_FILE_UNRECOGNIZED_PATH).
* @param aFollowLinks This attribute will determine if the nsLocalFile will
* auto resolve symbolic links. By default, this value
* will be false on all non unix systems. On unix, this
* attribute is effectively a noop.
*
* @return an instance of an nsILocalFile that points to given path
*
* @throws XPCOMException
*
* @throws XPCOMInitializationException if Mozilla was not properly
* initialized
*/
public nsILocalFile newLocalFile(String aPath, boolean aFollowLinks)
throws XPCOMException {
try {
return xpcom.newLocalFile(aPath, aFollowLinks);
} catch (NullPointerException e) {
throw new XPCOMInitializationException("Must call " +
"Mozilla.getInstance().initialize() before using this method", e);
}
}
/**
* If you create a class that implements nsISupports, you will need to provide
* an implementation of the queryInterface method. This helper
* function provides a simple implementation. Therefore, if your class does
* not need to do anything special with queryInterface, your
* implementation would look like:
*
* public nsISupports queryInterface(String aIID) {
* return XPCOM.queryInterface(this, aIID);
* }
*
*
* @param aObject object to query
* @param aIID requested interface IID
*
* @return aObject if the given object supports that
* interface;
* null otherwise.
*/
public static nsISupports queryInterface(nsISupports aObject, String aIID) {
ArrayList classes = new ArrayList();
classes.add(aObject.getClass());
while (!classes.isEmpty()) {
Class clazz = (Class) classes.remove(0);
// Skip over any class/interface in the "java.*" and "javax.*" domains.
String className = clazz.getName();
if (className.startsWith("java.") || className.startsWith("javax.")) {
continue;
}
// If given IID matches that of the current interface, then we
// know that aObject implements the interface specified by the given IID.
if (clazz.isInterface() && className.startsWith("org.mozilla")) {
String iid = Mozilla.getInterfaceIID(clazz);
if (iid != null && aIID.equals(iid)) {
return aObject;
}
}
// clazz didn't match, so add the interfaces it implements
Class[] interfaces = clazz.getInterfaces();
for (int i = 0; i < interfaces.length; i++ ) {
classes.add(interfaces[i]);
}
// Also add its superclass
Class superclass = clazz.getSuperclass();
if (superclass != null) {
classes.add(superclass);
}
}
return null;
}
/**
* Gets the interface IID for a particular Java interface. This is similar
* to NS_GET_IID in the C++ Mozilla files.
*
* @param aInterface interface which has defined an IID
*
* @return IID for given interface
*/
public static String getInterfaceIID(Class aInterface) {
// Get short class name (i.e. "bar", not "org.blah.foo.bar")
StringBuffer iidName = new StringBuffer();
String fullClassName = aInterface.getName();
int index = fullClassName.lastIndexOf(".");
String className = index > 0 ? fullClassName.substring(index + 1)
: fullClassName;
// Create iid field name
if (className.startsWith("ns")) {
iidName.append("NS_");
iidName.append(className.substring(2).toUpperCase());
} else {
iidName.append(className.toUpperCase());
}
iidName.append("_IID");
String iid;
try {
Field iidField = aInterface.getDeclaredField(iidName.toString());
iid = (String) iidField.get(null);
} catch (NoSuchFieldException e) {
// Class may implement non-Mozilla interfaces, which would not have an
// IID method. In that case, just null.
iid = null;
} catch (IllegalAccessException e) {
// Not allowed to access that field for some reason. Write out an
// error message, but don't fail.
System.err.println("ERROR: Could not get field " + iidName.toString());
iid = null;
}
return iid;
}
public long getNativeHandleFromAWT(Object widget) {
try {
return mozilla.getNativeHandleFromAWT(widget);
} catch (NullPointerException e) {
throw new XPCOMInitializationException("Must call " +
"Mozilla.getInstance().initialize() before using this method", e);
}
}
public long wrapJavaObject(Object aJavaObject, String aIID) {
try {
return jxutils.wrapJavaObject(aJavaObject, aIID);
} catch (NullPointerException e) {
throw new XPCOMInitializationException("Must call " +
"Mozilla.getInstance().initialize() before using this method", e);
}
}
public Object wrapXPCOMObject(long aXPCOMObject, String aIID) {
try {
return jxutils.wrapXPCOMObject(aXPCOMObject, aIID);
} catch (NullPointerException e) {
throw new XPCOMInitializationException("Must call " +
"Mozilla.getInstance().initialize() before using this method", e);
}
}
}