com.sun.dtv.tuner
Class Tuner

java.lang.Object
  com.sun.dtv.tuner.Tuner

All Implemented Interfaces:

ScarceResource

public class Tuner
extends Object
implements ScarceResource

A class representing a network interface or "tuner" for the reception of broadcast transport streams.

A physical tuner is a scarce system resource, and therefore must be reserved through the ScarceResource API before use. Access to the reserve(boolean, long, ScarceResourceListener) method is guarded by ScarceResourcePermission("tuner.any", "reserve").

See Also:

ScarceResourcePermission

Method Summary

static void	addResourceTypeListener(ResourceTypeListener listener) Adds a ResourceTypeListener to the implementation.
void	addTunerListener(TunerListener listener) Subscribes a TunerListener to receive tuning events from this Tuner.
TransportStream[]	getAvailableTransportStreams() Provides the transport streams that can be accessed through this tuner.
TransportStream	getCurrentTransportStream() Reports the transport stream to which the tuner is currently associated.
DeliverySystemType	getDeliverySystemType() Provides the delivery system type of the Tuner.
static Tuner[]	getInstances() Returns an array of handlers representing each a separate Tuner resource available on the platform corresponding to the network interfaces which may be used for tuning.
boolean	isAvailable() Checks whether the given resource is currently available for reservation.
void	release() Releases this resource.
static void	removeResourceTypeListener(ResourceTypeListener listener) Removes a previously attached listener.
void	removeTunerListener(TunerListener listener) Unsubscribes a TunerListener from receiving tuning events from this Tuner.
void	reserve(boolean force, long timeoutms, ScarceResourceListener listener) Requests reservation of the given scarce resource instance.
static Tuner	reserveOne(boolean force, long timeoutms, ScarceResourceListener listener) Returns a reserved instance out of the pool of all physical Tuner instances.
void	tune(Locator tsLocator) Tunes the network interface to the transport stream referenced by the specified locator.
void	tune(TransportStream transportStream) Tunes the network interface to the specified transport stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

tune

public void tune(TransportStream transportStream)
          throws TuningException

Tunes the network interface to the specified transport stream. This method completes asynchronously. If the tuning operation is successfully initiated, TuningInitiatedEvent is sent to the listeners of this Tuner. Upon successful completion of the tuning operation, TuningCompletedEvent is sent to the listeners, and transportStream will be the Tuner's current transport stream. If the tuning operation does not complete successfully, TuningFailedEvent is sent to the listeners, and the Tuner's current transport stream is undefined. If the requested tuning operation cannot be initiated, TuningException is thrown, no events are posted, and the current transport stream of the Tuner remains unchanged.

Parameters:

transportStream - the transport stream to which to tune

Throws:

TuningException - if tuning cannot be initiated

IllegalStateException - if the caller has not reserved this Tuner

NullPointerException - if transportStream is null

See Also:

TunerListener

tune

public void tune(Locator tsLocator)
          throws TuningException,
                 InvalidLocatorException

Tunes the network interface to the transport stream referenced by the specified locator. This method completes asynchronously. If the tuning operation is successfully initiated, TuningInitiatedEvent is sent to the listeners of this Tuner. Upon successful completion of the tuning operation, TuningCompletedEvent is sent to the listeners, and transportStream will be the Tuner's current transport stream. If the tuning operation does not complete successfully, TuningFailedEvent is sent to the listeners, and the Tuner's current transport stream is undefined. If the requested tuning operation cannot be initiated, TuningException is thrown, no events are posted, and the current transport stream of the Tuner remains unchanged.

Parameters:

tsLocator - a locator referencing the transport stream to which to tune

Throws:

TuningException - if tuning cannot be initiated

InvalidLocatorException - if the specified locator does not reference a transport stream.

IllegalStateException - if the caller has not reserved this Tuner

NullPointerException - if transportStream is null

See Also:

TunerListener

getInstances

public static Tuner[] getInstances()

Returns an array of handlers representing each a separate Tuner resource available on the platform corresponding to the network interfaces which may be used for tuning. Each handler object is unique to both the application and the platform. Each handler object may be different to each other in subsequent calls to the getInstances() method. The list contains all instances whether they are already reserved or not.

If no network interfaces exist, this method returns a zero-length array.

Returns:

an array of instances of resources of type Tuner.

reserveOne

public static Tuner reserveOne(boolean force,
                               long timeoutms,
                               ScarceResourceListener listener)
                        throws SecurityException,
                               IllegalArgumentException,
                               TimeoutException

Returns a reserved instance out of the pool of all physical Tuner instances. This method either returns with the instance or throws an exception according to the situation.

This method behaves exactly as the reserve() method.

Parameters:

force - If true, this method is allowed to withdraw any given resource from its current owner. If false, the implementation will block and wait until a resource of the given type is made available (using release()) or until timeoutms milliseconds.

timeoutms - A positive amount of time in millisecond until which this method will wait for any resource to be released by its current owner. The value of -1 indicates that the implementation will wait forever.

listener - The listener to be attached to receive notification about the status of the resource.

Returns:

The instance of type Tuner that has been reserved.

Throws:

SecurityException - If the application has no permission for the reserve action for the resource it is about to reserve. Also thrown if force is set to true but the application has no permission for the force action.

IllegalArgumentException - If listener is null or if the value specified in timeoutms is not valid i.e. not either a positive integer or -1.

TimeoutException - If the time specified in timeoutms is over and the resource could not be reserved.

See Also:

reserve(boolean, long, com.sun.dtv.resources.ScarceResourceListener)

