[234726][apidoc] Update IRemoteFile Javadocs

rse/plugins/org.eclipse.rse.subsystems.files.core/src/org/eclipse/rse/subsystems/files/core/servicesubsystem/AbstractRemoteFile.java

@@ -7,12 +7,13 @@
  *
  * Initial Contributors:
  * The following IBM employees contributed to the Remote System Explorer
- * component that contains this file: David McKnight, Kushal Munir, 
+ * component that contains this file: David McKnight, Kushal Munir,
- * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson, 
+ * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson,
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
- * 
+ *
  * Contributors:
  * David McKnight   (IBM)        - [231209] [api][breaking] IRemoteFile.getSystemConnection() should be changed to IRemoteFile.getHost()
+ * Martin Oberhuber (Wind River) - [234726] Update IRemoteFile Javadocs
  *******************************************************************************/
 
 package org.eclipse.rse.subsystems.files.core.servicesubsystem;
@@ -25,12 +26,12 @@ import org.eclipse.rse.subsystems.files.core.subsystems.IRemoteFileSubSystem;
 import org.eclipse.rse.subsystems.files.core.subsystems.RemoteFile;
 
 
-public abstract class AbstractRemoteFile extends RemoteFile implements IRemoteFile
+public abstract class AbstractRemoteFile extends RemoteFile
 {
 	protected IHostFile _hostFile;
 	protected FileServiceSubSystem _subSystem;
 	protected String _classiciation;
-	
+
 
 	public AbstractRemoteFile(FileServiceSubSystem subSystem, IRemoteFileContext context, IRemoteFile parent, IHostFile hostFile)
 	{
@@ -41,7 +42,7 @@ public abstract class AbstractRemoteFile extends RemoteFile implements IRemoteFi
 		if (_hostFile.isFile() && !_hostFile.isArchive()) // no need to query this again so marking false for stale
     		markStale(false, false);
 	}
-	
+
 	public IRemoteFileSubSystem getParentRemoteFileSubSystem()
 	{
 		return _subSystem;
@@ -105,7 +106,7 @@ public abstract class AbstractRemoteFile extends RemoteFile implements IRemoteFi
 		return _hostFile.getSize();
 	}
 
-	public int compareTo(Object other) throws ClassCastException 
+	public int compareTo(Object other) throws ClassCastException
 	{
 		IRemoteFile otherFile = (IRemoteFile)other;
 		if (otherFile.isFile())
@@ -114,7 +115,7 @@ public abstract class AbstractRemoteFile extends RemoteFile implements IRemoteFi
 			{
 				String otherPath = otherFile.getAbsolutePath();
 				String thisPath = getAbsolutePath();
-		
+
 				return thisPath.compareToIgnoreCase(otherPath);
 			}
 			else
@@ -128,7 +129,7 @@ public abstract class AbstractRemoteFile extends RemoteFile implements IRemoteFi
 			{
 				String otherPath = otherFile.getAbsolutePath();
 				String thisPath = getAbsolutePath();
-		
+
 				return thisPath.compareToIgnoreCase(otherPath);
 			}
 			else
@@ -199,5 +200,5 @@ public abstract class AbstractRemoteFile extends RemoteFile implements IRemoteFi
 		return _hostFile;
 	}
 
-	
+
 }

rse/plugins/org.eclipse.rse.subsystems.files.core/src/org/eclipse/rse/subsystems/files/core/subsystems/IRemoteFile.java

@@ -7,13 +7,14 @@
  *
  * Initial Contributors:
  * The following IBM employees contributed to the Remote System Explorer
- * component that contains this file: David McKnight, Kushal Munir, 
+ * component that contains this file: David McKnight, Kushal Munir,
- * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson, 
+ * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson,
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
- * 
+ *
  * Contributors:
  * David McKnight   (IBM)        - [209593] [api] add support for "file permissions" and "owner" properties for unix files
  * David McKnight   (IBM)        - [231209] [api][breaking] IRemoteFile.getSystemConnection() should be changed to IRemoteFile.getHost()
+ * Martin Oberhuber (Wind River) - [234726] Update IRemoteFile Javadocs
  *******************************************************************************/
 
 package org.eclipse.rse.subsystems.files.core.subsystems;
@@ -26,113 +27,121 @@ import org.eclipse.rse.core.subsystems.IRemotePropertyHolder;
 import org.eclipse.rse.services.files.IHostFile;
 import org.eclipse.rse.services.files.IHostFilePermissions;
 import org.eclipse.rse.subsystems.files.core.model.RemoteFileFilterString;
