console API cleanup

3 files changed, 63 insertions, 32 deletions

diff --git a/org.eclipse.ui.console/src/org/eclipse/ui/console/IConsoleManager.java b/org.eclipse.ui.console/src/org/eclipse/ui/console/IConsoleManager.java
index 634ad3484..31fcee3ea 100644
--- a/org.eclipse.ui.console/src/org/eclipse/ui/console/IConsoleManager.java
+++ b/org.eclipse.ui.console/src/org/eclipse/ui/console/IConsoleManager.java
@@ -92,6 +92,7 @@ public interface IConsoleManager {
 	 * 
 	 * @param console the console for which pattern match listeners are requested
 	 * @return a collection of new pattern match listeners
+     * @see IPatternMatchListener
 	 * @since 3.1
 	 */
 	public IPatternMatchListener[] createPatternMatchListeners(IConsole console);
diff --git a/org.eclipse.ui.console/src/org/eclipse/ui/console/IPatternMatchListener.java b/org.eclipse.ui.console/src/org/eclipse/ui/console/IPatternMatchListener.java
index 927575a77..8d47365ff 100644
--- a/org.eclipse.ui.console/src/org/eclipse/ui/console/IPatternMatchListener.java
+++ b/org.eclipse.ui.console/src/org/eclipse/ui/console/IPatternMatchListener.java
@@ -11,14 +11,48 @@
 package org.eclipse.ui.console;
 
 /**
- * A pattern match listener is registered with an <code>IOConsole</code>,
- * and is notified when its pattern has been matched to the contents in
- * that console.
- * 
- * @see org.eclipse.ui.console.IOConsole
+ * A pattern match listener is registered with a <code>TextConsole</code>,
+ * and is notified when its pattern has been matched to contents in
+ * that console. A pattern match listener can be registered with a console
+ * programmatically or via the <code>consolePatternMatchListeners</code> extension
+ * point.
+ * <p>
+ * Following is an example console pattern match listener extension definition.
+ * </pre>
+ * &lt;extension point="org.eclipse.ui.console.consolePatternMatchListeners"&gt;
+ *   &lt;consolePatternMatchListener
+ *      id="com.example.ConsolePatternMatcher"
+ *      regex=".*foo.*"
+ *      class="com.example.ConsolePatternMatcher"&gt;
+ *   &lt;/consolePatternMatchListener&gt;
+ * &lt;/extension&gt;
+ * </pre>
+ * Attributes are specified as follows:
+ * <ul>
+ * <li><code>id</code> - a unique identifier for the pattern match listener</li>
+ * <li><code>regex</code> - regular expression to match</li>
+ * <li><code>class</code> - fully qualified name of the Java class implementing
+ *  <code>org.eclipse.ui.console.IPatternMatchListenerDelegate</code></li>
+ * </ul>
+ * </p> 
+ * <p>
+ * Optionally a <code>qualifier</code> attribute may be specified to improve performance
+ * of regular expression matching. A qualifier specifies a simple regular expression used to
+ * qualify lines for the search. Lines that do not contain the qualifier are not considered.
+ * </p>
+ * <p>
+ * Optionally an <code>enablement</code> expression may be provided to specify
+ * which console(s) a pattern matcher should be contributed to.
+ * </p>
+ * <p>
+ * Clients may implement this interface directly if registering a pattern match listener with
+ * a text console programmatically. Clients contributing a pattern match listener via an
+ * extension implement <code>IPatternMatchListenerDelegate</code> instead.
+ * </p>
+ * @see org.eclipse.ui.console.TextConsole
  * @since 3.1
  */
-public interface IPatternMatchListener {
+public interface IPatternMatchListener extends IPatternMatchListenerDelegate {
     /**
      * Returns the pattern to be used for matching. The pattern is
      * a string representing a regular expression. 
@@ -28,8 +62,12 @@ public interface IPatternMatchListener {
     public String getPattern();
     
     /**
-     * Returns an int to be used by <code>Pattern.compile(String regex, int flags)</code>
-     * @return
+     * Returns the flags to use when compiling this pattern match listener's
+     * regular expression, as defined by by <code>Pattern.compile(String regex, int flags)</code>
+     * 
+     * @return the flags to use when compiling this pattern match listener's
+     * regular expression
+     * @see java.util.regex.Pattern#compile(java.lang.String, int)
      */
     public int getCompilerFlags();
     
@@ -39,30 +77,11 @@ public interface IPatternMatchListener {
      * Use of this attribute can improve performance by disqualifying lines
      * from the search. When a line is found containing a match for this expression,
      * the line is searched from the beginning for this pattern matcher's
-     * complete pattern.
+     * complete pattern. Lines not containing this pattern are discarded.
      * 
      * @return a simple regular expression used to identify lines that may
      * match this pattern matcher's complete pattern, or <code>null</code>
      */
     public String getLineQualifier();
-        
-    /**
-     * Notification that a match has been found.
-     * 
-     * @param event event describing where the match was found
-     */
-
-    public void matchFound(PatternMatchEvent event);
-
-    /**
-     * Connects this PatternMatchListener to the console
-     * @param console The console this Listener is attached to
-     */
-    public void connect(IConsole console);
-    
-    /**
-     * Disconnects this PatternMatchListener from the console
-     */
-    public void disconnect();
     
 }
diff --git a/org.eclipse.ui.console/src/org/eclipse/ui/console/IPatternMatchListenerDelegate.java b/org.eclipse.ui.console/src/org/eclipse/ui/console/IPatternMatchListenerDelegate.java
index ab8d7863c..8a3ab15b3 100644
--- a/org.eclipse.ui.console/src/org/eclipse/ui/console/IPatternMatchListenerDelegate.java
+++ b/org.eclipse.ui.console/src/org/eclipse/ui/console/IPatternMatchListenerDelegate.java
@@ -11,18 +11,29 @@
 package org.eclipse.ui.console;
 
 /**
- * @see org.eclipse.ui.console.IOConsole
+ * A pattern match listener delegate is notified of regular expression matches
+ * in a <code>TextConsole</code>. A delegate is contributed via the
+ * <code>consolePatternMatcherListeners</code> extension point.
+ * <p>
+ * Clients contributing a console pattern match listener extension are intended
+ * to implement this interface.
+ * </p>
+ * @see org.eclipse.ui.console.IPatternMatchListener
+ * @see org.eclipse.ui.console.TextConsole
  * @since 3.1
  */
 public interface IPatternMatchListenerDelegate {
     /**
-     * Connects the delegate to the console being monitored
-     * @param console the console being monitored
+     * Notification that pattern matching will begin in the specified console.
+     * A pattern matcher is connected to only one console at a time.
+     * 
+     * @param console the console in which pattern matching will be performed
      */
     public void connect(IConsole console);
     
     /**
-     * Disconnects the delegate from the console
+     * Notification that pattern matching has been completed in the console
+     * this delegate was last connected to.
      */
     public void disconnect();