1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

package Torello.JavaDoc;

import java.io.File;

/**
 * Keeps a copy of the {@code String} as a series of {@code '../'} (Dot-Dot's) the connects a
 * Sub-Directory to some Root Parent-Directory.
 * 
 * <BR /><BR />This class is vital to a (albeit a very small) sub-set of the operations of the
 * Upgrade Process.  When adding links to {@code '.html'}, {@code '.js'} or even Image Files in the
 * Root JavaDoc Directory, a quick way to obtain the necessary Path-{@code String} to the Root
 * Directory can be extremely convenient.
 * 
 * <BR /><BR />An instance of this class is always available from the main class
 * {@link JavaDocHTMLFile}, using the public constant field {@link JavaDocHTMLFile#dotDots}.
 * 
 * <BR /><BR /><B CLASS=JDDescLabel>Example {@code String's}</B>
 * 
 * <BR />Some example of the values maintained by this class would include:
 * 
 * <BR /><TABLE CLASS=JDBriefTable>
 * <TR> <TH>Relative Path String</TH>
 *      <TH>Java-Doc HTML File</TH>
 *      </TR>
 * 
 * <TR> <TD><CODE>"../../"</CODE></TD>
 *      <TD><CODE>javadoc/Torello/HTML/package-summary.html</CODE></TD>
 *      </TR>
 * 
 * <TR> <TD><CODE>"../../"</CODE></TD>
 *      <TD><CODE>javadoc/Torello/Java/package-summary.html</CODE></TD>
 *      </TR>
 * 
 * <TR> <TD><CODE>"../../../../"</CODE></TD>
 *      <TD><CODE>javadoc/Torello/HTML/Tools/Images/ImageScraper.html</CODE></TD>
 *      </TR>
 * 
 * </TABLE>
 */
public class RelativePathStr
{
    /* <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;

    /**
     * Dot-Dot {@code '../../'}, Relative-Path-String from the a Java-Doc Sub-Directory /
     * Package-Directory to the Root JavaDoc-Directory.
     * 
     * <BR /><BR />This {@code String} uses the forward-slash {@code '/'}, which is the Directory
     * Separator used by Web-Browsers in {@code URL's}.
     */
    public final String urls;

    /**
     * Dot-Dot {@code '../../'}, Relative-Path-String from the a Java-Doc Sub-Directory /
     * Package-Directory to the Root JavaDoc-Directory.
     * 
     * <BR /><BR />This is the exact same Relative-Path-String as {@link #urls}, but this
     * {@code String} uses the File-System's {@code File.separator} between separate
     * Directory-Names.
     * 
     * <BR /><BR /><I>This separator may be <B STYLE='color: red;'><I>either</I></B> a {@code '/'}
     * Foward-Slash, or a {@code '\} Backward-Slash.</I>  It is dependent on which Operating-System
     * the Java Virtual Machine is currently running.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>MS-DOS Note:</B>
     * 
     * <BR />Most know that the {@code '/'} Foward-Slash is always used in UNIX, and by
     * Web-Browsers {@code URL's}.  Years ago, however, an MS-DOS / Windows
     * Computer running Java would stick by its choice to use the {@code '\'} as a Path-Separator.
     * 
     * <BR /><BR />In later releases of DOS / Windows, Microsoft actuallh decided to allow either
     * the forward or backward slash as a Path-Separator.  This decision, sort of, makes this class
     * a little superfluous and out-dated.  However, it was decided that choosing which
     * {@code String} to use is best left as a choice to be made by the developer.
     */
    public final String fileSystem;

    public RelativePathStr(final String fileSystem)
    {
        this.fileSystem = fileSystem;

        // String replace(CharSequence target, CharSequence replacement)
        //
        // Replaces each substring of this string that matches the literal target sequence with the
        // specified literal replacement sequence.

        this.urls = fileSystem.replace(File.separator, "/");
    }

    /**
     * Retrieve a {@code String} representation of {@code 'this'} instance's data.
     * @return The contents of this class, converted to a {@code String}
     */
    public String toString()
    {
        return
            "File-System Relative-Path to Root:  " + fileSystem + '\n' +
            "Browsser-URL Relative-Path to Root: " + urls + '\n';
    }

    /**
     * Generates a Hash-Table's Hash-Code for {@code 'this'} instance's data.
     * @return An integer that may be used for hashing {@code 'this'} instance.
     */
    public int hashCode()
    { return fileSystem.hashCode(); }

    /**
     * Checks whether {@code 'this'} equals {@code 'other'}
     * @return {@code TRUE} if {@code 'this'} equals {@code 'other'}
     */
    public boolean equals(Object other)
    {
        if (! RelativePathStr.class.isAssignableFrom(other.getClass())) return false;

        RelativePathStr o = (RelativePathStr) other;

        return this.fileSystem.equals(o.fileSystem) &&  this.urls.equals(o.urls);
    }
}