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