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.jcr.cache;
025    
026    import java.util.Iterator;
027    import java.util.UUID;
028    import org.jboss.dna.graph.property.Name;
029    import org.jboss.dna.graph.property.Path;
030    
031    /**
032     * Class that maintains the ordered list of {@link ChildNode} instances yet allows fast access to the children with a specified
033     * name.
034     */
035    public interface Children extends Iterable<ChildNode> {
036    
037        /**
038         * Get the number of children.
039         * 
040         * @return the number of children
041         */
042        int size();
043    
044        /**
045         * The UUID of the parent node.
046         * 
047         * @return the parent node's UUID
048         */
049        UUID getParentUuid();
050    
051        /**
052         * Get the child with the given UUID.
053         * 
054         * @param uuid the UUID of the child node
055         * @return the child node, or null if there is no child with the supplied UUID
056         */
057        ChildNode getChild( UUID uuid );
058    
059        /**
060         * Get the child given the path segment.
061         * 
062         * @param segment the path segment for the child, which includes the {@link Path.Segment#getName() name} and
063         *        {@link Path.Segment#getIndex() one-based same-name-sibling index}; may not be null
064         * @return the information for the child node, or null if no such child existed
065         */
066        ChildNode getChild( Path.Segment segment );
067    
068        /**
069         * Get the same-name-sibling children that all share the supplied name, in order of increasing SNS index.
070         * 
071         * @param name the name for the children; may not be null
072         * @return the children with the supplied name; never null
073         */
074        Iterator<ChildNode> getChildren( Name name );
075    
076        /**
077         * Get the number of same-name-siblings that all share the supplied name.
078         * 
079         * @param name the name for the children; may not be null
080         * @return the number of same-name-siblings with the supplied name
081         */
082        int getCountOfSameNameSiblingsWithName( Name name );
083    
084    }