467045: Connectors can register different brandings

Change-Id: Ibf2872214ec3d314dd09cf3c04368eac7f7168da
Task-Url: https://bugs.eclipse.org/bugs/show_bug.cgi?id=467045

2 files changed, 85 insertions, 8 deletions

diff --git a/org.eclipse.mylyn.tasks.core/src/org/eclipse/mylyn/internal/tasks/core/ITasksCoreConstants.java b/org.eclipse.mylyn.tasks.core/src/org/eclipse/mylyn/internal/tasks/core/ITasksCoreConstants.java
index 284a3c351..e38d2d24e 100644
--- a/org.eclipse.mylyn.tasks.core/src/org/eclipse/mylyn/internal/tasks/core/ITasksCoreConstants.java
+++ b/org.eclipse.mylyn.tasks.core/src/org/eclipse/mylyn/internal/tasks/core/ITasksCoreConstants.java
@@ -71,6 +71,8 @@ public interface ITasksCoreConstants {
 	@Deprecated
 	public static final String PROPERTY_USE_SECURE_STORAGE = "org.eclipse.mylyn.tasklist.repositories.configuration.securestorage"; //$NON-NLS-1$
 
+	public static final String PROPERTY_BRAND_ID = "org.eclipse.mylyn.brand.id"; //$NON-NLS-1$
+
 	/**
 	 * Jobs that have the same instances of this rule set are mutually exclusive.
 	 */
diff --git a/org.eclipse.mylyn.tasks.core/src/org/eclipse/mylyn/tasks/core/spi/RepositoryConnectorBranding.java b/org.eclipse.mylyn.tasks.core/src/org/eclipse/mylyn/tasks/core/spi/RepositoryConnectorBranding.java
index 64f659a8a..f18f44158 100644
--- a/org.eclipse.mylyn.tasks.core/src/org/eclipse/mylyn/tasks/core/spi/RepositoryConnectorBranding.java
+++ b/org.eclipse.mylyn.tasks.core/src/org/eclipse/mylyn/tasks/core/spi/RepositoryConnectorBranding.java
@@ -13,15 +13,18 @@ package org.eclipse.mylyn.tasks.core.spi;
 
 import java.io.IOException;
 import java.io.InputStream;
+import java.util.List;
 
 import org.eclipse.core.runtime.IAdapterFactory;
 import org.eclipse.jdt.annotation.NonNull;
+import org.eclipse.jdt.annotation.Nullable;
 import org.eclipse.mylyn.tasks.core.AbstractRepositoryConnector;
 
+import com.google.common.collect.ImmutableList;
+
 /**
- * Specifies branding for a connector that is registered as runtime using {@link RepositoryConnectorContributor}. The
- * branding extension is obtained by adapting an {@link AbstractRepositoryConnector} instance to
- * {@link RepositoryConnectorBranding}.
+ * Specifies branding for a connector. The branding extension is obtained by adapting an
+ * {@link AbstractRepositoryConnector} instance to {@link RepositoryConnectorBranding}.
  * <p>
  * To contribute branding clients need to register an {@link IAdapterFactory} for the type
  * {@link AbstractRepositoryConnector}.
@@ -81,8 +84,12 @@ import org.eclipse.mylyn.tasks.core.AbstractRepositoryConnector;
 public abstract class RepositoryConnectorBranding {
 
 	/**
-	 * Returns an input stream with the image data for a 16x16 branding icon. This is typically shown in the UI when
-	 * selecting connectors. Supported file formats are GIF and PNG.
+	 * Returns an input stream with the image data for a 16x16 branding icon, for a connector that is registered at
+	 * runtime using {@link RepositoryConnectorContributor}. This is typically shown in the UI when selecting
+	 * connectors. Supported file formats are GIF and PNG.
+	 * <p>
+	 * Note: for connectors contributed through the <code>org.eclipse.mylyn.tasks.ui.repositories</code> extension
+	 * point, the branding image specified in the extension takes precedence; this method is never called.
 	 * 
 	 * @return input stream for image data
 	 * @throws IOException
@@ -92,9 +99,12 @@ public abstract class RepositoryConnectorBranding {
 	public abstract InputStream getBrandingImageData() throws IOException;
 
 	/**
-	 * Returns an input stream with the image data for a 7x8 overlay branding icon. This is typically a very small
-	 * version of the branding icon that is used for overlays over repository icons. Supported file formats are GIF and
-	 * PNG.
+	 * Returns an input stream with the image data for a 7x8 overlay branding icon, for a connector that is registered
+	 * at runtime using {@link RepositoryConnectorContributor}. This is typically a very small version of the branding
+	 * icon that is used for overlays over repository icons. Supported file formats are GIF and PNG.
+	 * <p>
+	 * Note: for connectors contributed through the <code>org.eclipse.mylyn.tasks.ui.repositories</code> extension
+	 * point, the overlay image specified in the extension takes precedence; this method is never called.
 	 * 
 	 * @return input stream for image data
 	 * @throws IOException
@@ -103,4 +113,69 @@ public abstract class RepositoryConnectorBranding {
 	@NonNull
 	public abstract InputStream getOverlayImageData() throws IOException;
 
+	/**
+	 * Returns a list of identifiers of the brands supported by this connector. This is useful for connectors that can
+	 * connect to different brands of the same system. Typically, different brands are functionally identical but use
+	 * different labels and icons.
+	 * <p>
+	 * Each brand may be presented in the UI as though it were a separate connector.
+	 * 
+	 * @since 3.16
+	 */
+	@NonNull
+	public List<String> getBrands() {
+		return ImmutableList.of();
+	}
+
+	/**
+	 * Returns branding image data for a specific brand of the target system. Returns <code>null</code> if the given
+	 * brand is unknown to the connector or uses the {@link #getBrandingImageData() default branding image}. The default
+	 * implementation always returns <code>null</code>.
+	 * 
+	 * @return input stream for image data, or <code>null</code>
+	 * @throws IOException
+	 *             thrown if opening of the stream fails
+	 * @see #getBrandingImageData()
+	 * @see #getBrands()
+	 * @since 3.16
+	 */
+	@Nullable
+	public InputStream getBrandingImageData(@NonNull String brand) throws IOException {
+		return null;
+	}
+
+	/**
+	 * Returns overlay image data for a specific brand of the target system. Returns <code>null</code> if the given
+	 * brand is unknown to the connector or uses the {@link #getOverlayImageData() default overlay image}. The default
+	 * implementation always returns <code>null</code>.
+	 * 
+	 * @param brand
+	 * @throws IOException
+	 *             thrown if opening of the stream fails
+	 * @return
+	 * @see #getOverlayImageData()
+	 * @see #getBrands()
+	 * @since 3.16
+	 */
+	@Nullable
+	public InputStream getOverlayImageData(@NonNull String brand) throws IOException {
+		return null;
+	}
+
+	/**
+	 * Returns the connector label to use for a specific brand of the target system. Returns <code>null</code> if the
+	 * given brand is unknown to the connector or uses the {@link AbstractRepositoryConnector#getLabel() default
+	 * connector label}. The default implementation always returns <code>null</code>.
+	 * 
+	 * @param brand
+	 * @return
+	 * @see AbstractRepositoryConnector#getLabel()
+	 * @see #getBrands()
+	 * @since 3.16
+	 */
+	@Nullable
+	public String getConnectorLabel(@NonNull String brand) {
+		return null;
+	}
+
 }