Commit fbe929d3 authored by (no author)'s avatar (no author)

This commit was manufactured by cvs2svn to create tag

'OCAP10-I15-050415'.
parent 6232e1c7
package org.ocap.dvr;
import org.ocap.shared.dvr.RecordedService;
/**
* This interface represents a RecordedService in OCAP. The object returned when
* an applications calls the getService method on a RecordingRequest will be an instance of
* this interface.
*/
public interface OcapRecordedService extends RecordedService
{
/**
* Get the bit-rate used for encoding and storage of this recorded service.
*
* @return Bit-rate in bytes per second.
*/
public long getRecordedBitRate();
/**
* Gets the size of the recording in bytes.
*
* @return Space occupied by the recording in bytes.
*/
public long getRecordedSize();
/**
* Determines if the recording can be decrypted by the implementation
* on the current network.
*
* @return True if the recording can be decrypted, otherwise returns false.
**/
public boolean isDecryptable();
/**
* Determines if the recording has a format which can be decoded
* for presentation by the implementation, e.g. the bit rate,
* resolution, and encoding are supported.
*
* @return True if the recording can be decoded, othwerwise returns false.
**/
public boolean isDecodable();
}
package org.ocap.dvr;
import org.ocap.dvr.storage.SpaceAllocationHandler;
import org.ocap.shared.dvr.RecordingRequest;
import org.ocap.shared.dvr.RecordingSpec;
import org.ocap.dvr.RequestResolutionHandler;
import org.ocap.shared.dvr.RecordingManager;
import org.ocap.resource.ResourceUsage;
/**
* 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.
*/
public abstract class OcapRecordingManager extends RecordingManager
{
/**
* Adds an event listener for recieving 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.
*
* @param ral The listener to be registered.
*/
public abstract void addRecordingAlertListener(RecordingAlertListener ral);
/**
* Adds an event listener for recieving 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.
*
* @param ral The listener to be registered.
*
* @param alertBefore Time in milliseconds for the alert to be generated
* before the start of the scheduled event.
*/
public abstract void addRecordingAlertListener(RecordingAlertListener ral,
long alertBefore);
/**
* Removes a registed event listener for receiving recording events.
* If the listener specified is not registered then this method has
* no effect.
*
* @param ral the listener to be removed.
*/
public abstract void removeRecordingAlertListener(
RecordingAlertListener ral);
/**
* Set the SpaceAllocationHandler that will be invoked when any application
* attempts to allocate space in any MediaStorageVolume. At most only one
* instance of this handler can be set. Subsequent calls to this method
* replaces the previous instance with the new one.
*
* @param sah the space reservation handler.
*
* @throws SecurityException if the caller does not have
* MonitorAppPermission("handler.recording").
*/
public abstract void setSpaceAllocationHandler(SpaceAllocationHandler sah);
/**
* 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.
*
* @param rrh the request resolution handler.
*
* @throws SecurityException if the caller does not have
* MonitorAppPermission("handler.recording").
*/
public abstract void setRequestResolutionHandler(
RequestResolutionHandler rrh);
/**
* 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.
* <p>
* Implementation should set the state of the recording request
* "request" to "resolutionState" before the return of this call.
*
* @param request the RecordingRequest for which the resolution is
* provided.
* @param spec the RecordingSpec for the child recording request.
* @param resolutionState the state of the RecordingRequest after
* the return of this method. The possible values for this
* parameter are the states defined in ParentRecordingRequest.
*
* @return the newly scheduled recording request.
*
* @throws SecurityException if the caller does not have
* MonitorAppPermission("handler.recording").
* @throws IllegalArgumentException if the resoltionState is not a
* state defined in ParentRecordingRequest, or if the
* request is not in unresolved or partially resolved state.
*/
public abstract RecordingRequest resolve(RecordingRequest request,
RecordingSpec spec, int resolutionState);
/**
* 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 are based on the order specified by the
* ResourceContentionHandler or based on the order specified by a
* previous call to the setPrioritization() call. If a
* ResourceContentionHandler is not registered or the
* setResourcePriorities() was not called previously, the
* prioritization order will be based on application priorities of
* the applications returned by the getAppID() call on the ResourceUsages.
*
* @param recording the RecordingRequest for which overlapping resource
* usages are sought.
*
* @return 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 pending or in-progress states.
*
* @throws SecurityException if the caller does not have
* MonitorAppPermission("handler.recording").
*/
public abstract ResourceUsage[] getPrioritizedResourceUsages(
RecordingRequest recording);
/**
* 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.
*
* @param resourceUsageList a list of ResourceUsages sorted in
* descending order of prioritization
*
* @throws SecurityException if the caller does not have
* MonitorAppPermission("handler.recording").
*/
public abstract void setPrioritization(ResourceUsage[] resourceUsageList);
}
package org.ocap.dvr;
import org.ocap.shared.dvr.RecordingProperties;
import org.ocap.dvr.storage.MediaStorageVolume;
import org.ocap.storage.ExtendedFileAccessPermissions;
/**
* Encapsulates the details about how a recording is to be made.
*/
public class OcapRecordingProperties extends RecordingProperties
{
/**
* Indicates an implementation specific value for high bit-rate.
*/
public static final byte HIGH_BIT_RATE =1;
/**
* Indicates an implementation specific value for low bit-rate.
*/
public static final byte LOW_BIT_RATE =2;
/**
* Indicates an implementation specific value for medium bit-rate.
*/
public static final byte MEDIUM_BIT_RATE =3;
/**
* Record only if there are no conflicts. When used as the priorityFlag
* to the constructor for instances of this class, the recording request is
* scheduled only if there are no conflicts. If there are conflicts the
* record method will return a recording request in
* PENDING_WITH_CONFLICT_STATE.
*/
public static final byte RECORD_IF_NO_CONFLICTS =1;
/**
* Record even when resource
* conflicts exist. This value could be used as the priorityFlag
* parameter value to the constructor for instances of this class. When
* this is used as a priority value, if the request conflicts with
* another RecordingRequest , resources are resolved using recording
* resource conflict resolution rules.
*/
public static final byte RECORD_WITH_CONFLICTS =2;
/**
* Schedule only test recording requests corresponding to this spec.
* 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.
*/
public static final byte TEST_RECORDING =3;
/**
* Constructor
*
* @param 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.
* @param 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
* off any expired recording requests without application
* intervention.
* @param priorityFlag Indication whether the recording should be made
* regardless of resource conflict or not. This parameter can
* contain the values RECORD_IF_NO_CONFLICTS, or
* RECORD_WITH_CONFLICTS.
* @param access File access permission for the recording request.
* @param organization Name of the organization this recording will be
* tied to. Used to authenticate playback applications by matching
* this parameter to an organization name field in any playback
* application's certificate chain. Can be set to null to disable
* this playback application authentication.
* @param 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 or
* RECORD_WITH_CONFLICTS, or if organization is not found in the
* application's certificate file.
*/
public OcapRecordingProperties(long bitRate, long expirationPeriod,
byte priorityFlag,
ExtendedFileAccessPermissions access,
String organization,
MediaStorageVolume destination)
throws IllegalArgumentException
{
super(expirationPeriod);
}
/**
* Return the bitRate to use for the recording
* @return the bitRate as passed into the constructor
*/
public long getBitRate()
{
return 0;
}
/**
* Return whether or not the recording should be made if there are
* resource conflicts
* @return the priority flag passed into the constructor
*/
public byte getPriorityFlag()
{
return 0;
}
/**
* Return the file access permission to use for the recording
* @return the file access permission passed into the constructor
*/
public ExtendedFileAccessPermissions getAccessPermissions()
{
return null;
}
/**
* Return the name of the organization that this recording will be tied to
* @return the organization passed into the constructor
*/
public String getOrganization()
{
return null;
}
/**
* Return the volume that represents the storage location of the recording
* @return the volume passed into the constructor
*/
public MediaStorageVolume getDestination()
{
return null;
}
}
package org.ocap.dvr;
import org.ocap.shared.dvr.LeafRecordingRequest;
import org.ocap.shared.dvr.navigation.RecordingList;
/**
* This interface represents a LeafRecordingRequest in OCAP.
* <p>
* When the implementation detects a schedule conflict, it either resolves
* the conflict using the Application priority of the conflicting recordings,
* or invokes the
* {@link org.ocap.resource.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.
*/
public interface OcapRecordingRequest extends LeafRecordingRequest
{
/**
* 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 invokation of the RecordingManager.record(..)
* method with the priority value in OcapRecordingProperties set to
* TEST_RECORDING.
*/
public static final int TEST_STATE = 9;
/**
* Gets the estimated space, in bytes, required for the recording.
*
* @return Space required for the recording in bytes. This method
* returns zero if the recordings is in failed state.
*/
public long getSpaceRequired();
/**
* 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
* 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.
* @return a RecordingList
*/
public RecordingList getOverlappingEntries();
}
package org.ocap.dvr;
import java.io.Serializable;
import org.ocap.shared.dvr.RecordingSpec;
import org.ocap.shared.dvr.RecordingProperties;
/**
* Specifies a recording request that can be resolved only by an application
* defined request resolution handler.
*/
public class PrivateRecordingSpec extends RecordingSpec
{
/**
* Constructor
* @param requestData private data the format of which is known only
* to the application.
* @param properties the definition of how the recording is to be done
*/
public PrivateRecordingSpec(Serializable requestData,
RecordingProperties properties)
{
super(properties);
}
/**
* Returns the private data stored in this recording spec
* @return the private data passed into the constructor
*/
public Serializable getPrivateData()
{
return null;
}
}
package org.ocap.dvr;
import org.ocap.shared.dvr.RecordingRequest;
import java.util.EventObject;
/**
* Event notifying that a scheduled recording is about to occur. This event
* is triggered for <code>LeafRecordingRequest</code>s in pending states.
*/
public class RecordingAlertEvent extends EventObject
{
/**
* Constructs the event.
*
* @param source The <code>RecordingRequest</code> that
* caused the event.
*/
public RecordingAlertEvent(RecordingRequest source)
{
super(source);
}
/**
* Returns the <code>RecordingRequest</code> that caused the event.
*
* @return The <code>RecordingRequest</code> that caused the event.
*/
public RecordingRequest getRecordingRequest()
{
return(RecordingRequest)super.getSource();
}
}
package org.ocap.dvr;
import java.util.EventListener;
/**
* Listener for Recording Alerts.
*/
public interface RecordingAlertListener extends EventListener
{
/**
* Notifies the <code>RecordingAlertListener</code> that a scheduled
* acitivity is about to happen.
*
* @param e The generated event.
*/
public void recordingAlert(RecordingAlertEvent e);
}
package org.ocap.dvr;
import org.dvb.application.AppID;
import org.davic.resources.ResourceProxy;
import org.ocap.shared.dvr.RecordingRequest;
import org.ocap.resource.ResourceUsage;
/**
* This interface represents a grouping of resources specific to an recording
* function performed by an application.
*/
public interface RecordingResourceUsage extends ResourceUsage
{
/**
* Gets the {@link RecordingRequest} associated with the set of resources
* contained in the usage and initiated by the application returned by the
* base ResourceUsage.getAppID method.
*
* @return The recording request associated with the resource usage.
*/
public RecordingRequest getRecordingRequest();
}
package org.ocap.dvr;
import org.ocap.shared.dvr.RecordingRequest;
/**
* This interface will be implemented by the application that registers the
* RequestResolutionHandler. The RequestResolutionHandler will be invoked
* whenever a new unresolved recording request is added to the
* RecordingManager database. The RecordingResolutionHandler may call
* the resolve(..) method of the OcapRecordingManager multiple times to
* schedule one or more recording requests corresponding to the recording
* request.
*
*/
public interface RequestResolutionHandler
{
/**
* This method would be invoked by the implementation when an
* unresolved recording request is scheduled in response to an
* application calling the record(..) method of the RecordingManager.
*/
public void requestResolution(RecordingRequest request);
}
package org.ocap.dvr;
import org.dvb.application.AppID;
import org.davic.resources.ResourceProxy;
import org.ocap.dvr.storage.TimeShiftBufferOption;
import org.ocap.resource.ResourceUsage;
/**
* This interface represents a grouping of resources specific to a time-shift
* buffering performed by an application.
*/
public interface TimeShiftBufferResourceUsage extends ResourceUsage
{
/**
* Gets the {@link TimeShiftBufferOption} associated with the set of resources
* contained in the usage where the last service selection was initiated
* by the application returned by the base ResourceUsage.getAppID method.
*
* @return The time-shift buffer associated with the resource usage.
*/
public TimeShiftBufferOption getTimeShiftBufferOption();
}
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">