Extended file system API to allow specifying a speed multiplier for f…

…ile systems.

For now, valid range is [1,6]. Floppies use 1, HDDs use 2-4, Raid is 6.
Deprecated some internal FileSystem interface methods to allow simplifying the interface a bit when the time comes.
Let's hope nobody is shipping the API \o/

src/main/java/li/cil/oc/api/API.java

@@ -16,7 +16,7 @@
  */
 public class API {
     public static final String ID_OWNER = "OpenComputers|Core";
-    public static final String VERSION = "5.1.1";
+    public static final String VERSION = "5.2.0";
 
     public static DriverAPI driver = null;
     public static FileSystemAPI fileSystem = null;

src/main/java/li/cil/oc/api/FileSystem.java

@@ -141,6 +141,17 @@ public static li.cil.oc.api.fs.FileSystem fromComputerCraft(final Object mount)
      * access sounds.
      * <p/>
      * The container may be <tt>null</tt>, if no such context can be provided.
+     * <p/>
+     * The access sound is the name of the sound effect to play when the file
+     * system is accessed, for example by listing a directory or reading from
+     * a file. It may be <tt>null</tt> to create a silent file system.
+     * <p/>
+     * The speed multiplier controls how fast read and write operations on the
+     * file system are. It must be a value in [1,6], and controls the access
+     * speed, with the default being one.
+     * For reference, floppies are using the default, hard drives scale with
+     * their tiers, i.e. a tier one hard drive uses speed two, tier three uses
+     * speed four.
      *
      * @param fileSystem  the file system to wrap.
      * @param label       the label of the file system.
@@ -149,73 +160,121 @@ public static li.cil.oc.api.fs.FileSystem fromComputerCraft(final Object mount)
      *                    system is accessed. This has to be the fully
      *                    qualified resource name, e.g.
      *                    <tt>opencomputers:floppy_access</tt>.
+     * @param speed       the speed multiplier for this file system.
      * @return the network node wrapping the file system.
      */
-    public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem, final Label label, final EnvironmentHost host, final String accessSound) {
+    public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem, final Label label, final EnvironmentHost host, final String accessSound, int speed) {
         if (API.fileSystem != null)
-            return API.fileSystem.asManagedEnvironment(fileSystem, label, host, accessSound);
+            return API.fileSystem.asManagedEnvironment(fileSystem, label, host, accessSound, speed);
         return null;
     }
 
     /**
-     * Like {@link #asManagedEnvironment(li.cil.oc.api.fs.FileSystem, Label, li.cil.oc.api.driver.EnvironmentHost, String)},
-     * but creates a read-only label initialized to the specified value.
+     * Creates a network node that makes the specified file system available via
+     * the common file system driver.
+     * <p/>
+     * Creates a file system with the a read-only label and the specified
+     * access sound and file system speed.
      *
      * @param fileSystem  the file system to wrap.
-     * @param label       the read-only label of the file system.
+     * @param label       the label of the file system.
      * @param host        the tile entity containing the file system.
      * @param accessSound the name of the sound effect to play when the file
      *                    system is accessed. This has to be the fully
      *                    qualified resource name, e.g.
      *                    <tt>opencomputers:floppy_access</tt>.
+     * @param speed       the speed multiplier for this file system.
      * @return the network node wrapping the file system.
      */
