001 /*
002 * JBoss, Home of Professional Open Source.
003 * Copyright 2008, Red Hat Middleware LLC, and individual contributors
004 * as indicated by the @author tags. See the copyright.txt file in the
005 * distribution for a full listing of individual contributors.
006 *
007 * This is free software; you can redistribute it and/or modify it
008 * under the terms of the GNU Lesser General Public License as
009 * published by the Free Software Foundation; either version 2.1 of
010 * the License, or (at your option) any later version.
011 *
012 * This software is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * You should have received a copy of the GNU Lesser General Public
018 * License along with this software; if not, write to the Free
019 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021 */
022 package org.jboss.dna.repository.sequencers;
023
024 import java.util.Set;
025 import javax.jcr.Node;
026 import javax.jcr.RepositoryException;
027 import javax.jcr.Session;
028 import net.jcip.annotations.ThreadSafe;
029 import org.jboss.dna.common.component.Component;
030 import org.jboss.dna.common.monitor.ProgressMonitor;
031 import org.jboss.dna.repository.observation.NodeChange;
032 import org.jboss.dna.repository.observation.NodeChangeListener;
033 import org.jboss.dna.repository.observation.NodeChanges;
034 import org.jboss.dna.repository.observation.ObservationService;
035 import org.jboss.dna.repository.util.JcrExecutionContext;
036 import org.jboss.dna.repository.util.RepositoryNodePath;
037
038 /**
039 * The interface for a DNA sequencer, which sequences nodes and their content to extract additional information from the
040 * information.
041 * <p>
042 * Implementations must provide a no-argument constructor.
043 * </p>
044 * @author Randall Hauch
045 */
046 @ThreadSafe
047 public interface Sequencer extends Component<SequencerConfig> {
048
049 /**
050 * Execute the sequencing operation on the supplied node, which has recently been created or changed. The implementation of
051 * this method is responsible for {@link JcrExecutionContext#getSessionFactory() getting sessions}, modifying the appropriate
052 * nodes, {@link Session#save() saving} any changes made by this sequencer, and {@link Session#logout() closing} all sessions
053 * (and any other acquired resources), even in the case of {@link ProgressMonitor#isCancelled() cancellation} or exceptions.
054 * <p>
055 * The {@link SequencingService} determines the sequencers that should be executed by monitoring the changes to one or more
056 * workspaces (it is a {@link NodeChangeListener} registered with the {@link ObservationService}). Changes in those
057 * workspaces are aggregated for each transaction, and organized into {@link NodeChanges changes for each node}. The
058 * SequencingService then determines for each {@link NodeChange set of changes to a node} the set of full paths to the
059 * properties that have changed and whether those paths {@link SequencerPathExpression#matcher(String) match} the sequencer's
060 * {@link SequencerConfig#getPathExpressions() path expressions}. Each path expression produces the path to the output node,
061 * and these output paths are accumulated and (with the original node that changed, the node change summary, and other
062 * information) supplied to the sequencer via this method.
063 * <p>
064 * It is possible that a sequencer is configured to apply to multiple properties on a node. So, in cases where multiple
065 * properties are changed on a single node (within a single repository transaction), the sequencer will only be executed once.
066 * Also, in such cases the sequencer's configuration may imply multiple output nodes, so it is left to the sequencer to define
067 * the behavior in such cases.
068 * </p>
069 * <p>
070 * This operation should report progress to the supplied {@link ProgressMonitor}. At the beginning of the operation, call
071 * {@link ProgressMonitor#beginTask(double, org.jboss.dna.common.i18n.I18n, Object...)} with a meaningful message describing
072 * the operation and a total for the amount of work that will be done by this sequencer. Then perform the sequencing work,
073 * periodically reporting work by specifying the {@link ProgressMonitor#worked(double) amount of work} that has was just
074 * completed or by {@link ProgressMonitor#createSubtask(double) creating a subtask} and reporting work against that subtask
075 * monitor.
076 * </p>
077 * <p>
078 * The implementation should also periodically check whether the operation has been
079 * {@link ProgressMonitor#isCancelled() cancelled}. If this method returns true, the implementation should abort all work as
080 * soon as possible and close any resources that were acquired or opened.
081 * </p>
082 * <p>
083 * Finally, the implementation should call {@link ProgressMonitor#done()} when the operation has finished.
084 * </p>
085 * @param input the node that has recently been created or changed; never null
086 * @param sequencedPropertyName the name of the property that caused this sequencer to be executed; never null and never empty
087 * @param changes the immutable summary of changes that occurred on the <code>input</code> node within the transaction;
088 * never null
089 * @param outputPaths the paths to the nodes where the sequencing content should be placed; never null and never empty, but
090 * the set may contain paths for non-existant nodes or may reference the <code>input</code> node
091 * @param context the context in which this sequencer is executing; never null
092 * @param progress the progress monitor that should be kept updated with the sequencer's progress and that should be
093 * frequently consulted as to whether this operation has been {@link ProgressMonitor#isCancelled() cancelled}.
094 * @throws RepositoryException if there is a problem while working with the repository
095 * @throws SequencerException if there is an error in this sequencer
096 */
097 void execute( Node input, String sequencedPropertyName, NodeChange changes, Set<RepositoryNodePath> outputPaths, JcrExecutionContext context, ProgressMonitor progress )
098 throws RepositoryException, SequencerException;
099
100 }