001package Torello.JavaDoc;
002
003import java.io.File;
004
005/**
006 * Keeps a copy of the {@code String} as a series of {@code '../'} (Dot-Dot's) the connects a
007 * Sub-Directory to some Root Parent-Directory.
008 * 
009 * <BR /><BR />This class is vital to a (albeit a very small) sub-set of the operations of the
010 * Upgrade Process.  When adding links to {@code '.html'}, {@code '.js'} or even Image Files in the
011 * Root JavaDoc Directory, a quick way to obtain the necessary Path-{@code String} to the Root
012 * Directory can be extremely convenient.
013 * 
014 * <BR /><BR />An instance of this class is always available from the main class
015 * {@link JavaDocHTMLFile}, using the public constant field {@link JavaDocHTMLFile#dotDots}.
016 * 
017 * <BR /><BR /><B CLASS=JDDescLabel>Example {@code String's}</B>
018 * 
019 * <BR />Some example of the values maintained by this class would include:
020 * 
021 * <BR /><TABLE CLASS=JDBriefTable>
022 * <TR> <TH>Relative Path String</TH>
023 *      <TH>Java-Doc HTML File</TH>
024 *      </TR>
025 * 
026 * <TR> <TD><CODE>"../../"</CODE></TD>
027 *      <TD><CODE>javadoc/Torello/HTML/package-summary.html</CODE></TD>
028 *      </TR>
029 * 
030 * <TR> <TD><CODE>"../../"</CODE></TD>
031 *      <TD><CODE>javadoc/Torello/Java/package-summary.html</CODE></TD>
032 *      </TR>
033 * 
034 * <TR> <TD><CODE>"../../../../"</CODE></TD>
035 *      <TD><CODE>javadoc/Torello/HTML/Tools/Images/ImageScraper.html</CODE></TD>
036 *      </TR>
037 * 
038 * </TABLE>
039 */
040public class RelativePathStr
041{
042    /* <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
043    protected static final long serialVersionUID = 1;
044
045    /**
046     * Dot-Dot {@code '../../'}, Relative-Path-String from the a Java-Doc Sub-Directory /
047     * Package-Directory to the Root JavaDoc-Directory.
048     * 
049     * <BR /><BR />This {@code String} uses the forward-slash {@code '/'}, which is the Directory
050     * Separator used by Web-Browsers in {@code URL's}.
051     */
052    public final String urls;
053
054    /**
055     * Dot-Dot {@code '../../'}, Relative-Path-String from the a Java-Doc Sub-Directory /
056     * Package-Directory to the Root JavaDoc-Directory.
057     * 
058     * <BR /><BR />This is the exact same Relative-Path-String as {@link #urls}, but this
059     * {@code String} uses the File-System's {@code File.separator} between separate
060     * Directory-Names.
061     * 
062     * <BR /><BR /><I>This separator may be <B STYLE='color: red;'><I>either</I></B> a {@code '/'}
063     * Foward-Slash, or a {@code '\} Backward-Slash.</I>  It is dependent on which Operating-System
064     * the Java Virtual Machine is currently running.
065     * 
066     * <BR /><BR /><B CLASS=JDDescLabel>MS-DOS Note:</B>
067     * 
068     * <BR />Most know that the {@code '/'} Foward-Slash is always used in UNIX, and by
069     * Web-Browsers {@code URL's}.  Years ago, however, an MS-DOS / Windows
070     * Computer running Java would stick by its choice to use the {@code '\'} as a Path-Separator.
071     * 
072     * <BR /><BR />In later releases of DOS / Windows, Microsoft actuallh decided to allow either
073     * the forward or backward slash as a Path-Separator.  This decision, sort of, makes this class
074     * a little superfluous and out-dated.  However, it was decided that choosing which
075     * {@code String} to use is best left as a choice to be made by the developer.
076     */
077    public final String fileSystem;
078
079    public RelativePathStr(final String fileSystem)
080    {
081        this.fileSystem = fileSystem;
082
083        // String replace(CharSequence target, CharSequence replacement)
084        //
085        // Replaces each substring of this string that matches the literal target sequence with the
086        // specified literal replacement sequence.
087
088        this.urls = fileSystem.replace(File.separator, "/");
089    }
090
091    /**
092     * Retrieve a {@code String} representation of {@code 'this'} instance's data.
093     * @return The contents of this class, converted to a {@code String}
094     */
095    public String toString()
096    {
097        return
098            "File-System Relative-Path to Root:  " + fileSystem + '\n' +
099            "Browsser-URL Relative-Path to Root: " + urls + '\n';
100    }
101
102    /**
103     * Generates a Hash-Table's Hash-Code for {@code 'this'} instance's data.
104     * @return An integer that may be used for hashing {@code 'this'} instance.
105     */
106    public int hashCode()
107    { return fileSystem.hashCode(); }
108
109    /**
110     * Checks whether {@code 'this'} equals {@code 'other'}
111     * @return {@code TRUE} if {@code 'this'} equals {@code 'other'}
112     */
113    public boolean equals(Object other)
114    {
115        if (! RelativePathStr.class.isAssignableFrom(other.getClass())) return false;
116
117        RelativePathStr o = (RelativePathStr) other;
118
119        return this.fileSystem.equals(o.fileSystem) &&  this.urls.equals(o.urls);
120    }
121}