-    public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem, final String label, final EnvironmentHost host, final String accessSound) {
+    public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem, final String label, final EnvironmentHost host, final String accessSound, int speed) {
         if (API.fileSystem != null)
-            return API.fileSystem.asManagedEnvironment(fileSystem, label, host, accessSound);
+            return API.fileSystem.asManagedEnvironment(fileSystem, label, host, accessSound, speed);
         return null;
     }
 
     /**
-     * Like {@link #asManagedEnvironment(li.cil.oc.api.fs.FileSystem, Label, li.cil.oc.api.driver.EnvironmentHost, String)},
-     * but does not provide a container.
+     * Creates a network node that makes the specified file system available via
+     * the common file system driver.
+     * <p/>
+     * Creates a file system with the specified label and the specified access
+     * sound, using the default file system speed.
+     *
+     * @param fileSystem  the file system to wrap.
+     * @param label       the label of the file system.
+     * @param host        the tile entity containing the file system.
+     * @param accessSound the name of the sound effect to play when the file
+     *                    system is accessed. This has to be the fully
+     *                    qualified resource name, e.g.
+     *                    <tt>opencomputers:floppy_access</tt>.
+     * @return the network node wrapping the file system.
+     */
+    public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem, final Label label, final EnvironmentHost host, final String accessSound) {
+        return asManagedEnvironment(fileSystem, label, host, accessSound, 1);
+    }
+
+    /**
+     * Creates a network node that makes the specified file system available via
+     * the common file system driver.
+     * <p/>
+     * Creates a file system with a read-only label and the specified access
+     * sound, using the default file system speed.
+     *
+     * @param fileSystem  the file system to wrap.
+     * @param label       the read-only label of the file system.
+     * @param host        the tile entity containing the file system.
+     * @param accessSound the name of the sound effect to play when the file
+     *                    system is accessed. This has to be the fully
+     *                    qualified resource name, e.g.
+     *                    <tt>opencomputers:floppy_access</tt>.
+     * @return the network node wrapping the file system.
+     */
+    public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem, final String label, final EnvironmentHost host, final String accessSound) {
+        return asManagedEnvironment(fileSystem, label, host, accessSound, 1);
+    }
+
+    /**
+     * Creates a network node that makes the specified file system available via
+     * the common file system driver.
+     * <p/>
+     * Creates a file system with the specified label, without an environment
+     * and access sound, using the default file system speed.
      *
      * @param fileSystem the file system to wrap.
      * @param label      the label of the file system.
      * @return the network node wrapping the file system.
      */
     public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem, final Label label) {
-        if (API.fileSystem != null)
-            return API.fileSystem.asManagedEnvironment(fileSystem, label);
-        return null;
+        return asManagedEnvironment(fileSystem, label, null, null, 1);
     }
 
     /**
-     * Like {@link #asManagedEnvironment(li.cil.oc.api.fs.FileSystem, Label)},
-     * but creates a read-only label initialized to the specified value.
+     * Creates a network node that makes the specified file system available via
+     * the common file system driver.
+     * <p/>
+     * Creates a file system with a read-only label, without an environment and
+     * access sound, using the default file system speed.
      *
      * @param fileSystem the file system to wrap.
      * @param label      the read-only label of the file system.
      * @return the network node wrapping the file system.
      */
     public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem, final String label) {
-        if (API.fileSystem != null)
-            return API.fileSystem.asManagedEnvironment(fileSystem, label);
-        return null;
+        return asManagedEnvironment(fileSystem, label, null, null, 1);
     }
 
     /**
-     * Like {@link #asManagedEnvironment(li.cil.oc.api.fs.FileSystem, Label)},
-     * but creates an unlabeled file system (i.e. the label can neither be read
-     * nor written).
+     * Creates a network node that makes the specified file system available via
+     * the common file system driver.
+     * <p/>
+     * Creates an unlabeled file system (i.e. the label can neither be read nor
+     * written), without an environment and access sound, using the default
+     * file system speed.
      *
      * @param fileSystem the file system to wrap.
      * @return the network node wrapping the file system.
      */
     public static ManagedEnvironment asManagedEnvironment(final li.cil.oc.api.fs.FileSystem fileSystem) {
-        if (API.fileSystem != null)
-            return API.fileSystem.asManagedEnvironment(fileSystem);
-        return null;
+        return asManagedEnvironment(fileSystem, (Label) null, null, null, 1);
     }
 
     // ----------------------------------------------------------------------- //

src/main/java/li/cil/oc/api/detail/FileSystemAPI.java

