org.davic.net.tuning
Class NetworkInterfaceController

java.lang.Object
  extended byorg.davic.net.tuning.NetworkInterfaceController
All Implemented Interfaces:
ResourceProxy

public class NetworkInterfaceController
extends java.lang.Object
implements ResourceProxy

NetworkInterfaceController represents a controller that can be used for tuning a network interface. Applications may create a network interface controller object and use it to attempt to reserve the capability to tune a network interface.

The capability to tune a network interface is a resource and the network interface controller acts as a resource proxy for this resource.


Constructor Summary
NetworkInterfaceController(ResourceClient rc)
          Creates a NetworkInterfaceController
 
Method Summary
 ResourceClient getClient()
          Returns the resource client that is associated with this NetworkInterfaceController.
 NetworkInterface getNetworkInterface()
          Returns the network interface associated with this controller.
 void release()
          Releases the tuner.
 void reserve(NetworkInterface ni, java.lang.Object requestData)
          Tries to reserve exclusively the control over the specified network interface.
 void reserveFor(Locator locator, java.lang.Object requestData)
          Tries to reserve exclusively the control over a network interface that can receive the transport stream specified by the locator parameter.
 void tune(Locator locator)
          Tunes asynchronously to the given stream (specified by a Locator).
 void tune(TransportStream ts)
          Tunes asynchronously to the given transport stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

NetworkInterfaceController

public NetworkInterfaceController(ResourceClient rc)
Creates a NetworkInterfaceController

Parameters:
rc - The ResourceClient that the controller is associated with
Method Detail

tune

public void tune(Locator locator)
          throws NetworkInterfaceException
Tunes asynchronously to the given stream (specified by a Locator). This method causes the NetworkInterfaceTuningEvent and the NetworkInterfaceTuningOverEvent to be sent to the listeners of the NetworkInterface reserved by this NetworkInterfaceController.

If tuning fails for one of the reasons which generate an exception, the status of the network interface will be unchanged and no events generated. If failure of tuning is reported by the event code of the NetworkInterfaceTuningOverEvent then the state of the network interface is not defined and it may be tuned to any transport stream or be left in a state where it is not tuned to any transport stream.

Parameters:
locator - The locator describing the transport stream to tune to
Throws:
StreamNotFoundException - raised if the specified locator does not point to any known transport stream or the currently reserved NetworkInterface cannot tune to the specified transport stream
IncorrectLocatorException - raised if locator does not references a broadcast transport stream
NotOwnerException - raised if no network interface is reserved at the moment
NetworkInterfaceException

tune

public void tune(TransportStream ts)
          throws NetworkInterfaceException
Tunes asynchronously to the given transport stream.

This method causes the NetworkInterfaceTuningEvent and the NetworkInterfaceTuningOverEvent to be sent to the listeners of the NetworkInterface reserved by this NetworkInterfaceController. If tuning fails for one of the reasons which generate an exception, the status of the network interface will be unchanged and no events generated. If failure of tuning is reported by the event code of the NetworkInterfaceTuningOverEvent then the state of the network interface is not defined and it may be tuned to any transport stream or be left in a state where it is not tuned to any transport stream.

Parameters:
ts - Transport stream object to tune to
Throws:
StreamNotFoundException - raised if the specified transport stream is not associated with the currently reserved network interface
NotOwnerException - raised if no network interface is reserved at the moment
NetworkInterfaceException

reserve

public void reserve(NetworkInterface ni,
                    java.lang.Object requestData)
             throws NetworkInterfaceException
Tries to reserve exclusively the control over the specified network interface.

If the reservation succeeds, a NetworkInterfaceReservedEvent is sent to the listeners of the NetworkInterfaceManager. If this NetworkInterfaceController has currently reserved another NetworkInterface, then it will either release that NetworkInterface and reserve an appropriate one, or throw an exception. If a NetworkInterface that is able to tune to the specified transport stream is currently reserved by this NetworkInterfaceController, then this method does nothing.

Parameters:
ni - Network Interface to be reserved
requestData - Used by the Resource Notification API in the requestRelease method of the ResourceClient interface. The usage of this parameter is optional and a null reference may be supplied.
Throws:
NoFreeInterfaceException - raised if the requested network interface can not be reserved
java.lang.SecurityException - raised if the application does not have an instance of TunerPermission
NetworkInterfaceException

reserveFor

public void reserveFor(Locator locator,
                       java.lang.Object requestData)
                throws NetworkInterfaceException
Tries to reserve exclusively the control over a network interface that can receive the transport stream specified by the locator parameter.

The specific network interface is selected by the method implementation.

If the reservation succeeds, a NetworkInterfaceReservedEvent is sent to the listeners of the NetworkInterfaceManager. If this NetworkInterfaceController has currently reserved another NetworkInterface, then it will either release that NetworkInterface and reserve an appropriate one, or throw an exception. If a NetworkInterface that is able to tune to the specified transport stream is currently reserved by this NetworkInterfaceController, then this method does nothing.

Parameters:
locator - a Locator that points to a transport stream that the reserved network interface should be able to tune to
requestData - Used by the Resource Notification API in the requestRelease method of the ResourceClient interface. The usage of this parameter is optional and a null reference may be supplied.
Throws:
NoFreeInterfaceException - raised if a network interface can not be reserved
StreamNotFoundException - raised if the specified locator does not point to any known transport stream
IncorrectLocatorException - raised if the locator does not references a broadcast transport stream
java.lang.SecurityException - raised if the application does not have an instance of TunerPermission
NetworkInterfaceException

release

public void release()
             throws NetworkInterfaceException
Releases the tuner.

This method causes a NetworkInterfaceReleasedEvent to be sent to the listeners of the NetworkInterfaceManager.

Throws:
NotOwnerException - raised if the controller does not currently have a network interface reserved
NetworkInterfaceException

getNetworkInterface

public NetworkInterface getNetworkInterface()
Returns the network interface associated with this controller.

Returns:
the network interface associated with this controller or null if no network interface has been reserved.

getClient

public ResourceClient getClient()
Returns the resource client that is associated with this NetworkInterfaceController. This method implements getClient method of org.davic.resources.ResourceProxy.

Specified by:
getClient in interface ResourceProxy
Returns:
the resource client associated with this controller