XWIKI-19751: Move the "watch" button for a page to the page content menu

* Put revapi ignores * Start fixing since
xwiki · May 23, 2024 · 30a9cf9 · 30a9cf9
1 parent 212d1cc
commit 30a9cf9
Show file tree

Hide file tree

Showing 4 changed files with 100 additions and 23 deletions.
diff --git a/xwiki-platform-core/pom.xml b/xwiki-platform-core/pom.xml
@@ -158,11 +158,61 @@
               </justification>
               <criticality>allowed</criticality>
               <differences>
+                <item>
+                <ignore>true</ignore>
+                <code>java.method.numberOfParametersChanged</code>
+                <old>method org.xwiki.rest.model.jaxb.Pages org.xwiki.rest.resources.pages.PageChildrenResource::getPageChildren(java.lang.String, java.lang.String, java.lang.String, java.lang.Integer, java.lang.Integer, java.lang.Boolean) throws org.xwiki.rest.XWikiRestException</old>
+                <new>method org.xwiki.rest.model.jaxb.Pages org.xwiki.rest.resources.pages.PageChildrenResource::getPageChildren(java.lang.String, java.lang.String, java.lang.String, java.lang.Integer, java.lang.Integer, java.lang.Boolean, java.lang.String, java.lang.String) throws org.xwiki.rest.XWikiRestException</new>
+                </item>
+              </differences>
+            </revapi.differences>
+            <revapi.differences>
+              <justification>Changes in unstable API of notification for watching pages.</justification>
+              <criticality>allowed</criticality>
+              <differences>
+                <item>
+                  <ignore>true</ignore>
+                  <code>java.field.removed</code>
+                  <old>field org.xwiki.notifications.filters.watch.WatchedEntityReference.WatchedStatus.NOT_WATCHED</old>
+                </item>
+                <item>
+                  <ignore>true</ignore>
+                  <code>java.field.removed</code>
+                  <old>field org.xwiki.notifications.filters.watch.WatchedEntityReference.WatchedStatus.WATCHED_FOR_SOME_EVENTS_OR_FORMATS</old>
+                </item>
+                <item>
+                  <ignore>true</ignore>
+                  <code>java.method.parameterTypeChanged</code>
+                  <old>parameter org.xwiki.notifications.filters.watch.WatchedEntityReference.WatchedStatus org.xwiki.notifications.filters.watch.WatchedEntityReference::getWatchedStatus(===org.xwiki.model.reference.DocumentReference===) throws org.xwiki.notifications.NotificationException</old>
+                  <new>parameter org.xwiki.notifications.filters.watch.WatchedEntityReference.WatchedStatus org.xwiki.notifications.filters.watch.WatchedEntityReference::getWatchedStatus(===org.xwiki.user.UserReference===) throws org.xwiki.notifications.NotificationException</new>
+                  <parameterIndex>0</parameterIndex>
+                </item>
+                <item>
+                  <ignore>true</ignore>
+                  <code>java.method.parameterTypeChanged</code>
+                  <old>parameter org.xwiki.notifications.filters.watch.WatchedEntityReference.WatchedStatus org.xwiki.notifications.filters.watch.WatchedEntityReference::getWatchedStatus(===org.xwiki.model.reference.DocumentReference===) throws org.xwiki.notifications.NotificationException @ org.xwiki.notifications.filters.watch.WatchedUserReference</old>
+                  <new>parameter org.xwiki.notifications.filters.watch.WatchedEntityReference.WatchedStatus org.xwiki.notifications.filters.watch.WatchedUserReference::getWatchedStatus(===org.xwiki.user.UserReference===) throws org.xwiki.notifications.NotificationException</new>
+                  <parameterIndex>0</parameterIndex>
+                </item>
+              </differences>
+            </revapi.differences>
+            <revapi.differences>
+              <justification>Watch page API changes to be able to compute it more exactly</justification>
+              <criticality>highlight</criticality>
+              <differences>
+                <item>
+                  <ignore>true</ignore>
+                  <code>java.method.numberOfParametersChanged</code>
+                  <old>method void org.xwiki.notifications.filters.watch.WatchedLocationReference::&lt;init&gt;(org.xwiki.model.reference.EntityReference, java.lang.String, org.xwiki.model.reference.EntityReferenceResolver&lt;java.lang.String&gt;, org.xwiki.notifications.filters.internal.scope.ScopeNotificationFilterLocationStateComputer, org.xwiki.notifications.filters.NotificationFilterPreferenceManager)</old>
+                  <new>method void org.xwiki.notifications.filters.watch.WatchedLocationReference::&lt;init&gt;(org.xwiki.model.reference.EntityReference, org.xwiki.component.manager.ComponentManager)</new>
+                  <justification>Simplify future extensions of this API.</justification>
+                </item>
                 <item>
                   <ignore>true</ignore>
                   <code>java.method.numberOfParametersChanged</code>
