StorageProxy

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.ocap.storage
Interface StorageProxy

    public interface StorageProxy

This interface represents a persistent storage device. The current set of storage proxies is queried from the `StorageManager`.

A StorageProxy may contain one or more logical volumes. See `LogicalStorageVolume`. A LogicalStorageVolume is a construct for organizing files on a disk and corresponds to a directory subtree that is treated as a whole for some purposes. A StorageProxy only represents the application visible storage on the device, i.e. it does not include portions of the device reserved for internal system use.

If this proxy represents a detachable or hot-pluggable device, the proxy is not listed until the device is connected. When a storage device is attached, the proxy is added to the list returned by the StorageManager and an appropriate event is sent to any `StorageManagerListener` registered with the `StorageManager`. When a storage device is no longer available for use (or for reactivation after being made detachable), the corresponding proxy is removed from the StorageManager's list and a `StorageManagerEvent` is sent to any StorageManagerListeners registered with the StorageManager.

Field Summary
`static int` | `BUSY` Returned by `getStatus()` to indicate that the device is busy, e.g., being initialized, configured, checked for consistency or being made ready to detach.
`static int` | `DEVICE_ERROR` Returned by `getStatus()` to indicate that the device is in an unrecoverable error state and cannot be used.
`static int` | `NOT_PRESENT` Returned by `getStatus()` to indicate that a detected storage device bay does not contain a removable storage device, i.e.
`static int` | `OFFLINE` Returned by `getStatus()` to indicate that the device is present but some other action is required before the device can be used (e.g., `DetachableStorageOption.makeReady()`).
`static int` | `READY` Returned by `getStatus()` to indicate that the device is initialized, mounted and ready for use.
`static int` | `UNINITIALIZED` Returned by `getStatus()` to indicate that the device is completely uninitialized and contains no existing data.
`static int` | `UNSUPPORTED_DEVICE` Returned by `getStatus()` to indicate that the device that has been plugged in is not supported by the platform.
`static int` | `UNSUPPORTED_FORMAT` Returned by `getStatus()` to indicate that although the device is a supported type and model, it currently has a format, e.g., partitions or filesystems, that is not usable by the platform without reinitialization and the loss of the existing contents.

Method Summary
`LogicalStorageVolume` | `allocateGeneralPurposeVolume(String name, ExtendedFileAccessPermissions fap)` Allocates a general purpose `LogicalStorageVolume`.
`void` | `deleteVolume(LogicalStorageVolume vsp)` Deletes a `LogicalStorageVolume`.
`String` | `getDisplayName()` Gets a storage device name that can be displayed to a user for selection.
`long` | `getFreeSpace()` Gets the available storage capacity in bytes.
`String` | `getName()` Gets the storage device name assigned by the implementation.
`StorageOption[]` | `getOptions()` Gets the array of storage device options (e.g., `DetachableStorageOption`).
`int` | `getStatus()` Returns the status of the storage device.
`boolean[]` | `getSupportedAccessRights()` Gets the permissions supported by this storage device.
`long` | `getTotalSpace()` Gets the total storage capacity of the device in bytes.
`LogicalStorageVolume[]` | `getVolumes()` Gets the set of logical volumes see present on the StorageProxy.
`void` | `initialize(boolean userAuthorized)` Initializes the StorageProxy for use.

Field Detail

### READY

    static final int READY

  Returned by `getStatus()` to indicate that the device is initialized, mounted and ready for use.

  See Also:
    Constant Field Values

### OFFLINE

    static final int OFFLINE

  Returned by `getStatus()` to indicate that the device is present but some other action is required before the device can be used (e.g., `DetachableStorageOption.makeReady()`).

  See Also:
    Constant Field Values

### BUSY

    static final int BUSY

  Returned by `getStatus()` to indicate that the device is busy, e.g., being initialized, configured, checked for consistency or being made ready to detach. This value is not used to indicate that the device is currently reading or writing data.

  See Also:
    Constant Field Values

### UNSUPPORTED_DEVICE

    static final int UNSUPPORTED_DEVICE

  Returned by `getStatus()` to indicate that the device that has been plugged in is not supported by the platform.

  See Also:
    Constant Field Values

### UNSUPPORTED_FORMAT

    static final int UNSUPPORTED_FORMAT

  Returned by `getStatus()` to indicate that although the device is a supported type and model, it currently has a format, e.g., partitions or filesystems, that is not usable by the platform without reinitialization and the loss of the existing contents.

  See Also:
    Constant Field Values

### UNINITIALIZED

    static final int UNINITIALIZED

  Returned by `getStatus()` to indicate that the device is completely uninitialized and contains no existing data. It must be initialized by calling the initialize method to make the device is usable.

  See Also:
    Constant Field Values

### DEVICE_ERROR

    static final int DEVICE_ERROR

  Returned by `getStatus()` to indicate that the device is in an unrecoverable error state and cannot be used.

  See Also:
    Constant Field Values

### NOT_PRESENT

    static final int NOT_PRESENT

  Returned by `getStatus()` to indicate that a detected storage device bay does not contain a removable storage device, i.e. `StorageProxy` containing a `RemovableStorageOption`.

  See Also:
    Constant Field Values