+import org.eclipse.rse.subsystems.files.core.servicesubsystem.AbstractRemoteFile;
+import org.eclipse.rse.subsystems.files.core.servicesubsystem.IFileServiceSubSystem;
+import org.eclipse.rse.ui.view.ISystemEditableRemoteObject;
 
 /**
  * This interface represents a handle to a remote file system object,
- * which is either a file or a folder. This interface is similar to 
+ * which is either a file or a folder. This interface is similar to
  * a java.io.File object, but with some significant differences:
  * <ul>
- *   <li>This is an interface, so there are no static methods
+ *   <li>This represents a "handle" to the remote file or folder, and allows to
- *   <li>This represents a "handle" to the remote file or folder. For editing purposes,
+ *        mark special folders as "root" of the file system. For editing purposes,
- *        you may want to manage a local copy of the remote file. The support
+ *        a local copy of the remote file can be managed. The support for this is
- *        for this is captured in the child interface IRemoteEditableFile
+ *        captured in a separate interface, {@link ISystemEditableRemoteObject}.
- *   <li>This are no action methods, only read methods. The action methods
+ *   <li>This interface has no action methods, only property access methods. The action methods
- *        such as delete and rename are found in the file subsystem interface.
+ *        such as delete, rename, list or getRemoteFileObject() are found in the 
- *        All remote commands/actions are funnelled through subsystems in this
+ *        {@link IRemoteFileSubSystem} interface. All remote commands/actions are routed
- *        remote system framework.
+ *        through subsystems in this remote system framework.
- *   <li>Similarly, the methods for listing objects are in IRemoteFileSubSystem, not here
+ *   <li>Similarly, IRemoteFile handle objects are not constructed directly. They are obtained
- *   <li>Similarly, the methods for return an IRemoteFile object of the parent folder or
+ *        from factory methods in {@link IRemoteFileSubSystem#getRemoteFileObject(String, org.eclipse.core.runtime.IProgressMonitor)},
- *        root drive are in IRemoteFileSubSystem, not here.
+ *        and related methods, which may delegate the actual object creation to an
- *   <li>Similarly, you do not construct these objects directly. Rather, there are
+ *        {@link IHostFileToRemoteFileAdapter} in case of an {@link IFileServiceSubSystem}
- *        factory methods in IRemoteFileSubSystem to create them.
+ *        instance.
- *   <li>There is no relative names. All names are fully qualified, and include
+ *   <li>There are no relative names. All names are fully qualified, and include
  *        the root, the path and the file name (unless this is a folder).
  *   <li>There are additional methods for querying the root (ie, c:\) and the
  *        parent directory (unqualified name of the parent directory).
  * </ul>
  * <p>
  * Note for subsystem providers: this method does not capture the set methods that the
- * RemoteFileImpl class defines. For that, cast to IRemoteFileMutable.
+ * RemoteFile class defines. For that, cast to {@link RemoteFile}.
- */ 
+ *
+ * @noimplement This interface is not intended to be implemented by clients. Clients
+ *     should subclass the provided {@link RemoteFile} or one of its subclasses
+ *     instead. For use with file services (IFileServiceSubSystem), the
+ *     {@link AbstractRemoteFile} class must be subclassed.
+ */
 public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, ISchedulingRule
 {
     public static final char CONNECTION_DELIMITER = ':';
 	public static final boolean ISROOT_YES = true;
-	public static final boolean ISROOT_NO  = false;	
+	public static final boolean ISROOT_NO  = false;
-	
+
 	/**
 	 * Querying properties for the property sheet can be expensive on some operating systems.
 	 * By default all properties are shown on the property sheet for this object, unless true
 	 * is returned from this query, in which only a couple properties are shown.
 	 */
 	public boolean showBriefPropertySet();
-	
+
 	/**
 	 * 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 getHost();
-    
+
     /**
      * Return the parent remote file object expanded to get this object,
      * or <code>null</code> if no such parent exists.
-     * 
+     *
      * @return the parent remote file object or <code>null</code>.
      */
     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 
+     *  filter. In this case, when the folder is expanded, we want to filter the file names to
-     *  show all the files that match any of the filter strings that have the same parent path. 
+     *  show all the files that match any of the filter strings that have the same parent path.
      * <p>
      * This method supports that by returning all the filter strings in the filter which have the
-     *  same parent path as was used to produce this file. 
+     *  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 
+     * @return the fully qualified path for uniquely addressing this file
-     *     on the remote host. Never returns <code>null</code>. 
+     *     on the remote host. Never returns <code>null</code>.
      */
     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 '.'
@@ -145,13 +154,13 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
      * If this object represents only a root drive, this is the same as getRoot().
      */
     public String getLabel();
-    
+
     /**
      * Get unqualified file name. No root and no path.
      * 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.
@@ -161,17 +170,17 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
      * Example: <code>c:\folder1\folder2\file1.ext</code> results in <code>c:\folder1\folder2</code>
      */
     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. 
+     * Returns the path. No root prefix. No file name, and no ending separator.
      * <p>
      * If this object represent only a root drive, this returns null;
      * <p>
      * Example: <code>c:\folder1\folder2\file1.ext</code> results in <code>folder1\folder2</code>
      */
     public String getParentNoRoot();
-    
+
     /**
      * Get the root part of the name.
      * <p>
@@ -181,7 +190,7 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
      * </ul>
      */
     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.
@@ -190,53 +199,53 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
      * Example: <code>c:\folder1\folder2\file1.ext</code> results in <code>folder2</code>
      */
     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();
-    
+
     /**
      * 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();
-    
+
     /**
      * Returns true if this is a hidden file.
      */
     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.
      */
@@ -246,17 +255,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.
      */
@@ -266,27 +275,27 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
      * Returns true if the ReadOnly Property should be shown in the property page.
      */
     public boolean showReadOnlyProperty();
-   
+
     // ==================================
     // for comparator interface...
-    // ==================================    
+    // ==================================
     /**
      * Compare one remote file to another. This enables us to sort the files so they
      * are shown folders-first, and in alphabetical order.
      */
     public int compareTo(Object other) throws ClassCastException;
-    
+
     /**
      * Get the object.
      */
     public Object getFile();
-    
+
     /**
      * Note: if this remoteFile is the same as the file passed
      * as parameter, then this method returns true.
      */
     public boolean isAncestorOf(IRemoteFile file);
-    
+
 	/**
 	 * Note: if this remoteFile is the same as the file passed
 	 * as parameter, then this method returns true.
@@ -297,51 +306,51 @@ public interface IRemoteFile extends IRemoteContainer, IRemotePropertyHolder, IS
 	 * @return Any comments stored with the file in the file system or archive.
 	 */
     public String getComment();
-      
+
     /**
      * Returns the classification of this file.  If the file is
      * an executable, then "executable(...)" will be returned. If the
      * file is a symbolic link then it will appear as "symbolic link(....):resolvedPath".
      * The resolvedPath is the path that the link resolves to.
-     * A symbolic link that resolves to an executable would appear as 
+     * A symbolic link that resolves to an executable would appear as
      * "symbolic link(executable(...)):resolvedPath".
      * By default this should just return "file" or "directory".
      * @return the classification, or "unknown", or <code>null</code> if not classifiable.
      */
     public String getClassification();
-    
+
     /**
      * Returns whether the file is executable or not.
      * @return <code>true</code> if the file is executable, <code>false</code> otherwise.
      */
     public boolean isExecutable();
-    
+
     /**
      * Returns whether the file is a symbolic link or not.
      * @return <code>true</code> if the file is a symbolic link, <code>false</code> otherwise.
      */
     public boolean isLink();
-    
+
     /**
      * Returns the canonical path of the remote file.
-     * @return the resolved path if the file is a symbolic link, or 
+     * @return the resolved path if the file is a symbolic link, or
      */
     public String getCanonicalPath();
-    
+
     public IHostFile getHostFile();
-    
+
     /**
      * Returns the encoding of the remote file.
      * @return the encoding of the remote file.
      * @since 2.0
      */
     public String getEncoding();
-    
+
     /**
      * Returns the permissions for this file if they exist
      * @return the permissions
      * @since 3.0
      */
     public IHostFilePermissions getPermissions();
-    
+
 }

rse/plugins/org.eclipse.rse.subsystems.files.dstore/src/org/eclipse/rse/internal/subsystems/files/dstore/DStoreFile.java

@@ -7,12 +7,13 @@
  *
  * Initial Contributors:
  * The following IBM employees contributed to the Remote System Explorer
- * component that contains this file: David McKnight, Kushal Munir, 
+ * component that contains this file: David McKnight, Kushal Munir,
- * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson, 
+ * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson,
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
- * 
+ *
  * Contributors:
  * Martin Oberhuber (Wind River) - [168870] refactor org.eclipse.rse.core package of the UI plugin
+ * Martin Oberhuber (Wind River) - [234726] Update IRemoteFile Javadocs
  *******************************************************************************/
 
 package org.eclipse.rse.internal.subsystems.files.dstore;
@@ -31,16 +32,16 @@ import org.eclipse.rse.subsystems.files.core.subsystems.IRemoteFileContext;
 import org.eclipse.rse.subsystems.files.core.subsystems.IRemoteFileSubSystem;
 import org.eclipse.rse.ui.SystemBasePlugin;
 
-public class DStoreFile extends AbstractRemoteFile implements IRemoteFile
+public class DStoreFile extends AbstractRemoteFile
 {
-	
+
 	private DStoreFileService getDStoreFileService()
 	{
 		FileServiceSubSystem ss = (FileServiceSubSystem)_context.getParentRemoteFileSubSystem();
 		return (DStoreFileService)ss.getFileService();
 	}
-	
+
-	public IRemoteFile getParentRemoteFile() 
+	public IRemoteFile getParentRemoteFile()
 	{
 		// because this can get called by eclipse from the main thread, and dstore can have problems with main-thread queries,
 		// this is overridden to provide a parent without doing the actual query
@@ -50,17 +51,17 @@ public class DStoreFile extends AbstractRemoteFile implements IRemoteFile
     		{
     			return null;
     		}
-    		
+
 	    	IRemoteFile parentFile = null;
 
 	    	String pathOnly = getParentPath();
 	    	if (pathOnly != null)
-	    	{    	  
+	    	{
 	    	  DStoreFileService fileService = getDStoreFileService();
 	     	  IRemoteFileSubSystem ss = _context.getParentRemoteFileSubSystem();
 	    	  if (ss != null)
 	    	  {
-	    		  
+
 	    	  	try {
 		    	  	char sep = getSeparatorChar();
 		    	  	if (pathOnly.length() == 0)
@@ -75,7 +76,7 @@ public class DStoreFile extends AbstractRemoteFile implements IRemoteFile
 		    	  	{
 		    	  		// parentFile is already null
 		    	  		//parentFile = null;
-		    	  		
+
 		    	  		IHostFile hostParent = fileService.getHostFile(pathOnly);
 		    	  		if (hostParent == null)
 		    	  		{
@@ -111,10 +112,10 @@ public class DStoreFile extends AbstractRemoteFile implements IRemoteFile
 		    	  				parentName = pathOnly.substring(nameSep + 1);
 		    	  				parentPath = "" + sep; //$NON-NLS-1$
 		    	  			}
-		    	  		
+
 		    	  			DataElement element = ds.createObject(null, IUniversalDataStoreConstants.UNIVERSAL_FOLDER_DESCRIPTOR, parentName);
 		    	  			element.setAttribute(DE.A_VALUE, parentPath);
-		    	  			    	  	
+
 		    	  			hostParent = new DStoreHostFile(element);
 		    	  		}
 		    	  		parentFile = new DStoreFile((FileServiceSubSystem)ss, _context, (IRemoteFile)null, (DStoreHostFile)hostParent);
@@ -123,8 +124,8 @@ public class DStoreFile extends AbstractRemoteFile implements IRemoteFile
 		            else
 		            {
 		            	DataStore ds = _dstoreHostFile.getDataElement().getDataStore();
-		            	
+
-	    	  		
+
 		            	IHostFile hostParent = fileService.getHostFile(pathOnly);
 		    	  		if (hostParent == null)
 		    	  		{
@@ -145,13 +146,13 @@ public class DStoreFile extends AbstractRemoteFile implements IRemoteFile
 		    	  				parentName = pathOnly.substring(nameSep + 1);
 		    	  				parentPath = "" + sep; //$NON-NLS-1$
 		    	  			}
-		    	  		
+
 		    	  			DataElement element = ds.createObject(null, IUniversalDataStoreConstants.UNIVERSAL_FOLDER_DESCRIPTOR, parentName);
 		    	  			element.setAttribute(DE.A_VALUE, parentPath);
 		    	  			hostParent = new DStoreHostFile(element);
 		    	  		}
 		            	parentFile = new DStoreFile((FileServiceSubSystem)ss, _context, (IRemoteFile)null, (DStoreHostFile)hostParent);
-		            	
+
 		              //parentFile = ss.getRemoteFileObject(pathOnly);
 		            }
 	    	  	} catch (Exception e) {
@@ -178,7 +179,7 @@ public class DStoreFile extends AbstractRemoteFile implements IRemoteFile
 		super(ss,context, parent, hostFile);
 		_dstoreHostFile = hostFile;
 	}
-	
+
 	public boolean isVirtual()
 	{
 		DataElement element = _dstoreHostFile.getDataElement();

rse/plugins/org.eclipse.rse.subsystems.files.local/src/org/eclipse/rse/internal/subsystems/files/local/model/LocalFile.java

@@ -13,6 +13,7 @@
  *
  * Contributors:
  * Martin Oberhuber (Wind River) - [187571] Classification is empty for local directories
+ * Martin Oberhuber (Wind River) - [234726] Update IRemoteFile Javadocs
  *******************************************************************************/
 
 package org.eclipse.rse.internal.subsystems.files.local.model;
@@ -26,7 +27,7 @@ import org.eclipse.rse.subsystems.files.core.subsystems.IRemoteFileContext;
 
 
 
-public class LocalFile extends AbstractRemoteFile implements IRemoteFile
+public class LocalFile extends AbstractRemoteFile
 {
 	protected LocalHostFile _localHostFile;
 	protected String _classification;