xwiki · surli · May 13, 2025 · May 13, 2025 · May 16, 2025
diff --git a/...-core/xwiki-commons-properties/src/main/java/org/xwiki/properties/PropertyDescriptor.java b/...-core/xwiki-commons-properties/src/main/java/org/xwiki/properties/PropertyDescriptor.java
@@ -23,6 +23,8 @@
 import java.lang.reflect.Method;
 import java.lang.reflect.Type;
 
+import org.xwiki.stability.Unstable;
+
 /**
  * Describe a property in a bean.
  *
@@ -139,4 +141,15 @@ default boolean isDisplayHidden()
     {
         return false;
     }
+
+    /**
+     * @return the ordering value to use to display the property in the UI. The lower the value, the higher the
+     * priority. {@code -1} means no defined order.
+     * @since 17.5.0RC1
+     */
+    @Unstable
+    default int getOrder()
+    {
+        return -1;
+    }
 }
diff --git a/...xwiki-commons-properties/src/main/java/org/xwiki/properties/annotation/PropertyOrder.java b/...xwiki-commons-properties/src/main/java/org/xwiki/properties/annotation/PropertyOrder.java
@@ -0,0 +1,47 @@
+/*
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.xwiki.properties.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.xwiki.stability.Unstable;
+
+/**
+ * Use this annotation to specify how properties should be ordered in the UI.
+ * By convention, a lower value means a higher priority.
+ *
+ * @version $Id$
+ * @since 17.5.0RC1
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.METHOD, ElementType.FIELD })
+@Inherited
+@Unstable
+public @interface PropertyOrder
+{
+    /**
+     * @return the description.
+     */
+    int value();
+}
diff --git a/...commons-properties/src/main/java/org/xwiki/properties/internal/DefaultBeanDescriptor.java b/...commons-properties/src/main/java/org/xwiki/properties/internal/DefaultBeanDescriptor.java
@@ -33,6 +33,8 @@
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.SortedSet;
+import java.util.TreeSet;
 
 import org.apache.commons.lang3.ArrayUtils;
 import org.apache.commons.lang3.exception.ExceptionUtils;
@@ -53,6 +55,7 @@
 import org.xwiki.properties.annotation.PropertyId;
 import org.xwiki.properties.annotation.PropertyMandatory;
 import org.xwiki.properties.annotation.PropertyName;
+import org.xwiki.properties.annotation.PropertyOrder;
 
 /**
  * Default implementation for BeanDescriptor.
@@ -69,19 +72,32 @@ public class DefaultBeanDescriptor implements BeanDescriptor
 
     private static final List<Class<? extends Annotation>> COMMON_ANNOTATION_CLASSES = Arrays.asList(
         PropertyMandatory.class, Deprecated.class, PropertyAdvanced.class, PropertyGroup.class,
-        PropertyFeature.class, PropertyDisplayType.class, PropertyDisplayHidden.class);
+        PropertyFeature.class, PropertyDisplayType.class, PropertyDisplayHidden.class, PropertyOrder.class);
 
     /**
      * @see #getBeanClass()
      */
-    private Class<?> beanClass;
+    private final Class<?> beanClass;
 
     /**
      * The properties of the bean.
      */
-    private Map<String, PropertyDescriptor> parameterDescriptorMap = new LinkedHashMap<>();
+    private final Map<String, PropertyDescriptor> parameterDescriptorMap = new LinkedHashMap<>();
+    private final SortedSet<PropertyDescriptor> descriptorSortedSet = new TreeSet<>((d1, d2) -> {
+        int o1 = d1.getOrder();
+        int o2 = d2.getOrder();
+        if (o1 >= 0 && o2 >= 0) {
+            return Integer.compare(o1, o2);
+        } else if (o1 >= 0) {
+            return -1;
+        } else if (o2 >= 0) {
+            return 1;
+        } else {
+            return d1.getId().compareTo(d2.getId());
+        }
+    });
 
