001/*
002 * ModeShape (http://www.modeshape.org)
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *       http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.modeshape.schematic.document;
017
018import org.modeshape.schematic.annotation.Immutable;
019
020/**
021 * The path to a field somewhere within a document.
022 * 
023 * @author Randall Hauch <rhauch@redhat.com> (C) 2011 Red Hat Inc.
024 */
025@Immutable
026public interface Path extends Iterable<String>, Comparable<Path> {
027
028    /**
029     * Get a particular segment within this path.
030     * 
031     * @param segmentNumber the 0-based index of the segment in this path
032     * @return the segment; never null
033     * @throws IndexOutOfBoundsException if the segment number is negative, or greater than or equal to the {@link #size() size}.
034     */
035    String get( int segmentNumber );
036
037    /**
038     * Get the last segment in the path.
039     * 
040     * @return the field name in the last segment of this path, or null if this is the empty path
041     */
042    String getLast();
043
044    /**
045     * Get the first segment in the path.
046     * 
047     * @return the field name in the first segment of this path, or null if this is the empty path
048     */
049    String getFirst();
050
051    /**
052     * Get the number of segments in this path. An empty path with have a size of '0'.
053     * 
054     * @return the size of this path; never negative
055     */
056    int size();
057
058    /**
059     * Obtain a path that has this path as the parent and which has as the last segment the supplied field name.
060     * 
061     * @param fieldName the field name for the last segment in the new path; may be null
062     * @return the new path, or this path if the <code>fieldName</code> parameter is null; never null
063     */
064    Path with( String fieldName );
065
066    /**
067     * Get the parent path, which may be an empty path.
068     * 
069     * @return the parent path; never null
070     */
071    Path parent();
072
073    /**
074     * Determine if the first segments of this path are equal to the segments in the supplied path. This method returns true if
075     * the two paths are equal, or if the supplied path is an ancestor of this path.
076     * 
077     * @param other the other path; may not be null
078     * @return true if the other path is equal to or an ancestor of this path, or false otherwise
079     */
080    boolean startsWith( Path other );
081
082}