org.ocap.dvr.storage
Interface MediaStorageVolume

All Superinterfaces:
LogicalStorageVolume

public interface MediaStorageVolume
extends LogicalStorageVolume

This interface represents a media volume on a storage device and is contained within a StorageProxy. A MediaStorageVolume is a specialized LogicalStorageVolume that supports the recording and playback of media content through the DVR. The volume also provides a mechanism for allocating a fixed amount of storage for use by recordings on the volume.


Method Summary
 void addFreeSpaceListener(FreeSpaceListener listener, int level)
          Adds a listener that is notified when available free space is less than a specified level.
 void allocate(long bytes)
          Allocates the specified amount of storage from the containing StorageProxy for use by recordings made to this volume.
 void allowAccess(java.lang.String[] organizations)
          Adds a list of Organization strings to the set of organizations that are allowed to use this volume.
 long getAllocatedSpace()
          Gets the amount of space allocated on this volume.
 java.lang.String[] getAllowedList()
          Returns the list of Organizations who are allowed to use this volume.
 long getFreeSpace()
          Gets the remaining available space from an allocation after accounting for all used space (including recordings, time shift buffers, and meta-data).
 void removeAccess(java.lang.String organization)
          Removes an Organization from the list of Organization who are allowed to use this volume.
 void removeFreeSpaceListener(FreeSpaceListener listener)
          Removes a free space listener.
 
Methods inherited from interface org.ocap.storage.LogicalStorageVolume
getFileAccessPermissions, getPath, getStorageProxy, setFileAccessPermissions
 

Method Detail

allocate

void allocate(long bytes)
Allocates the specified amount of storage from the containing StorageProxy for use by recordings made to this volume. The volume is guaranteed to be able to use this amount of storage without requiring the deletion of the contents of other volumes and is also limited to using no more than the allocated amount of storage. The amount of space allocated may be rounded up to meet platform requirements. Once the storage on the volume reaches the amount allocated, the behavior is the same as if the storage device were full, e.g. a SpaceFullException is thrown or a RecordingAlertEvent generated.

A value of zero indicates that the volume has no minimum guaranteed size and may also use as much space as is available. Until set with the allocate() method, the space allocated is zero.

Subsequent calls to allocate() change the existing allocation. However, if a new allocation size is too small to contain existing recordings a IllegalArgumentException is thrown and the allocation size is not changed. Except when the allocation size is changed to zero which removes the limit and the guaranteed storage size. The allocated space can only be released by an explicit call to allocate() or through the deletion of the storage volume.

Parameters:
bytes - Number of bytes to allocate.
Throws:
java.lang.SecurityException - if the calling application does not have MonitorAppPermission("storage") permission.
java.lang.IllegalArgumentException - if the requested amount of storage exceeds the amount available for allocation, or reduces the previous allocation making it too small for existing recordings.

getAllocatedSpace

long getAllocatedSpace()
Gets the amount of space allocated on this volume. If the allocate method has not been called for the volume this method returns 0.

Returns:
Number of bytes allocated.

getFreeSpace

long getFreeSpace()
Gets the remaining available space from an allocation after accounting for all used space (including recordings, time shift buffers, and meta-data). If no allocated space has been used, this method returns the same value as the getAllocatedSpace method. When this method is called on a MediaStorageVolume without an explicit allocation, as is the case when allocate has not been called or was called with a value of 0, then the value returned is the space available on the associated StorgeProxy's MEDIAFS that has not been explicitly allocated to another MediaStorageVolume.

Returns:
Number of bytes available for use from an allocation.

allowAccess

void allowAccess(java.lang.String[] organizations)
Adds a list of Organization strings to the set of organizations that are allowed to use this volume. The volume is owned by the application that created the volume but is accessible to any record requests where the Organization string matches one of the strings in the organization array.

Note: Given Organization strings should represent an application's organization_id, formatted as would be found in the OrganizationName field of the application's leaf certificate. That is, the organization_id as a fixed length 8 character hexadecimal string (with leading zeros where required).

Parameters:
organizations - An array of strings representing organizations that are allowed to use this volume. The String passed as a parameter to the record method should match one of this strings to record onto this volume. If an array of length 0 is passed, any application can use this volume. If null is passed in and all access to this volume has been removed by a call to the removeAccess method, then access is restored to the same organizations that had access before all access was removed.
Throws:
java.lang.SecurityException - if the calling application is not the owner of the volume and does not have MonitorAppPermission("storage") permission.

removeAccess

void removeAccess(java.lang.String organization)
Removes an Organization from the list of Organization who are allowed to use this volume. When application access to the volume is in progress from either the Java I/O (java.io package) or recording manager (org.ocap.dvr, org.ocap.shared.dvr packages) APIs and that application's access is removed by this method, the implementation SHALL terminate the reads or writes immediately and generate the appropriate response, e.g. IOException, interrupted recording request. This includes all forms of access from those APIs including file I/O, service recording, and recording playback.

Parameters:
organization - A string representing an organization that should be removed from the list of allowed organizations. Passing in null removes all application access to this volume.
Throws:
java.lang.SecurityException - if the calling application is not the owner and the calling application does not have MonitorAppPermission("storage") permission.

getAllowedList

java.lang.String[] getAllowedList()
Returns the list of Organizations who are allowed to use this volume. The volume is owned by the application that created the volume but is accessible to any record requests where the Organization string matches one of the strings in the organization array.

Returns:
An array of strings representing organizations that are allowed to use this volume. A zero length array is returned when all organizations have access. Null is returned when all access has been removed from this volume.

addFreeSpaceListener

void addFreeSpaceListener(FreeSpaceListener listener,
                          int level)
Adds a listener that is notified when available free space is less than a specified level. The parameter level is a percentage of the total available space in the volume. For example, a level of 10 would cause the listener to be notified when less than 10% of the volume is available for use. Determination of the level is implementation specific and the listener is notified whenever the threshold indicated by the level is crossed and available storage is less than the level parameter

Parameters:
listener - The listener to be added.
level - The level of free space remaining at which to notify the listener.

removeFreeSpaceListener

void removeFreeSpaceListener(FreeSpaceListener listener)
Removes a free space listener. If the parameter listener was not previously added or has already been removed this method does nothing successfully.

Parameters:
listener - The listener to remove.