1 /*
2 * ModeShape (http://www.modeshape.org)
3 * See the COPYRIGHT.txt file distributed with this work for information
4 * regarding copyright ownership. Some portions may be licensed
5 * to Red Hat, Inc. under one or more contributor license agreements.
6 * See the AUTHORS.txt file in the distribution for a full listing of
7 * individual contributors.
8 *
9 * ModeShape is free software. Unless otherwise indicated, all code in ModeShape
10 * is licensed to you under the terms of the GNU Lesser General Public License as
11 * published by the Free Software Foundation; either version 2.1 of
12 * the License, or (at your option) any later version.
13 *
14 * ModeShape is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this software; if not, write to the Free
21 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
22 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
23 */
24 package org.modeshape.repository.sequencer;
25
26 import java.util.Set;
27 import net.jcip.annotations.ThreadSafe;
28 import org.modeshape.common.collection.Problems;
29 import org.modeshape.common.component.Component;
30 import org.modeshape.graph.Node;
31 import org.modeshape.graph.io.Destination;
32 import org.modeshape.graph.observe.Observer;
33 import org.modeshape.graph.observe.NetChangeObserver.NetChange;
34 import org.modeshape.repository.RepositoryLibrary;
35 import org.modeshape.repository.util.RepositoryNodePath;
36
37 /**
38 * The interface for a ModeShape sequencer, which sequences nodes and their content to extract additional information from the
39 * information.
40 * <p>
41 * Implementations must provide a no-argument constructor.
42 * </p>
43 */
44 @ThreadSafe
45 public interface Sequencer extends Component<SequencerConfig> {
46
47 /**
48 * Execute the sequencing operation on the supplied node, which has recently been created or changed. The implementation of
49 * this method is responsible for modifying the appropriate nodes and {@link Destination#submit() saving} any changes made by
50 * this sequencer, and closing any other acquired resources, even in the case of exceptions.
51 * <p>
52 * The {@link SequencingService} determines the sequencers that should be executed by monitoring the changes to one or more
53 * workspaces (it registers an {@link Observer} with the {@link RepositoryLibrary}). Changes in those workspaces are
54 * aggregated for each transaction, and organized into {@link NetChange changes for each node}. The SequencingService then
55 * determines for each {@link NetChange set of changes to a node} the set of full paths to the properties that have changed
56 * and whether those paths {@link SequencerPathExpression#matcher(String) match} the sequencer's
57 * {@link SequencerConfig#getPathExpressions() path expressions}. Each path expression produces the path to the output node,
58 * and these output paths are accumulated and (with the original node that changed, the node change summary, and other
59 * information) supplied to the sequencer via this method.
60 * <p>
61 * It is possible that a sequencer is configured to apply to multiple properties on a node. So, in cases where multiple
62 * properties are changed on a single node (within a single repository transaction), the sequencer will only be executed once.
63 * Also, in such cases the sequencer's configuration may imply multiple output nodes, so it is left to the sequencer to define
64 * the behavior in such cases.
65 * </p>
66 *
67 * @param input the node that has recently been created or changed; never null
68 * @param sequencedPropertyName the name of the property that caused this sequencer to be executed; never null and never empty
69 * @param changes the immutable summary of changes that occurred on the <code>input</code> node within the transaction; never
70 * null
71 * @param outputPaths the paths to the nodes where the sequencing content should be placed; never null and never empty, but
72 * the set may contain paths for non-existent nodes or may reference the <code>input</code> node
73 * @param context the context in which this sequencer is executing; never null
74 * @param problems the interface used for recording problems; never null
75 * @throws SequencerException if there is an error in this sequencer
76 */
77 void execute( Node input,
78 String sequencedPropertyName,
79 NetChange changes,
80 Set<RepositoryNodePath> outputPaths,
81 SequencerContext context,
82 Problems problems ) throws SequencerException;
83
84 }