bug 342640: Ability to create build console dynamically

core/org.eclipse.cdt.core/src/org/eclipse/cdt/core/CCorePlugin.java

@@ -16,6 +16,7 @@
 package org.eclipse.cdt.core;
 
 import java.io.IOException;
+import java.net.URL;
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.HashSet;
@@ -45,6 +46,7 @@ import org.eclipse.cdt.core.settings.model.util.CDataUtil;
 import org.eclipse.cdt.internal.core.CContentTypes;
 import org.eclipse.cdt.internal.core.CDTLogWriter;
 import org.eclipse.cdt.internal.core.CdtVarPathEntryVariableManager;
+import org.eclipse.cdt.internal.core.ICConsole;
 import org.eclipse.cdt.internal.core.PositionTrackerManager;
 import org.eclipse.cdt.internal.core.cdtvariables.CdtVariableManager;
 import org.eclipse.cdt.internal.core.cdtvariables.UserVarSupplier;
@@ -201,11 +203,10 @@ public class CCorePlugin extends Plugin {
 	private static CCorePlugin fgCPlugin;
 	private static ResourceBundle fgResourceBundle;
 
-
 	/**
 	 * @noreference This field is not intended to be referenced by clients.
 	 */
-    public CDTLogWriter cdtLog = null;
+	public CDTLogWriter cdtLog = null;
 
 	private volatile CProjectDescriptionManager fNewCProjectDescriptionManager;
 
@@ -214,6 +215,31 @@ public class CCorePlugin extends Plugin {
 	private PDOMManager pdomManager;
 
 	private CdtVarPathEntryVariableManager fPathEntryVariableManager;
+	
+	private final class NullConsole implements IConsole {
+		private ConsoleOutputStream nullStream = new ConsoleOutputStream() {
+			@Override
+			public void write(byte[] b) throws IOException {
+			}
+			@Override
+			public void write(byte[] b, int off, int len) throws IOException {
+			}
+			@Override
+			public void write(int c) throws IOException {
+			}
+		};
+		public void start(IProject project) {
+		}
+		public ConsoleOutputStream getOutputStream() {
+			return nullStream;
+		}
+		public ConsoleOutputStream getInfoStream() {
+			return nullStream; 
+		}
+		public ConsoleOutputStream getErrorStream() {
+			return nullStream;
+		}
+	}
 
 	// -------- static methods --------
 
@@ -482,17 +508,42 @@ public class CCorePlugin extends Plugin {
     }    
     
 
-	public IConsole getConsole(String id) {
+	/**
+	 * Create CDT console adapter for build console defined as an extension.
+	 * See {@code org.eclipse.cdt.core.CBuildConsole} extension point.
+	 * If the console class is instance of {@link ICConsole} it is initialized
+	 * with context id, name and icon to be shown in the list of consoles in the
+	 * Console view.
+	 * 
+	 * @param extConsoleId - console id defined in the extension point.
+	 * @param contextId - context menu id in the Console view. A caller needs to define
+	 *    a distinct one for own use.
+	 * @param name - name of console to appear in the list of consoles in context menu
+	 *    in the Console view.
+	 * @param iconUrl - a {@link URL} of the icon for the context menu of the Console
+	 *    view. The url is expected to point to an image in eclipse OSGi bundle.
+	 *    Here is an example how to retrieve URL:<br/>
+	 *    <code>
+	 *    URL iconUrl = CUIPlugin.getDefault().getBundle().getResource("icons/obj16/flask.png");
+	 *    </code>
+	 * 
+	 * @return CDT console adapter.
+	 */
+	private IConsole getConsole(String extConsoleId, String contextId, String name, URL iconUrl) {
 		try {
-	        IExtensionPoint extension = Platform.getExtensionRegistry().getExtensionPoint(CCorePlugin.PLUGIN_ID, "CBuildConsole"); //$NON-NLS-1$
+			IExtensionPoint extensionPoint = Platform.getExtensionRegistry().getExtensionPoint(CCorePlugin.PLUGIN_ID, "CBuildConsole"); //$NON-NLS-1$
-			if (extension != null) {
+			if (extensionPoint != null) {
-				IExtension[] extensions = extension.getExtensions();
+				IExtension[] extensions = extensionPoint.getExtensions();
-				for (IExtension extension2 : extensions) {
+				for (IExtension extension : extensions) {
-					IConfigurationElement[] configElements = extension2.getConfigurationElements();
+					IConfigurationElement[] configElements = extension.getConfigurationElements();
 					for (IConfigurationElement configElement : configElements) {
 						String consoleID = configElement.getAttribute("id"); //$NON-NLS-1$
-						if ((id == null && consoleID == null) || (id != null && id.equals(consoleID))) {
+						if ((extConsoleId == null && consoleID == null) || (extConsoleId != null && extConsoleId.equals(consoleID))) {
-							return (IConsole) configElement.createExecutableExtension("class"); //$NON-NLS-1$
+							IConsole console = (IConsole) configElement.createExecutableExtension("class"); //$NON-NLS-1$
+							if (console instanceof ICConsole) {
+								((ICConsole) console).init(contextId, name, iconUrl);
+							}
+							return console;
 						}
 					}
 				}
@@ -500,34 +551,52 @@ public class CCorePlugin extends Plugin {
 		} catch (CoreException e) {
 			log(e);
 		}
-		return new IConsole() { // return a null console
+		return new NullConsole();
-			private ConsoleOutputStream nullStream = new ConsoleOutputStream() {
-			    @Override
-				public void write(byte[] b) throws IOException {
-			    }			    
-				@Override
-				public void write(byte[] b, int off, int len) throws IOException {
-				}					
-				@Override
-				public void write(int c) throws IOException {
-				}
-			};
-			
-			public void start(IProject project) {
-			}
-		    // this can be a null console....
-			public ConsoleOutputStream getOutputStream() {
-				return nullStream;
-			}
-			public ConsoleOutputStream getInfoStream() {
-				return nullStream; 
-			}
-			public ConsoleOutputStream getErrorStream() {
-				return nullStream;
-			}
-		};
 	}
 
+	/**
+	 * Create CDT console adapter.
+	 * The adapter serves as a bridge between core plugin and UI console API in a way that
+	 * a user can create a UI console from plugins having no dependencies to UI.
+	 *  
+	 * @param id - id of the console specified in extension point to instantiate
+	 *    console adapter.
+	 * @return CDT console adapter.
+	 */
+	public IConsole getConsole(String id) {
+		return getConsole(id, null, null, null);
+	}
+
+	/**
+	 * Create CDT console adapter for build console. A new instance of class
+	 * {@code org.eclipse.cdt.internal.ui.buildconsole.CBuildConsole} is created
+	 * and initialized with the parameters.
+	 * 
+	 * @param contextId - context menu id in the Console view. A caller needs to define
+	 *    a distinct one for own use.
+	 * @param name - name of console to appear in the list of consoles in context menu
+	 *    in the Console view.
+	 * @param iconUrl - a {@link URL} of the icon for the context menu of the Console
+	 *    view. The url is expected to point to an image in eclipse OSGi bundle.
+	 *    Here is an example how to retrieve URL:<br/>
+	 *    <code>
+	 *    URL iconUrl = CUIPlugin.getDefault().getBundle().getResource("icons/obj16/flask.png");
+	 *    </code>
+	 *    <br/>
+	 *    {@code iconUrl} can be <b>null</b>, in that case the default image is used.
+	 *    See {@code org.eclipse.cdt.internal.ui.buildconsole.BuildConsole(IBuildConsoleManager, String, String, URL)}
+	 * 
+	 * @return CDT console adapter.
+	 * 
+	 * @since 5.3
+	 */
+	public IConsole getBuildConsole(String contextId, String name, URL iconUrl) {
+		return getConsole(null, contextId, name, iconUrl);
+	}
+
+	/**
+	 * Create CDT console adapter connected to the default build console.
+	 */
 	public IConsole getConsole() {
 		String consoleID = System.getProperty("org.eclipse.cdt.core.console"); //$NON-NLS-1$
 		return getConsole(consoleID);

core/org.eclipse.cdt.core/src/org/eclipse/cdt/core/resources/IConsole.java

@@ -10,16 +10,23 @@
  *******************************************************************************/
 package org.eclipse.cdt.core.resources;
 
-
 import org.eclipse.cdt.core.ConsoleOutputStream;
 import org.eclipse.core.resources.IProject;
 import org.eclipse.core.runtime.CoreException;
 
-
+/**
+ * CDT console adaptor interface providing output streams.
+ * The adaptor provides the means of access to UI plugin console streams.
+ */
 public interface IConsole {
+	/**
+	 * Start the console for a given project.
+	 * 
+	 * @param project - the project to start the console.
+	 */
 	void start(IProject project);
-    ConsoleOutputStream getOutputStream() throws CoreException;
-    ConsoleOutputStream getInfoStream() throws CoreException;
-    ConsoleOutputStream getErrorStream() throws CoreException;
-}
 
+	ConsoleOutputStream getOutputStream() throws CoreException;
+	ConsoleOutputStream getInfoStream() throws CoreException;
+	ConsoleOutputStream getErrorStream() throws CoreException;
+}

core/org.eclipse.cdt.core/src/org/eclipse/cdt/internal/core/ICConsole.java

@@ -0,0 +1,35 @@
+/*******************************************************************************
+ * Copyright (c) 2011 Andrew Gvozdev and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *     Andrew Gvozdev - Initial API and implementation
+ *******************************************************************************/
+package org.eclipse.cdt.internal.core;
+
+import java.net.URL;
+
+import org.eclipse.cdt.core.resources.IConsole;
+
+/**
+ * Extension of CDT console adaptor interface to UI plugin console. This extension
+ * provides control over context id, name and icon in the Console view.
+ */
+public interface ICConsole extends IConsole {
+	/**
+	 * Initialize console with user-controlled context, name and icon
+	 * in "Display Selected Console" dropbox in the Console view.
+	 * 
+	 * @param contextId - context menu id in the Console view. A caller needs to define
+	 *    a distinct one for own use.
+	 * @param name - name of console to appear in the list of consoles in context menu
+	 *    in the Console view.
+	 * @param iconUrl - a {@link URL} of the icon for the context menu of the Console
+	 *    view. The url is expected to point to an image in eclipse OSGi bundle.
+	 *    {@code iconUrl} can be <b>null</b>, in that case the default image is supposed to be used.
+	 */
+	void init(String contextId, String name, URL iconUrl);
+}

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/buildconsole/BuildConsole.java

@@ -13,6 +13,8 @@
  *******************************************************************************/
 package org.eclipse.cdt.internal.ui.buildconsole;
 
+import java.net.URL;
+
 import org.eclipse.core.resources.IProject;
 import org.eclipse.swt.graphics.Color;
 import org.eclipse.ui.console.AbstractConsole;
@@ -24,6 +26,10 @@ import org.eclipse.cdt.ui.CDTSharedImages;
 import org.eclipse.cdt.ui.CUIPlugin;
 import org.eclipse.cdt.ui.IBuildConsoleManager;
 
+/**
+ * CDT Build console.
+ *
+ */
 public class BuildConsole extends AbstractConsole {
 
 	/**
@@ -47,11 +53,38 @@ public class BuildConsole extends AbstractConsole {
 	private String fConsoleId;
 	private Color fBackground;
 
-	public BuildConsole(IBuildConsoleManager manager, String name, String id) {
+	/**
+	 * Constructor.
+	 * 
+	 * @param manager - build console manager.
+	 * @param name - name of console to appear in the list of consoles in context menu
+	 *    in the Console view.
+	 * @param contextId - context menu id in the Console view.
+	 */
+	public BuildConsole(IBuildConsoleManager manager, String name, String contextId) {
+		this(manager, name, contextId, null);
+	}
+
+	/**
+	 * Constructor.
+	 * 
+	 * @param manager - build console manager.
+	 * @param name - name of console to appear in the list of consoles in context menu
+	 *    in the Console view.
+	 * @param contextId - context menu id in the Console view.
+	 * @param iconUrl - a {@link URL} of the icon for the context menu of the Console
+	 *    view. The url is expected to point to an image in eclipse OSGi bundle.
+	 *    {@code iconUrl} can be <b>null</b>, in that case the default image is used.
+	 */
+	public BuildConsole(IBuildConsoleManager manager, String name, String contextId, URL iconUrl) {
 		super(name, CDTSharedImages.getImageDescriptor(CDTSharedImages.IMG_VIEW_BUILD_CONSOLE));
+		if (iconUrl!=null) {
+			CDTSharedImages.register(iconUrl);
+			this.setImageDescriptor(CDTSharedImages.getImageDescriptor(iconUrl.toString()));
+		}
 		fConsoleManager = manager;
 		fConsoleName = name;
-		fConsoleId = id;
+		fConsoleId = contextId;
 	}
 
 	public IPageBookViewPage createPage(IConsoleView view) {

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/buildconsole/BuildConsoleManager.java

@@ -13,6 +13,7 @@
  *******************************************************************************/
 package org.eclipse.cdt.internal.ui.buildconsole;
 
+import java.net.URL;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -238,12 +239,12 @@ public class BuildConsoleManager implements IBuildConsoleManager, IResourceChang
 		}
 	}
 
-	public void startup(String name, String id) {
+	public void startup(String name, String contextId, final URL iconUrl) {
 		infoStream = new BuildConsoleStreamDecorator();
 		outputStream = new BuildConsoleStreamDecorator();
 		errorStream = new BuildConsoleStreamDecorator();
 		fName = name;
-		fContextMenuId = id;
+		fContextMenuId = contextId;
 
 		runUI(new Runnable() {
 
@@ -255,7 +256,7 @@ public class BuildConsoleManager implements IBuildConsoleManager, IResourceChang
 			public void run() {
 				// install colors
 				fGlobalConsole = new GlobalBuildConsole(BuildConsoleManager.this, fName, null);
-				fConsole = new BuildConsole(BuildConsoleManager.this, fName, fContextMenuId);
+				fConsole = new BuildConsole(BuildConsoleManager.this, fName, fContextMenuId, iconUrl);
 				ConsolePlugin.getDefault().getConsoleManager().addConsoles(new org.eclipse.ui.console.IConsole[]{fGlobalConsole, fConsole});
 				infoStream.setConsole(fConsole);
 				infoColor = createColor(CUIPlugin.getStandardDisplay(), BuildConsolePreferencePage.PREF_BUILDCONSOLE_INFO_COLOR);

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/internal/ui/buildconsole/CBuildConsole.java

@@ -10,14 +10,22 @@
  *******************************************************************************/
 package org.eclipse.cdt.internal.ui.buildconsole;
 
-import org.eclipse.cdt.core.ConsoleOutputStream;
+import java.net.URL;
-import org.eclipse.cdt.core.resources.IConsole;
+
-import org.eclipse.cdt.ui.CUIPlugin;
-import org.eclipse.cdt.ui.IBuildConsoleManager;
 import org.eclipse.core.resources.IProject;
 import org.eclipse.core.runtime.CoreException;
 
-public class CBuildConsole implements IConsole {
+import org.eclipse.cdt.core.ConsoleOutputStream;
+import org.eclipse.cdt.ui.CUIPlugin;
+import org.eclipse.cdt.ui.IBuildConsoleManager;
+
+import org.eclipse.cdt.internal.core.ICConsole;
+
+/**
+ * CDT console adaptor providing output streams. The adaptor provides means of
+ * access to UI plugin console.
+ */
+public class CBuildConsole implements ICConsole {
 	IProject project;
 	IBuildConsoleManager fConsoleManager;
 	
@@ -25,10 +33,21 @@ public class CBuildConsole implements IConsole {
 	 * Constructor for BuildConsole.
 	 */
 	public CBuildConsole() {
-		fConsoleManager = CUIPlugin.getDefault().getConsoleManager();
 	}
 
-	public void start(IProject project ) {
+	public void init(String contextId, String name, URL iconUrl) {
+		if (contextId==null)
+			fConsoleManager = CUIPlugin.getDefault().getConsoleManager();
+		else
+			fConsoleManager = CUIPlugin.getDefault().getConsoleManager(name, contextId, iconUrl); // careful with order of arguments
+	}
+
+	/**
+	 * Start the console for a given project.
+	 * 
+	 * @param project - the project to start the console.
+	 */
+	public void start(IProject project) {
 		this.project = project;
 		fConsoleManager.getConsole(project).start(project);
 	}

core/org.eclipse.cdt.ui/src/org/eclipse/cdt/ui/CUIPlugin.java

@@ -16,6 +16,7 @@
 package org.eclipse.cdt.ui;
 
 import java.io.IOException;
+import java.net.URL;
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.HashSet;
@@ -481,17 +482,39 @@ public class CUIPlugin extends AbstractUIPlugin {
 	}
 
 	/**
-	 * Return a console manager specified by id.
+	 * Obtain a console manager with the given id. If a manager has not been created yet,
-	 * @param name console name
+	 * it is created and its console created and activated.
-	 * @param id console id
+	 * 
-	 * @return IBuildConsoleManager
+	 * @param name - console name.
-	 */	
+	 * @param contextId - console id matching context id in the Console view dropdown.
-	public IBuildConsoleManager getConsoleManager(String name, String id) {
+	 * @return console manager.
-		BuildConsoleManager manager = fBuildConsoleManagers.get(id);
+	 * 
+	 * Note that this method is rather internal and should not be referenced by clients.
+	 * To create a build console, use {@link CCorePlugin#getBuildConsole(String, String, URL)}
+	 */
+	public IBuildConsoleManager getConsoleManager(String name, String contextId) {
+		return getConsoleManager(name, contextId, null);
+	}
+
+	/**
+	 * Obtain a console manager with the given id. If a manager has not been created yet,
+	 * it is created and its console created and activated with the given attributes.
+	 * 
+	 * @param name - console name.
+	 * @param contextId - console id matching context id in the Console view dropdown.
+	 * @param iconUrl - a {@link URL} of the icon for the context menu of the Console
+	 *    view. The url is expected to point to an image in eclipse OSGi bundle.
+	 *    {@code iconUrl} can be <b>null</b>, in that case the default image is used.
+	 * @return console manager.
+	 * 
+	 * @noreference This method is not intended to be referenced by clients.
+	 */
+	public IBuildConsoleManager getConsoleManager(String name, String contextId, URL iconUrl) {
+		BuildConsoleManager manager = fBuildConsoleManagers.get(contextId);
 		if (manager == null ) {
 			manager = new BuildConsoleManager();
-			fBuildConsoleManagers.put(id, manager);
+			fBuildConsoleManagers.put(contextId, manager);
-			manager.startup(name, id);
+			manager.startup(name, contextId, iconUrl);
 		}
 		return manager;
 	}