001/*
002 * file Location.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * (c) Copyright IBM Corporation 2004, 2008.  All Rights Reserved. 
008 * Note to U.S. Government Users Restricted Rights:  Use, duplication or  
009 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp. 
010 */
011package javax.wvcm;
012
013/**
014 * The location of a resource.
015 * <p>
016 * The format of the location string is specific to the repository that stores
017 * the persistent resource.  A URL, a UNC filename, and an NFS filename
018 * are examples of possible formats for a location string.  Locations are
019 * constructed by the {@link Provider#location} method. </p>
020 * <p>
021 * All methods in this interface are implemented in-memory only, i.e.,
022 * no access to the repository is required. </p>
023 * 
024 * @since 1.0
025 */
026public interface Location {
027
028    /**
029     * Return a string value for this Location.
030     * The {@link Provider#location} method
031     * is the inverse of this method, i.e., 
032     * <code>location.equals(Provider.location(location.string()))</code>.
033     * 
034     * @return a string value for this Location.
035     */
036    public String string();
037
038    /**
039     * Return the location of a folder that has the resource at
040     * this Location as a bound member whose binding name is
041     * the lastSegment of this Location.
042     * 
043     * @return the location of a folder that has the resource at
044     * this Location as a bound member whose binding name is
045     * the lastSegment of this Location.
046     * If this Location has no parent, <code>null</code> is returned.
047     */
048    public Location parent();
049
050    /**
051     * Return the location of the bound member with the specified
052     * bindingName in the folder at this Location.
053     * 
054     * @param bindingName the name of the bound member.
055     * The last segment of the returned location must be bindingName.
056     * The bindingName commonly is not allowed to contain the "/" character.
057     * @return the location of the bound member with the specified
058     * binding name in the folder at this Location.
059     * @throws WvcmException
060     * if this Location is not one that can have bound members,
061     * or if the bindingName is not syntactically valid.
062     */
063    public Location child(String bindingName) throws WvcmException;
064
065    /**
066     * Get the last segment of this Location.
067     * If the {@link #parent} is <code>null</code>, the {@link #lastSegment} is <code>null</code>.
068     * In general, if <code>loc</code> is a Location that has a parent,
069     * <code>loc.parent().child(loc.lastSegment()).equals(loc)</code>.
070     * 
071     * @return the last segment of this Location.
072     * Commonly, this is the portion following the last "/" in
073     * the string value of this Location.
074     */
075    public String lastSegment();
076}
077
078
079