Add Source Lookups preference page with ordering and external source locator for issue #2073

ISSUE_UI_SCREENSHOT_IMPROVEMENT.md

@@ -0,0 +1,49 @@
+# Improve UI screenshot generation for PR documentation
+
+## Problem
+
+The current approach to generating screenshots for UI components using Python/PIL produces white/blank images that don't accurately represent the Eclipse UI.
+
+## Proposed Solutions
+
+### 1. SWT Snippet Approach
+Create small SWT snippets that can render the UI components. However, this requires complex setup for many components that depend on Eclipse platform infrastructure.
+
+### 2. MCP Server with Eclipse Install (Recommended)
+Create a Model Context Protocol (MCP) server that includes a full Eclipse installation. This would allow:
+- Programmatic access to Eclipse UI components
+- Automated screenshot capture of actual rendered UI
+- Better representation of Eclipse styling and themes
+- Reusable infrastructure for future UI documentation
+
+## Context
+
+This issue was identified while implementing the Source Lookups preference page (see related PR for #2073). The generated screenshot using Python/PIL doesn't accurately show how the preference page would look in a real Eclipse environment.
+
+## Benefits of MCP Server Approach
+
+- **Accuracy**: Screenshots show actual Eclipse UI rendering with proper fonts, colors, and styling
+- **Reusability**: Can be used for all future UI-related PRs and documentation
+- **Automation**: Can be integrated into CI/CD pipeline for automatic screenshot generation
+- **Quality**: Better documentation quality improves contributor and user experience
+
+## Implementation Ideas
+
+1. Create a headless Eclipse installation in a container
+2. Build an MCP server that can:
+   - Launch Eclipse workbench programmatically
+   - Navigate to specific UI components (dialogs, preference pages, views, etc.)
+   - Capture screenshots using SWT/platform APIs
+   - Return screenshots as base64 or file paths
+3. Integrate with Copilot workflow for automatic screenshot generation
+
+## Labels
+
+- `enhancement`
+- `documentation`
+- `tooling`
+
+## Related
+
+- Source Lookups preference page PR
+- Issue #2073

ui/org.eclipse.pde.core/plugin.xml

@@ -430,6 +430,9 @@
           <locator
                 class="org.eclipse.pde.internal.core.LocalMavenPluginSourcePathLocator"
                 complexity="low"/>
+          <locator
+                class="org.eclipse.pde.internal.core.ExternalPluginSourcePathLocator"
+                complexity="high"/>
     </extension>
         <extension
               point="org.eclipse.pde.core.targetLocations">

ui/org.eclipse.pde.core/src/org/eclipse/pde/internal/core/ExternalPluginSourcePathLocator.java

@@ -0,0 +1,224 @@
+/*******************************************************************************
+ * Copyright (c) 2025 Christoph Läubrich and others.
+ *
+ * This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License 2.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *
+ * Contributors:
+ *     Christoph Läubrich - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.pde.internal.core;
+
+import java.io.File;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.Set;
+
+import org.eclipse.core.runtime.IPath;
+import org.eclipse.core.runtime.Platform;
+import org.eclipse.equinox.p2.metadata.Version;
+import org.eclipse.equinox.spi.p2.publisher.PublisherHelper;
+import org.eclipse.jface.preference.IPreferenceStore;
+import org.eclipse.pde.core.IPluginSourcePathLocator;
+import org.eclipse.pde.core.plugin.IPluginBase;
+import org.eclipse.pde.internal.core.copyfrom.oomph.P2Index;
+import org.eclipse.pde.internal.core.copyfrom.oomph.P2Index.Repository;
+import org.eclipse.pde.internal.core.copyfrom.oomph.P2IndexImpl;
+import org.eclipse.pde.internal.ui.IPreferenceConstants;
+import org.eclipse.pde.internal.ui.PDEPlugin;
+
+/**
+ * A plugin source path locator that queries external repositories and the
+ * Eclipse index for source bundles based on the configured preferences.
+ * <p>
+ * This locator checks the Source Lookups preference page settings and performs
+ * lookups according to the configured order.
+ * </p>
+ * 
+ * @since 3.17
+ */
+public class ExternalPluginSourcePathLocator implements IPluginSourcePathLocator {
+
+	// Source lookup strategy identifiers
+	private static final String STRATEGY_REPOSITORIES = "REPOSITORIES"; //$NON-NLS-1$
+	private static final String STRATEGY_TARGETS = "TARGETS"; //$NON-NLS-1$
+	private static final String STRATEGY_INDEX = "INDEX"; //$NON-NLS-1$
+	private static final String STRATEGY_SITES = "SITES"; //$NON-NLS-1$
+
+	private P2Index p2Index;
+
+	@Override
+	public IPath locateSource(IPluginBase plugin) {
+		IPreferenceStore store = PDEPlugin.getDefault().getPreferenceStore();
+
+		// Check if source lookup is enabled
+		if (!store.getBoolean(IPreferenceConstants.SOURCE_LOOKUP_ENABLED)) {
+			return null;
+		}
+
+		// Get the lookup order
+		List<String> lookupOrder = getLookupOrder(store);
+
+		// Execute lookups in the configured order
+		for (String strategy : lookupOrder) {
+			IPath result = null;
+			switch (strategy) {
+			case STRATEGY_REPOSITORIES:
+				result = searchInRepositories(plugin, getConfiguredRepositories(store));
+				break;
+			case STRATEGY_TARGETS:
+				result = searchInTargets(plugin, getSelectedTargets(store));
+				break;
+			case STRATEGY_INDEX:
+				result = queryEclipseIndex(plugin);
+				break;
+			case STRATEGY_SITES:
+				result = queryAvailableSoftwareSites(plugin);
+				break;
+			default:
+				// Unknown strategy, skip
+				break;
+			}
+
+			if (result != null) {
+				return result;
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Gets the configured lookup order from preferences.
+	 * 
+	 * @param store the preference store
+	 * @return the list of strategy identifiers in order
+	 */
+	private List<String> getLookupOrder(IPreferenceStore store) {
+		String order = store.getString(IPreferenceConstants.SOURCE_LOOKUP_ORDER);
+		if (order == null || order.trim().isEmpty()) {
+			// Use default order
+			return Arrays.asList(STRATEGY_REPOSITORIES, STRATEGY_TARGETS, STRATEGY_INDEX, STRATEGY_SITES);
+		}
+		return Arrays.asList(order.split(",")); //$NON-NLS-1$
+	}
+
+	/**
+	 * Searches for the source bundle in the configured repositories.
+	 * 
+	 * @param plugin       the plugin to locate sources for
+	 * @param repositories the list of repository URLs
+	 * @return the path to the source bundle or null if not found
+	 */
+	private IPath searchInRepositories(IPluginBase plugin, List<String> repositories) {
+		// TODO: Implement searching in configured repositories
+		// This will be implemented in a future step
+		return null;
+	}
+
+	/**
+	 * Searches for the source bundle in the specified target platforms.
+	 * 
+	 * @param plugin          the plugin to locate sources for
+	 * @param selectedTargets the list of selected target platform names
+	 * @return the path to the source bundle or null if not found
+	 */
+	private IPath searchInTargets(IPluginBase plugin, List<String> selectedTargets) {
+		// TODO: Implement searching in selected target platforms
+		// This will be implemented in a future step
+		return null;
+	}
+
+	/**
+	 * Queries the Eclipse index for the source bundle.
+	 * 
+	 * @param plugin the plugin to locate sources for
+	 * @return the path to the source bundle or null if not found
+	 */
+	private IPath queryEclipseIndex(IPluginBase plugin) {
+		try {
+			// Lazy initialization of P2Index
+			if (p2Index == null) {
+				File indexCacheDir = new File(Platform.getStateLocation(PDECore.getDefault().getBundle()).toFile(),
+						"index"); //$NON-NLS-1$
+				p2Index = new P2IndexImpl(indexCacheDir);
+			}
+
+			String pluginId = plugin.getId();
+			String sourcePluginId = pluginId + ".source"; //$NON-NLS-1$
+
+			// Query the index for the source bundle using OSGi bundle capability
+			Map<Repository, Set<Version>> repositories = p2Index
+					.lookupCapabilities(PublisherHelper.CAPABILITY_NS_OSGI_BUNDLE, sourcePluginId);
+
+			if (repositories != null && !repositories.isEmpty()) {
+				// Find the repository with the matching version
+				String pluginVersion = plugin.getVersion();
+				for (Entry<Repository, Set<Version>> entry : repositories.entrySet()) {
+					for (Version version : entry.getValue()) {
+						if (version.toString().equals(pluginVersion)) {
+							// Found matching source bundle in the index
+							// The repository location is available but actual download/resolution
+							// would require P2 repository manager which is not available in this context
+							// For now, log the finding and return null (to be implemented with P2 integration)
+							PDECore.log("Found source bundle " + sourcePluginId + " version " + version //$NON-NLS-1$ //$NON-NLS-2$
+									+ " in repository " + entry.getKey().getLocation()); //$NON-NLS-1$
+							// TODO: Implement actual artifact resolution and download from the repository
+							return null;
+						}
+					}
+				}
+			}
+		} catch (Exception e) {
+			// Log but don't fail - this is just one lookup strategy
+			PDECore.log(e);
+		}
+		return null;
+	}
+
+	/**
+	 * Queries available software sites for the source bundle.
+	 * 
+	 * @param plugin the plugin to locate sources for
+	 * @return the path to the source bundle or null if not found
+	 */
+	private IPath queryAvailableSoftwareSites(IPluginBase plugin) {
+		// TODO: Implement querying available software sites
+		// This will be implemented in a future step
+		return null;
+	}
+
+	/**
+	 * Gets the list of selected target platform names from preferences.
+	 * 
+	 * @param store the preference store
+	 * @return the list of selected target names
+	 */
+	private List<String> getSelectedTargets(IPreferenceStore store) {
+		String selectedTargets = store.getString(IPreferenceConstants.SOURCE_LOOKUP_SELECTED_TARGETS);
+		if (selectedTargets == null || selectedTargets.trim().isEmpty()) {
+			return List.of();
+		}
+		return Arrays.asList(selectedTargets.split(",")); //$NON-NLS-1$
+	}
+
+	/**
+	 * Gets the list of configured repository URLs from preferences.
+	 * 
+	 * @param store the preference store
+	 * @return the list of repository URLs
+	 */
+	private List<String> getConfiguredRepositories(IPreferenceStore store) {
+		String repositories = store.getString(IPreferenceConstants.SOURCE_LOOKUP_REPOSITORIES);
+		if (repositories == null || repositories.trim().isEmpty()) {
+			return List.of();
+		}
+		return Arrays.asList(repositories.split(",")); //$NON-NLS-1$
+	}
+}

ui/org.eclipse.pde.core/src/org/eclipse/pde/internal/core/copyfrom/oomph/P2Index.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2014, 2016 Eike Stepper (Loehne, Germany) and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v2.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v20.html
+ *
+ * Contributors:
+ *    Eike Stepper - initial API and implementation
+ */
+package org.eclipse.pde.internal.core.copyfrom.oomph;
+
+import java.util.Map;
+import java.util.Set;
+
+import org.eclipse.emf.common.util.URI;
+import org.eclipse.equinox.p2.metadata.Version;
+
+/**
+ * @author Eike Stepper
+ */
+public interface P2Index {
+	public static final int SIMPLE_REPOSITORY = 0;
+
+	public static final int COMPOSED_REPOSITORY = 1;
+
+	public Repository[] getRepositories();
+
+	public Map<String, Set<String>> getCapabilities();
+
+	public Map<Repository, Set<Version>> lookupCapabilities(String namespace, String name);
+
+	public Map<Repository, Set<Version>> generateCapabilitiesFromComposedRepositories(
+			Map<Repository, Set<Version>> capabilitiesFromSimpleRepositories);
+
+	/**
+	 * @author Eike Stepper
+	 */
+	public interface Repository extends Comparable<Repository> {
+		public URI getLocation();
+
+		public int getID();
+
+		public boolean isComposed();
+
+		public boolean isCompressed();
+
+		public long getTimestamp();
+
+		public int getCapabilityCount();
+
+		public int getUnresolvedChildren();
+
+		public Repository[] getChildren();
+
+		public Repository[] getComposites();
+	}
+}