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;
023    
024    import java.util.Collection;
025    import java.util.List;
026    import java.util.Map;
027    import net.jcip.annotations.Immutable;
028    import org.jboss.dna.graph.properties.Name;
029    import org.jboss.dna.graph.properties.Path;
030    import org.jboss.dna.graph.properties.Property;
031    
032    /**
033     * A node in a {@link Graph graph}, with methods to access the properties and children.
034     * 
035     * @author Randall Hauch
036     */
037    @Immutable
038    public interface Node extends Iterable<Location> {
039    
040        /**
041         * Get the graph containing the node.
042         * 
043         * @return the graph
044         */
045        Graph getGraph();
046    
047        /**
048         * Get the location of the node.
049         * 
050         * @return the node's location
051         */
052        Location getLocation();
053    
054        /**
055         * Get the properties on the node.
056         * 
057         * @return the properties
058         */
059        Collection<Property> getProperties();
060    
061        /**
062         * Get the property with the supplied name.
063         * 
064         * @param name the property name
065         * @return the property, or null if there is no property by that name
066         */
067        Property getProperty( String name );
068    
069        /**
070         * Get the property with the supplied name.
071         * 
072         * @param name the property name
073         * @return the property, or null if there is no property by that name
074         */
075        Property getProperty( Name name );
076    
077        /**
078         * Get the map of properties keyed by the property names.
079         * 
080         * @return the map of properties keyed by property name
081         */
082        Map<Name, Property> getPropertiesByName();
083    
084        /**
085         * Get the children of the node.
086         * 
087         * @return the list of locations for each child
088         */
089        List<Location> getChildren();
090    
091        /**
092         * Get the list of child {@link Path.Segment segments}.
093         * 
094         * @return the list containing a segment for each child
095         */
096        List<Path.Segment> getChildrenSegments();
097    
098        /**
099         * Return whether this node has children.
100         * 
101         * @return true if the node has children, or false otherwise
102         */
103        boolean hasChildren();
104    
105    }