org.ocap.dvr
Interface OcapRecordingRequest

All Superinterfaces:
LeafRecordingRequest, RecordingRequest

public interface OcapRecordingRequest
extends LeafRecordingRequest

This interface represents a LeafRecordingRequest in OCAP.

When the implementation detects a schedule conflict, it either resolves the conflict using the Application priority of the conflicting recordings, or invokes the ResourceContentionHandler if one is set. The resolution of the conflict by the implementation or the ResourceContentionHandler will result in some of the overlapping recordings to be pending without conflict and some to be pending with conflict.


Field Summary
static int CANCELLED_STATE
          This recording request was cancelled.
static int TEST_STATE
          This recording request is a test recording request.
 
Fields inherited from interface org.ocap.shared.dvr.LeafRecordingRequest
COMPLETED_STATE, DELETED_STATE, FAILED_STATE, IN_PROGRESS_INCOMPLETE_STATE, IN_PROGRESS_INSUFFICIENT_SPACE_STATE, IN_PROGRESS_STATE, IN_PROGRESS_WITH_ERROR_STATE, INCOMPLETE_STATE, PENDING_NO_CONFLICT_STATE, PENDING_WITH_CONFLICT_STATE
 
Method Summary
 void cancel()
          Cancels a pending recording request.
 RecordingList getOverlappingEntries()
          Gets any other RecordingRequest that overlaps with the duration of this recording request.
 long getSpaceRequired()
          Gets the estimated space, in bytes, required for the recording.
 boolean isStorageReady()
          Returns whether the destined MediaStorageVolume for this recording is present and ready or not.
 void setParent(ParentRecordingRequest parent, int resolutionParentState)
          Sets the parent for this recording request.
 
Methods inherited from interface org.ocap.shared.dvr.LeafRecordingRequest
getDeletionDetails, getFailedException, getService, stop
 
Methods inherited from interface org.ocap.shared.dvr.RecordingRequest
addAppData, delete, getAppData, getAppID, getId, getKeys, getParent, getRecordingSpec, getRoot, getState, isRoot, removeAppData, reschedule, setRecordingProperties
 

Field Detail

TEST_STATE

static final int TEST_STATE
This recording request is a test recording request. Actual recording is not initiated for recording requests in this state. RecordingRequests in this state do not transition to other states. No events are generated when a recording request is added or deleted in this state. A recording in this state is a leaf recording request. Recordings in this states are the leaf recording requests corresponding to invocation of the RecordingManager.record(..) method with the priority value in OcapRecordingProperties set to TEST_RECORDING.

See Also:
Constant Field Values

CANCELLED_STATE

static final int CANCELLED_STATE
This recording request was cancelled. Transitioned to when the cancel method completes successfully.

See Also:
Constant Field Values
Method Detail

cancel

void cancel()
            throws AccessDeniedException
Cancels a pending recording request. The recording request will be not be deleted from the database after the successful invocation of this method. Successful completion places this recording request in the CANCELLED_STATE. Canceling a recording request may resolve one or more conflicts. In this case some pending recordings with conflicts would be changed to pending without conflicts.

Specified by:
cancel in interface LeafRecordingRequest
Throws:
AccessDeniedException - if the calling application is not permitted to perform this operation by RecordingRequest specific security attributes.
java.lang.SecurityException - if the calling application does not have RecordingPermission("cancel",..) or RecordingPermission("*",..)
java.lang.IllegalStateException - if the state of the recording is not in PENDING_STATE_NO_CONFLICT_STATE or PENDING_WITH_CONFLICT_STATE.

getSpaceRequired

long getSpaceRequired()
Gets the estimated space, in bytes, required for the recording.

Returns:
Space required for the recording in bytes. This method returns zero if the recordings is in failed state.

getOverlappingEntries

RecordingList getOverlappingEntries()
Gets any other RecordingRequest that overlaps with the duration of this recording request. This method will return null unless the recording request is in the PENDING_WITH_CONFLICTS_STATE, PENDING_NO_CONFLICTS_STATE, IN_PROGRESS_INSUFFICIENT_SPACE_STATE or IN_PROGRESS_STATE. The returned list will contain only overlapping recording requests for which the application has read access permission. The RecordingList returned is only a copy of the list of overlapping entries at the time of this method call. This list is not updated if there are any changes. A new call to this method will be required to get the updated list.

Returns:
a RecordingList

isStorageReady

boolean isStorageReady()
Returns whether the destined MediaStorageVolume for this recording is present and ready or not.

Returns:
If the MediaStorageVolume destination of this recording request can be written to, assuming write permission, then this method returns true, otherwise it returns false. If the getDestination method returns null then the destination MediaStorageVolume is a default volume on a default storage device as determined by the implementation.

setParent

void setParent(ParentRecordingRequest parent,
               int resolutionParentState)
Sets the parent for this recording request. If the parent parameter is null this leaf is orphaned from any previously set parent. If the parent parameter is null and this leaf does not have a parent, this method does nothing and returns successfully. If the parameter is not null and the parent was already set by any method, this leaf is removed from the previously set parent and added to the parent parameter. Unless otherwise noted, the state of the previously set parent will not be affected. If, as a result of this method invocation, this OcapRecordingRequest is removed from a ParentRecordingRequest which is in the COMPLETELY_RESOLVED_STATE, and which contains no other RecordingRequests, that ParentRecordingRequest SHALL be transitioned to the PARTIALLY_RESOLVED_STATE. If, as a result of this method invocation, this OcapRecordingRequest is removed from a ParentRecordingRequest which is in the CANCELLED_STATE and which contains no additional RecordingRequests, that ParentRecordingRequest SHALL be deleted from the recording database.

Parameters:
parent - The new parent of this leaf recording request or null if the leaf is to be orphaned.
resolutionParentState - The state into which the parent recording parameter shall be transitioned to as a result of this method invocation. If the parent parameter in this method is null, this parameter is ignored.
Throws:
java.lang.SecurityException - if the calling application does not have RecordingPermission("modify",..) or RecordingPermission("*",..).
java.lang.IllegalStateException - if the parent parameter is in the CANCELLED_STATE.