1 /**
2 * This file Copyright (c) 2014-2018 Magnolia International
3 * Ltd. (http://www.magnolia-cms.com). All rights reserved.
4 *
5 *
6 * This file is dual-licensed under both the Magnolia
7 * Network Agreement and the GNU General Public License.
8 * You may elect to use one or the other of these licenses.
9 *
10 * This file is distributed in the hope that it will be
11 * useful, but AS-IS and WITHOUT ANY WARRANTY; without even the
12 * implied warranty of MERCHANTABILITY or FITNESS FOR A
13 * PARTICULAR PURPOSE, TITLE, or NONINFRINGEMENT.
14 * Redistribution, except as permitted by whichever of the GPL
15 * or MNA you select, is prohibited.
16 *
17 * 1. For the GPL license (GPL), you can redistribute and/or
18 * modify this file under the terms of the GNU General
19 * Public License, Version 3, as published by the Free Software
20 * Foundation. You should have received a copy of the GNU
21 * General Public License, Version 3 along with this program;
22 * if not, write to the Free Software Foundation, Inc., 51
23 * Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
24 *
25 * 2. For the Magnolia Network Agreement (MNA), this file
26 * and the accompanying materials are made available under the
27 * terms of the MNA which accompanies this distribution, and
28 * is available at http://www.magnolia-cms.com/mna.html
29 *
30 * Any modifications to this file must keep this entire header
31 * intact.
32 *
33 */
34 package info.magnolia.module.delta;
35
36 import info.magnolia.jcr.util.NodeUtil;
37 import info.magnolia.jcr.util.NodeVisitor;
38 import info.magnolia.module.InstallContext;
39
40 import javax.jcr.Node;
41 import javax.jcr.RepositoryException;
42 import javax.jcr.Session;
43
44 import org.apache.jackrabbit.commons.predicate.Predicate;
45
46 /**
47 * The <code>NodeVisitorTask</code> helps traversing a repository, match nodes and execute changes on them.
48 * <p>
49 * This is intended to replace {@link QueryTask} for most cases, since query results may not account for pending changes in the session (e.g. coming from earlier deltas).
50 */
51 public abstract class NodeVisitorTask extends AbstractRepositoryTask {
52
53 private final String workspace;
54 private final String absPath;
55
56 public NodeVisitorTask(String name, String description, String workspace, String absPath) {
57 super(name, description);
58 this.workspace = workspace;
59 this.absPath = absPath;
60 }
61
62 @Override
63 protected void doExecute(final InstallContext installContext) throws RepositoryException, TaskExecutionException {
64
65 // get node where we should start visiting
66 Session session = installContext.getJCRSession(workspace);
67 Node node = session.getNode(absPath);
68
69 // visitor to help decoupling matching from operating logic
70 NodeVisitor.html#NodeVisitor">NodeVisitor visitor = new NodeVisitor() {
71 @Override
72 public void visit(Node node) throws RepositoryException {
73 if (nodeMatches(node)) {
74 operateOnNode(installContext, node);
75 }
76 }
77 };
78
79 // predicate defining where we should stop visiting the hierarchy
80 Predicate predicate = getFilteringPredicate();
81
82 NodeUtil.visit(node, visitor, predicate);
83 }
84
85 /**
86 * Implement this method to define which nodes should subsequently be operated upon.
87 * <p>
88 * This will be called for every visited node in that task, and serves a similar purpose as a JCR query statement.
89 *
90 * @param node the JCR node that is currently being visited
91 * @return <code>true</code> if the node should be operated upon, <code>false</code> otherwise
92 * @see #operateOnNode(InstallContext, Node)
93 */
94 protected abstract boolean nodeMatches(Node node);
95
96 /**
97 * Implement this method to apply changes to each of the nodes that are matched by {@link #nodeMatches(Node)}.
98 * <p>
99 * This is typically where the update logic goes, in a similar fashion as the {@link QueryTask}.
100 *
101 * @param installContext the current install context
102 * @param node the JCR node that should be operated upon
103 * @see QueryTask#operateOnNode(InstallContext, Node)
104 */
105 protected abstract void operateOnNode(InstallContext installContext, Node node);
106
107 /**
108 * Override this method to specify a {@link Predicate} where we should stop visiting the hierarchy, e.g. to restrict node-types.
109 * <p>
110 * Mind that whatever the predicate, <b>the starting node is always visited by {@link NodeUtil}, even if it doesn't match the predicate</b>.
111 *
112 * @return by default, the constant predicate that returns <code>true</code> for all objects.
113 */
114 protected Predicate getFilteringPredicate() {
115 return Predicate.TRUE;
116 }
117 }