-    private Map<PropertyGroup, PropertyGroupDescriptor> groups = new HashMap<>();
+    private final Map<PropertyGroup, PropertyGroupDescriptor> groups = new HashMap<>();
 
     /**
      * @param beanClass the class of the JAVA bean.
@@ -209,6 +225,7 @@ protected void extractPropertyDescriptor(java.beans.PropertyDescriptor propertyD
                 desc.setReadMethod(readMethod);
 
                 this.parameterDescriptorMap.put(desc.getId(), desc);
+                this.descriptorSortedSet.add(desc);
             }
         }
     }
@@ -264,6 +281,7 @@ protected void extractPropertyDescriptor(Field field, Object defaultInstance)
             desc.setField(field);
 
             this.parameterDescriptorMap.put(desc.getId(), desc);
+            this.descriptorSortedSet.add(desc);
         }
     }
 
@@ -275,6 +293,7 @@ private void setCommonProperties(DefaultPropertyDescriptor desc, Map<Class, Anno
         handlePropertyFeatureAndGroupAnnotations(desc, annotations);
         handlePropertyDisplayTypeAnnotation(desc, annotations);
         desc.setDisplayHidden(annotations.get(PropertyDisplayHidden.class) != null);
+        handlePropertyOrder(desc, annotations);
     }
 
     private void handlePropertyFeatureAndGroupAnnotations(DefaultPropertyDescriptor desc, Map<Class,
@@ -320,6 +339,14 @@ private void handlePropertyDisplayTypeAnnotation(DefaultPropertyDescriptor desc,
         desc.setDisplayType(displayType);
     }
 
+    private void handlePropertyOrder(DefaultPropertyDescriptor desc, Map<Class, Annotation> annotations)
+    {
+        PropertyOrder propertyOrderAnnotation = (PropertyOrder) annotations.get(PropertyOrder.class);
+        if (propertyOrderAnnotation != null && propertyOrderAnnotation.value() > 0) {
+            desc.setOrder(propertyOrderAnnotation.value());
+        }
+    }
+
     /**
      * Get the parameter annotation. Try first on the setter then on the getter if no annotation has been found.
      *
@@ -350,7 +377,7 @@ public Class<?> getBeanClass()
     @Override
     public Collection<PropertyDescriptor> getProperties()
     {
-        return this.parameterDescriptorMap.values();
+        return this.descriptorSortedSet;
     }
 
     @Override

diff --git a/...ons-properties/src/main/java/org/xwiki/properties/internal/DefaultPropertyDescriptor.java b/...ons-properties/src/main/java/org/xwiki/properties/internal/DefaultPropertyDescriptor.java
@@ -107,6 +107,11 @@ public class DefaultPropertyDescriptor implements PropertyDescriptor
      */
     private boolean displayHidden;
 
+    /**
+     * @see #getOrder()
+     */
+    private int order = -1;
+
     @Override
     public String getId()
     {
@@ -345,4 +350,19 @@ public void setDisplayHidden(boolean isDisplayHidden)
     {
         this.displayHidden = isDisplayHidden;
     }
+
+    @Override
+    public int getOrder()
+    {
+        return this.order;
+    }
+
+    /**
+     * @param order see {@link #getOrder()}.
+     * @since 17.5.0RC1
+     */
+    public void setOrder(int order)
+    {
+        this.order = order;
+    }
 }
diff --git a/...ons-properties/src/test/java/org/xwiki/properties/internal/DefaultBeanDescriptorTest.java b/...ons-properties/src/test/java/org/xwiki/properties/internal/DefaultBeanDescriptorTest.java
@@ -20,6 +20,7 @@
 package org.xwiki.properties.internal;
 
 import java.lang.reflect.ParameterizedType;
+import java.util.Collection;
 import java.util.List;
 
 import org.apache.commons.lang3.tuple.Triple;
@@ -92,6 +93,7 @@ void propertyDescriptorTest()
         assertEquals("test1", advancedDescriptor.getGroupDescriptor().getGroup().get(0));
         assertEquals("test2", advancedDescriptor.getGroupDescriptor().getGroup().get(1));
         assertEquals("feature2", advancedDescriptor.getGroupDescriptor().getFeature());
+        assertEquals(10, advancedDescriptor.getOrder());
 
         PropertyDescriptor displayTypeDescriptor = this.beanDescriptor.getProperty("displayTypeParameter");
         assertEquals(new DefaultParameterizedType(null, Triple.class, Boolean.class, String.class, Long.class),
@@ -121,6 +123,7 @@ void propertyDescriptorWithUpperCaseTest()
         assertNotNull(upperPropertyDescriptor.getWriteMethod());
         assertNotNull(upperPropertyDescriptor.getReadMethod());
         assertNull(upperPropertyDescriptor.getField());
+        assertEquals(-1, upperPropertyDescriptor.getOrder());
     }
 
     @Test
