Deprecate more ViewerSorter(s) forRemoval

bundles/org.eclipse.jface/src/org/eclipse/jface/viewers/AbstractTreeViewer.java

@@ -261,6 +261,7 @@ private Widget internalFindItem(TreePath path) {
 	 *            the child elements to add
 	 * @since 3.1
 	 */
+	@SuppressWarnings("removal")
 	protected void internalAdd(Widget widget, Object parentElementOrTreePath,
 			Object[] childElements) {
 		Object parent;
@@ -309,6 +310,11 @@ protected void internalAdd(Widget widget, Object parentElementOrTreePath,
 						path = internalGetSorterParentPath(widget, comparator);
 					}
 					tpvs.sort(this, path, filtered);
+				} else if (comparator instanceof TreePathViewerComparator tpvs) {
+					if (path == null) {
+						path = internalGetSorterParentPath(widget, comparator);
+					}
+					tpvs.sort(this, path, filtered);
 				} else {
 					comparator.sort(this, filtered);
 				}
@@ -500,23 +506,18 @@ private boolean itemExists(Item[] items, Object element) {
 
 	/**
 	 * Returns the index where the item should be inserted. It uses sorter to
-	 * determine the correct position, if sorter is not assigned, returns the
-	 * index of the element after the last.
-	 *
-	 * @param items
-	 *            the items to search
-	 * @param comparator
-	 *            The comparator to use.
-	 * @param lastInsertion
-	 *            the start index to start search for position from this allows
-	 *            optimizing search for multiple elements that are sorted
-	 *            themselves.
-	 * @param element
-	 *            element to find position for.
-	 * @param parentPath
-	 *            the tree path for the element's parent or <code>null</code>
-	 *            if the element is a root element or the sorter is not a
-	 *            {@link TreePathViewerSorter}
+	 * determine the correct position, if sorter is not assigned, returns the index
+	 * of the element after the last.
+	 *
+	 * @param items         the items to search
+	 * @param comparator    The comparator to use.
+	 * @param lastInsertion the start index to start search for position from this
+	 *                      allows optimizing search for multiple elements that are
+	 *                      sorted themselves.
+	 * @param element       element to find position for.
+	 * @param parentPath    the tree path for the element's parent or
+	 *                      <code>null</code> if the element is a root element or
+	 *                      the sorter is not a {@link TreePathViewerComparator}
 	 * @return the index to use when inserting the element.
 	 */
 
@@ -615,22 +616,22 @@ protected int indexForElement(Widget parent, Object element) {
 
 	/**
 	 * Return the tree path that should be used as the parent path for the given
-	 * widget and sorter. A <code>null</code> is returned if either the sorter
-	 * is not a {@link TreePathViewerSorter} or if the parent widget is not an
+	 * widget and sorter. A <code>null</code> is returned if either the sorter is
+	 * not a {@link TreePathViewerComparator} or if the parent widget is not an
 	 * {@link Item} (i.e. is the root of the tree).
 	 *
-	 * @param parent
-	 *            the parent widget
-	 * @param comparator
-	 *            the sorter
-	 * @return the tree path that should be used as the parent path for the
-	 *         given widget and sorter
+	 * @param parent     the parent widget
+	 * @param comparator the sorter
+	 * @return the tree path that should be used as the parent path for the given
+	 *         widget and sorter
 	 */
+	@SuppressWarnings("removal")
 	private TreePath internalGetSorterParentPath(Widget parent,
 			ViewerComparator comparator) {
 		TreePath path;
-		if (comparator instanceof TreePathViewerSorter
-				&& parent instanceof Item item) {
+		if (comparator instanceof TreePathViewerSorter && parent instanceof Item item) {
+			path = getTreePathFromItem(item);
+		} else if (comparator instanceof TreePathViewerComparator && parent instanceof Item item) {
 			path = getTreePathFromItem(item);
 		} else {
 			path = null;
@@ -640,24 +641,23 @@ private TreePath internalGetSorterParentPath(Widget parent,
 
 	/**
 	 * Compare the two elements using the given sorter. If the sorter is a
-	 * {@link TreePathViewerSorter}, the provided tree path will be used. If
-	 * the tree path is null and the sorter is a tree path sorter, then the
-	 * elements are root elements
-	 *
-	 * @param comparator
-	 *            the sorter
-	 * @param parentPath
-	 *            the path of the elements' parent
-	 * @param e1
-	 *            the first element
-	 * @param e2
-	 *            the second element
+	 * {@link TreePathViewerComparator}, the provided tree path will be used. If the
+	 * tree path is null and the sorter is a tree path sorter, then the elements are
+	 * root elements
+	 *
+	 * @param comparator the sorter
+	 * @param parentPath the path of the elements' parent
+	 * @param e1         the first element
+	 * @param e2         the second element
 	 * @return the result of comparing the two elements
 	 */
+	@SuppressWarnings("removal")
 	private int internalCompare(ViewerComparator comparator,
 			TreePath parentPath, Object e1, Object e2) {
 		if (comparator instanceof TreePathViewerSorter tpvs) {
 			return tpvs.compare(this, parentPath, e1, e2);
+		} else if (comparator instanceof TreePathViewerComparator tpvs) {
+			return tpvs.compare(this, parentPath, e1, e2);
 		}
 		return comparator.compare(this, e1, e2);
 	}
@@ -667,7 +667,7 @@ protected Object[] getSortedChildren(Object parentElementOrTreePath) {
 		Object[] result = null;
 		ViewerComparator comparator = getComparator();
 		if (parentElementOrTreePath != null
-				&& comparator instanceof TreePathViewerSorter tpvs) {
+				&& comparator instanceof TreePathViewerComparator tpvs) {
 			result = getFilteredChildren(parentElementOrTreePath);
 			// be sure we're not modifying the original array from the model
 			result = result.clone();

bundles/org.eclipse.jface/src/org/eclipse/jface/viewers/TreePathViewerComparator.java

@@ -0,0 +1,107 @@
+/*******************************************************************************
+ * Copyright (c) 2026 IBM Corporation 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:
+ *     IBM Corporation - initial API and implementation
+ *******************************************************************************/
+
+package org.eclipse.jface.viewers;
+
+import java.util.Arrays;
+
+/**
+ * A viewer sorter that is provided extra context in the form of the path of the
+ * parent element of the elements being sorted.
+ *
+ * @since 3.39
+ */
+public class TreePathViewerComparator extends ViewerComparator {
+
+	/**
+	 * Provide a category for the given element that will have the given parent
+	 * path when it is added to the viewer. The provided path is relative to the
+	 * viewer input. The parent path will be <code>null</code> when the elements
+	 * are root elements.
+	 * <p>
+	 * By default, the this method calls {@code ViewerSorter#category(Object)}.
+	 * Subclasses may override.
+	 *
+	 * @param parentPath
+	 *            the parent path for the element
+	 * @param element
+	 *            the element
+	 * @return the category of the element
+	 */
+	public int category(TreePath parentPath, Object element) {
+		return category(element);
+	}
+
+	/**
+	 * Compare the given elements that will have the given parent
+	 * path when they are added to the viewer. The provided path is
+	 * relative to the viewer input. The parent path will
+	 * be <code>null</code> when the elements are root elements.
+	 * <p>
+	 * By default, the this method calls
+	 * {@code ViewerSorter#sort(Viewer, Object[])}. Subclasses may override.
+	 * @param viewer the viewer
+	 * @param parentPath the parent path for the two elements
+	 * @param e1 the first element
+	 * @param e2 the second element
+	 * @return a negative number if the first element is less  than the
+	 *  second element; the value <code>0</code> if the first element is
+	 *  equal to the second element; and a positive
+	 */
+	public int compare(Viewer viewer, TreePath parentPath, Object e1, Object e2) {
+		return compare(viewer, e1, e2);
+	}
+
+	/**
+	 * Returns whether this viewer sorter would be affected
+	 * by a change to the given property of the given element.
+	 * The provided path is
+	 * relative to the viewer input. The parent path will
+	 * be <code>null</code> when the elements are root elements.
+	 * <p>
+	 * The default implementation of this method calls
+	 * {@code ViewerSorter#isSorterProperty(Object, String)}.
+	 * Subclasses may reimplement.
+	 * @param parentPath the parent path of the element
+	 * @param element the element
+	 * @param property the property
+	 * @return <code>true</code> if the sorting would be affected,
+	 *    and <code>false</code> if it would be unaffected
+	 */
+	public boolean isSorterProperty(TreePath parentPath, Object element, String property) {
+		return isSorterProperty(element, property);
+	}
+
+	/**
+	 * Sorts the given elements in-place, modifying the given array.
+	 * The provided path is
+	 * relative to the viewer input. The parent path will
+	 * be <code>null</code> when the elements are root elements.
+	 * <p>
+	 * The default implementation of this method uses the
+	 * java.util.Arrays#sort algorithm on the given array,
+	 * calling {@link #compare(Viewer, TreePath, Object, Object)} to compare elements.
+	 * </p>
+	 * <p>
+	 * Subclasses may reimplement this method to provide a more optimized implementation.
+	 * </p>
+	 *
+	 * @param viewer the viewer
+	 * @param parentPath the parent path of the given elements
+	 * @param elements the elements to sort
+	 */
+	public void sort(final Viewer viewer, final TreePath parentPath, Object[] elements) {
+		Arrays.sort(elements, (a, b) -> TreePathViewerComparator.this.compare(viewer, parentPath, a, b));
+	}
+}

bundles/org.eclipse.jface/src/org/eclipse/jface/viewers/TreePathViewerSorter.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006, 2015 IBM Corporation and others.
+ * Copyright (c) 2006, 2026 IBM Corporation and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -21,7 +21,9 @@
  * parent element of the elements being sorted.
  *
  * @since 3.2
+ * @deprecated Use {@link TreePathViewerComparator} instead.
  */
+@Deprecated(forRemoval = true, since = "2026-03")
 public class TreePathViewerSorter extends ViewerSorter {
 
 	/**
@@ -39,6 +41,7 @@ public class TreePathViewerSorter extends ViewerSorter {
 	 *            the element
 	 * @return the category of the element
 	 */
+	@Deprecated(forRemoval = true, since = "2026-03")
 	public int category(TreePath parentPath, Object element) {
 		return category(element);
 	}
@@ -59,6 +62,7 @@ public int category(TreePath parentPath, Object element) {
 	 *  second element; the value <code>0</code> if the first element is
 	 *  equal to the second element; and a positive
 	 */
+	@Deprecated(forRemoval = true, since = "2026-03")
 	public int compare(Viewer viewer, TreePath parentPath, Object e1, Object e2) {
 		return compare(viewer, e1, e2);
 	}
@@ -79,6 +83,7 @@ public int compare(Viewer viewer, TreePath parentPath, Object e1, Object e2) {
 	 * @return <code>true</code> if the sorting would be affected,
 	 *    and <code>false</code> if it would be unaffected
 	 */
+	@Deprecated(forRemoval = true, since = "2026-03")
 	public boolean isSorterProperty(TreePath parentPath, Object element, String property) {
 		return isSorterProperty(element, property);
 	}
@@ -101,6 +106,7 @@ public boolean isSorterProperty(TreePath parentPath, Object element, String prop
 	 * @param parentPath the parent path of the given elements
 	 * @param elements the elements to sort
 	 */
+	@Deprecated(forRemoval = true, since = "2026-03")
 	public void sort(final Viewer viewer, final TreePath parentPath, Object[] elements) {
 		Arrays.sort(elements, (a, b) -> TreePathViewerSorter.this.compare(viewer, parentPath, a, b));
 	}

bundles/org.eclipse.search/search/org/eclipse/search/internal/ui/SorterDescriptor.java

@@ -21,7 +21,7 @@
 import org.eclipse.core.runtime.Platform;
 
 import org.eclipse.jface.resource.ImageDescriptor;
-import org.eclipse.jface.viewers.ViewerSorter;
+import org.eclipse.jface.viewers.ViewerComparator;
 
 import org.eclipse.search.internal.ui.util.ExceptionHandler;
 
@@ -53,9 +53,9 @@ public SorterDescriptor(IConfigurationElement element) {
 	 * Creates a new sorter from this node.
 	 * @return new sorter
 	 */
-	public ViewerSorter createObject() {
+	public ViewerComparator createObject() {
 		try {
-			return (ViewerSorter)fElement.createExecutableExtension(CLASS_ATTRIBUTE);
+			return (ViewerComparator) fElement.createExecutableExtension(CLASS_ATTRIBUTE);
 		} catch (CoreException ex) {
 			ExceptionHandler.handle(ex, SearchMessages.Search_Error_createSorter_title, SearchMessages.Search_Error_createSorter_message);
 			return null;

bundles/org.eclipse.ui.navigator/src/org/eclipse/ui/navigator/CommonNavigator.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2003, 2023 IBM Corporation and others.
+ * Copyright (c) 2003, 2026 IBM Corporation and others.
  *
  * This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License 2.0
@@ -192,7 +192,7 @@ public void createPartControl(Composite aParent) {
 				commonViewer.addFilter(visibleFilter);
 			}
 
-			commonViewer.setComparator(new CommonViewerSorter());
+			commonViewer.setComparator(new CommonViewerComparator());
 
 			/*
 			 * make sure input is set after sorters and filters to avoid unnecessary

bundles/org.eclipse.ui.navigator/src/org/eclipse/ui/navigator/CommonViewer.java

@@ -268,6 +268,7 @@ public void dispose() {
 	 * @param sorter a viewer sorter, or <code>null</code> if none
 	 * @deprecated Use {@link #setComparator(ViewerComparator)} instead.
 	 */
+	@SuppressWarnings("removal")
 	@Override
 	@Deprecated(forRemoval = true, since = "2025-03")
 	public void setSorter(ViewerSorter sorter) {
@@ -284,10 +285,15 @@ public void setSorter(ViewerSorter sorter) {
 	 *
 	 * @param comparator a viewer sorter, or <code>null</code> if none
 	 */
+	@SuppressWarnings("removal")
 	@Override
 	public void setComparator(ViewerComparator comparator) {
-		if (comparator != null && comparator instanceof CommonViewerSorter commonSorter) {
-			commonSorter.setContentService(contentService);
+		if (comparator != null) {
+			if (comparator instanceof CommonViewerSorter commonSorter) {
+				commonSorter.setContentService(contentService);
+			} else if (comparator instanceof CommonViewerComparator commonComparator) {
+				commonComparator.setContentService(contentService);
+			}
 		}
 
 		super.setComparator(comparator);