OcapRecordingProperties

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 OcapRecordingProperties

    java.lang.Object
      org.ocap.shared.dvr.RecordingProperties
          org.ocap.dvr.OcapRecordingProperties

    public class OcapRecordingProperties

extends RecordingProperties

Encapsulates the details about how a recording is to be made.

For purposes of the `setRecordingProperties` method, properties MAY be changed under the following state conditions:

- bitRate - in the PENDING_NO_CONFLICT_STATE and PENDING_WITH_CONFLICT_STATE
- priorityFlag - in the PENDING_NO_CONFLICT_STATE and PENDING_WITH_CONFLICT_STATE
- retentionPriority - any state except DELETED_STATE and CANCELLED_STATE
- access - any state
- organization - cannot be changed in any state
- destination - in the PENDING_NO_CONFLICT_STATE and PENDING_WITH_CONFLICT_STATE
- expirationPeriod - any state except DELETED_STATE and CANCELLED_STATE
- resourcePriority - any state except DELETED_STATE, CANCELLED_STATE, FAILED_STATE, COMPLETE_STATE, or INCOMPLETE_STATE

Field Summary
`static int` | `DELETE_AT_EXPIRATION` Indicates a recording SHALL be deleted by the implementation as soon as its expiration date is reached.
`static byte` | `HIGH_BIT_RATE` Indicates an implementation specific value for high bit-rate.
`static byte` | `LOW_BIT_RATE` Indicates an implementation specific value for low bit-rate.
`static byte` | `MEDIUM_BIT_RATE` Indicates an implementation specific value for medium bit-rate.
`static byte` | `RECORD_IF_NO_CONFLICTS` Record only if there are no conflicts.
`static byte` | `RECORD_WITH_CONFLICTS` Record even when resource conflicts exist.
`static byte` | `TEST_RECORDING` Schedule only test recording requests corresponding to this spec.

Constructor Summary
`OcapRecordingProperties(byte bitRate, long expirationPeriod, int retentionPriority, byte priorityFlag, ExtendedFileAccessPermissions access, String organization, MediaStorageVolume destination)` Constructs an immutable instance of `OcapRecordingProperties` with the specified attributes.
`OcapRecordingProperties(byte bitRate, long expirationPeriod, int retentionPriority, byte priorityFlag, ExtendedFileAccessPermissions access, String organization, MediaStorageVolume destination, int resourcePriority)` Constructs an immutable instance of `OcapRecordingProperties` with the specified attributes.

Method Summary
`ExtendedFileAccessPermissions` | `getAccessPermissions()` Return the file access permission to use for the recording
`byte` | `getBitRate()` Return the bitRate to use for the recording
`MediaStorageVolume` | `getDestination()` Return the volume that represents the storage location of the recording
`long` | `getExpirationPeriod()` Gets the period in seconds the recording expires after being scheduled.
`String` | `getOrganization()` Return the name of the organization that this recording will be tied to
`byte` | `getPriorityFlag()` Return whether or not the recording should be made if there are resource conflicts
`int` | `getResourcePriority()` Return the application-specified resource priority that may be considered at resource contention resolution time.
`int` | `getRetentionPriority()` Gets the priority determining how the recording is deleted.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### HIGH_BIT_RATE

    public static final byte HIGH_BIT_RATE

  Indicates an implementation specific value for high bit-rate.

  See Also:
    Constant Field Values

### LOW_BIT_RATE

    public static final byte LOW_BIT_RATE

  Indicates an implementation specific value for low bit-rate.

  See Also:
    Constant Field Values

### MEDIUM_BIT_RATE

    public static final byte MEDIUM_BIT_RATE

  Indicates an implementation specific value for medium bit-rate.

  See Also:
    Constant Field Values

### DELETE_AT_EXPIRATION

    public static final int DELETE_AT_EXPIRATION

  Indicates a recording SHALL be deleted by the implementation as soon as its expiration date is reached.

  See Also:
    Constant Field Values

### RECORD_IF_NO_CONFLICTS

    public static final byte RECORD_IF_NO_CONFLICTS

  Record only if there are no conflicts.

  See Also:
    Constant Field Values

### RECORD_WITH_CONFLICTS

    public static final byte RECORD_WITH_CONFLICTS

  Record even when resource conflicts exist.

  See Also:
    Constant Field Values

