Classes to access access and manipulate the W3C DOM of the +current page.
+ +The normal way to gain access to the dom is by calling {@link
+org.mozilla.webclient.CurrentPage#getDOM}. This returns an org.w3c.dom.Document
+instance which can be manipulated and inspected as desired.
DOM Utilities.
+
- * Debug Vendor of debug "filter" strings set & queried by clients. This allows
- * conditional code to only be executed if a certain filter is set.
+ *
Vendor of debug "filter" strings set & queried by + * clients. This allows conditional code to only be executed if a + * certain filter is set.
* - * Example of use from JAG days:JDApplication allows the setting of filters from the commandline + * at app startup time, and Log supports printing debug messages only + * when a specific filter string has been set.
* - *+ *
Alternatively, users can use the System Properties table to + * define filter strings at runtime:
* - * Alternatively, users can use the System Properties table to define - * filter strings at runtime:
- *
- *
- *
+ *
*
- * where String is comma (,) separated list of constants WITH NO
- * WHITESPACE. ie "AXISPANEL_PAINT,BODYPANEL_PAINT".
* java -DDebug.filters=String ...
+ *
+ *
where String is comma (,) separated list of constants WITH NO + * WHITESPACE. ie "AXISPANEL_PAINT,BODYPANEL_PAINT".
* * - * All filters are case-sensitive. + *All filters are case-sensitive.
* - * This class also provides various timing routines. + *This class also provides various timing routines.
* * * @author Keith Bernstein - * @version $Id: Debug.java,v 1.3 2002-04-12 22:57:18 edburns%acm.org Exp $ */ + * @version $Id: Debug.java,v 1.4 2005-03-15 02:49:16 edburns%acm.org Exp $ */ public class Debug extends Object { static public final String HELP_FILTER_STRING = "HELP"; @@ -101,59 +100,66 @@ public class Debug extends Object { } } -/** + /** + *Wait until a debugger attaches.
+ * + *Usage:
+ * + *Place a call to this method in the earliest possible entry + * point of your servlet app. It will cause the app to enter into + * an infinite loop, sleeping until the static var keepWaiting is + * set to false. The idea is that you attach your debugger to the + * servlet, then, set a breakpont in this method. When it is hit, + * you use the debugger to set the keepWaiting class var to + * false.
+ */ -* Usage:- -* Place a call to this method in the earliest possible entry point of -* your servlet app. It will cause the app to enter into an infinite -* loop, sleeping until the static var keepWaiting is set to false. The -* idea is that you attach your debugger to the servlet, then, set a -* breakpont in this method. When it is hit, you use the debugger to set -* the keepWaiting class var to false. - -*/ - -public static void waitForDebugger() { - while (keepWaiting) { - try { - Thread.sleep(5000); - } - catch (InterruptedException e) { - System.out.println("DebugUtil.waitForDebugger(): Exception: " + - e.getMessage()); + public static void waitForDebugger() { + while (keepWaiting) { + try { + Thread.sleep(5000); + } + catch (InterruptedException e) { + System.out.println("DebugUtil.waitForDebugger(): Exception: " + + e.getMessage()); + } } } -} - + /** - * Sets a debug filter, for future consumption by this class, as well as other - * utility classes, like Log, etc. - * - * Virtually all "filters" are simply developer-meaningful strings which will be - * tested within developer code, to conditionally execute code. - * - * There are some predefined filters, which this class actually does something with - * (besides simply handing it back when asked for). - * - * The predefined filters are: - * HELP - * ALL - * TIMING - * - * If the "HELP" filter is found, this class will print a message displaying the - * predefined filters and what they do. - * - * If the "ALL" filter is found, this class will return "true" when queried for the - * existence of any filter, effectively turning on all debugging tests. - * This is useful for both quick and easy tests, as well as to find forgotten debug - * filters (see Log class for more info on this). - * - * If the "TIMING" filter is specified, then the time routines will always print - * their info, regardless of what filter string is passed to them. This is useful - * for turning on all timing tests. - * */ + *
Sets a debug filter, for future consumption by this class, as + * well as other utility classes, like Log, etc.
+ * + *Virtually all "filters" are simply developer-meaningful strings + * which will be tested within developer code, to conditionally + * execute code.
+ * + *There are some predefined filters, which this class actually + * does something with (besides simply handing it back when asked + * for).
+ * + *The predefined filters are:
+ * + *HELP
+ *ALL
+ *TIMING
+ * + *If the "HELP" filter is found, this class will print a message + * displaying the predefined filters and what they do.
+ * + *If the "ALL" filter is found, this class will return "true" + * when queried for the existence of any filter, effectively + * turning on all debugging tests. This is useful for both quick + * and easy tests, as well as to find forgotten debug filters (see + * Log class for more info on this).
+ * + *If the "TIMING" filter is specified, then the time routines + * will always print their info, regardless of what filter string is + * passed to them. This is useful for turning on all timing + * tests.
+ * + */ static public synchronized void addFilter(String aFilter) { if (aFilter != null) { if (filters == null) { @@ -200,11 +206,11 @@ public static void waitForDebugger() { } /** - * Look for any "filter" with the specified prefix. + *Look for any "filter" with the specified prefix.
* - * "ALL" is not considered to be a match. + *"ALL" is not considered to be a match.
* - * This method works in (normally) O-n time (if no match). + *This method works in (normally) O-n time (if no match).
*/ static public synchronized boolean containsFilterWithPrefix(String aFilterPrefix) { @@ -225,16 +231,19 @@ public static void waitForDebugger() { } /** - * Funnel-point method, which takes a filter and an "allFiltersgMatchThisString" string. - * See the javadoc for "containsFilter(String aFilter)" for the rest of what this method - * does. + *Funnel-point method, which takes a filter and an + * "allFiltersgMatchThisString" string. See the javadoc for + * "containsFilter(String aFilter)" for the rest of what this method + * does.
* - * This method works in (normally) O-1 time. + *This method works in (normally) O-1 time.
* - * NOTE: The "allFiltersgMatchThisString" parameter can be used to conditionally execute - * code while preventing the "ALL" filter from having any effect. So, the conditional code - * should use the test "if (Debug.containsFilter("SomeFilter", ""))" to see if a filter - * has been set, and not get a false positive from the "ALL" filter. + *NOTE: The "allFiltersgMatchThisString" parameter can be used to + * conditionally execute code while preventing the "ALL" filter from + * having any effect. So, the conditional code should use the test + * "if (Debug.containsFilter("SomeFilter", ""))" to see if a filter + * has been set, and not get a false positive from the "ALL" + * filter.
*/ static public synchronized boolean containsFilter(String aFilter, String allFiltersgMatchThisString) { if (((aFilter != null) && ((filters != null) && filters.contains(aFilter))) @@ -247,22 +256,35 @@ public static void waitForDebugger() { } /** - * Returns true if any of the following conditions are true: - * 1. The specified filter is contained in the current filter set. - * 2. The "ALL" filter is set (this is true even if the passed-in filter is "null"). - * 3. The passed-in filter is ""... as that filter is considered - * to always be a match, regardless of the current filter set. - * 4. The passed in filter is "null" and the "ALL" filter is currently set. - * Otherwise returns false. - * - * NOTE: This method, and all filtering of this class is case-sensitive. - */ + *Returns true if any of the following conditions are true.
+ * + *Otherwise returns false. + * + *
NOTE: This method, and all filtering of this class is + * case-sensitive.
+ */ static public synchronized boolean containsFilter(String aFilter) { return Debug.containsFilter(aFilter, Debug.ALL_FILTER_STRING); } - // Only used by the timing routines, since they ignore "ALL", but pay attention to - // "TIMING". + // Only used by the timing routines, since they ignore "ALL", but + // pay attention to "TIMING". static private synchronized boolean containsTimingFilter(String aFilter) { return Debug.containsFilter(aFilter, Debug.TIMING_FILTER_STRING); } @@ -317,11 +339,13 @@ public static void waitForDebugger() { } /** - * Starts a timer which can be stopped using one of the "stopTiming()" methods. + *Starts a timer which can be stopped using one of the + * "stopTiming()" methods.
* - * This method does not check debug filters... it always does what it's told. + *This method does not check debug filters... it always does what + * it's told.
* - * Calling this method resets the elapsed time ("lap time"). + *Calling this method resets the elapsed time ("lap time").
*/ static public synchronized void startTiming() { startTime = new Date().getTime(); @@ -329,30 +353,43 @@ public static void waitForDebugger() { } /** - * Identical to the "startTiming(String logMessage, String aFilter)" method, except it - * will only show the message if the filter "TIMING" exists in Debug's filter list. + *Identical to the "startTiming(String logMessage, String + * aFilter)" method, except it will only show the message if the + * filter "TIMING" exists in Debug's filter list.
*/ static public synchronized void startTiming(String logMessage) { Debug.startTiming(logMessage, Debug.TIMING_FILTER_STRING); } /** - * This method does absolutely nothing unless: - * 1. The specified filter is contained in the current filter set. - * 2. The "TIMING" filter is set (this is true even if the passed-in filter is "null"). - * 3. The passed-in filter is ""... as that filter is considered - * to always be a match, and so will cause this method to always work, - * regardless of the current filter set. - * NOTE: The "ALL" filter has no effect on timing methods. + *This method does absolutely nothing unless one or more of the + * following conditions are met.
* - * Otherwise, starts a timer which can be stopped using one of the "stopTiming()" methods - * and prints out a logMessage indicating that timing has begun. + *NOTE: The "ALL" filter has no effect on timing methods.
+ * + *Otherwise, starts a timer which can be stopped using one of the + * "stopTiming()" methods and prints out a logMessage indicating that + * timing has begun.
+ * + *This method may be called with a "null" logMessage. A + * logMessage is sometimes unneccesary since the matched filter + * string is printed with the output anyway, and that is frequently + * enough information.
+ * + *Calling this method resets the elapsed time ("lap time").
*/ static public synchronized void startTiming(String logMessage, String aFilter) { if (Debug.containsTimingFilter(aFilter)) { @@ -374,27 +411,26 @@ public static void waitForDebugger() { } /** - * Returns the elapsed time since this class was initialized. - * - * This method does not check debug filters... it always does what it's told. - * - * Calling this method resets the elapsed time ("lap time"). - * - * This method may be called repeatedly to get "lap" times. - */ + *Returns the elapsed time since this class was initialized.
+ * + *This method does not check debug filters... it always does + * what it's told.
+ * + *Calling this method resets the elapsed time ("lap time").
+ * + *This method may be called repeatedly to get "lap" times.
+ */ static public synchronized long elapsedTimeSinceInitialization() { return Debug.elapsedTime(initializationTime); } /** - * Returns the elapsed time since the preceeding startTiming() call, - * - * This method does not check debug filters... it always does what it's told. - * - * Calling this method resets the elapsed time ("lap time"). - * - * This method may be called repeatedly to get "lap" times. - */ + *Returns the elapsed time since the preceeding startTiming() + * call. This method does not check debug filters... it always does + * what it's told. Calling this method resets the elapsed time + * ("lap time"). This method may be called repeatedly to get "lap" + * times.
+ */ static public synchronized long elapsedTimeSinceStartTime() { if (startTime == 0) { return 0L; // "startTime()" was never called. @@ -404,13 +440,14 @@ public static void waitForDebugger() { } /** - * Returns the elapsed time since this class was initialized. + *Returns the elapsed time since this class was initialized.
* - * This method does not check debug filters... it always does what it's told. + *This method does not check debug filters... it always does what + * it's told.
* - * Calling this method resets the elapsed time ("lap time"). + *Calling this method resets the elapsed time ("lap time").
* - * This method may be called repeatedly to get "lap" times. + *This method may be called repeatedly to get "lap" times.
*/ static public synchronized long elapsedTimeSinceElapsedTime() { if (lapTime == 0) { @@ -421,41 +458,60 @@ public static void waitForDebugger() { } /** - * Identical to the "elapsedTime(String logMessage, String aFilter)" method, except it - * will only show the message if the filter "TIMING" exists in Debug's filter list. - */ + *Identical to the "elapsedTime(String logMessage, String + * aFilter)" method, except it will only show the message if the + * filter "TIMING" exists in Debug's filter list.
+ */ static public synchronized void elapsedTime(String logMessage) { Debug.elapsedTime(logMessage, Debug.TIMING_FILTER_STRING); } /** - * This method does absolutely nothing unless: - * 1. The specified filter is contained in the current filter set. - * 2. The "TIMING" filter is set (this is true even if the passed-in filter is "null"). - * 3. The passed-in filter is ""... as that filter is considered - * to always be a match, and so will cause this method to always work, - * regardless of the current filter set. - * NOTE: The "ALL" filter has no effect on timing methods. + *This method does absolutely nothing unless one or more of the + * following conditions are met.
* - * Otherwise, prints the following information: - * 1. The elapsed time since initialization of this class. - * 2. The elapsed time since the preceeding startTiming() call. - * 3. The "lap" time, since the last time "elapsedTime()" was called. - * 4. A client-supplied message. + *NOTE: The "ALL" filter has no effect on timing methods.
+ * + *Otherwise, prints the following information:
+ * + *When a filter matches, this method invokes the following methods:
* - * When a filter matches, calling this method resets the elapsed time ("lap time"). + *elapsedTime()
+ *elapsedTimeSinceInitialization()
+ *elapsedTimeSinceElapsedTime()
* + *When a filter matches, calling this method resets the elapsed + * time ("lap time").
* - * This method may be called with a "null" logMessage. A logMessage is sometimes - * unneccesary since the matched filter string is printed with the output anyway, and that - * is frequently enough information. + *This method may be called with a "null" logMessage. A + * logMessage is sometimes unneccesary since the matched filter + * string is printed with the output anyway, and that is frequently + * enough information.
* - * This method may be called repeatedly to get "lap" times. + *This method may be called repeatedly to get "lap" times.
*/ static public synchronized void elapsedTime(String logMessage, String aFilter) { if (Debug.containsTimingFilter(aFilter)) { @@ -499,10 +555,10 @@ public static void waitForDebugger() { } /** - * Print time since start of app, and time since the last time this method - * was called. - * Call this with a msg you want printed, and a filter. Then - * run with -jsdebug filter and all these timing msgs will come out. + *Print time since start of app, and time since the last time + * this method was called. Call this with a msg you want printed, + * and a filter. Then run with -jsdebug filter and all these timing + * msgs will come out.
*/ static public synchronized void printTime( String msg, String aFilter) { if ( filters != null && filters.contains( aFilter)) { @@ -517,8 +573,8 @@ public static void waitForDebugger() { } /** - * Returns a String containing the hexadecimal hashCode of the passed in object, - * of the form: "0x0000" + *Returns a String containing the hexadecimal hashCode of the + * passed in object, of the form: "0x0000".
*/ static public synchronized String getHashCode(Object anObject) { String returnValue; @@ -532,8 +588,9 @@ public static void waitForDebugger() { } /** - * Returns a String containing the class name and hexadecimal hashCode of the - * passed in object, of the form: "fully.qualified.ClassName[0x0000]" + *Returns a String containing the class name and hexadecimal + * hashCode of the passed in object, of the form: + * "fully.qualified.ClassName[0x0000]".
*/ static public synchronized String getNameAndHashCode(Object anObject) { String returnValue; diff --git a/mozilla/java/util/classes/org/mozilla/util/Log.java b/mozilla/java/util/classes/org/mozilla/util/Log.java index 754b60258ad..e1a3b374597 100644 --- a/mozilla/java/util/classes/org/mozilla/util/Log.java +++ b/mozilla/java/util/classes/org/mozilla/util/Log.java @@ -1,4 +1,4 @@ -/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- +/* -*- Mode: java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- * * The contents of this file are subject to the Mozilla Public * License Version 1.1 (the "License"); you may not use this file @@ -26,11 +26,9 @@ package org.mozilla.util; import java.util.Date; /** - *- * Log - *
+ *Logging facility.
* @author Keith Bernstein - * @version $Id: Log.java,v 1.2 1999-11-06 02:25:55 dmose%mozilla.org Exp $ + * @version $Id: Log.java,v 1.3 2005-03-15 02:49:16 edburns%acm.org Exp $ */ public class Log extends Object { @@ -40,25 +38,28 @@ public class Log extends Object { static int showTimestampPrefix = 1; /** - * This string will be prepended to all output from this class. + *This string will be prepended to all output from this + * class.
* - * This string is usually the application name, e.g. "JavaPlan". + *This string is usually the application name, e.g. "JavaPlan".
* - * It is useful because it includes a timestamp and the base string (usually the - * application name), so that if two apps are launched from the same commandline - * (for example), with "&", or one app invokes another, it is clear who the message - * is comming from. The time stamp can help see how long operations took, etc. + *It is useful because it includes a timestamp and the base string + * (usually the application name), so that if two apps are launched + * from the same commandline (for example), with "&", or one app + * invokes another, it is clear who the message is comming from. The + * time stamp can help see how long operations took, etc.
* - * If you don't want your messages prefixed with anything (no time stamp or name), you must - * pass "null" for "applicationName". + *If you don't want your messages prefixed with anything (no time + * stamp or name), you must pass "null" for "applicationName".
* - * If this method is never called, "applicationName" will default to: - * "APPLICATION NAME UNKNOWN [call setApplicationName from main]" + *If this method is never called, "applicationName" will default + * to: "APPLICATION NAME UNKNOWN [call setApplicationName from + * main]"
* */ static public synchronized void setApplicationName(String newApplicationName) { - // It's really unfortunate that we can't discover this dynamically. - applicationName = newApplicationName; + // It's really unfortunate that we can't discover this dynamically. + applicationName = newApplicationName; } /** @@ -114,9 +115,10 @@ public class Log extends Object { } /** - * Incrememnts or decrements whether or not to prefix logged messages with a timestamp. - * Two (or "n") calls with a value of "false" must be followed by two (or "n") calls - * with a value of "true" to reenable timestamp prefixes. + * Incrememnts or decrements whether or not to prefix logged messages + * with a timestamp. Two (or "n") calls with a value of "false" must + * be followed by two (or "n") calls with a value of "true" to + * reenable timestamp prefixes. */ static public synchronized void enableTimestampPrefix(boolean enable) { if (enable) { @@ -127,7 +129,8 @@ public class Log extends Object { } /** - * Writes "infoMessage" to stdout, prefixed by the string "ApplicationName: " + * Writes "infoMessage" to stdout, prefixed by the string + * "ApplicationName: " */ static public synchronized void log(Object infoMessage) { System.out.println(Log.applicationNameWithTimeStamp()+": "+infoMessage); @@ -135,7 +138,8 @@ public class Log extends Object { } /** - * Writes "errorMessage" to stderr, prefixed by the string "ApplicationName error: " + * Writes "errorMessage" to stderr, prefixed by the string + * "ApplicationName error: " */ static public synchronized void logError(Object errorMessage) { System.err.println(Log.applicationNameWithTimeStamp()+" error: "+errorMessage); @@ -143,7 +147,8 @@ public class Log extends Object { } /** - * Writes "errorMessage" to stderr, prefixed by the string "ApplicationName: " + * Writes "errorMessage" to stderr, prefixed by the string + * "ApplicationName: " */ static public synchronized void logErrorMessage(Object errorMessage) { System.err.println(Log.applicationNameWithTimeStamp()+": "+errorMessage); @@ -156,19 +161,22 @@ public class Log extends Object { } /** - * Funnel-point method for printing debug messages. + *Funnel-point method for printing debug messages.
* - * Writes "debugMessage" to stderr, prefixed by the string "ApplicationName:" + *Writes "debugMessage" to stderr, prefixed by the string + * "ApplicationName:"
* - * This method only works if the debugFilter string is found in Debug's list of - * filter strings (which you can normally set on the commandline, see JDApplication), - * or if the "ALL" filter has been set into Debug's list of filters, or if the passed - * in filter is "", which is considered to always be "set", and will print a line with - * "[DEBUG]" listed as the filter. + *This method only works if the debugFilter string is found in + * Debug's list of filter strings (which you can normally set on the + * commandline, see JDApplication), or if the "ALL" filter has been + * set into Debug's list of filters, or if the passed in filter is + * "", which is considered to always be "set", and will print a line + * with "[DEBUG]" listed as the filter.
* - * This method may be called with a "null" debugMessage. A debugMessage is sometimes - * unneccesary since the matched filter string is printed with the output anyway, and that - * is frequently enough information. + *This method may be called with a "null" debugMessage. A + * debugMessage is sometimes unneccesary since the matched filter + * string is printed with the output anyway, and that is frequently + * enough information.
*/ static public synchronized void logDebugMessage(Object debugMessage, String debugFilter) { if (Debug.containsFilter(debugFilter)) { @@ -191,16 +199,17 @@ public class Log extends Object { } /** - * Equivalent to calling "logDebugMessage(debugMessage, "ALL")". - */ + * Equivalent to calling "logDebugMessage(debugMessage, "ALL")". + */ static public synchronized void logDebugMessage(Object debugMessage) { logDebugMessage(debugMessage, "ALL"); } /** - * Log a message when "aCondition" is true, otherwise be silent. - * Equivalent to calling "if (aCondition) logDebugMessage(debugMessage, "")". - */ + * Log a message when "aCondition" is true, otherwise be silent. + * Equivalent to calling "if (aCondition) + * logDebugMessage(debugMessage, "")". + */ static public synchronized void logDebugMessage(Object debugMessage, boolean aCondition) { if (aCondition) { Log.logDebugMessage(debugMessage, ""); @@ -208,8 +217,8 @@ public class Log extends Object { } /** - * Log a message when "aCondition" is true, otherwise be silent. - */ + * Log a message when "aCondition" is true, otherwise be silent. + */ static public synchronized void logDebugMessage(Object anInstance, Object debugMessage, boolean aCondition) { if (aCondition) { Log.logDebugMessage(Debug.getNameAndHashCode(anInstance)+": "+debugMessage, ""); diff --git a/mozilla/java/util/classes/org/mozilla/util/Range.java b/mozilla/java/util/classes/org/mozilla/util/Range.java index 96e1129f0ea..17f1352e283 100644 --- a/mozilla/java/util/classes/org/mozilla/util/Range.java +++ b/mozilla/java/util/classes/org/mozilla/util/Range.java @@ -34,7 +34,7 @@ import java.lang.Math; * introduce mutability. A mutable range will return true from * isMutable(). * - * @version $Id: Range.java,v 1.2 1999-11-06 02:25:56 dmose%mozilla.org Exp $ + * @version $Id: Range.java,v 1.3 2005-03-15 02:49:16 edburns%acm.org Exp $ * @author The LFC Team (Rob Davis, Paul Kim, Alan Chung, Ray Ryan, etc) * @author David-John Burrowes (he moved it to the AU package) * @see Range#isMutable() @@ -51,7 +51,7 @@ public class Range extends Object implements Cloneable, Serializable { * The RCSID for this class. */ private static final String RCSID = - "$Id: Range.java,v 1.2 1999-11-06 02:25:56 dmose%mozilla.org Exp $"; + "$Id: Range.java,v 1.3 2005-03-15 02:49:16 edburns%acm.org Exp $"; /** * A zero range @@ -80,7 +80,7 @@ public class Range extends Object implements Cloneable, Serializable { * Creates an instance of Range from another Range object * otherRange which must be non-null. * - * @param range the reference range to create this range from + * @param otherRange the reference range to create this range from * @exception IllegalArgumentException if otherRange is null */ public Range(Range otherRange) { @@ -262,7 +262,7 @@ public class Range extends Object implements Cloneable, Serializable { * otherRange. A zero-length range has no overlapping elements * with any range. * - * @param a range to check overlaps with this range + * @param otherRange a range to check overlaps with this range * @exception IllegalArgumentException if otherRange is null * @return number of elements in both this range and otherRange */ diff --git a/mozilla/java/util/classes/org/mozilla/util/Utilities.java b/mozilla/java/util/classes/org/mozilla/util/Utilities.java index 2d049270660..c2ce0d39e5f 100644 --- a/mozilla/java/util/classes/org/mozilla/util/Utilities.java +++ b/mozilla/java/util/classes/org/mozilla/util/Utilities.java @@ -293,8 +293,8 @@ public class Utilities extends Object { /** * *This method tries to load the resource
- * META-INF/services/>interfaceClassName>, where
- * >interfaceClassName< is the argument to this
+ * META-INF/services/<interfaceClassName>, where
+ * <interfaceClassName> is the argument to this
* method. If the resource is found, interpret it as a
* Properties file and read out its first line.
* Interpret the first line as the fully qualified class name of a
diff --git a/mozilla/java/util/classes/org/mozilla/util/package.html b/mozilla/java/util/classes/org/mozilla/util/package.html
new file mode 100644
index 00000000000..f1486695ff8
--- /dev/null
+++ b/mozilla/java/util/classes/org/mozilla/util/package.html
@@ -0,0 +1,45 @@
+
+
+
+
+
+
+
Application utilities. Logging, Debugging, Factory, Assertion, and +Parameter Checking
+ + +Provides a common access point for other webclient interfaces. + * There is one instance of this class per application-level browser + * window. Instances must be created using {@link + * BrowserControlFactory}.
* - * @version $Id: BrowserControl.java,v 1.4 2003-09-28 06:29:04 edburns%acm.org Exp $ + * @version $Id: BrowserControl.java,v 1.5 2005-03-15 02:49:16 edburns%acm.org Exp $ * * @see org.mozilla.webclient.BrowserControlFactory - * */ + * + */ -public interface BrowserControl -{ +public interface BrowserControl { + + /** + *The name of the interface for the {@link Bookmarks} API.
+ */ + + public static String BOOKMARKS_NAME = "webclient.Bookmarks"; + + /** + *The name of the interface for the {@link BrowserControlCanvas} + * that must be added to the application to show the browser + * window.
+ */ + + public static String BROWSER_CONTROL_CANVAS_NAME = "webclient.BrowserControlCanvas"; -public static String BOOKMARKS_NAME = "webclient.Bookmarks"; -public static String BROWSER_CONTROL_CANVAS_NAME = "webclient.BrowserControlCanvas"; -public static String CURRENT_PAGE_NAME = "webclient.CurrentPage"; -public static String EVENT_REGISTRATION_NAME = "webclient.EventRegistration"; -public static String EXTENDED_EVENT_REGISTRATION_NAME = "webclient.ExtendedEventRegistration"; -public static String HISTORY_NAME = "webclient.History"; -public static String NAVIGATION_NAME = "webclient.Navigation"; -public static String CACHE_MANAGER_NAME = "webclient.cache.NetDataCacheManager"; -public static String PREFERENCES_NAME = "webclient.Preferences"; -public static String PRINT_NAME = "webclient.Print"; -public static String WINDOW_CONTROL_NAME = "webclient.WindowControl"; -public static String PROFILE_MANAGER_NAME = "webclient.ProfileManager"; + /** + *The name of the interface for the {@link CurrentPage} API.
+ */ + + public static String CURRENT_PAGE_NAME = "webclient.CurrentPage"; + + /** + *The name of the interface for the {@link EventRegistration} + * API.
+ */ + public static String EVENT_REGISTRATION_NAME = "webclient.EventRegistration"; + + /** + *The name of the interface for the {@link EventRegistration2} + * API.
+ */ + + public static String EXTENDED_EVENT_REGISTRATION_NAME = "webclient.ExtendedEventRegistration"; + + /** + *The name of the interface for the {@link History} API.
+ */ + + public static String HISTORY_NAME = "webclient.History"; + + /** + *The name of the interface for the {@link Navigation} API.
+ */ + + public static String NAVIGATION_NAME = "webclient.Navigation"; + + /** + *The name of the interface for the cache management API. + * Unimplemented.
+ */ + + public static String CACHE_MANAGER_NAME = "webclient.cache.NetDataCacheManager"; + + /** + *The name of the interface for the {@link Preferences} API.
+ */ + + public static String PREFERENCES_NAME = "webclient.Preferences"; + + /** + *The name of the interface for the Print API. + * Unimplemented.
+ */ + + public static String PRINT_NAME = "webclient.Print"; + + /** + *The name of the interface for the {@link WindowControl} API.
+ */ + + public static String WINDOW_CONTROL_NAME = "webclient.WindowControl"; + + /** + *The name of the interface for the {@link ProfileManager} API.
+ */ + + public static String PROFILE_MANAGER_NAME = "webclient.ProfileManager"; /** * @deprecated the type of browser implementation is derived using a @@ -63,18 +125,24 @@ public static String PROFILE_MANAGER_NAME = "webclient.ProfileManager"; * org.mozilla.util.Utilities#getImplFromServices} * */ - -public static String BROWSER_TYPE_NATIVE = null; -public static String BROWSER_TYPE_NON_NATIVE = null; - + + public static String BROWSER_TYPE_NATIVE = null; + public static String BROWSER_TYPE_NON_NATIVE = null; + /** - + * + *Obtain a reference to a class implementing the argument
+ * interfaceName.
interfaceName
* are any of the *_NAME class variables in this interface.
-
+ *
+ * @throws ClassNotFoundException if the interfaceName
+ * can't be instantiated for whatever reason.
+ *
*/
-
-public Object queryInterface(String interfaceName) throws ClassNotFoundException;
+
+ public Object queryInterface(String interfaceName) throws ClassNotFoundException;
} // end of interface BrowserControl
diff --git a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/BrowserControlFactory.java b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/BrowserControlFactory.java
index c5145416e24..701ae7dc70f 100644
--- a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/BrowserControlFactory.java
+++ b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/BrowserControlFactory.java
@@ -1,4 +1,4 @@
-/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
+/* -*- Mode: java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
*
* The contents of this file are subject to the Mozilla Public
* License Version 1.1 (the "License"); you may not use this file
@@ -37,109 +37,143 @@ import java.io.FileNotFoundException;
/**
+ * The factory from which {@link BrowserControl} instances are + * created.
* - *BrowserControlFactory uses {@link - * Utilities#getImplFromServices} to find an implementation of {@link - * WebclientFactory}. All of the public static methods in this class - * simply call through to this implemenatation instance.
+ *BrowserControlFactory uses {@link + * Utilities#getImplFromServices} to find an implementation of {@link + * WebclientFactory}. All of the public static methods in this class + * simply call through to this implementation instance.
* - * - * @version $Id: BrowserControlFactory.java,v 1.11 2004-11-05 06:40:26 edburns%acm.org Exp $ + * @version $Id: BrowserControlFactory.java,v 1.12 2005-03-15 02:49:16 edburns%acm.org Exp $ * * */ -public class BrowserControlFactory extends Object -{ -// -// Protected Constants -// +public class BrowserControlFactory extends Object { + // + // Protected Constants + // + + // + // Class Variables + // + + private static WebclientFactory instance = null; + + // + // Constructors and Initializers + // + + private BrowserControlFactory() { + Assert.assert_it(false, "This class shouldn't be constructed."); + } + + // + // Class methods + // -// -// Class Variables -// - -private static WebclientFactory instance = null; - -// -// Constructors and Initializers -// - -private BrowserControlFactory() -{ - Assert.assert_it(false, "This class shouldn't be constructed."); -} - -// -// Class methods -// - -public static void setProfile(String profileName) -{ - getInstance().setProfile(profileName); -} - -/** - * - *Initialize the webclient API passing in the path to the browser - * binary, if necessary. This must be the first method called in the - * Webclient API.
- * - *If we are embedding a native browser, calling this method will - * cause the native libraries to be loaded into the JVM.
- * - * @param absolutePathToNativeBrowserBinDir if non-null
- * this must be the path to the bin dir of the native browser, including
- * the bin. ie: "D:\\Projects\\mozilla\\dist\\win32_d.obj\\bin". When
- * embedding a non-native browser, this may be null.
- *
- */
-
-public static void setAppData(String absolutePathToNativeBrowserBinDir) throws FileNotFoundException, ClassNotFoundException
-{
- getInstance().setAppData(absolutePathToNativeBrowserBinDir);
-}
-
-/**
- *
- * @deprecated Use {@link #setAppData(java.lang.String)} instead.
- */
-
-public static void setAppData(String notUsed, String absolutePathToNativeBrowserBinDir) throws FileNotFoundException, ClassNotFoundException
-{
- getInstance().setAppData(absolutePathToNativeBrowserBinDir);
-}
-
-public static void appTerminate() throws Exception
-{
- getInstance().appTerminate();
-}
-
-public static BrowserControl newBrowserControl() throws InstantiationException, IllegalAccessException, IllegalStateException
-{
- BrowserControl result = null;
- result = getInstance().newBrowserControl();
- return result;
-}
-
-public static void deleteBrowserControl(BrowserControl toDelete)
-{
- getInstance().deleteBrowserControl(toDelete);
-}
-
-//
-// helper methods
-//
-
-protected static WebclientFactory getInstance()
-{
- if (null != instance) {
- return instance;
+ /**
+ * If called before the first {@link BrowserControl} has been + * created, set the name of the profile to use for this browser + * session. If the underlying browser does not support the concept + * of profiles, this method is a no-op.
+ * + * @param profileName the name of the profile + */ + + public static void setProfile(String profileName) { + getInstance().setProfile(profileName); } - instance = (WebclientFactory) - Utilities.getImplFromServices("org.mozilla.webclient.WebclientFactory"); - return instance; -} + /** + * + *Initialize the webclient API passing in the path to the browser + * binary, if necessary. This must be the first method called in the + * Webclient API, and it must be called once and only once.
+ * + *If we are embedding a native browser, calling this method will + * cause the native libraries to be loaded into the JVM.
+ * + * @param absolutePathToNativeBrowserBinDir if non-null
+ * this must be the path to the bin dir of the native browser, including
+ * the bin. ie: "D:\\Projects\\mozilla\\dist\\win32_d.obj\\bin". When
+ * embedding a non-native browser, this may be null.
+ *
+ */
+
+ public static void setAppData(String absolutePathToNativeBrowserBinDir) throws FileNotFoundException, ClassNotFoundException {
+ getInstance().setAppData(absolutePathToNativeBrowserBinDir);
+ }
+ /**
+ *
+ * @deprecated Use {@link #setAppData(java.lang.String)} instead.
+ */
+
+ public static void setAppData(String notUsed, String absolutePathToNativeBrowserBinDir) throws FileNotFoundException, ClassNotFoundException {
+ getInstance().setAppData(absolutePathToNativeBrowserBinDir);
+ }
+
+ /**
+ * This method must be called when the application no longer + * needs to use the Webclient API for the rest of its lifetime.
+ */ + + public static void appTerminate() throws Exception { + getInstance().appTerminate(); + } + + /** + *Create, initialize, and return a new {@link BrowserControl}
+ * instance. There is one BrowserControl instance per
+ * browser window. For example, in a tabbed browser application
+ * with three browser tabs open, there will be three
+ * BrowserControl instances, one for each tab. Also,
+ * any pop-up windows that are created during the course of a user
+ * session also correspond to a BrowserControl
+ * instance.
Delete a {@link BrowserControl} instance created with {@link
+ * #newBrowserControl}. This method must be called when the user no
+ * longer needs a BrowserControl instance. For
+ * example, when a browser tab closes.
BrowserControl instance to
+ * delete.
+ */
+
+ public static void deleteBrowserControl(BrowserControl toDelete) {
+ getInstance().deleteBrowserControl(toDelete);
+ }
+
+ //
+ // helper methods
+ //
+
+ /**
+ * This method enables separating the webclient interface from + * its implementation via the {@link Utilities#getImplFromServices} + * method.
+ */ + + protected static WebclientFactory getInstance() + { + if (null != instance) { + return instance; + } + + instance = (WebclientFactory) + Utilities.getImplFromServices("org.mozilla.webclient.WebclientFactory"); + return instance; + } + } // end of class BrowserControlFactory diff --git a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/ImplObject.java b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/ImplObject.java index 5324636eb45..b86e738f3fe 100644 --- a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/ImplObject.java +++ b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/ImplObject.java @@ -91,8 +91,6 @@ public BrowserControl getBrowserControl() { * Subclasses should override this and call super.delete() at the end of * their overridden delete() method. - * @see org.mozilla.webclient.wrapper_native.ImplObjectNative#delete - */ public void delete() diff --git a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/Navigation2.java b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/Navigation2.java index 929b9001335..fcb22a4c6d3 100644 --- a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/Navigation2.java +++ b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/Navigation2.java @@ -37,7 +37,7 @@ public interface Navigation2 extends Navigation /** - * @param absoluteUrl, must be absolute + * @param absoluteUrl must be absolute * @param target null at the moment diff --git a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/WebclientFactory.java b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/WebclientFactory.java index 4bf12468516..464290991c8 100644 --- a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/WebclientFactory.java +++ b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/WebclientFactory.java @@ -56,9 +56,10 @@ public interface WebclientFactory { throws FileNotFoundException, ClassNotFoundException; /** - *if called before {@link setAppData}, this will cause the - * profile used for starting up the underlying browser to be set. - * If not called, the default will be "webclient"
+ *if called before {@link + * BrowserControlFactory#setAppData(java.lang.String)}, this will + * cause the profile used for starting up the underlying browser to + * be set. If not called, the default will be "webclient"
*/ public void setProfile(String profileName); diff --git a/mozilla/java/webclient/classes_spec/org/mozilla/webclient/overview.html b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/overview.html new file mode 100644 index 00000000000..b8ef13b0802 --- /dev/null +++ b/mozilla/java/webclient/classes_spec/org/mozilla/webclient/overview.html @@ -0,0 +1,48 @@ + + + + + + +The API Javadocs for the Webclient specification.
+ +Brief usage available in the package docs for the
+org.mozilla.webclient package. Detailed usage instructions
+are available at http://www.mozilla.org/projects/blackwood/webclient/#Using.
The Webclient public API.
+ +The first Webclient public API call in the application must be {@link
+org.mozilla.webclient.BrowserControlFactory#setAppData}. If embedding a
+native browser, the argument must be the fully qualified path name of
+the binary directory for the browser. If embedding a non-native
+browser, null must be passed to this method. This method
+must be called once and only once.
For browsers that support the concept of "profiles" it must be
+possible to set the current profile used for this browsing session by
+calling {@link org.mozilla.webclient.BrowserControlFactory#setProfile}.
+This call must be made before the first BrowserControl
+instance is created. If not specified, the "webclient"
+profile is used to avoid overwriting any settings in the user's
+profile.
Upon from return from
+BrowserControlFactory.setAppData(), {@link
+org.mozilla.webclient.BrowserControlFactory#newBrowserControl} may be
+used to create one or more web browser instances. The returned {@link
+org.mozilla.webclient.BrowserControl} may then be queried, via {@link
+org.mozilla.webclient.BrowserControl#queryInterface} for additional
+features.
When the application is done with a BrowserControl
+instance, it must pass the instance to {@link
+org.mozilla.webclient.BrowserControlFactory#deleteBrowserControl}.
When the application no longer needs the Webclient API, it must call +{@link +org.mozilla.webclient.BrowserControlFactory#appTerminate}.
+ + +