-                  <old>method org.xwiki.rest.model.jaxb.Pages org.xwiki.rest.resources.pages.PageChildrenResource::getPageChildren(java.lang.String, java.lang.String, java.lang.String, java.lang.Integer, java.lang.Integer, java.lang.Boolean) throws org.xwiki.rest.XWikiRestException</old>
-                  <new>method org.xwiki.rest.model.jaxb.Pages org.xwiki.rest.resources.pages.PageChildrenResource::getPageChildren(java.lang.String, java.lang.String, java.lang.String, java.lang.Integer, java.lang.Integer, java.lang.Boolean, java.lang.String, java.lang.String) throws org.xwiki.rest.XWikiRestException</new>
+                  <old>method void org.xwiki.notifications.filters.watch.WatchedUserReference::&lt;init&gt;(java.lang.String, org.xwiki.notifications.filters.internal.user.EventUserFilterPreferencesGetter, org.xwiki.notifications.filters.NotificationFilterPreferenceManager)</old>
+                  <new>method void org.xwiki.notifications.filters.watch.WatchedUserReference::&lt;init&gt;(java.lang.String, org.xwiki.notifications.filters.internal.user.EventUserFilterPreferencesGetter, org.xwiki.notifications.filters.NotificationFilterPreferenceManager, org.xwiki.user.UserReferenceSerializer&lt;org.xwiki.model.reference.DocumentReference&gt;)</new>
+                  <justification>Simplify future extensions of this API.</justification>
                 </item>
               </differences>
             </revapi.differences>

diff --git a/...ers-watch/src/main/java/org/xwiki/notifications/filters/watch/WatchedEntitiesManager.java b/...ers-watch/src/main/java/org/xwiki/notifications/filters/watch/WatchedEntitiesManager.java
@@ -43,8 +43,9 @@ public interface WatchedEntitiesManager
      * @param entity the entity to watch
      * @param user user that will watch the entity
      * @throws NotificationException if an error happens
+     * @deprecated use {@link #watch(WatchedEntityReference, UserReference)}.
      */
-    @Deprecated
+    @Deprecated(since = "16.5.0RC1")
     void watchEntity(WatchedEntityReference entity, DocumentReference user) throws NotificationException;
 
     /**
@@ -53,41 +54,51 @@ public interface WatchedEntitiesManager
      * @param user the user for whom to create the filter
      * @return {@code true} if a new filter has been created
      * @throws NotificationException in case of problem to save the changes
-     * @since 16.4.0RC1
+     * @since 16.5.0RC1
      */
     @Unstable
-    boolean watch(WatchedEntityReference entity, UserReference user) throws NotificationException;
+    default boolean watch(WatchedEntityReference entity, UserReference user) throws NotificationException
+    {
+        return false;
+    }
 
     /**
      * Remove filter related to watching the specified location be it inclusive or exclusive.
      * @param entity the entity for which to remove a filter.
      * @param user the user for whom to remove the filter
      * @return {@code true} if a filter has been removed
      * @throws NotificationException in case of problem to save the changes
-     * @since 16.4.0RC1
+     * @since 16.5.0RC1
      */
     @Unstable
-    boolean removeWatchFilter(WatchedEntityReference entity, UserReference user) throws NotificationException;
+    default boolean removeWatchFilter(WatchedEntityReference entity, UserReference user) throws NotificationException
+    {
+        return false;
+    }
 
     /**
      * Add an exclusive filter to ignore the specified location if it's not ignored yet.
      * @param entity the entity to be watched
      * @param user the user for whom to create the filter
      * @return {@code true} if a new filter has been created
      * @throws NotificationException in case of problem to save the changes
-     * @since 16.4.0RC1
+     * @since 16.5.0RC1
      */
     @Unstable
-    boolean block(WatchedEntityReference entity, UserReference user) throws NotificationException;
+    default boolean block(WatchedEntityReference entity, UserReference user) throws NotificationException
+    {
+        return false;
+    }
 
     /**
      * Remove a filter to stop watching the specified entity.
      *
      * @param entity the entity to watch
      * @param user user that will watch the entity
      * @throws NotificationException if an error happens
+     * @deprecated use {@link #block(WatchedEntityReference, UserReference)}.
      */
-    @Deprecated
+    @Deprecated(since = "16.5.0RC1")
     void unwatchEntity(WatchedEntityReference entity, DocumentReference user) throws NotificationException;
 
     /**

diff --git a/...ers-watch/src/main/java/org/xwiki/notifications/filters/watch/WatchedEntityReference.java b/...ers-watch/src/main/java/org/xwiki/notifications/filters/watch/WatchedEntityReference.java
@@ -52,14 +52,14 @@ enum WatchedStatus
 
         /**
          * The entity is watched for all events and all formats through a filter placed on an ancestor.
-         * @since 16.4.0RC1
+         * @since 16.5.0RC1
          */
         @Unstable
         WATCHED_BY_ANCESTOR_FOR_ALL_EVENTS_AND_FORMATS(true, false),
 
         /**
          * The entity and its children are watched for all events and all formats.
-         * @since 16.4.0RC1
+         * @since 16.5.0RC1
          */
         @Unstable
         WATCHED_WITH_CHILDREN_FOR_ALL_EVENTS_AND_FORMATS(true, false),
@@ -78,21 +78,21 @@ enum WatchedStatus
 
         /**
          * The entity is ignored for all events and all formats through a filter placed on an ancestor.
-         * @since 16.4.0RC1
+         * @since 16.5.0RC1
          */
         @Unstable
         BLOCKED_BY_ANCESTOR_FOR_ALL_EVENTS_AND_FORMATS(false, true),
 
         /**
          * The entity and its children are ignored for all events and all formats.
-         * @since 16.4.0RC1
+         * @since 16.5.0RC1
          */
         @Unstable
         BLOCKED_WITH_CHILDREN_FOR_ALL_EVENTS_AND_FORMATS(false, true),
 
         /**
          * There is a filter for the exact location of the entity but it concerns a subset of event types or formats.
-         * @since 16.4.0RC1
+         * @since 16.5.0RC1
          */
         @Unstable
         CUSTOM(false, false);
@@ -135,10 +135,13 @@ public boolean isBlocked()
      * @param userReference the user for whom to check if the entity is watched or not
      * @return the specific watched status of the entity by the given user
      * @throws NotificationException in case of errors
-     * @since 16.4.0RC1
+     * @since 16.5.0RC1
      */
     @Unstable
-    WatchedStatus getWatchedStatus(UserReference userReference) throws NotificationException;
+    default WatchedStatus getWatchedStatus(UserReference userReference) throws NotificationException
+    {
+        return WatchedStatus.CUSTOM;
+    }
 
     /**
      * Try to retrieve the first ancestor of the location which have a status whose status is watched or blocked.
@@ -151,28 +154,33 @@ public boolean isBlocked()
      * @see WatchedStatus#isWatched()
      * @see WatchedStatus#isBlocked()
      * @throws NotificationException in case of problem for computing the status
-     * @since 16.4.0RC1
+     * @since 16.5.0RC1
      */
     @Unstable
-    Optional<Pair<EntityReference, WatchedStatus>> getFirstFilteredAncestor(UserReference userReference)
-        throws NotificationException;
+    default Optional<Pair<EntityReference, WatchedStatus>> getFirstFilteredAncestor(UserReference userReference)
+        throws NotificationException
+    {
+        return Optional.empty();
+    }
 
     /**
      * @param userReference a user
      * @return {@code true} if the given user watch the current entity reference for any event type or format.
      * @throws NotificationException if an error happens
      * @since 9.9RC1
+     * @deprecated use {@link #getWatchedStatus(UserReference)}.
      */
-    @Deprecated
+    @Deprecated(since = "16.5.0RC1")
     boolean isWatched(DocumentReference userReference) throws NotificationException;
 
     /**
      * @param userReference a user
      * @return {@code true} if the given user watch the current entity reference for all events.
      * @throws NotificationException if an error happens
      * @since 12.8RC1
+     * @deprecated use {@link #getWatchedStatus(UserReference)}.
      */
-    @Deprecated
+    @Deprecated(since = "16.5.0RC1")
     default boolean isWatchedWithAllEventTypes(DocumentReference userReference) throws NotificationException
     {
         return isWatched(userReference);

diff --git a/...s-watch/src/main/java/org/xwiki/notifications/filters/watch/WatchedLocationReference.java b/...s-watch/src/main/java/org/xwiki/notifications/filters/watch/WatchedLocationReference.java
@@ -117,7 +117,15 @@ public WatchedStatus getWatchedStatus(UserReference userReference) throws Notifi
         return getWatchedStatus(userDocReference);
     }
 
-    private WatchedStatus getWatchedStatus(DocumentReference userReference) throws NotificationException
+    /**
+     * Retrieve the specific watched status of an entity for the given user.
+     *
+     * @param userReference the user for whom to check if the entity is watched or not
+     * @return the specific watched status of the entity by the given user
+     * @throws NotificationException in case of errors
+     * @since 15.5RC1
+     */
+    public WatchedStatus getWatchedStatus(DocumentReference userReference) throws NotificationException
     {
         Collection<NotificationFilterPreference> filterPreferences =
             notificationFilterPreferenceManager.getFilterPreferences(userReference);