### TEST_RECORDING

    public static final byte TEST_RECORDING

  Schedule only test recording requests corresponding to this spec. Does not cause a recording to be started. This value could be used as the priorityFlag parameter value to the constructor for instances of this class. When an OcapRecordingProperties with this value used as a priority value is used to schedule a recording request, any leaf recording requests scheduled will be in the TEST_STATE. If a test recording request is unresolved, partially resolved or completely resolved, the states would be UNRESOLVED_STATE, PARTIALLY_RESOLVED_STATE and COMPLETELY_RESOLVED_STATE respectively. Test recording requests maybe used by applications to detect potential conflicts before scheduling a regular recording. Scheduling a test recording request will not affect the states of any other recording requests. No events will be generated corresponding to a test recording request. Test recording requests will not change state to any other state.

  See Also:
    Constant Field Values

Constructor Detail

### OcapRecordingProperties

    public OcapRecordingProperties(byte bitRate,
                                   long expirationPeriod,
                                   int retentionPriority,
                                   byte priorityFlag,
                                   ExtendedFileAccessPermissions access,
                                   String organization,
                                   MediaStorageVolume destination)
                            throws IllegalArgumentException

  Constructs an immutable instance of `OcapRecordingProperties` with the specified attributes.

  The unspecified `resourcePriority` attribute is assigned a value of `PRIORITY_UNKNOWN`.

  Parameters:
    `bitRate` - An application may specify LOW_BIT_RATE, MEDIUM_BIT_RATE, or HIGH_BIT_RATE. For analog recordings the corresponding bit-rate values are implementation specific. For digital recordings these values request optional transrating. When transrating is supported, HIGH_BIT_RATE indicates no transrating, and MEDIUM_BIT_RATE to LOW_BIT_RATE indicates increasing compression with a potential decrease in video quality.
    `expirationPeriod` - The period in seconds after the initiation of recording when leaf recording requests with this recording property are deemed as expired. The implementation will delete recorded services based on the expirationPeriod and retentionPriority parameters. This is done without application intervention and transitions those recording requests to the deleted state.
    `retentionPriority` - Indicates when the recording shall be deleted. An application MAY pass in DELETE_AT_EXPIRATION or a higher value indicating a retention priority. If the value is not DELETE_AT_EXPIRATION the recording will be kept after the expirationPeriod has passed if the implementation does not need the storage space for any other reason. If the space is needed expired recordings will be deleted based on retention priority, i.e. higher value equals higher priority, until the needed space is achieved.
    `priorityFlag` - Indication whether the recording should be made regardless of resource conflict or not. This parameter can contain the values RECORD_IF_NO_CONFLICTS, TEST_RECORDING or RECORD_WITH_CONFLICTS.
    `access` - File access permission for the recording request.
    `organization` - Name of the organization this recording will be tied to. This `String` will be compared against the `organization_id` as would be found in the organization name field of an application's leaf certificate to authenticate a playback request. A value of null disables such playback authentication for this recording.
    `destination` - The volume that represents the Storage location of the recording. When an instance of this class is used with a ServiceRecordingSpec a LocatorRecordingSpec, or a ServiceContextRecordingSpec where the specified service context is not attached to a time-shift buffer, with the value of this parameter set to null, the implementation shall use the default recording volume (see org.ocap.storage.MediaStorageOption ) in one of the storage devices connected. If the value is null when used with a ServiceContextRecordingSpec, when the service context specified in the ServiceContextRecordingSpec is attached to a time-shift buffer, the default recording volume from the storage device where the time-shift buffer is located shall be used. When an instance of this class is used with a ServiceContextRecordingSpec, the record(..) method will throw an IllegalArgumentException if the destination is not in same storage device where an attached time-shift buffer is located.
  Throws:
    `IllegalArgumentException` - if bitRate does not equal one of LOW_BIT_RATE, MEDIUM_BIT_RATE, or HIGH_BIT_RATE; or if priorityFlag does not contain the value RECORD_IF_NO_CONFLICTS, TEST_RECORDING or RECORD_WITH_CONFLICTS; or if organization is not found in the application's certificate file.

