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 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. 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.
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.
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. 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. * * * @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").
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. * * @param transportStream the transport stream to which to tune * * @throws TuningException if tuning cannot be initiated * @throws IllegalStateException if the caller has not reserved this * Tuner * @throws NullPointerException if transportStream is null * * @see TunerListener

Throws:

TuningException

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. * * @param tsLocator a locator referencing the transport stream to which * to tune * * @throws TuningException if tuning cannot be initiated * @throws InvalidLocatorException if the specified locator does not * reference a transport stream. * @throws IllegalStateException if the caller has not reserved this * Tuner * @throws NullPointerException if transportStream is null * * @see TunerListener

Throws:

TuningException

InvalidLocatorException

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.

* * @return 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.

* * @param 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. * @param 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. * @param listener The listener to be attached to receive * notification about the status of the resource. * * @return 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. * @throws IllegalArgumentException If listener is * null or if the value specified in * timeoutms is not valid i.e. not either a positive integer * or -1. * @throws TimeoutException If the time specified in * timeoutms is over and the resource could not be reserved. * * @see #reserve

Throws:

SecurityException

IllegalArgumentException

TimeoutException

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. * * @param listener The listener that is triggered for events on resources * of the same type. * * @throws NullPointerException If listener is * null. * * @see #removeResourceTypeListener

Throws:

NullPointerException

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. * * @param listener The listener that is triggered for events on resources * of the same type. * * @throws NullPointerException If listener is * null. * * @see #addResourceTypeListener

Throws:

NullPointerException

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.

* * * @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").

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 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.

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. * * @return 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. * * @return array of transport streams accessible through this tuner

getDeliverySystemType

public DeliverySystemType getDeliverySystemType()

Provides the delivery system type of the Tuner. * * @return the delivery system type

addTunerListener

public void addTunerListener(TunerListener listener)

Subscribes a TunerListener to receive tuning events from this Tuner. * * @param listener the TunerListener to subscribe * * @throws NullPointerException if listener is null * * @see #removeTunerListener

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. * * @param listener the TunerListener to unsubscribe * * @throws NullPointerException if listener is null * * @see #addTunerListener