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.graph.sequencers;
023    
024    import org.jboss.dna.graph.properties.Name;
025    import org.jboss.dna.graph.properties.Path;
026    
027    /**
028     * Interface for sequencers to use to generate their output.
029     * 
030     * @author Randall Hauch
031     * @author John Verhaeg
032     */
033    public interface SequencerOutput {
034    
035        /**
036         * Set the supplied property on the supplied node.
037         * <p>
038         * The {@link SequencerContext#getValueFactories() value factories} should be used to create paths, names, and values. These
039         * factories can be used to create new values or convert values from one property type to another. (Note that each of the
040         * factories have methods that create values from all of the property types.)
041         * </p>
042         * <p>
043         * This method is provided as a convenience, but it identical to creating a {@link Path} and {@link Name} using the
044         * {@link SequencerContext#getValueFactories() factories} and calling {@link #setProperty(Path, Name, Object...)}.
045         * </p>
046         * 
047         * @param nodePath the path to the node containing the property; may not be null
048         * @param propertyName the name of the property to be set
049         * @param values the value(s) for the property; may be empty if any existing property is to be removed
050         */
051        void setProperty( String nodePath,
052                          String propertyName,
053                          Object... values );
054    
055        /**
056         * Set the supplied reference on the supplied node.
057         * <p>
058         * This method is provided as a convenience, but it identical to creating a {@link Path} and {@link Name} using the
059         * {@link SequencerContext#getValueFactories() factories} and calling {@link #setProperty(Path, Name, Object...)}.
060         * </p>
061         * 
062         * @param nodePath the path to the node containing the property; may not be null
063         * @param propertyName the name of the property to be set
064         * @param paths the paths to the referenced property, which may be absolute paths or relative to the sequencer output node;
065         *        may be empty if any existing property is to be removed
066         */
067        void setReference( String nodePath,
068                           String propertyName,
069                           String... paths );
070    
071        /**
072         * Set the supplied property on the supplied node.
073         * <p>
074         * The {@link SequencerContext#getValueFactories() value factories} should be used to create paths, names, and values. These
075         * factories can be used to create new values or convert values from one property type to another. (Note that each of the
076         * factories have methods that create values from all of the property types.)
077         * </p>
078         * 
079         * @param nodePath the path to the node containing the property; may not be null
080         * @param propertyName the name of the property to be set
081         * @param values the value(s) for the property; may be empty if any existing property is to be removed
082         */
083        void setProperty( Path nodePath,
084                          Name propertyName,
085                          Object... values );
086    }