From 819d6c6d4e808e1fc47a09074e76ac49a715cceb Mon Sep 17 00:00:00 2001 From: "pedemont%us.ibm.com" Date: Tue, 21 Dec 2004 17:36:55 +0000 Subject: [PATCH] Bug 275106 - Add JavaDoc comments to non-generated Java files. r=darin --- extensions/java/xpcom/AppFileLocProvider.java | 25 ++++ extensions/java/xpcom/GeckoEmbed.java | 39 +++++- extensions/java/xpcom/XPCOM.java | 132 ++++++++++++++++-- extensions/java/xpcom/XPCOMException.java | 24 ++-- 4 files changed, 195 insertions(+), 25 deletions(-) diff --git a/extensions/java/xpcom/AppFileLocProvider.java b/extensions/java/xpcom/AppFileLocProvider.java index 20e39b0ae0c6..b8ce68a241da 100644 --- a/extensions/java/xpcom/AppFileLocProvider.java +++ b/extensions/java/xpcom/AppFileLocProvider.java @@ -39,8 +39,33 @@ package org.mozilla.xpcom; import java.io.*; + +/** + * Used by XPCOM's Directory Service to get file locations. + * + * @see GeckoEmbed#initEmbedding + * @see XPCOM#initXPCOM + */ public interface AppFileLocProvider { + /** + * Directory Service calls this when it gets the first request for + * a prop or on every request if the prop is not persistent. + * + * @param prop the symbolic name of the file + * @param persistent an array of length one used to supply the output value: + * + * @return the file represented by the property + * + * @see + * Directory Service property names + */ public File getFile(String prop, boolean[] persistent); } diff --git a/extensions/java/xpcom/GeckoEmbed.java b/extensions/java/xpcom/GeckoEmbed.java index 6d32136cd098..0900e628efca 100644 --- a/extensions/java/xpcom/GeckoEmbed.java +++ b/extensions/java/xpcom/GeckoEmbed.java @@ -39,9 +39,44 @@ package org.mozilla.xpcom; import java.io.*; +/** + * Provides access to functions that are used to embed Mozilla's Gecko layer. + */ public final class GeckoEmbed { - public static native void initEmbedding(File aMozBinDirectory, AppFileLocProvider aAppFileLocProvider); - public static native void termEmbedding(); + /** + * Initializes the Gecko embedding layer. You must + * call this method before proceeding to use Gecko. This function ensures + * XPCOM is started, creates the component registry if necessary and + * starts global services. + * + * @param aMozBinDirectory The Gecko directory containing the component + * registry and runtime libraries; + * or use 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. + * + * @exception XPCOMException if a failure occurred during initialization + */ + public static native + void initEmbedding(File aMozBinDirectory, + AppFileLocProvider aAppFileLocProvider); + + /** + * Terminates the Gecko embedding layer. Call this function during shutdown to + * ensure that global services are unloaded, files are closed and + * XPCOM is shutdown. + *

+ * NOTE: Release any XPCOM objects within Gecko that you may be holding a + * reference to before calling this function. + *

+ * + * @exception XPCOMException if a failure occurred during termination + */ + public static native + void termEmbedding(); } diff --git a/extensions/java/xpcom/XPCOM.java b/extensions/java/xpcom/XPCOM.java index 4cb331e622f8..aeadef9aa38b 100644 --- a/extensions/java/xpcom/XPCOM.java +++ b/extensions/java/xpcom/XPCOM.java @@ -41,19 +41,121 @@ import java.lang.reflect.*; import java.io.*; +/** + * Provides access to methods for initializing XPCOM, as well as helper methods + * for working with XPCOM classes. + */ public final class XPCOM { - public static native nsIServiceManager initXPCOM(File aMozBinDirectory, AppFileLocProvider aAppFileLocProvider); - public static native void shutdownXPCOM(nsIServiceManager aServMgr); - public static native nsIServiceManager getServiceManager(); - public static native nsIComponentManager getComponentManager(); - public static native nsIComponentRegistrar getComponentRegistrar(); - public static native nsILocalFile newLocalFile(String aPath, boolean followLinks); + /** + * 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 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 + * + * @exception XPCOMException + */ + public static native + nsIServiceManager initXPCOM(File aMozBinDirectory, AppFileLocProvider aAppFileLocProvider); + + /** + * 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. + * + * @exception XPCOMException if a failure occurred during termination + */ + public static native + void shutdownXPCOM(nsIServiceManager aServMgr); + + /** + * Public Method to access to the service manager. + * + * @return the service manager + * + * @exception XPCOMException + */ + public static native + nsIServiceManager getServiceManager(); + + /** + * Public Method to access to the component manager. + * + * @return the component manager + * + * @exception XPCOMException + */ + public static native + nsIComponentManager getComponentManager(); + + /** + * Public Method to access to the component registration manager. + * + * @return the component registration manager + * + * @exception XPCOMException + */ + public static native + nsIComponentRegistrar getComponentRegistrar(); + + /** + * 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 + * + * @exception XPCOMException + */ + public static native + nsILocalFile newLocalFile(String aPath, boolean aFollowLinks); - /* Utility functions */ - - // Generic QueryInterface implementation + /** + * 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) { Class[] interfaces = aObject.getClass().getInterfaces(); @@ -64,8 +166,14 @@ public final class XPCOM { return null; } - // Given an interface, this will construct the name of the IID field (such as - // NS_ISUPPORTS_IID) and return its value. + /** + * 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") @@ -90,7 +198,7 @@ public final class XPCOM { 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 return an emptry string. + // IID method. In that case, just return an empty string. iid = ""; } catch (IllegalAccessException e) { // XXX Should be using a logging service, such as java.util.logging diff --git a/extensions/java/xpcom/XPCOMException.java b/extensions/java/xpcom/XPCOMException.java index 3ee5031e8197..e29be6554978 100644 --- a/extensions/java/xpcom/XPCOMException.java +++ b/extensions/java/xpcom/XPCOMException.java @@ -37,26 +37,28 @@ package org.mozilla.xpcom; + +/** + * This exception is thrown whenever an internal XPCOM/Gecko error occurs. + * The internal Mozilla error ID is contained in the message. + */ public final class XPCOMException extends RuntimeException { + /** + * Constructs a new XPCOMException instance. + */ public XPCOMException() { super(); } + /** + * Constructs a new XPCOMException instance. + * + * @param message detailed message of exception + */ public XPCOMException(String message) { super(message); } - /* The RuntimeException constructors that take a Throwable parameter are only - available starting in Java 1.4. Commenting out for now to allow use by - Java 1.3 - */ -/* public XPCOMException(String message, Throwable cause) { - super(message, cause); - } - - public XPCOMException(Throwable cause) { - super(cause); - }*/ }