@@ -97,56 +97,76 @@ public interface FileSystemAPI {
      * access sounds.
      * <p/>
      * The container may be <tt>null</tt>, if no such context can be provided.
+     * <p/>
+     * The access sound is the name of the sound effect to play when the file
+     * system is accessed, for example by listing a directory or reading from
+     * a file. It may be <tt>null</tt> to create a silent file system.
+     * <p/>
+     * The speed multiplier controls how fast read and write operations on the
+     * file system are. It must be a value in [1,6], and controls the access
+     * speed, with the default being one.
+     * For reference, floppies are using the default, hard drives scale with
+     * their tiers, i.e. a tier one hard drive uses speed two, tier three uses
+     * speed four.
      *
      * @param fileSystem  the file system to wrap.
      * @param label       the label of the file system.
      * @param host        the tile entity containing the file system.
      * @param accessSound the name of the sound effect to play when the file
-     *                    system is accessed.
+     *                    system is accessed. This has to be the fully
+     *                    qualified resource name, e.g.
+     *                    <tt>opencomputers:floppy_access</tt>.
+     * @param speed       the speed multiplier for this file system.
      * @return the network node wrapping the file system.
      */
-    ManagedEnvironment asManagedEnvironment(FileSystem fileSystem, Label label, EnvironmentHost host, String accessSound);
+    ManagedEnvironment asManagedEnvironment(FileSystem fileSystem, Label label, EnvironmentHost host, String accessSound, int speed);
 
     /**
-     * Like {@link #asManagedEnvironment(li.cil.oc.api.fs.FileSystem, Label, li.cil.oc.api.driver.EnvironmentHost, String)},
-     * but creates a read-only label initialized to the specified value.
+     * Creates a network node that makes the specified file system available via
+     * the common file system driver.
+     * <p/>
+     * Creates a file system with the a read-only label and the specified
+     * access sound and file system speed.
      *
      * @param fileSystem  the file system to wrap.
      * @param label       the read-only label of the file system.
      * @param host        the tile entity containing the file system.
      * @param accessSound the name of the sound effect to play when the file
-     *                    system is accessed.
+     *                    system is accessed. This has to be the fully
+     *                    qualified resource name, e.g.
+     *                    <tt>opencomputers:floppy_access</tt>.
+     * @param speed       the speed multiplier for this file system.
      * @return the network node wrapping the file system.
      */
+    ManagedEnvironment asManagedEnvironment(FileSystem fileSystem, String label, EnvironmentHost host, String accessSound, int speed);
+
+    /**
+     * @deprecated Don't use this directly, use the wrapper in {@link li.cil.oc.api.FileSystem}.
+     */
+    @Deprecated
+    ManagedEnvironment asManagedEnvironment(FileSystem fileSystem, Label label, EnvironmentHost host, String accessSound);
+
+    /**
+     * @deprecated Don't use this directly, use the wrapper in {@link li.cil.oc.api.FileSystem}.
+     */
+    @Deprecated
     ManagedEnvironment asManagedEnvironment(FileSystem fileSystem, String label, EnvironmentHost host, String accessSound);
 
     /**
-     * Like {@link #asManagedEnvironment(li.cil.oc.api.fs.FileSystem, Label, li.cil.oc.api.driver.EnvironmentHost, String)},
-     * but does not provide a container and access sound.
-     *
-     * @param fileSystem the file system to wrap.
-     * @param label      the label of the file system.
-     * @return the network node wrapping the file system.
+     * @deprecated Don't use this directly, use the wrapper in {@link li.cil.oc.api.FileSystem}.
      */
+    @Deprecated
     ManagedEnvironment asManagedEnvironment(FileSystem fileSystem, Label label);
 
     /**
-     * Like {@link #asManagedEnvironment(li.cil.oc.api.fs.FileSystem, Label)},
-     * but creates a read-only label initialized to the specified value.
-     *
-     * @param fileSystem the file system to wrap.
-     * @param label      the read-only label of the file system.
-     * @return the network node wrapping the file system.
+     * @deprecated Don't use this directly, use the wrapper in {@link li.cil.oc.api.FileSystem}.
      */
+    @Deprecated
     ManagedEnvironment asManagedEnvironment(FileSystem fileSystem, String label);
 
     /**
-     * Like {@link #asManagedEnvironment(li.cil.oc.api.fs.FileSystem, Label)},
-     * but creates an unlabeled file system (i.e. the label can neither be read
-     * nor written).
-     *
-     * @param fileSystem the file system to wrap.
-     * @return the network node wrapping the file system.
+     * @deprecated Don't use this directly, use the wrapper in {@link li.cil.oc.api.FileSystem}.
      */
+    @Deprecated
     ManagedEnvironment asManagedEnvironment(FileSystem fileSystem);
 }

