XWIKI-21699: Add new API to help evaluate xobjects

XWIKI-21473: Improve search suggest evaluation

Author: pjeanjean

xwiki-platform-core/xwiki-platform-oldcore/src/main/java/com/xpn/xwiki/api/Object.java

@@ -19,7 +19,12 @@
  */
 package com.xpn.xwiki.api;
 
+import java.util.Map;
+
+import org.xwiki.evaluation.ObjectEvaluator;
+import org.xwiki.evaluation.ObjectEvaluatorException;
 import org.xwiki.model.reference.ObjectPropertyReference;
+import org.xwiki.stability.Unstable;
 
 import com.xpn.xwiki.XWikiContext;
 import com.xpn.xwiki.XWikiException;
@@ -159,4 +164,18 @@ public ObjectPropertyReference getPropertyReference(String propertyName)
     {
         return new ObjectPropertyReference(propertyName, getReference());
     }
+
+    /**
+     * Evaluates the properties of an object using a matching implementation of {@link ObjectEvaluator}.
+     *
+     * @return a Map storing the evaluated properties
+     * @since 14.10.21
+     * @since 15.5.5
+     * @since 15.10.2
+     */
+    @Unstable
+    public Map<String, String> evaluate() throws ObjectEvaluatorException
+    {
+        return getBaseObject().evaluate();
+    }
 }

xwiki-platform-core/xwiki-platform-oldcore/src/main/java/com/xpn/xwiki/objects/BaseObject.java

@@ -22,15 +22,19 @@
 import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
 import java.util.UUID;
 
 import org.apache.commons.lang3.builder.HashCodeBuilder;
 import org.dom4j.Element;
+import org.xwiki.evaluation.ObjectEvaluator;
+import org.xwiki.evaluation.ObjectEvaluatorException;
 import org.xwiki.model.EntityType;
 import org.xwiki.model.reference.DocumentReference;
 import org.xwiki.model.reference.DocumentReferenceResolver;
 import org.xwiki.model.reference.EntityReference;
 import org.xwiki.model.reference.SpaceReference;
+import org.xwiki.stability.Unstable;
 
 import com.xpn.xwiki.XWikiContext;
 import com.xpn.xwiki.XWikiException;
@@ -435,4 +439,20 @@ protected void mergeField(PropertyInterface currentElement, ElementInterface pre
 
         super.mergeField(currentElement, previousElement, newElement, configuration, context, mergeResult);
     }
+
+    /**
+     * Evaluates the properties of an object using a matching implementation of {@link ObjectEvaluator}.
+     *
+     * @return a Map storing the evaluated properties
+     * @throws ObjectEvaluatorException if the evaluation fails
+     * @since 14.10.21
+     * @since 15.5.5
+     * @since 15.10.2
+     */
+    @Unstable
+    public Map<String, String> evaluate() throws ObjectEvaluatorException
+    {
+        ObjectEvaluator objectEvaluator = Utils.getComponent(ObjectEvaluator.class);
+        return objectEvaluator.evaluate(this);
+    }
 }

xwiki-platform-core/xwiki-platform-oldcore/src/main/java/org/xwiki/evaluation/ObjectEvaluator.java

@@ -0,0 +1,55 @@
+/*
+ * 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.evaluation;
+
+import java.util.Map;
+
+import org.xwiki.component.annotation.Role;
+import org.xwiki.evaluation.internal.DefaultObjectEvaluator;
+import org.xwiki.stability.Unstable;
+
+import com.xpn.xwiki.objects.BaseObject;
+
+/**
+ * Evaluates the properties of an object and returns a Map that stores the evaluation results, in which keys are the
+ * field names of the properties, and values their evaluated content.
+ * Implement an instance with a hint corresponding to the class name of the object you want to evaluate and use
+ * {@link DefaultObjectEvaluator} that will proxy the calls to the right implementation.
+ * This ensures that the properties being evaluated are only the ones referenced explicitly by the provided
+ * implementation, in order to avoid accidental evaluation of properties that should only be used in specific contexts.
+ *
+ * @version $Id$
+ * @since 14.10.21
+ * @since 15.5.5
+ * @since 15.10.2
+ */
+@Unstable
+@Role
+public interface ObjectEvaluator
+{
+    /**
+     * Evaluates the properties of an object.
+     *
+     * @param object the object to evaluate
+     * @return a Map storing the evaluated properties
+     * @throws ObjectEvaluatorException if the evaluation fails
+     */
+    Map<String, String> evaluate(BaseObject object) throws ObjectEvaluatorException;
+}

xwiki-platform-core/xwiki-platform-oldcore/src/main/java/org/xwiki/evaluation/ObjectEvaluatorException.java

