org.ocap.dvr
Class OcapRecordingManager

java.lang.Object
  extended by org.ocap.shared.dvr.RecordingManager
      extended by org.ocap.dvr.OcapRecordingManager

public abstract class OcapRecordingManager
extends RecordingManager

RecordingManager represents the entity that performs recordings and maintains a database of recordings. An instance of this class is returned when an application calls the RecordingManager.getInstance() class in OCAP platforms.

The setPrioitization method is intended to be used with the current set of prioritized resource usages that would be returned by a call to the getPrioritizedUsages method. However, the set of resource usages returned by a call to the getPrioritizedResourceUsages MAY be invalid in a subsequent call to the setPrioritization method as the set MAY have changed during the time between the two method calls.


Constructor Summary
OcapRecordingManager()
           
 
Method Summary
abstract  void addRecordingAlertListener(RecordingAlertListener ral)
          Adds an event listener for receiving events corresponding to a transition from a pending state to an in-progress state or a failed state.
abstract  void addRecordingAlertListener(RecordingAlertListener ral, long alertBefore)
          Adds an event listener for receiving events corresponding to a transition from a pending state to an in-progress state or a failed state.
abstract  void addRecordingPlaybackListener(RecordingPlaybackListener listener)
          Adds an event listener for receiving events corresponding to a recording playback start.
abstract  void cancelBufferingRequest(BufferingRequest request)
          Cancels an active buffering request.
abstract  void deleteAllRecordings()
          Deletes all recordings.
abstract  void deleteRecordings(RecordingList requests)
          Deletes multiple recordings.
abstract  void disableBuffering()
          Disables time-shift buffering and buffering without presentation.
abstract  void enableBuffering()
          Enables time-shift buffering and buffering without presentation.
abstract  BufferingRequest[] getBufferingRequests()
          Gets a set of buffering requests that were passed to the requestBuffering method and have not been cancelled.
abstract  long getMaxBitRate()
          Gets the maximum bit rate the implementation will use for duration to space in calculations.
abstract  ResourceUsage[] getPrioritizedResourceUsages(RecordingRequest recording)
          Get the prioritized list of overlapping ResourceUsages corresponding to a particular recording request.
abstract  long getSmallestTimeShiftDuration()
          Gets the smallest time-shift duration supported by the implementation.
abstract  RecordingRequest record(RecordingSpec source, java.lang.String[] keys, java.io.Serializable[] appData)
          Records the stream or streams according to the source parameter.
abstract  void removeRecordingAlertListener(RecordingAlertListener ral)
          Removes a registered event listener for receiving recording events.
abstract  void removeRecordingPlaybackListener(RecordingPlaybackListener listener)
          Removes a registered event listener for receiving recording playback events.
abstract  void requestBuffering(BufferingRequest request)
          Requests the implementation to start buffering a service using implementation specific time-shift storage.
abstract  RecordingRequest resolve(RecordingRequest request, RecordingSpec spec, int resolutionState)
          Schedule a child recording request corresponding to an unresolved or partially resolved recording request.
abstract  void setPrioritization(ResourceUsage[] resourceUsageList)
          Sets the relative priorities for a set of ResourceUsages.
abstract  void setRecordingDelay(long seconds)
          Sets the amount of time to delay the start of scheduled recordings after the initial monitor application is running.
abstract  void setRequestResolutionHandler(RequestResolutionHandler rrh)
          Set the RequestResolutionHandler that will be invoked when any application calls the RecordingManager.record method.
abstract  void setSpaceAllocationHandler(SpaceAllocationHandler sah)
          Set the SpaceAllocationHandler that will be invoked when any application attempts to allocate space in any MediaStorageVolume.
abstract  void signalRecordingStart()
          Informs the implementation it SHALL start scheduled recordings if it hasn't already done so.
 
Methods inherited from class org.ocap.shared.dvr.RecordingManager
addRecordingChangedListener, getEntries, getEntries, getInstance, getRecordingRequest, record, removeRecordingChangedListener
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

OcapRecordingManager

public OcapRecordingManager()
Method Detail

addRecordingAlertListener

public abstract void addRecordingAlertListener(RecordingAlertListener ral)
Adds an event listener for receiving events corresponding to a transition from a pending state to an in-progress state or a failed state. The listener parameter will only be informed of these events for entries the calling application has read file access permission to.

Parameters:
ral - The listener to be registered.

addRecordingAlertListener

public abstract void addRecordingAlertListener(RecordingAlertListener ral,
                                               long alertBefore)
Adds an event listener for receiving events corresponding to a transition from a pending state to an in-progress state or a failed state. The listener parameter will only be informed of these events for entries the calling application has read file access permission to.

Parameters:
ral - The listener to be registered.
alertBefore - Time in milliseconds for the alert to be generated before the start of the scheduled event.

removeRecordingAlertListener

public abstract void removeRecordingAlertListener(RecordingAlertListener ral)
Removes a registered event listener for receiving recording events. If the listener specified is not registered then this method has no effect.

Parameters:
ral - the listener to be removed.

