[MAGNOLIA-6314] Enhance javadoc of ObservationUtil.registerChangeListener for parameter "nodeTypes" Created: 21/Jul/15  Updated: 15/Apr/16  Resolved: 14/Oct/15

Status: Closed
Project: Magnolia
Component/s: core
Affects Version/s: 5.3.10, 5.4
Fix Version/s: 5.3.12, 5.4.3

Type: Improvement Priority: Neutral
Reporter: Christian Ringele Assignee: Mikaël Geljić
Resolution: Done Votes: 0
Labels: quickwin, support
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
relation
Template:
Acceptance criteria:
Empty
Task DoD:
[ ]* Doc/release notes changes? Comment present?
[ ]* Downstream builds green?
[ ]* Solution information and context easily available?
[ ]* Tests
[ ]* FixVersion filled and not yet released
[ ]  Architecture Decision Record (ADR)
Date of First Response:
Sprint: Basel 15
Story Points: 1

 Description   

A customer got confused by the Javadoc of this parameter:
@param nodeTypes the node types to filter events for

It lead him to the assumption:
"Right now it says "nodeTypes the node types to filter events for" and we interpreted that to mean we'd only receive events for those node types, but actually it's the exact opposite."

The code of JCR using this parameter is:
org.apache.jackrabbit.core.observation.EventFilter.blocks(EventState)

To this code parts:

// check node types
        if (nodeTypes != null) {
            Set<NodeType> eventTypes = eventState.getNodeTypes(session.getNodeTypeManager());
            boolean match = false;
            for (int i = 0; i < nodeTypes.length && !match; i++) {
                for (NodeType eventType : eventTypes) {
                    NodeTypeImpl nodeType = (NodeTypeImpl) eventType;
                    match |= nodeType.getQName().equals(nodeTypes[i].getQName())
                            || nodeType.isDerivedFrom(nodeTypes[i].getQName());
                }
            }
            if (!match) {
                return true;
            }
        }

See support issue for further information.



 Comments   
Comment by Mikaël Geljić [ 09/Oct/15 ]

This is not exactly correct. In fact, we just delegate to JCR's ObservationManager#addEventListener. Here's what the spec says:

nodeTypeName: Only events whose associated parent node has one of the node types (or a subtype of one of the node types) in this list will be received.

Concretely, given you *add* the following nodes to the root, and you observe mgnl:page:

page (*)
├── page (*)
└── area
  • You will not receive any NODE_ADDED event for /page
    • ... because its parent (the root node) is not an mgnl:page.
    • but you will receive several PROPERTY_ADDED events for its system and magnolia properties, like /page/jcr:uuid.
  • You will receive a NODE_ADDED event for /page/page
    • + PROPERTY_ADDED events, e.g. /page/page/jcr:uuid
  • You will also receive a NODE_ADDED event for /page/area, but no PROPERTY_ADDED events below it.

... and I have a test-case that proves all of this

Meanwhile, I propose not to document the ObservationUtil params ourselves anymore, but point to those parameters in the JCR spec.
In the long run, I would like to deprecate most of ObservationUtil (except for DeferredEventListeners maybe), in favor of direct usage of JCR's ObservationManager.

Cheers!
Mika

Generated at Mon Feb 12 04:13:20 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.