[E4 XPath] Deprecate unsuitable XPathContextFactory methods for removal

Author: HannesWell

bundles/org.eclipse.e4.emf.xpath/META-INF/MANIFEST.MF

@@ -1,7 +1,7 @@
 Manifest-Version: 1.0
 Bundle-ManifestVersion: 2
 Bundle-Name: %Bundle-Name
-Bundle-SymbolicName: org.eclipse.e4.emf.xpath
+Bundle-SymbolicName: org.eclipse.e4.emf.xpath;deprecated:="This bundle is deprecated since 2025-03 (removal in 2027-03 or later)"
 Bundle-Version: 0.6.0.qualifier
 Bundle-RequiredExecutionEnvironment: JavaSE-17
 Require-Bundle: org.eclipse.emf.ecore;bundle-version="2.35.0",

bundles/org.eclipse.e4.emf.xpath/src/org/eclipse/e4/emf/xpath/EcoreXPathContextFactory.java

@@ -13,14 +13,14 @@
  ******************************************************************************/
 package org.eclipse.e4.emf.xpath;
 
-import org.eclipse.e4.emf.xpath.internal.java.JavaXPathContextFactoryImpl;
 import org.eclipse.emf.ecore.EObject;
 
 /**
  * Factory which creates an XPathContextFactory for {@link EObject}s
  *
  * @since 1.0
  */
+@Deprecated(forRemoval = true, since = "2025-03 (removal in 2027-03 or later)")
 public class EcoreXPathContextFactory {
 
 	/**
@@ -29,7 +29,7 @@ public class EcoreXPathContextFactory {
 	 * @return the factory
 	 */
 	public static XPathContextFactory<EObject> newInstance() {
-		return new JavaXPathContextFactoryImpl<>();
+		return XPathContextFactory.newInstance();
 	}
 
 }

bundles/org.eclipse.e4.emf.xpath/src/org/eclipse/e4/emf/xpath/XPathContext.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2010, 2024 BestSolution.at and others.
+ * Copyright (c) 2010, 2025 BestSolution.at and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -23,7 +23,11 @@
  * Context in which the xpath is executed
  *
  * @since 1.0
