001    /*
002     * JBoss DNA (http://www.jboss.org/dna)
003     * See the COPYRIGHT.txt file distributed with this work for information
004     * regarding copyright ownership.  Some portions may be licensed
005     * to Red Hat, Inc. under one or more contributor license agreements.
006     * See the AUTHORS.txt file in the distribution for a full listing of 
007     * individual contributors.
008     *
009     * Unless otherwise indicated, all code in JBoss DNA is licensed
010     * to you under the terms of the GNU Lesser General Public License as
011     * published by the Free Software Foundation; either version 2.1 of
012     * the License, or (at your option) any later version.
013     * 
014     * JBoss DNA is distributed in the hope that it will be useful,
015     * but WITHOUT ANY WARRANTY; without even the implied warranty of
016     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
017     * Lesser General Public License for more details.
018     *
019     * You should have received a copy of the GNU Lesser General Public
020     * License along with this software; if not, write to the Free
021     * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
022     * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
023     */
024    package org.jboss.dna.graph.io;
025    
026    import java.util.List;
027    import net.jcip.annotations.NotThreadSafe;
028    import org.jboss.dna.graph.ExecutionContext;
029    import org.jboss.dna.graph.property.Path;
030    import org.jboss.dna.graph.property.Property;
031    
032    /**
033     * Interface used internally as the destination for the requests. This is used to abstract whether the requests should be
034     * submitted immediately or in a single batch.
035     * 
036     * @author Randall Hauch
037     */
038    @NotThreadSafe
039    public interface Destination {
040    
041        /**
042         * Obtain the execution context of the destination.
043         * 
044         * @return the destination's execution context
045         */
046        public ExecutionContext getExecutionContext();
047    
048        /**
049         * Create a node at the supplied path and with the supplied attributes. The path will be absolute.
050         * 
051         * @param path the absolute path of the node
052         * @param properties the properties for the node; never null, but may be empty if there are no properties
053         */
054        public void create( Path path,
055                            List<Property> properties );
056    
057        /**
058         * Create a node at the supplied path and with the supplied attributes. The path will be absolute.
059         * 
060         * @param path the absolute path of the node
061         * @param firstProperty the first property
062         * @param additionalProperties the remaining properties for the node
063         */
064        public void create( Path path,
065                            Property firstProperty,
066                            Property... additionalProperties );
067    
068        /**
069         * Sets the given properties on the node at the supplied path. The path will be absolute.
070         * 
071         * @param path the absolute path of the node
072         * @param properties the remaining properties for the node
073         */
074        public void setProperties( Path path,
075                                   Property... properties );
076    
077        /**
078         * Signal to this destination that any enqueued create requests should be submitted. Usually this happens at the end of the
079         * document parsing, but an implementer must allow for it to be called multiple times and anytime during parsing.
080         */
081        public void submit();
082    }