addRecordingPlaybackListener

public abstract void addRecordingPlaybackListener(RecordingPlaybackListener listener)
Adds an event listener for receiving events corresponding to a recording playback start. The listener parameter will only be informed of these events for service contexts and services that the calling application respectively owns and has access to.

Parameters:
listener - The listener to add.

removeRecordingPlaybackListener

public abstract void removeRecordingPlaybackListener(RecordingPlaybackListener listener)
Removes a registered event listener for receiving recording playback events. If the listener specified is not registered then this method has no effect.

Parameters:
listener - The listener to be removed.

setSpaceAllocationHandler

public abstract void setSpaceAllocationHandler(SpaceAllocationHandler sah)
Set the SpaceAllocationHandler that will be invoked when any application attempts to allocate space in any MediaStorageVolume. At most one instance of this handler can be set. Subsequent calls to this method replace the previous instance with the new one.

Parameters:
sah - the space reservation handler.
Throws:
java.lang.SecurityException - if the caller does not have MonitorAppPermission("handler.recording").

setRequestResolutionHandler

public abstract void setRequestResolutionHandler(RequestResolutionHandler rrh)
Set the RequestResolutionHandler that will be invoked when any application calls the RecordingManager.record method. At most only one instance of this handler can be set. Subsequent calls to this method replaces the previous instance with the new one.

Parameters:
rrh - the request resolution handler.
Throws:
java.lang.SecurityException - if the caller does not have MonitorAppPermission("handler.recording").

resolve

public abstract RecordingRequest resolve(RecordingRequest request,
                                         RecordingSpec spec,
                                         int resolutionState)
Schedule a child recording request corresponding to an unresolved or partially resolved recording request. This method is called either by the RequestResolutionHandler or by an application that has enough information to provide request resolutions. The implementation SHALL generate a recording request corresponding to each successful invocation of this method and make that recording request a child of the RecordingRequest passed in as the first parameter. If the implementation has enough information to resolve the newly created recording request, the implementation should resolve the recording request.

Implementation should set the state of the recording request "request" to "resolutionState" before the return of this call.

Parameters:
request - the RecordingRequest for which the resolution is provided.
spec - the RecordingSpec for the child recording request.
resolutionState - the state of the RecordingRequest after the return of this method. The possible values for this parameter are the states defined in ParentRecordingRequest.
Returns:
the newly scheduled recording request.
Throws:
java.lang.SecurityException - if the caller does not have MonitorAppPermission("handler.recording").
java.lang.IllegalArgumentException - if the resolutionState is not a state defined in ParentRecordingRequest, or if the request is not in unresolved or partially resolved state.

getPrioritizedResourceUsages

public abstract ResourceUsage[] getPrioritizedResourceUsages(RecordingRequest recording)
Get the prioritized list of overlapping ResourceUsages corresponding to a particular recording request. The list of resource usages may include RecordingResourceUsages and other types of ResourceUsages. The ResourceUsage corresponding to the specified recording request is also included in the prioritized list. The prioritized list is sorted in descending order of prioritization. The prioritization for resource usages is based on OCAP resource management.

Parameters:
recording - the RecordingRequest for which overlapping resource usages are sought.
Returns:
the list of ResourceUsages overlapping with the specified RecordingRequest, including the ResourceUsage corresponding to the specified RecordingRequest, sorted in descending order of prioritization, null if the RecordingRequest is not in one of the pending or in-progress states.
Throws:
java.lang.SecurityException - if the caller does not have MonitorAppPermission("handler.recording").
java.lang.IllegalArgumentException - if the parameter is null.

setPrioritization

public abstract void setPrioritization(ResourceUsage[] resourceUsageList)
Sets the relative priorities for a set of ResourceUsages. This method MAY be used by an application with MonitorAppPermission("handler.recording") to set the relative priorities for a set of overlapping resource usages. The implementation SHOULD use the specified prioritization scheme to resolve conflicts (resource conflicts as well as conflicts for RecordingRequests) between these overlapping resource usages. This call MAY change the relative priorities specified by the contention handler or a previous call to this method. Changing the relative priorities for the resource usages MAY result in one or more recording requests changing states. The implementation SHALL only change the ordering of the ResourceUsages passed in the resourceUsageList parameter. This method is meant to be used with the getPrioritizedResourceUsages method.

Parameters:
resourceUsageList - a list of ResourceUsages sorted in descending order of prioritization
Throws:
java.lang.SecurityException - if the caller does not have MonitorAppPermission("handler.recording").
java.lang.IllegalArgumentException - if the parameter does not match a current set of overlapping ResourceUsages.

requestBuffering

public abstract void requestBuffering(BufferingRequest request)
Requests the implementation to start buffering a service using implementation specific time-shift storage. If successful, the service will be buffered, but audio and video presentation will not take place.

Parameters:
request - The <@link BufferingRequest> to make active.
Throws:
java.lang.SecurityException - if the calling application does not have the "file" element set to true in its permission request file.

getBufferingRequests

