null if {@link #isRoot()} is true.
@@ -44,16 +46,19 @@ public interface IHostFile {
public String getParentPath();
/**
- * Gets the fully qualified path to this object in the remote file system. The name is constructed
- * as it would be used on the remote file system.
- * @return a string representing the path name. This string can be interpreted and used by its file service
- * to locate this object on the remote file system beginning
- * at the file system root.
+ * Gets the fully qualified path to this object in the remote file system.
+ *
+ * The name is constructed as it would be used on the remote file system.
+ * This string can be interpreted and used by its file service to locate
+ * this object on the remote file system beginning at the file system root.
+ *
+ * @return a String representing the path name. Never returns null.
*/
public String getAbsolutePath();
/**
* Determines if the file system object is hidden on the remote file system.
+ *
* @return true if and only if the file on the remote system has a "hidden" attribute or a naming
* convention that would normal indicate that it was hidden when listing the contents of its parent
* on that file system. It is up to the file services to conform to the correct notion of "hidden" for
@@ -63,6 +68,7 @@ public interface IHostFile {
/**
* Determines if the file system object is a directory on the remote file system.
+ *
* @return true if and only if the object on the remote system is a directory. That is, it contains
* entries that can be interpreted as other IHostFile objects. A return value of true does not
* necessarily imply that isFile() returns false.
@@ -71,6 +77,7 @@ public interface IHostFile {
/**
* Determines if the file system object is a "root" directory on the remote file system.
+ *
* @return true if and only if the object on the remote system is a directory whose simple name and
* absolute path name are the same.
*/
@@ -78,6 +85,7 @@ public interface IHostFile {
/**
* Determines if the file system object is a file on the remote file system.
+ *
* @return true if and only if the object on the remote system can be considered to have "contents" that
* have the potential to be read and written as a byte or character stream. A return value of true
* does not necessarily imply that {@link #isDirectory()} returns false.
@@ -86,6 +94,7 @@ public interface IHostFile {
/**
* Determines if the file system object is "writeable" on the remote file system.
+ *
* @return true if and only if the object on the remote system is a file that can be written. This could
* mean that there is write permission granted to this user or perhaps a "writable" attribute is set for the
* file. It is up to the file services to conform to the correct notion of "writable" for the remote
@@ -96,6 +105,7 @@ public interface IHostFile {
/**
* Determines if the file system object is "readable" on the remote file system.
+ *
* @return true if and only if the object on the remote system is a file that can be read. This could
* mean that there is read permission granted to this user or perhaps a "readable" attribute is set for the
* file. It is up to the file services to conform to the correct notion of "readable" for the remote
@@ -106,6 +116,7 @@ public interface IHostFile {
/**
* Determines if the file system object exists on the remote file system.
+ *
* @return true if and only if the remote object represented by this object exists
* in the remote file system. Symbolic links on a UNIX file system exist even if
* the target they point to does not exist.
@@ -114,6 +125,7 @@ public interface IHostFile {
/**
* Determines if the file system object represents an archive on the remote file system.
+ *
* @return true if and only if the remote object is a file that can be "extracted" to contain other files.
* Examples would be tar and zip files. It is up to the file services to conform to the correct notion of
* "archive" for the remote systems they support. If a file service creates an object with
@@ -124,13 +136,15 @@ public interface IHostFile {
/**
* Gets the size of the file system object on the remote file system in bytes if isFile() is true.
* If the storage unit on the remote system is not bytes then the file service creating this must
- * convert the remote value to bytes.
+ * convert the remote value to bytes.
+ *
* @return the size in bytes of the file if {@link #isFile()} is true, 0L otherwise.
*/
public long getSize();
/**
* Gets a timestamp representing the date and time of last modification to the file.
+ *
* @return the timestamp as obtained from the remote file system.
* The timestamp represents the time the file was modified in milliseconds from January 1, 1970, 00:00:00 UTC.
* Note that even so, comparison of timestamps between systems should be avoided since clock resolution and
diff --git a/rse/plugins/org.eclipse.rse.subsystems.files.core/src/org/eclipse/rse/subsystems/files/core/subsystems/IRemoteFile.java b/rse/plugins/org.eclipse.rse.subsystems.files.core/src/org/eclipse/rse/subsystems/files/core/subsystems/IRemoteFile.java
index e8293352036..48a5e2c341e 100644
--- a/rse/plugins/org.eclipse.rse.subsystems.files.core/src/org/eclipse/rse/subsystems/files/core/subsystems/IRemoteFile.java
+++ b/rse/plugins/org.eclipse.rse.subsystems.files.core/src/org/eclipse/rse/subsystems/files/core/subsystems/IRemoteFile.java
@@ -64,37 +64,55 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
* is returned from this query, in which only a couple properties are shown.
*/
public boolean showBriefPropertySet();
+
/**
- * Get parent subsystem
+ * Get parent subsystem.
+ *
+ * @return the Subsystem holding this file.
*/
public IRemoteFileSubSystem getParentRemoteFileSubSystem();
+
/**
* Return the separator character for this file system: \ or /.
* Queries it from the subsystem factory.
+ *
+ * @return the separator character for this file system.
*/
public char getSeparatorChar();
+
/**
* Return the separator character for this file system, as a string: "\" or "/".
* Queries it from the subsystem factory.
+ *
+ * @return the separator character for this file system as a String.
*/
+
public String getSeparator();
+
/**
* Return as a string the line separator for this file system
* Queries it from the subsystem factory.
*/
public String getLineSeparator();
+
/**
* Return the connection this remote file is from.
*/
public IHost getSystemConnection();
+
/**
- * Return the parent remote file object expanded to get this object, or null if no such parent
+ * Return the parent remote file object expanded to get this object,
+ * or null if no such parent exists.
+ *
+ * @return the parent remote file object or null.
*/
public IRemoteFile getParentRemoteFile();
+
/**
* Return the filter string resolved to get this object
*/
public RemoteFileFilterString getFilterString();
+
/**
* If this is a folder, it is possible that it is listed as part of a multiple filter string
* filter. In this case, when the folder is expanded, we want to filter the file names to
@@ -104,10 +122,15 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
* same parent path as was used to produce this file.
*/
public RemoteFileFilterString[] getAllFilterStrings();
+
/**
* Get fully qualified name: root plus path plus name. No connection name.
+ *
+ * @return the fully qualified path for uniquely addressing this file
+ * on the remote host. Never returns null.
*/
public String getAbsolutePath();
+
/**
* Get fully qualified connection and file name: profile.connection\path\file.
* Note the separator character between the profile name and the connection name is always '.'
@@ -126,6 +149,7 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
* If this object represents only a root drive, this is the same as getRoot().
*/
public String getName();
+
/**
* Get fully qualified path and name of folder containing this file or folder.
* Returns the root and path. No file name, and no ending separator.
@@ -135,6 +159,7 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
* Example: c:\folder1\folder2\file1.ext results in c:\folder1\folder2
*/
public String getParentPath();
+
/**
* Get fully qualified path and name of folder containing this file or folder, minus the root.
* Returns the path. No root prefix. No file name, and no ending separator.
@@ -143,7 +168,8 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
*
* Example: c:\folder1\folder2\file1.ext results in folder1\folder2
*/
- public String getParentNoRoot();
+ public String getParentNoRoot();
+
/**
* Get the root part of the name.
*
@@ -153,6 +179,7 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
*
*/
public String getRoot();
+
/**
* Get the unqualified name of the parent directory containing this file or folder.
* Compare this to getParent() that returns the fully qualified parent directory.
@@ -161,45 +188,53 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
* Example: c:\folder1\folder2\file1.ext results in folder2
*/
public String getParentName();
+
/**
* Return the extension part of a file name.
* Eg, for abc.java, return "java"
*/
public String getExtension();
+
/**
* Returns true if this represents a root folder (eg: c:\\ or /).
*/
public boolean isRoot();
+
/**
* Returns true if this represents a folder (eg: c:\\folder)
*/
public boolean isDirectory();
+
/**
* Returns true if this represents a file, versus a root or folder
*/
- public boolean isFile();
+ public boolean isFile();
+
/**
* Returns true if this represents an archive file, versues a non-archive file
*/
public boolean isArchive();
-
/**
* Returns true if this is a binary file
*/
public boolean isBinary();
+
/**
* Returns true if this is a text file
*/
- public boolean isText();
+ public boolean isText();
+
/**
* Returns true if this is a hidden file.
*/
- public boolean isHidden();
+ public boolean isHidden();
+
/**
* Returns true if the application can read this file.
*/
public boolean canRead();
+
/**
* Returns true if the application can write to this file.
*/
@@ -209,14 +244,17 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
* Returns true if this folder or file actually exists.
*/
public boolean exists();
+
/**
* Returns the time (in milliseconds since epoch) this file was last modified.
*/
public long getLastModified();
+
/**
* Return the last modified time as a Date object.
*/
public Date getLastModifiedDate() ;
+
/**
* Returns the length, in bytes, of this file.
*/