@@ -0,0 +1,55 @@
+/*
+ * 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.evaluation;
+
+import org.xwiki.stability.Unstable;
+
+/**
+ * Exception raised during evaluation of XObjects properties.
+ *
+ * @version $Id$
+ * @since 14.10.21
+ * @since 15.5.5
+ * @since 15.10.2
+ */
+@Unstable
+public class ObjectEvaluatorException extends Exception
+{
+    /**
+     * Creates an instance of ObjectEvaluatorException with a message and a cause.
+     *
+     * @param message the message detailing the issue
+     * @param cause the cause of the exception
+     */
+    public ObjectEvaluatorException(String message, Throwable cause)
+    {
+        super(message, cause);
+    }
+
+    /**
+     * Creates an instance of ObjectEvaluatorException with a message.
+     *
+     * @param message the message detailing the issue
+     */
+    public ObjectEvaluatorException(String message)
+    {
+        this(message, null);
+    }
+}

xwiki-platform-core/xwiki-platform-oldcore/src/main/java/org/xwiki/evaluation/ObjectPropertyEvaluator.java

@@ -0,0 +1,52 @@
+/*
+ * 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.evaluation;
+
+import java.util.Map;
+
+import org.xwiki.component.annotation.Role;
+import org.xwiki.stability.Unstable;
+
+import com.xpn.xwiki.objects.BaseObject;
+
+/**
+ * Evaluates the properties of an object and returns a Map that stores the evaluation results, in which keys are the
+ * field names of the properties, and values their evaluated content.
+ * Instances of this interface should be used as helpers by implementations of {@link ObjectEvaluator}.
+ *
+ * @version $Id$
+ * @since 14.10.21
+ * @since 15.5.5
+ * @since 15.10.2
+ */
+@Unstable
+@Role
+public interface ObjectPropertyEvaluator
+{
+    /**
+     * Evaluates the properties of an object.
+     *
+     * @param object the object to evaluate
+     * @param properties the names of the properties to evaluate
+     * @return a Map storing the evaluated properties
+     * @throws ObjectEvaluatorException if the evaluation fails
+     */
+    Map<String, String> evaluateProperties(BaseObject object, String... properties) throws ObjectEvaluatorException;
+}

xwiki-platform-core/xwiki-platform-oldcore/src/main/java/org/xwiki/evaluation/internal/DefaultObjectEvaluator.java

@@ -0,0 +1,82 @@
+/*
+ * 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.evaluation.internal;
+
+import java.util.Collections;
+import java.util.Map;
+
+import javax.inject.Inject;
+import javax.inject.Named;
+import javax.inject.Provider;
+import javax.inject.Singleton;
+
+import org.xwiki.component.annotation.Component;
+import org.xwiki.component.manager.ComponentLookupException;
+import org.xwiki.component.manager.ComponentManager;
+import org.xwiki.evaluation.ObjectEvaluator;
+import org.xwiki.evaluation.ObjectEvaluatorException;
+import org.xwiki.model.reference.EntityReferenceSerializer;
+
+import com.xpn.xwiki.objects.BaseObject;
+
+/**
+ * Evaluator that proxies the actual evaluation to the right ObjectEvaluator implementation, based on the XClass of
+ * the object.
+ *
+ * @version $Id$
+ * @since 14.10.21
+ * @since 15.5.5
+ * @since 15.10.2
+ */
+@Component
+@Singleton
+public class DefaultObjectEvaluator implements ObjectEvaluator
+{
+    @Inject
+    @Named("context")
+    private Provider<ComponentManager> contextComponentManagerProvider;
+
+    @Inject
+    @Named("local")
+    private EntityReferenceSerializer<String> entityReferenceSerializer;
+
+    @Override
+    public Map<String, String> evaluate(BaseObject object) throws ObjectEvaluatorException
+    {
+        if (object == null) {
+            return Collections.emptyMap();
+        }
+
+        String xClassName = this.entityReferenceSerializer.serialize(object.getXClassReference());
+        ComponentManager componentManager = this.contextComponentManagerProvider.get();
+        if (!componentManager.hasComponent(ObjectEvaluator.class, xClassName)) {
+            throw new ObjectEvaluatorException(String.format("Could not find an instance of 'ObjectEvaluator' for "
+                + "XObject of class '%s'.", xClassName));
+        }
+
+        try {
+            ObjectEvaluator objectEvaluator = componentManager.getInstance(ObjectEvaluator.class, xClassName);
+            return objectEvaluator.evaluate(object);
+        } catch (ComponentLookupException e) {
+            throw new ObjectEvaluatorException(String.format("Could not instantiate 'ObjectEvaluator' for XObject of "
+                + "class '%s'.", xClassName), e);
+        }
+    }
+}