### OcapRecordingProperties

    public OcapRecordingProperties(byte bitRate,
                                   long expirationPeriod,
                                   int retentionPriority,
                                   byte priorityFlag,
                                   ExtendedFileAccessPermissions access,
                                   String organization,
                                   MediaStorageVolume destination,
                                   int resourcePriority)
                            throws IllegalArgumentException

  Constructs an immutable instance of `OcapRecordingProperties` with the specified attributes.

  Parameters:
    `bitRate` - An application may specify LOW_BIT_RATE, MEDIUM_BIT_RATE, or HIGH_BIT_RATE. For analog recordings the corresponding bit-rate values are implementation specific. For digital recordings these values request optional transrating. When transrating is supported, HIGH_BIT_RATE indicates no transrating, and MEDIUM_BIT_RATE to LOW_BIT_RATE indicates increasing compression with a potential decrease in video quality.
    `expirationPeriod` - The period in seconds after the initiation of recording when leaf recording requests with this recording property are deemed as expired. The implementation will delete recorded services based on the expirationPeriod and retentionPriority parameters. This is done without application intervention and transitions those recording requests to the deleted state.
    `retentionPriority` - Indicates when the recording shall be deleted. An application MAY pass in DELETE_AT_EXPIRATION or a higher value indicating a retention priority. If the value is not DELETE_AT_EXPIRATION the recording will be kept after the expirationPeriod has passed if the implementation does not need the storage space for any other reason. If the space is needed expired recordings will be deleted based on retention priority, i.e. higher value equals higher priority, until the needed space is achieved.
    `priorityFlag` - Indication whether the recording should be made regardless of resource conflict or not. This parameter can contain the values RECORD_IF_NO_CONFLICTS, TEST_RECORDING or RECORD_WITH_CONFLICTS.
    `access` - File access permission for the recording request.
    `organization` - Name of the organization this recording will be tied to. This `String` will be compared against the `organization_id` as would be found in the organization name field of an application's leaf certificate to authenticate a playback request. A value of null disables such playback authentication for this recording.
    `destination` - The volume that represents the Storage location of the recording. When an instance of this class is used with a ServiceRecordingSpec a LocatorRecordingSpec, or a ServiceContextRecordingSpec where the specified service context is not attached to a time-shift buffer, with the value of this parameter set to null, the implementation shall use the default recording volume (see org.ocap.storage.MediaStorageOption ) in one of the storage devices connected. If the value is null when used with a ServiceContextRecordingSpec, when the service context specified in the ServiceContextRecordingSpec is attached to a time-shift buffer, the default recording volume from the storage device where the time-shift buffer is located shall be used. When an instance of this class is used with a ServiceContextRecordingSpec, the record(..) method will throw an IllegalArgumentException if the destination is not in same storage device where an attached time-shift buffer is located.
    `resourcePriority` - Indicates the application-specified resource priority that should be used for any implied resource reservations. This value will be made available for consideration for resource contention resolution.
  Throws:
    `IllegalArgumentException` - if bitRate does not equal one of LOW_BIT_RATE, MEDIUM_BIT_RATE, or HIGH_BIT_RATE; or if priorityFlag does not contain the value RECORD_IF_NO_CONFLICTS, TEST_RECORDING or RECORD_WITH_CONFLICTS; or if organization is not found in the application's certificate file; or if resourcePriority is not a valid resource priority as defined by the `ResourcePriority` interface.

Method Detail

### getBitRate

    public byte getBitRate()

  Return the bitRate to use for the recording

  Returns:
    the bitRate as passed into the constructor

### getExpirationPeriod

    public long getExpirationPeriod()

  Gets the period in seconds the recording expires after being scheduled.

  Overrides:
    `getExpirationPeriod` in class `RecordingProperties`
  Returns:
    the expiration period as passed into the constructor

### getRetentionPriority

    public int getRetentionPriority()

  Gets the priority determining how the recording is deleted.

  Returns:
    the retention priority as passed into the constructor

### getPriorityFlag

    public byte getPriorityFlag()

  Return whether or not the recording should be made if there are resource conflicts

  Returns:
    the priority flag passed into the constructor

### getAccessPermissions

    public ExtendedFileAccessPermissions getAccessPermissions()

  Return the file access permission to use for the recording

  Returns:
    the file access permission passed into the constructor

### getOrganization

    public String getOrganization()

  Return the name of the organization that this recording will be tied to

  Returns:
    the organization passed into the constructor

### getDestination

    public MediaStorageVolume getDestination()

  Return the volume that represents the storage location of the recording

  Returns:
    the volume passed into the constructor

### getResourcePriority

    public int getResourcePriority()

  Return the application-specified resource priority that may be considered at resource contention resolution time.

  Returns:
    the resource priority

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

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