Method Detail

### getName

    String getName()

  Gets the storage device name assigned by the implementation. This name must be unique across all storage devices. The name can be used to determine equality between two storage devices, but does not contain path information.

  Returns:
    The name of the resource represented by the proxy.

### getDisplayName

    String getDisplayName()

  Gets a storage device name that can be displayed to a user for selection. The implementation must keep this name at or below 40 characters in length. This name should match naming conventions displayed to the consumer via any implementation specific setup and configuration menus.

  Returns:
    The display name of the resource represented by the proxy.

### getOptions

    StorageOption[] getOptions()

  Gets the array of storage device options (e.g., `DetachableStorageOption`).

  Returns:
    The array of StorageOptions associated with this StorageProxy.

### getStatus

    int getStatus()

  Returns the status of the storage device. An application can be notified of changes in the status of storage proxies by registering a `StorageManagerListener` with `StorageManager.addStorageManagerListener()` .

### getTotalSpace

    long getTotalSpace()

  Gets the total storage capacity of the device in bytes. Storage that is reserved for system use is not included in this number.

  Returns:
    Total storage capacity in bytes.

### getFreeSpace

    long getFreeSpace()

  Gets the available storage capacity in bytes. The value returned may already have changed by the time this method returns because other applications or the system may be writing files, deleting files, or otherwise allocating space.

  Returns:
    Available storage capacity in bytes.

### getVolumes

    LogicalStorageVolume[] getVolumes()

  Gets the set of logical volumes see present on the StorageProxy. If a StorageProxy has no logical volumes present, one or more must be created before the device may be used for application storage.

  Returns:
    The partitioned storage volumes.

### getSupportedAccessRights

    boolean[] getSupportedAccessRights()

  Gets the permissions supported by this storage device.

  Returns:
    An array of booleans indicating which access rights are supported where location 0 is world read access right, 1 is world write access right, 2 is application read access right, 3 is application write access right, 4 is application's organization read access right, 5 is application's organization write access right, 6 is other organization read access right, and 7 is other organization write access right. If the boolean for one of the access rights is true, the storage device supports it, otherwise the storage device does not support that access right.

### allocateGeneralPurposeVolume

    LogicalStorageVolume allocateGeneralPurposeVolume(String name,
                                                      ExtendedFileAccessPermissions fap)
                                                      throws IOException

  Allocates a general purpose `LogicalStorageVolume`. A general purpose volume can be accessed through file locators and java.io with the absolute path retrieved from `LogicalStorageVolume.getPath()`. Specialized storage proxies may support other types of volumes, such as media volumes used to store DVR content. The volume is owned by the application that allocated it (see `deleteVolume(org.ocap.storage.LogicalStorageVolume)`). The name parameter SHALL be used as the last directory name in the absolute path of the logical storage volume when created.

  Parameters:
    `name` - Name of the new LogicalStorageVolume. Must be unique for the organization and application identifiers in the path on this StorageProxy.
    `fap` - Application access permissions of the new LogicalStorageVolume. Applies to the last directory in the path returned by getPath.
  Returns:
    Allocated volume storage proxy.
  Throws:
    `IllegalArgumentException` - if the name does not meet the persistentfilename form specified by DVB-MHP 1.0.3 chapter 14, or if the length is greater than 255, or if the name is not unique, or if the storage device does not support an access permission specified in the fap parameter.
    `IOException` - if the storage device represented by the StorageProxy is read-only based on a hardware constraint. The `getSupportedAccessRights` method indicates if the `StorageProxy` can be written to by the calling application.
    `SecurityException` - if the calling application does not have persistent storage permission as requested by its permission request file.

### deleteVolume

    void deleteVolume(LogicalStorageVolume vsp)

  Deletes a `LogicalStorageVolume`. Only the owning application or a privileged application with MonitorAppPermission("storage") may delete a volume. This causes all of the file and directories within the volume to be destroyed. This method deletes the volume regardless of file locks.

  Parameters:
    `vsp` - LogicalStorageVolume to delete.
  Throws:
    `SecurityException` - if the calling application is not the owner of the volume or an application with MonitorAppPermission("storage").

### initialize

    void initialize(boolean userAuthorized)

  Initializes the StorageProxy for use. This method is usually invoked on the proxy for a newly attached storage device which is not currently suitable for use, e.g., is in the `UNSUPPORTED_FORMAT` state. It is only required to be effective on detachable storage devices, but may be implemented for other types of devices as well. Successful invocation of this method destroys all application visible contents of the device and should not be called unless the application has determined, e.g., by prompting the user, that it is safe to do so. If the StorageProxy was in the `READY` state and has storage visible to the application, access to that storage is removed and the StorageProxy enters the `BUSY` state until this method returns.

  Parameters:
    `userAuthorized` - True if the application has received authorization from the user for the destruction of the contents of this device. The implementation may use this to determine whether it needs to perform additional user prompting.
  Throws:
    `SecurityException` - if the calling application does not have MonitorAppPermission("storage").
    `IllegalStateException` - if the system is unable to initialize the storage device. If the device was in the `UNINITIALIZED` state and the error is permanent, the StorageProxy status is set to `DEVICE_ERROR`.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD