[234726][apidoc] Update IRemoteFile Javadocs

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

@@ -13,6 +13,7 @@
  *
  * 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,7 +26,7 @@ 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;

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

@@ -14,6 +14,7 @@
  * 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,33 +27,41 @@ 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
  * 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
 {

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

@@ -13,6 +13,7 @@
  *
  * 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,7 +32,7 @@ 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()

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;