public abstract BufferingRequest[] getBufferingRequests()
Gets a set of buffering requests that were passed to the requestBuffering method and have not been cancelled.

Returns:
An array of active buffering requests, or a 0 length array if no buffering requests are active.

cancelBufferingRequest

public abstract void cancelBufferingRequest(BufferingRequest request)
Cancels an active buffering request. If the <@link BufferingRequest> parameter is not active this method does nothing and returns successfully.

Parameters:
request - The BufferingRequest to cancel.
Throws:
java.lang.SecurityException - if the calling application does not have write permission for the request as determined by the ExtendedFileAccessPermissions returned by the getExtendedFileAccessPermissions method in the parameter, or if the calling application does not have MonitorAppPermission("handler.recording").

getMaxBitRate

public abstract long getMaxBitRate()
Gets the maximum bit rate the implementation will use for duration to space in calculations.

Returns:
Maximum bit-rate in bits per second.

record

public abstract RecordingRequest record(RecordingSpec source,
                                        java.lang.String[] keys,
                                        java.io.Serializable[] appData)
                                 throws AccessDeniedException
Records the stream or streams according to the source parameter. The concrete sub-class of RecordingSpec MAY define additional semantics to be applied when instances of that sub-class are used. Overloaded from the org.ocap.shared.dvr.RecordingManager.record method. This method is identical to that method except for the key and appData parameters used to add application specific private data.

The keys and appData parameters are parallel arrays where the first entry in the keys array corresponds to the first entry in the appData array and so forth. When a RecordingRequest is created from a call to this method and then delivered to a RecordingChangedListener, the request SHALL contain the application data passed to this method. This method SHALL add the new RecordingRequest to the recording database maintained by this manager before returning and it SHALL include the appData parameter in the RecordingRequest in the database at that time. If conflicts are detected during this method, the appData SHALL be made available in the recording database for application access before any OCAP handler application is called, e.g., resource contention handler application.

Parameters:
source - specification of stream or streams to be recorded and how they are to be recorded.
keys - the IDs under which the application data is to be added.
appData - the private application data to be added.
Returns:
an instance of RecordingRequest that represents the added recording.
Throws:
java.lang.IllegalArgumentException - if the source is an application defined class or as defined in the concrete sub-class of RecordingSpec for instances of that class. Also throws this exception if the keys or appData parameters are null or not the same length.
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("create",..) or RecordingPermission("*",..)

setRecordingDelay

public abstract void setRecordingDelay(long seconds)
Sets the amount of time to delay the start of scheduled recordings after the initial monitor application is running. Calling this method more than once over-writes the previous setting.

Parameters:
seconds - Number of seconds to delay.
Throws:
java.lang.SecurityException - if the calling application does not have MonitorAppPermission("recording").
java.lang.IllegalArgumentException - is the parameter is negative.

signalRecordingStart

public abstract void signalRecordingStart()
Informs the implementation it SHALL start scheduled recordings if it hasn't already done so. Terminates timeout of the delay set by the #setRecordingDelay method if it is still in effect.

Throws:
java.lang.SecurityException - if the calling application does not have MonitorAppPermission("recording").

getSmallestTimeShiftDuration

public abstract long getSmallestTimeShiftDuration()
Gets the smallest time-shift duration supported by the implementation. This method SHALL return a value greater than zero.

Returns:
The smallest time-shift duration in seconds that is supported by the implementation.

enableBuffering

public abstract void enableBuffering()
Enables time-shift buffering and buffering without presentation. The default is buffering is enabled.

Throws:
java.lang.SecurityException - if the calling application does not have MonitorAppPermission("recording").

disableBuffering

public abstract void disableBuffering()
Disables time-shift buffering and buffering without presentation. All time-shift operations cease immediately and any presenting services that are time-shifted SHALL be taken to the live point. Any buffering without presentation activities SHALL cease to be honored. Any content in a time-shift buffer before this method was called SHALL not be accessible if the enableBuffering method is called. If an implementation uses time-shift buffering for recording creation it MAY segment the recording.

Throws:
java.lang.SecurityException - if the calling application does not have MonitorAppPermission("recording").

deleteRecordings

public abstract void deleteRecordings(RecordingList requests)
Deletes multiple recordings. The implementation SHALL execute the equivalent of the RecordingRequest.delete method for each RecordingRequest in the requests parameter.

The recordings SHALL be deleted in incrementing array index order from the first element at requests[0].

Parameters:
requests - List of RecordingRequest recordings to delete.
Throws:
AccessDeniedException - if the calling application is not granted MonitorAppPermission("handler.recording").

deleteAllRecordings

public abstract void deleteAllRecordings()
Deletes all recordings. The implementation SHALL execute the equivalent of the RecordingRequest.delete method for each RecordingRequest in the database of recordings maintained by this manager and delete all of the recordings in the database.

The recordings SHALL be deleted in order of pending recordings first in any order, then in progress recordings in any order, then failed recordings in any order, then completed recordings in any order.

Throws:
AccessDeniedException - if the calling application is not granted MonitorAppPermission("handler.recording").