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}