src/main/java/li/cil/oc/api/fs/Label.java

@@ -5,7 +5,7 @@
 /**
  * Used by file system components to get and set the file system's label.
  *
- * @see li.cil.oc.api.FileSystem#asManagedEnvironment(FileSystem, Label)
+ * @see li.cil.oc.api.FileSystem#asManagedEnvironment
  */
 public interface Label extends Persistable {
     /**

src/main/scala/li/cil/oc/common/tileentity/Raid.scala

@@ -81,7 +81,7 @@ class Raid extends traits.Environment with traits.Inventory with traits.Rotatabl
       filesystem.foreach(fs => if (fs.node != null) fs.node.remove())
       val fs = api.FileSystem.asManagedEnvironment(
         api.FileSystem.fromSaveDirectory(id, wipeDisksAndComputeSpace, Settings.get.bufferChanges),
-        label, this, Settings.resourceDomain + ":hdd_access").
+        label, this, Settings.resourceDomain + ":hdd_access", 6).
         asInstanceOf[FileSystem]
       val nbtToSetAddress = new NBTTagCompound()
       nbtToSetAddress.setString("address", id)

src/main/scala/li/cil/oc/integration/opencomputers/DriverFileSystem.scala

@@ -22,8 +22,8 @@ object DriverFileSystem extends Item {
 
   override def createEnvironment(stack: ItemStack, host: EnvironmentHost) =
     Delegator.subItem(stack) match {
-      case Some(hdd: HardDiskDrive) => createEnvironment(stack, hdd.kiloBytes * 1024, host)
-      case Some(disk: FloppyDisk) => createEnvironment(stack, Settings.get.floppySize * 1024, host)
+      case Some(hdd: HardDiskDrive) => createEnvironment(stack, hdd.kiloBytes * 1024, host, hdd.tier + 2)
+      case Some(disk: FloppyDisk) => createEnvironment(stack, Settings.get.floppySize * 1024, host, 1)
       case _ => null
     }
 
@@ -40,14 +40,14 @@ object DriverFileSystem extends Item {
       case _ => 0
     }
 
-  private def createEnvironment(stack: ItemStack, capacity: Int, host: EnvironmentHost) = {
+  private def createEnvironment(stack: ItemStack, capacity: Int, host: EnvironmentHost, speed: Int) = {
     // We have a bit of a chicken-egg problem here, because we want to use the
     // node's address as the folder name... so we generate the address here,
     // if necessary. No one will know, right? Right!?
     val address = addressFromTag(dataTag(stack))
     val isFloppy = api.Items.get(stack) == api.Items.get(Constants.ItemName.Floppy)
     val fs = oc.api.FileSystem.fromSaveDirectory(address, capacity, Settings.get.bufferChanges)
-    val environment = oc.api.FileSystem.asManagedEnvironment(fs, new ReadWriteItemLabel(stack), host, Settings.resourceDomain + ":" + (if (isFloppy) "floppy_access" else "hdd_access"))
+    val environment = oc.api.FileSystem.asManagedEnvironment(fs, new ReadWriteItemLabel(stack), host, Settings.resourceDomain + ":" + (if (isFloppy) "floppy_access" else "hdd_access"), speed)
     if (environment != null && environment.node != null) {
       environment.node.asInstanceOf[oc.server.network.Node].address = address
     }