org.ocap.dvr
Class OcapRecordingProperties

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

public class OcapRecordingProperties
extends RecordingProperties

Encapsulates the details about how a recording is to be made. Used by the implementation to create a parent or leaf recording request when the RecordingManager record or resolve methods are called. The only attributes in this class that are used by a ParentRecordingRequest are the access and organization attributes. All of the other attributes are not used by a parent recording request ParentRecordingRequest for the life cycle of the request.

When the implementation creates a ParentRecordingRequest using this class it SHALL set the ExtendedFileAccessPermissions to read and write application access rights only.

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


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, java.lang.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, java.lang.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.
 java.lang.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
clone, equals, finalize, 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,
                               java.lang.String organization,
                               MediaStorageVolume destination)
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. If a null value is passed in the implementation SHALL create an ExtendedFileAccessPermissions object with read and write application access rights only and contain it in the object instantiated from this class.
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:
java.lang.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,
                               java.lang.String organization,
                               MediaStorageVolume destination,
                               int resourcePriority)
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. If a null value is passed in the implementation SHALL create an ExtendedFileAccessPermissions object with read and write application access rights only and contain it in the object instantiated from this class.
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. This value MAY be used by a resource contention handler application.
Throws:
java.lang.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.
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 java.lang.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