OcapRecordingManager

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.dvr
Class OcapRecordingManager

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

    public abstract class OcapRecordingManager

extends RecordingManager

RecordingManager represents the entity that performs 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` | `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, String[] keys, 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
`equals, 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.

  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:
    `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:
    `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:
    `SecurityException` - if the caller does not have MonitorAppPermission("handler.recording").
    `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:
    `SecurityException` - if the caller does not have MonitorAppPermission("handler.recording").
    `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:
    `SecurityException` - if the caller does not have MonitorAppPermission("handler.recording").
    `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:
    `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:
    `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,
                                            String[] keys,
                                            Serializable[] appData)
                                     throws IllegalArgumentException,
                                            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.

  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:
    `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.
    `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:
    `SecurityException` - if the calling application does not have MonitorAppPermission("recording").
    `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:
    `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:
    `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:
    `SecurityException` - if the calling application does not have MonitorAppPermission("recording").

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

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