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     */
011    package 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     */
026    public 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