| package li.cil.oc.api; |
| |
| import li.cil.oc.api.network.EnvironmentHost; |
| import li.cil.oc.api.fs.Label; |
| import li.cil.oc.api.network.ManagedEnvironment; |
| |
| /** |
| * This class provides factory methods for creating file systems that are |
| * compatible with the built-in file system driver. |
| * <p/> |
| * File systems created this way and wrapped in a managed environment via |
| * {@link #asManagedEnvironment} or its overloads will appear as |
| * <tt>filesystem</tt> components in the component network. Note that the |
| * component's visibility is set to <tt>Neighbors</tt> per default. If you wish |
| * to change the file system's visibility (e.g. like the disk drive does) you |
| * must cast the environment's node to {@link li.cil.oc.api.network.Component} |
| * and set the visibility to the desired value. |
| * <p/> |
| * Note that these methods should <em>not</em> be called in the pre-init phase, |
| * since the {@link li.cil.oc.api.API#fileSystem} may not have been initialized |
| * at that time. Only start calling these methods in the init phase or later. |
| */ |
| public final class FileSystem { |
| /** |
| * Creates a new file system based on the location of a class. |
| * <p/> |
| * This can be used to wrap a folder in the assets folder of your mod's JAR. |
| * The actual path is built like this: |
| * <pre>"/assets/" + domain + "/" + root</pre> |
| * <p/> |
| * If the class is located in a JAR file, this will create a read-only file |
| * system based on that JAR file. If the class file is located in the native |
| * file system, this will create a read-only file system first trying from |
| * the actual location of the class file, and failing that by searching the |
| * class path (i.e. it'll look for a path constructed as described above). |
| * <p/> |
| * If the specified path cannot be located, the creation fails and this |
| * returns <tt>null</tt>. |
| * |
| * @param clazz the class whose containing JAR to wrap. |
| * @param domain the domain, usually your mod's ID. |
| * @param root an optional subdirectory. |
| * @return a file system wrapping the specified folder. |
| */ |
| public static li.cil.oc.api.fs.FileSystem fromClass(final Class<?> clazz, final String domain, final String root) { |
| if (API.fileSystem != null) |
| return API.fileSystem.fromClass(clazz, domain, root); |
| return null; |
| } |
| |
| /** |
| * Creates a new <em>writable</em> file system in the save folder. |
| * <p/> |
| * This will create a folder, if necessary, and create a writable virtual |
| * file system based in that folder. The actual path is based in a sub- |
| * folder of the save folder. The actual path is built like this: |
| * <pre>"saves/" + WORLD_NAME + "/opencomputers/" + root</pre> |
| * The first part may differ, in particular for servers. |
| * <p/> |
| * Usually the name will be the address of the node used to represent the |
| * file system. |
| * <p/> |
| * Note that by default file systems are "buffered", meaning that any |
| * changes made to them are only saved to disk when the world is saved. This |
| * ensured that the file system contents do not go "out of sync" when the |
| * game crashes, but introduces additional memory overhead, since all files |
| * in the file system have to be kept in memory. |
| * |
| * @param root the name of the file system. |
| * @param capacity the amount of space in bytes to allow being used. |
| * @param buffered whether data should only be written to disk when saving. |
| * @return a file system wrapping the specified folder. |
| */ |
| public static li.cil.oc.api.fs.FileSystem fromSaveDirectory(final String root, final long capacity, final boolean buffered) { |
| if (API.fileSystem != null) |
| return API.fileSystem.fromSaveDirectory(root, capacity, buffered); |
| return null; |
| } |
| |
| /** |
| * Same as {@link #fromSaveDirectory(String, long, boolean)} with the |
| * <tt>buffered</tt> parameter being true, i.e. will always create a |
| * buffered file system. |
| * |
| * @param root the name of the file system. |
| * @param capacity the amount of space in bytes to allow being used. |
| * @return a file system wrapping the specified folder. |
| */ |
| public static li.cil.oc.api.fs.FileSystem fromSaveDirectory(final String root, final long capacity) { |
| return fromSaveDirectory(root, capacity, true); |
| } |
| |
| /** |
| * Creates a new <em>writable</em> file system that resides in memory. |
| * <p/> |
| * Any contents created and written on this file system will be lost when |
| * the node is removed from the network. |
| * <p/> |
| * This is used for computers' <tt>/tmp</tt> mount, for example. |
| * |
| * @param capacity the capacity of the file system. |
| * @return a file system residing in memory. |
| */ |
| public static li.cil.oc.api.fs.FileSystem fromMemory(final long capacity) { |
| if (API.fileSystem != null) |
| return API.fileSystem.fromMemory(capacity); |
| return null; |
| } |
| |
| /** |
| * Wrap a file system retrieved via one of the <tt>from???</tt> methods to |
| * make it read-only. |
| * |
| * @param fileSystem the file system to wrap. |
| * @return the specified file system wrapped to be read-only. |
| */ |
| public static li.cil.oc.api.fs.FileSystem asReadOnly(final li.cil.oc.api.fs.FileSystem fileSystem) { |
| if (API.fileSystem != null) |
| return API.fileSystem.asReadOnly(fileSystem); |
| return null; |
| } |
| |
| /** |
| * Creates a network node that makes the specified file system available via |
| * the common file system driver. |
| * <p/> |
| * This can be useful for providing some data if you don't wish to implement |
| * your own driver. Which will probably be most of the time. If you need |
| * more control over the node, implement your own, and connect this one to |
| * it. In that case you will have to forward any disk driver messages to the |
| * node, though. |
| * <p/> |
| * The container parameter is used to give the file system some physical |
| * relation to the world, for example this is used by hard drives to send |
| * the disk event notifications to the client that are used to play disk |
| * 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. 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, int speed) { |
| if (API.fileSystem != null) |
| return API.fileSystem.asManagedEnvironment(fileSystem, label, host, accessSound, speed); |
| return null; |
| } |
| |
| /** |
| * 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 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, int speed) { |
| if (API.fileSystem != null) |
| return API.fileSystem.asManagedEnvironment(fileSystem, label, host, accessSound, speed); |
| return null; |
| } |
| |
| /** |
| * 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) { |
| return asManagedEnvironment(fileSystem, label, null, null, 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, 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) { |
| return asManagedEnvironment(fileSystem, label, null, null, 1); |
| } |
| |
| /** |
| * 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) { |
| return asManagedEnvironment(fileSystem, (Label) null, null, null, 1); |
| } |
| |
| // ----------------------------------------------------------------------- // |
| |
| private FileSystem() { |
| } |
| } |