+ * @deprecated To query an E4-model use
+ *             {@link org.eclipse.e4.ui.workbench.modeling.EModelService#findMatchingElements(org.eclipse.e4.ui.model.application.MApplicationElement, String, Class)}
+ *             instead.
  */
+@Deprecated(forRemoval = true, since = "2025-03 (removal in 2027-03 or later)")
 public interface XPathContext {
 
 	/**
@@ -34,6 +38,7 @@ public interface XPathContext {
 	 *            to evaluate
 	 * @return Object found
 	 */
+	@Deprecated(forRemoval = true, since = "2025-03 (removal in 2027-03 or later)")
 	Object getValue(String xpath);
 
 	/**
@@ -46,6 +51,7 @@ public interface XPathContext {
 	 *            required type
 	 * @return Object found
 	 */
+	@Deprecated(forRemoval = true, since = "2025-03 (removal in 2027-03 or later)")
 	<T> T getValue(String xpath, Class<T> requiredType);
 
 	/**

bundles/org.eclipse.e4.emf.xpath/src/org/eclipse/e4/emf/xpath/XPathContextFactory.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2010, 2024 BestSolution.at and others.
+ * Copyright (c) 2010, 2025 BestSolution.at and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -19,7 +19,11 @@
  * Factory responsible to create an XPath-Context
  *
  * @param <T> the object type the XPath is created for
+ * @deprecated To query an E4-model use
+ *             {@link org.eclipse.e4.ui.workbench.modeling.EModelService#findMatchingElements(org.eclipse.e4.ui.model.application.MApplicationElement, String, Class)}
+ *             instead.
  */
+@Deprecated(forRemoval = true, since = "2025-03 (removal in 2027-03 or later)")
 public abstract class XPathContextFactory<T> {
 
 	/**
@@ -38,12 +42,18 @@ public abstract class XPathContextFactory<T> {
 	 * @param parentContext parent context
 	 * @param contextBean   Object
 	 * @return XPathContext
+	 * @deprecated The parent-context does not provide any real value. Just use
+	 *             {@link #newContext(Object)}
 	 */
+	@Deprecated(forRemoval = true, since = "2025-03 (removal in 2027-03 or later)")
 	public abstract XPathContext newContext(XPathContext parentContext, T contextBean);
 
 	/**
+	 * Creates a new {@link XPathContextFactory XPathContextFactory<EObject>} that's
+	 * suitable to query the E4-model.
+	 *
 	 * @param <T> the object type the xpath is created for
-	 * @return Create a new XPath-Factory
+	 * @return A new {@code XPathContextFactory}.
 	 */
 	public static <T> XPathContextFactory<T> newInstance() {
 		return new JavaXPathContextFactoryImpl<>();

bundles/org.eclipse.e4.emf.xpath/src/org/eclipse/e4/emf/xpath/XPathNotFoundException.java

@@ -20,6 +20,7 @@
  *
  * @since 0.6
  */
+@Deprecated(forRemoval = true, since = "2025-03 (removal in 2027-03 or later)")
 public class XPathNotFoundException extends IllegalArgumentException {
 	private static final long serialVersionUID = -4174244860692153739L;
 

bundles/org.eclipse.e4.emf.xpath/src/org/eclipse/e4/emf/xpath/internal/java/JavaXPathContextFactoryImpl.java

@@ -165,6 +165,7 @@ public <R> R getValue(String xpath, Class<R> requiredType) {
 		}
 
 		@Override
+		@SuppressWarnings("removal")
 		public Object getValue(String xpath) {
 			Iterator<Object> iterator = iterate(xpath);
 			if (!iterator.hasNext()) {

bundles/org.eclipse.e4.ui.model.workbench/src/org/eclipse/e4/ui/model/XPathHelper.java

@@ -19,6 +19,7 @@
 
 public class XPathHelper {
 
+	@SuppressWarnings("removal")
 	public static <T> Stream<T> findMatchingElements(MApplicationElement searchRoot, String xPath, Class<T> clazz) {
 		return XPathContextFactory.newInstance().newContext(searchRoot).stream(xPath, clazz);
 	}

tests/org.eclipse.e4.emf.xpath.test/src/org/eclipse/e4/emf/xpath/test/ExampleQueriesApplicationTest.java

@@ -19,7 +19,6 @@
 
 import java.util.List;
 
-import org.eclipse.e4.emf.xpath.EcoreXPathContextFactory;
 import org.eclipse.e4.emf.xpath.XPathContext;
 import org.eclipse.e4.emf.xpath.XPathContextFactory;
 import org.eclipse.e4.ui.internal.workbench.E4XMIResourceFactory;
@@ -43,6 +42,7 @@
 import org.junit.Before;
 import org.junit.Test;
 
+@SuppressWarnings("removal")
 public class ExampleQueriesApplicationTest {
 
 	private ResourceSet resourceSet;
@@ -69,11 +69,11 @@ public void setUp() {
 
 		URI uri = URI.createPlatformPluginURI("/org.eclipse.e4.emf.xpath.test/model/Application.e4xmi", true);
 		resource = resourceSet.getResource(uri, true);
-		XPathContextFactory<EObject> f = EcoreXPathContextFactory.newInstance();
+		XPathContextFactory<EObject> f = XPathContextFactory.newInstance();
 		xpathContext = f.newContext(resource.getContents().get(0));
 		URI childUri = URI.createPlatformPluginURI("/org.eclipse.e4.emf.xpath.test/model/fragment.e4xmi", true);
 		childResource = resourceSet.getResource(childUri, true);
-		xpathChildContext = f.newContext(xpathContext, childResource.getContents().get(0));
+		xpathChildContext = f.newContext(childResource.getContents().get(0));
 	}
 
 	@After

tests/org.eclipse.e4.emf.xpath.test/src/org/eclipse/e4/emf/xpath/test/ExampleQueriesTestCase.java

@@ -25,7 +25,6 @@
 import java.util.Iterator;
 import java.util.List;
 
-import org.eclipse.e4.emf.xpath.EcoreXPathContextFactory;
 import org.eclipse.e4.emf.xpath.XPathContext;
 import org.eclipse.e4.emf.xpath.XPathContextFactory;
 import org.eclipse.e4.emf.xpath.XPathNotFoundException;
@@ -44,6 +43,7 @@
 import org.junit.Before;
 import org.junit.Test;
 
+@SuppressWarnings("removal")
 public class ExampleQueriesTestCase {
 
 	private ResourceSet resourceSet;
@@ -61,7 +61,7 @@ public void setUp() {
 		resourceSet.getPackageRegistry().put(XpathtestPackage.eNS_URI, XpathtestPackage.eINSTANCE);
 		URI uri = URI.createPlatformPluginURI("/org.eclipse.e4.emf.xpath.test/model/Test.xmi", true);
 		resource = resourceSet.getResource(uri, true);
-		xpathContextFactory = EcoreXPathContextFactory.newInstance();
+		xpathContextFactory = XPathContextFactory.newInstance();
 		xpathContext = xpathContextFactory.newContext(resource.getContents().get(0));
 	}