@@ -137,6 +140,7 @@ void propertyDescriptorPublicFieldTest()
         assertNull(publicFieldPropertyDescriptor.getWriteMethod());
         assertNull(publicFieldPropertyDescriptor.getReadMethod());
         assertNotNull(publicFieldPropertyDescriptor.getField());
+        assertEquals(8, publicFieldPropertyDescriptor.getOrder());
     }
 
     @Test
@@ -158,6 +162,7 @@ void propertyDescriptorWithDescriptionTest()
         assertNotNull(prop1Descriptor.getWriteMethod());
         assertNotNull(prop1Descriptor.getReadMethod());
         assertNull(prop1Descriptor.getField());
+        assertEquals(-1, prop1Descriptor.getOrder());
     }
 
     @Test
@@ -173,6 +178,7 @@ void propertyDescriptorWithDescriptionAndMandatoryTest()
         assertNotNull(prop2Descriptor.getWriteMethod());
         assertNotNull(prop2Descriptor.getReadMethod());
         assertNull(prop2Descriptor.getField());
+        assertEquals(-1, prop2Descriptor.getOrder());
     }
 
     @Test
@@ -188,6 +194,7 @@ void propertyDescriptorWithDescriptionAndMandatoryOnSetterTest()
         assertNotNull(prop3Descriptor.getWriteMethod());
         assertNotNull(prop3Descriptor.getReadMethod());
         assertNull(prop3Descriptor.getField());
+        assertEquals(-1, prop3Descriptor.getOrder());
     }
 
     @Test
@@ -284,4 +291,30 @@ void propertyDescriptorbackwardCompatible()
         assertNull(propertyDescriptor.getGroupDescriptor().getGroup());
         assertNull(propertyDescriptor.getGroupDescriptor().getFeature());
     }
+
+    @Test
+    void getProperties()
+    {
+        Collection<PropertyDescriptor> properties = this.beanDescriptor.getProperties();
+        assertEquals(16, properties.size());
+        assertEquals(List.of(
+            "publicField", // order: 8
+            "advancedParameter", // order: 10
+            // no defined order for other ones, so ordered by id
+            "deprecatedParameter",
+            "displayHiddenParameter",
+            "displayTypeParameter",
+            "displayTypeParameter2",
+            "genericField",
+            "genericProp",
+            "impossible.field.name",
+            "impossible.method.name",
+            "lowerprop",
+            "prop1",
+            "prop2",
+            "prop3",
+            "propertyWithDifferentId",
+            "upperProp"
+        ), properties.stream().map(PropertyDescriptor::getId).toList());
+    }
 }
diff --git a/...mmons-core/xwiki-commons-properties/src/test/java/org/xwiki/properties/test/TestBean.java b/...mmons-core/xwiki-commons-properties/src/test/java/org/xwiki/properties/test/TestBean.java
@@ -32,6 +32,7 @@
 import org.xwiki.properties.annotation.PropertyId;
 import org.xwiki.properties.annotation.PropertyMandatory;
 import org.xwiki.properties.annotation.PropertyName;
+import org.xwiki.properties.annotation.PropertyOrder;
 
 public class TestBean
 {
@@ -65,6 +66,7 @@ public class TestBean
 
     @PropertyName("Public Field")
     @PropertyDescription("a public field")
+    @PropertyOrder(8)
     public String publicField;
 
     public List<Integer> genericField;
@@ -106,6 +108,7 @@ public String getProp1()
 
     @PropertyMandatory
     @PropertyDescription("prop2 description")
+    @PropertyOrder(-3)
     public void setProp2(int prop2)
     {
         this.prop2 = prop2;
@@ -176,6 +179,7 @@ public void setDeprecatedParameter(String deprecatedParameter)
     @PropertyAdvanced
     @PropertyGroup({"test1", "test2"})
     @PropertyFeature("feature2")
+    @PropertyOrder(10)
     public String getAdvancedParameter()
     {
         return advancedParameter;