Commit 145c843d authored by nshah's avatar nshah

Tagging ocap_dvr for the 1.2.3 bundle release

parent 56ada4ab
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<artifactId>stubs-parent</artifactId>
<groupId>com.cablelabs.ocap</groupId>
<version>1.2.3-SNAPSHOT</version>
</parent>
<artifactId>ocap_dvr</artifactId>
<packaging>jar</packaging>
<name>OCAP RI DVR Stubs</name>
<dependencies>
<dependency>
<groupId>com.cablelabs.ocap</groupId>
<artifactId>ocap_api</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
<build>
<sourceDirectory>${basedir}/src</sourceDirectory>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>
<version>2.3</version>
<configuration>
<descriptorRefs>
<descriptorRef>src</descriptorRef>
</descriptorRefs>
</configuration>
<executions>
<execution>
<id>srcpkg</id>
<goals>
<goal>single</goal>
</goals>
<phase>prepare-package</phase>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
package org.ocap.dvr;
import java.util.Date;
import javax.tv.service.Service;
import org.dvb.application.AppID;
import org.davic.net.tuning.NetworkInterface;
import org.ocap.storage.ExtendedFileAccessPermissions;
/**
* This class represents an application request for buffering. An application
* can call the <code>createInstance</code> method to create a request.
*/
public abstract class BufferingRequest
{
/**
* Protected constructor, not to be used by applications.
*/
protected BufferingRequest()
{
}
/**
* Creates a BufferingRequest object.
*
* @param service The service to buffer.
* @param minDuration Minimum duration in seconds to buffer.
* @param maxDuration Maximum duration in seconds to buffer.
* @param efap Extended file access permissions for this request. If this
* parameter is null, no write permissions are given to this request.
* Read permissions for <code>BufferingRequest</code> instances are
* always world regardless of read permissions set by this parameter.
* @throws IllegalArgumentException if the service parameter is not a valid
* <code>Service</code>, or if <code>minDuration</code> is less than
* {@link OcapRecordingManager#getSmallestTimeShiftDuration}, or if
* <code>maxDuration</code> is less than <code>minDuration</code>.
*/
public static BufferingRequest createInstance(Service service,
long minDuration,
long maxDuration,
ExtendedFileAccessPermissions efap)
{
return null;
}
/**
* Gets the Service this request is attempting to buffer.
*
* @return Service being buffered for this request.
*/
public abstract Service getService();
/**
* Sets the Service this request is attempting to buffer.
*
* @param service The <code>Service</code> to buffer for this request.
*
* @throws IllegalArgumentException if the parameter is not a valid
* <code>Service</code>.
* @throws SecurityException if the calling applications does not have one
* of the write ExtendedFileAccessPermissions set by the
* <code>createInstance</code> or
* <code>setExtendedFileAccessPermissions</code> methods.
*/
public abstract void setService(Service service);
/**
* Gets the minimum content buffering duration for this request.
*
* @return The minimum content buffering duration in seconds.
*/
public abstract long getMinimumDuration();
/**
* Sets the minimum duration of content that SHALL be buffered for this
* request. If this method necessitates a buffer re-size the implementation
* MAY flush the contents of the buffer.
*
* @param minDuration Minimum duration in seconds.
*
* @throws IllegalArgumentException If the parameter is greater than the current
* value and Host device does not have enough space to meet the request, or if
* the parameter is greater than the maximum duration set by the
* <code>createInstance</code> or <code>setMaximumDuration</code> methods,
* or if the parameter is less than the duration returned by
* {@link OcapRecordingManager#getSmallestTimeShiftDuration}.
*
* @throws SecurityException if the calling application does not have one
* of the write ExtendedFileAccessPermissions set by the
* <code>createInstance</code> or
* <code>setExtendedFileAccessPermissions</code> methods.
*/
public abstract void setMinimumDuration(long minDuration);
/**
* Gets the maximum duration to buffer for this request. Returns the
* value set by the <code>createInstance</code> or
* <code>setMaximumDuration</code> methods.
*
* @return Maximum duration in seconds.
*/
public abstract long getMaxDuration();
/**
* Sets the maximum duration of content that MAY be buffered for this
* <code>BufferingRequest</code>. Informs the implementation that
* storing more content than this is not needed by the application
* owning this <code>BufferingRequest</code>.
*
* @param duration The maximum duration in seconds.
*
* @throws IllegalArgumentException if the duration parameter is negative
* or if the parameter is less than the minimum duration set by the
* <code>createInstance</code> or <code>setMaximumDuration</code>
* methods, or if the parameter is less than the duration returned by
* {@link OcapRecordingManager#getSmallestTimeShiftDuration}.
* @throws SecurityException if the calling application does not have one
* of the write ExtendedFileAccessPermissions set by the
* <code>createInstance</code> or
* <code>setExtendedFileAccessPermissions</code> methods.
*/
public abstract void setMaxDuration(long duration);
/**
* Gets the ExtendedFileAccessPermissions for this request.
*
* @return The ExtendedFileAccessPermissions.
*/
public abstract ExtendedFileAccessPermissions getExtendedFileAccessPermissions();
/**
* Sets the ExtendedFileAccessPermissions for this request.
*
* @param efap The ExtendedFileAccessPermissions for this request.
*
* @throws IllegalArgumentException if the parameter is null;
* @throws SecurityException if the calling application is not the creator
* of this request.
*/
public abstract void setExtendedFileAccessPermissions(
ExtendedFileAccessPermissions efap);
/**
* Gets the AppID of the application that created the request. If null is
* returned the implementation created the request.
*
* @return AppID of the owning application.
*/
public abstract AppID getAppID();
}
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, otherwise returns false.
**/
public boolean isDecodable();
}
This diff is collapsed.
This diff is collapsed.
package org.ocap.dvr;
import org.ocap.shared.dvr.LeafRecordingRequest;
import org.ocap.shared.dvr.ParentRecordingRequest;
import org.ocap.shared.dvr.navigation.RecordingList;
import org.ocap.shared.dvr.AccessDeniedException;
/**
* 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 invocation of the RecordingManager.record(..)
* method with the priority value in OcapRecordingProperties set to
* TEST_RECORDING.
*/
public static final int TEST_STATE = 9;
/**
* This recording request was cancelled. Transitioned to when the
* cancel method completes successfully.
*/
public static final int CANCELLED_STATE = 10;
/**
* Cancels a pending recording request. The recording request will be not
* be deleted from the database after the successful invocation of this
* method. Successful completion places this recording request in the
* CANCELLED_STATE.
*
* Canceling a recording request may resolve one or more conflicts. In
* this case some pending recordings with conflicts would be changed to
* pending without conflicts.
*
* @throws AccessDeniedException if the calling application is not
* permitted to perform this operation by RecordingRequest specific
* security attributes.
* @throws SecurityException if the calling application does not have
* RecordingPermission("cancel",..) or RecordingPermission("*",..)
* @throws IllegalStateException if the state of the recording is not in
* PENDING_STATE_NO_CONFLICT_STATE or PENDING_WITH_CONFLICT_STATE.
*/
public void cancel() throws AccessDeniedException;
/**
* 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 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();
/**
* Returns whether the destined <code>MediaStorageVolume</code> for this
* recording is present and ready or not.
*
* @return If the <code>MediaStorageVolume</code> destination of this
* recording request can be written to, assuming write permission,
* then this method returns true, otherwise it returns
* false. If the <code>getDestination</code> method returns null then
* the destination <code>MediaStorageVolume</code> is a default volume
* on a default storage device as determined by the implementation.
*/
public boolean isStorageReady();
/**
* Sets the parent for this recording request. If the parent parameter is
* null this leaf is orphaned from any previously set parent. If the parent
* parameter is null and this leaf does not have a parent, this method
* does nothing and returns successfully. If the parameter is not null and
* the parent was already set by any method, this leaf is removed from the
* previously set parent and added to the parent parameter. Unless otherwise
* noted, the state of the previously set parent will not be affected.
*
* If, as a result of this method invocation, this
* <code>OcapRecordingRequest</code> is removed from a
* <code>ParentRecordingRequest</code> which is in the
* COMPLETELY_RESOLVED_STATE, and which contains no other
* <code>RecordingRequest</code>s, that <code>ParentRecordingRequest</code>
* SHALL be transitioned to the PARTIALLY_RESOLVED_STATE.
*
* If, as a result of this method invocation, this
* <code>OcapRecordingRequest</code>
* is removed from a <code>ParentRecordingRequest</code> which is in the
* CANCELLED_STATE and which contains no additional
* <code>RecordingRequest</code>s,
* that <code>ParentRecordingRequest</code> SHALL be deleted from the
* recording database.
*
* @param parent The new parent of this leaf recording request or null if the
* leaf is to be orphaned.
* @param resolutionParentState The state into which the parent recording
* parameter shall be transitioned to as a result of this method
* invocation. If the parent parameter in this method is null, this
* parameter is ignored.
*
* @throws SecurityException if the calling application does not have
* RecordingPermission("modify",..) or RecordingPermission("*",..).
* @throws IllegalStateException if the parent parameter is in the
* CANCELLED_STATE.
*/
public void setParent(ParentRecordingRequest parent, int resolutionParentState);
}
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 java.util.EventListener;
import javax.tv.service.selection.ServiceContext;
/**
* This interface represents a listener that can be added to listen for
* recording playback start. The implementation SHALL notify a listener
* once when a recording playback starts. For purposes of this listener
* playback is considered ongoing while the presenting
* <code>ServiceContext</code> is in the presenting state regardless of
* trick mode. This listener is specific to <code>ServiceContext</code>
* recording playback and does not notify for discreet
* <code>Player</code> based recording playback.
*/
public interface RecordingPlaybackListener extends EventListener
{
/**
* Notifies the listener a recording playback has started. The
* implementation SHALL create a new carousel Id for any
* artificial carousel in each playback. The carouselIDs parameter
* SHALL reference broadcast carousels when stored with a recorded
* service. An artificial carousel ID shall not conflict with a
* carousel ID of a signaled carousel that was also stored with the
* recorded service and presented by the context parameter.
* An artificial carousel ID MAY conflict with other carousel IDs.
*
* @param context The <code>ServiceContext</code> presenting the
* recorded service.
* @param artificialCarouselID Carousel ID for an artificial carousel
* that MAY have been created for the recording being played back.
* A value of -1 indicates no artificial carousel was created.
* @param carouselIDs Array of carousel IDs associated with broadcast
* carousels stored with the recording being played back. If no
* carousels are contained a zero length array is passed in.
*/
public void notifyRecordingPlayback(ServiceContext context,
int artificialCarouselID,
int [] carouselIDs);
}
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 a 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.ocap.resource.ResourceUsage;
import org.davic.resources.ResourceProxy;
/**
* This interface represents a group of resources where one or more
* resources are shared between multiple resource usages. For example,
* when a tuner is used for an ongoing recording and also for presenting
* a broadcast service in a service context, and if the tuner is in a
* resource contention, the tuner is considered shared between a
* <code>RecordingResourceUsage</code> and a
* <code>ServiceContextResourceUsage</code>.
* If there is a resource contention for a tuner, the shared usage of tuner is
* represented by a <code>SharedResourceUsage</code> where the
* getResourceUsages() method would return both <code>ResourceUsage</code>
* instances that share the tuner.
* </p>
* Because a <code>SharedResourceUsage</code> can contain multiple
* <code>ResourceUsage</code> instances where different entities reserved
* the resources, the value returned by the
* <code>SharedResourceUsage.getAppID</code> method
* SHALL be the AppID of the highest-priority ResourceUsage contained in the
* SharedResourceUsage or {@code null} if none of the contained ResourceUsages
* have AppIDs.
*/
public interface SharedResourceUsage extends org.ocap.resource.SharedResourceUsage {
}
package org.ocap.dvr;
import org.ocap.resource.ResourceUsage;
import javax.tv.service.Service;
/**
* 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 Service} 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.