org.ocap.dvr.event
Interface LightweightTriggerSession


public interface LightweightTriggerSession

This interface represents a session created to build an artificial carousel with a DSMCCStreamEvent.


Method Summary
 BufferingRequest getBufferingRequest()
          Gets the BufferingService for the stream type of interest when the stream is being buffered in the background by a BufferingService.
 OcapLocator getLocator()
          Gets the locator for the artificial carousel.
 NetworkInterface getNetworkInterface()
          Gets the NetworkInterface for the stream type of interest.
 int[] getPIDs()
          Get the array of PIDs for the streams with the stream type of interest.
 RecordingRequest getRecordingRequest()
          Gets an in-progress recording request for this session.
 ServiceContext getServiceContext()
          Gets the ServiceContext for the stream type of interest.
 short getStreamType()
          Gets the stream type this session was created for and that the handler registered interest in.
 boolean isPresenting()
          Returns an indication of service containing stream type is presenting to outputs or display, or if it is being buffered or recorded in the background.
 void registerEvent(Date date, String name, int id, byte[] data)
          Registers a synchronized event to the stream event list for this session.
 void setStreamChangeListener(StreamChangeListener listener)
          Sets the listener for this session.
 void stop()
          Stops the session.
 void store()
          Stores the artificial carousel created for an open session with any permanent recordings made of any elementary streams in the same program as the stream type associated with the open session.
 

Method Detail

getLocator

OcapLocator getLocator()
Gets the locator for the artificial carousel. The locator is only valid during this session. The locator returned is a valid Locator that is implementation specific and unique to the artificial carousel. The locator returned SHALL be valid and usable in a ServiceDomain attach method call as long as the service containing the stream is presenting or is accessible in a time-shift buffer.

Returns:
locator Locator of the artificial carousel.

getStreamType

short getStreamType()
Gets the stream type this session was created for and that the handler registered interest in.

Returns:
Stream type for this session.

getPIDs

int[] getPIDs()
Get the array of PIDs for the streams with the stream type of interest. The array SHALL be ordered from lowest PID number to highest. Returns the PIDs for the stream type of interest and that are associated with this session.

Returns:
The PIDs for this session.

getServiceContext

ServiceContext getServiceContext()
Gets the ServiceContext for the stream type of interest.

Returns:
If a ServiceContext is presenting the service containing the stream type of interest and the calling application has permission to access it, then the ServiceContext for this session is returned, otherwise this method returns null.

getBufferingRequest

BufferingRequest getBufferingRequest()
Gets the BufferingService for the stream type of interest when the stream is being buffered in the background by a BufferingService. The return value of this method MAY be incorrect as soon as this method returns.

Returns:
If the stream type of interest is buffering in the background and is not presenting, then the BufferingService for the stream is returned, otherwise this method returns null.

getNetworkInterface

NetworkInterface getNetworkInterface()
Gets the NetworkInterface for the stream type of interest.

Returns:
If a NetworkInterface is reserved for the stream type of interest it is returned, otherwise this method returns null.

getRecordingRequest

RecordingRequest getRecordingRequest()
Gets an in-progress recording request for this session. If the stream associated with the session is being recorded this method returns the recording request for it. The return value of this method MAY be incorrect as soon as this method returns.

Returns:
RecordingRequest associated with the stream, or null if the stream is not being recorded by an in-progress RecordingRequest.

isPresenting

boolean isPresenting()
Returns an indication of service containing stream type is presenting to outputs or display, or if it is being buffered or recorded in the background.

Returns:
True if the service containing stream type of interest is presenting, otherwise returns false.

registerEvent

void registerEvent(Date date,
                   String name,
                   int id,
                   byte[] data)
Registers a synchronized event to the stream event list for this session.

Parameters:
date - The time when the event is to be generated. The implementation SHALL create JMF media time from this value for use with presenting broadcast and recorded services.
name - A name for the event being registered. This name SHALL appear in the list of events returned by the DSMCCStreamEvent getEventList method.
id - The unique identifier of the event.
data - Application specific data associated with the event. This data will be delivered with the StreamEvent when the media time is incurred in the interested stream during playback. The maximum size of this data is 4096 bytes.
Throws:
IllegalArgumentException - if the name or id already exist, or if the data array contains more than 4096 byte entries.
IllegalStateException - if the session is not open, i.e. has been stopped by the implementation or an application.

setStreamChangeListener

void setStreamChangeListener(StreamChangeListener listener)
Sets the listener for this session.

Parameters:
listener - The listener to set. If null any previously set listener is removed.

stop

void stop()
Stops the session. If an artificial carousel was created and the store method was called the carousel is stored at this time. If the session was already stopped this method does nothing successfully.


store

void store()
Stores the artificial carousel created for an open session with any permanent recordings made of any elementary streams in the same program as the stream type associated with the open session. The implementation SHALL adjust the media times in the stored DSMCCStreamEvent so that they occur at the same point in the recording presentation as they did in the presentation recorded from. The implementation SHALL store all events added to the DSMCCStreamEvent while the session is active, i.e. events added after the LightweightTriggerHandler.notifyStreamType(org.ocap.dvr.event.LightweightTriggerSession) method was called and before the stop is called for the session. If a session does not contain any registered events that fall within the duration of a recording when the session is stopped the artificial carousel is not stored with the recording. The implementation SHALL update the stored carousel as soon as an event is registered that falls within the duration of the recording. It is illegal to call this method after a session has been closed.

Throws:
SecurityException - if the calling application does not have file permission granted in its permission request file.
IllegalStateException - if this method is called after the session has been closed, or if there are no events in the artificial carousel.