[eclipse-equinox#713] API to identify bundle resources (like images)

`ImageIdentity` interface with surrounding types

Signed-off-by: Alexander Fedorov <[email protected]>

bundles/org.eclipse.equinox.common/META-INF/MANIFEST.MF

@@ -16,6 +16,7 @@ Export-Package: org.eclipse.core.internal.boot;x-friends:="org.eclipse.core.reso
    org.eclipse.equinox.security",
  org.eclipse.core.runtime;common=split;version="3.7.0";mandatory:=common,
  org.eclipse.core.text;version="3.13.0",
+ org.eclipse.equinox.common.identity;x-internal:=true,
  org.eclipse.equinox.events;version="1.0.0"
 Bundle-Vendor: %providerName
 Bundle-Activator: org.eclipse.core.internal.runtime.Activator

bundles/org.eclipse.equinox.common/src/org/eclipse/equinox/common/identity/BundleIdentity.java

@@ -0,0 +1,32 @@
+/*******************************************************************************
+ * Copyright (c) 2024 ArSysOp.
+ *
+ * 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:
+ *     Alexander Fedorov (ArSysOp) - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.equinox.common.identity;
+
+/**
+ * 
+ * <code>Bundle-SymbolicName</code> to be used as qualifier
+ * 
+ * @see BundleIdentityRecord
+ * @see ContributionIdentity
+ */
+public interface BundleIdentity {
+
+	/**
+	 * <code>Bundle-SymbolicName</code> value
+	 * 
+	 * @return bundle symbolic name
+	 */
+	String symbolic();
+
+}

bundles/org.eclipse.equinox.common/src/org/eclipse/equinox/common/identity/BundleIdentityRecord.java

@@ -0,0 +1,21 @@
+/*******************************************************************************
+ * Copyright (c) 2024 ArSysOp.
+ *
+ * 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:
+ *     Alexander Fedorov (ArSysOp) - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.equinox.common.identity;
+
+/**
+ * Default implementation for {@link BundleIdentity}
+ */
+public record BundleIdentityRecord(String symbolic) implements BundleIdentity {
+
+}

bundles/org.eclipse.equinox.common/src/org/eclipse/equinox/common/identity/ContributionIdentity.java

@@ -0,0 +1,58 @@
+/*******************************************************************************
+ * Copyright (c) 2024 ArSysOp.
+ *
+ * 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:
+ *     Alexander Fedorov (ArSysOp) - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.equinox.common.identity;
+
+/**
+ * 
+ * Identifies string in a manifest like <code>plugin.xml</code> that should
+ * match string in another manifest or in Java code
+ */
+public interface ContributionIdentity {
+
+	/**
+	 * Required to match historical contributions defined by a key only
+	 */
+	BundleIdentity HISTORICAL = new BundleIdentity() {
+
+		@Override
+		public String symbolic() {
+			return ""; //$NON-NLS-1$
+		}
+	};
+
+	/**
+	 * The identity of contributing bundle, typically a part of
+	 * {@link ContributionIdentity#id()}
+	 * 
+	 * @return contributing bundle identity
+	 */
+	BundleIdentity bundle();
+
+	/**
+	 * The key of contribution, typically a part of
+	 * {@link ContributionIdentity#id()}
+	 * 
+	 * @return key of contribution
+	 */
+	String key();
+
+	/**
+	 * Full qualified id of this contribution, typically contains both
+	 * {@link BundleIdentity#symbolic()} and {@link ContributionIdentity#key()}
+	 * 
+	 * @return full qualified id
+	 */
+	String id();
+
+}

bundles/org.eclipse.equinox.common/src/org/eclipse/equinox/common/identity/CreateResourceUrl.java

@@ -0,0 +1,73 @@
+/*******************************************************************************
+ * Copyright (c) 2024 ArSysOp.
+ *
+ * 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:
+ *     Alexander Fedorov (ArSysOp) - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.equinox.common.identity;
+
+import java.net.MalformedURLException;
+import java.net.URL;
+import java.util.MissingResourceException;
+import java.util.Objects;
+
+/**
+ * Provides an URL with "platform" schema to be used for resource access.
+ * <p/>
+ * 
+ * JFace usage:
+ * 
+ * <pre>
+ * ImageIdentity EXAMPLE
+ * ImageRegistry registry
+ * registry.put(EXAMPLE.id(), ImageDescriptor.createFromURL(new CreateResourceUrl(EXAMPLE).get()));
+ * ...
+ * Image image = registry.get(EXAMPLE.id());
+ *  *
+ * </pre>
+ * 
+ * EMF usage:
+ * 
+ * <pre>
+ * ImageIdentity EXAMPLE
+ * 
+ * public Object getImage(Object object) {
+ * 	return overlayImage(object, new CreateResourceUrl(EXAMPLE).get());
+ * }
+ * </pre>
+ * 
+ */
+public final class CreateResourceUrl {
+
+	private final String raw;
+
+	public CreateResourceUrl(ResourceUrl identity) {
+		this(identity.url());
+	}
+
+	public CreateResourceUrl(String raw) {
+		this.raw = Objects.requireNonNull(raw);
+	}
+
+	/**
+	 * Returns an {@link URL} to access given {@link ResourceUrl}
+	 * 
+	 * @return {@link URL} to access resource
+	 * @throws MissingResourceException in case of malformed URL
+	 */
+	public URL get() throws MissingResourceException {
+		try {
+			return new URL(raw);
+		} catch (MalformedURLException e) {
+			throw new MissingResourceException("Invalid resource url specification", getClass().getName(), raw); //$NON-NLS-1$
+		}
+	}
+
+}

bundles/org.eclipse.equinox.common/src/org/eclipse/equinox/common/identity/ImageIdentity.java

@@ -0,0 +1,27 @@
+/*******************************************************************************
+ * Copyright (c) 2024 ArSysOp.
+ *
+ * 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:
+ *     Alexander Fedorov (ArSysOp) - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.equinox.common.identity;
+
+/**
+ * Identify an image for further reuse in
+ * <ul>
+ * <li>EMF: org.eclipse.emf.edit.provider.ItemProvider</li>
+ * <li>JFace: org.eclipse.jface.resource.ImageRegistry</li>
+ * <li>other places where we need both image identifier and URL</li>
+ * </ul>
+ * 
+ */
+public interface ImageIdentity extends ContributionIdentity, ResourceUrl {
+	// consider adding image specifics like size
+}

bundles/org.eclipse.equinox.common/src/org/eclipse/equinox/common/identity/ImageIdentityRecord.java

@@ -0,0 +1,42 @@
+/*******************************************************************************
+ * Copyright (c) 2024 ArSysOp.
+ *
+ * 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:
+ *     Alexander Fedorov (ArSysOp) - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.equinox.common.identity;
+
+/**
+ * Default implementation for {@link ImageIdentity}
+ * 
+ * Useful to declare images constants and then use them from both headless and
+ * GUI part:
+ * 
+ * <pre>
+ * public static final ImageIdentity EXAMPLE = new ImageIdentityRecord(//
+ * 		new BundleIdentityRecord("org.examples.resources"), //
+ * 		"icons/full/obj16/example.png", //
+ * 		"example");
+ * </pre>
+ * 
+ */
+public record ImageIdentityRecord(BundleIdentity bundle, String path, String key) implements ImageIdentity {
+
+	@Override
+	public String id() {
+		return bundle.symbolic() + ".image." + key; //$NON-NLS-1$
+	}
+
+	@Override
+	public String url() {
+		return "platform:/plugin/" + bundle.symbolic() + "/$nl$/" + path; //$NON-NLS-1$ //$NON-NLS-2$
+	}
+
+}

bundles/org.eclipse.equinox.common/src/org/eclipse/equinox/common/identity/ResourceUrl.java

@@ -0,0 +1,31 @@
+/*******************************************************************************
+ * Copyright (c) 2024 ArSysOp.
+ *
+ * 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:
+ *     Alexander Fedorov (ArSysOp) - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.equinox.common.identity;
+
+/**
+ * Allows to work with resources (like images) from headless code
+ * 
+ * @see ImageIdentity
+ * 
+ */
+public interface ResourceUrl {
+
+	/**
+	 * An URL to access the resource, most probably with "platform" schema
+	 * 
+	 * @return an URL to access the resource
+	 */
+	String url();
+
+}