addResourceTypeListener

public static void addResourceTypeListener(ResourceTypeListener listener)
                                    throws NullPointerException

Adds a ResourceTypeListener to the implementation. Whenever a reserve() or a release() is called on any resources of the same type, the implementation will call the listener's corresponding methods.

Parameters:

listener - The listener that is triggered for events on resources of the same type.

Throws:

NullPointerException - If listener is null.

See Also:

removeResourceTypeListener(com.sun.dtv.resources.ResourceTypeListener)

removeResourceTypeListener

public static void removeResourceTypeListener(ResourceTypeListener listener)
                                       throws NullPointerException

Removes a previously attached listener. If the listener was not attached before, this method does nothing.

Parameters:

listener - The listener that is triggered for events on resources of the same type.

Throws:

NullPointerException - If listener is null.

See Also:

addResourceTypeListener(com.sun.dtv.resources.ResourceTypeListener)

reserve

public void reserve(boolean force,
                    long timeoutms,
                    ScarceResourceListener listener)
             throws IllegalArgumentException,
                    TimeoutException,
                    SecurityException

Requests reservation of the given scarce resource instance. The method will block until this instance is available. The method returns normally only if the reservation succeeded. All other cases are handled by exceptions.

First, if there is a security manager, its checkPermission method is called with the permission ScarceResourcePermission(name, "reserve"). If force is moreover set to true, then the permission is also checked on ScarceResourcePermission(name, "force").

During the reservation process, if that resource instance is already allocated, the implementation must notify the current owner of that resource about the reservation request via the ScarceResourceListener interface:

• either by ScarceResourceListener.releaseRequested() if force is false,
• or by ScarceResourceListener.releaseForced() in the other case.

The listener will be used for such notification only until this resource is released. After releasing, the implementation must not call any of the listener's interface methods.

After that first event, the implementation will proceed accordingly and release (or not) the requested resource. In case the implementation releases the resource, it will trigger a ScarceResourceListener.released() event to the original listening owner of the resource to inform him that the resource does not belong to him anymore.

The application may control the time to wait for such a resource to be available by setting timeoutms. In case the duration of the reservation exceeds the time expressed in timeoutms, a TimeoutException is thrown.

Under normal operation, resources are released using the release method. However, in the case where the application does not release resources when requested or the application is terminated, the implementation must release all resources allocated to the application to allow other applications to be notified of changes in resource allocation and to be able to reserve them. See the Resource Cleanup section of the application lifecycle.

Specified by:

reserve in interface ScarceResource

Parameters:

force - If true, this method will withdraw the resource from the current owner. If false, the implementation will block and wait until the resource is made available (using release()) or until timeoutms.

timeoutms - A positive amount of time in millisecond until which this method will wait for the resource to be released by its current owner. The value of -1 indicates that the implementation will wait forever.

listener - The listener to be attached to receive notification about the status of the resource.

Throws:

SecurityException - If the caller does not have ScarceResourcePermission("tuner", "reserve"), or if force is true and the caller does not have ScarceResourcePermission("tuner", "force").

IllegalArgumentException - If listener is null or if the value specified in timeoutms is not valid i.e. not either a positive integer or -1.

TimeoutException - If the time specified in timeoutms is over and the resource could not be reserved.

release

public void release()

Releases this resource.

The resource will be made available to another application across the platform. After calling this method, it is no more possible to interact with the given resource: calls to critical methods of that scarce resource must be ignored and may throw IllegalStateException. This assertion is valid and the behavior required for any class implementing the ScarceResource interface. In order to interact again with the given resource, the application must call the reserve() method and become the owner again.

The implementation may dispose any system resources that this object is using. After the implementation must not call any of the methods of the listener that was attached at reservation time.

If the resource was already available (i.e. not reserved), this method does nothing.

Specified by:

release in interface ScarceResource

isAvailable

public boolean isAvailable()

Checks whether the given resource is currently available for reservation. The returned value gives the current situation and does not guarantee that the resource will still be available at a later moment e.g. at reservation time: another application may have taken that resource in the meantime.

Specified by:

isAvailable in interface ScarceResource

Returns:

A boolean set to true if the given resource is currently available for reservation.

getCurrentTransportStream

public TransportStream getCurrentTransportStream()

Reports the transport stream to which the tuner is currently associated. If the tuner is not currently tuned to a transport stream, this method returns null.

Returns:

Transport stream to which the tuner is currently tuned

getAvailableTransportStreams

public TransportStream[] getAvailableTransportStreams()

Provides the transport streams that can be accessed through this tuner. If no such transport streams exist, a zero-length array is returned.

Returns:

array of transport streams accessible through this tuner

getDeliverySystemType

public DeliverySystemType getDeliverySystemType()

Provides the delivery system type of the Tuner.

Returns:

the delivery system type

addTunerListener

public void addTunerListener(TunerListener listener)

Subscribes a TunerListener to receive tuning events from this Tuner.

Parameters:

listener - the TunerListener to subscribe

Throws:

NullPointerException - if listener is null

See Also:

removeTunerListener(com.sun.dtv.tuner.TunerListener)

removeTunerListener

public void removeTunerListener(TunerListener listener)

Unsubscribes a TunerListener from receiving tuning events from this Tuner. If the specified listener is not currently subscribed, this method does nothing.

Parameters:

listener - the TunerListener to unsubscribe

Throws:

NullPointerException - if listener is null

See Also:

addTunerListener(com.sun.dtv.tuner.TunerListener)