org.dvb.net.rc
Class ConnectionRCInterface

java.lang.Object
  extended byorg.dvb.net.rc.RCInterface
      extended byorg.dvb.net.rc.ConnectionRCInterface
All Implemented Interfaces:
ResourceProxy

public class ConnectionRCInterface
extends RCInterface
implements ResourceProxy

This class models a connection based return channel network interface for use in receiving and transmitting IP packets over a return channel. Targets for connections are specified as strings including the number to dial. These strings can only include either numbers or a "+" character (as the first character only).

When a ConnectionRCInterface instance is first obtained by an application, the current target shall be set to the default. Applications which wish to use a non-default target need to set this target before attempting to reserve the ConnectionRCInterface. This is because if the application does not have the permission to use the default target, the reserve() method is required throw a SecurityException.


Field Summary
 
Fields inherited from class org.dvb.net.rc.RCInterface
TYPE_CATV, TYPE_DECT, TYPE_ISDN, TYPE_LMDS, TYPE_MATV, TYPE_OTHER, TYPE_PSTN, TYPE_RCS, TYPE_UNKNOWN
 
Constructor Summary
protected ConnectionRCInterface()
          Constructor for instances of this class.
 
Method Summary
 void addConnectionListener(ConnectionListener l)
          Add a listener for events related to connections of this interface.
 void connect()
          Connect this return channel to the current target.
 void disconnect()
          Disconnect this return channel from the current target.
 ResourceClient getClient()
          Return the object which asked to be notified about withdrawal of the underlying resource.
 int getConnectedTime()
          Return the time an interface has been connected
 ConnectionParameters getCurrentTarget()
          Get the current target for connections.
 float getSetupTimeEstimate()
          Obtain an estimate of the setup time for a successful connection for this interface in seconds.
 boolean isConnected()
          Check if this interface is connected.
 void release()
          Release the right to control this return channel interface.
 void removeConnectionListener(ConnectionListener l)
          Remove a listener for events related to connections of this interface.
 void reserve(ResourceClient c, java.lang.Object requestData)
          Request the right to control this return channel interface.
 void setTarget(ConnectionParameters target)
          Set a non-default target for connections.
 void setTargetToDefault()
          Set the target for connections to the default.
 
Methods inherited from class org.dvb.net.rc.RCInterface
getDataRate, getType
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ConnectionRCInterface

protected ConnectionRCInterface()
Constructor for instances of this class. This constructor is provided for the use of implementations and specifications which extend the present document. Applications shall not define sub-classes of this class. Implementations are not required to behave correctly if any such application defined sub-classes are used.

Method Detail

isConnected

public boolean isConnected()
Check if this interface is connected. Connected means able to receive and transmit packets.

Returns:
true if the interface is connected, otherwise false

getSetupTimeEstimate

public float getSetupTimeEstimate()
Obtain an estimate of the setup time for a successful connection for this interface in seconds.

Returns:
an estimate of the setup time for a successful connection for this interface in seconds.

reserve

public void reserve(ResourceClient c,
                    java.lang.Object requestData)
             throws PermissionDeniedException
Request the right to control this return channel interface. If the right to control the return channel interface has already been reserved then this method shall have no effect.

The details of the current connection target shall be obtained from the ConnectionParameters instance which is the current target during the call to this method. Hence changes to that ConnectionParameters instance before a call to this method shall be taken account of during the method call. Changes after the call to this method shall have no effect on that connection.

Parameters:
c - the object to be notified when resources are removed
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:
PermissionDeniedException - if this interface cannot be reserved
java.lang.SecurityException - if the application is denied access to the resource by security policy.

release

public void release()
Release the right to control this return channel interface. If this object does not have the right to control this return channel interface then this method shall have no effect.


connect

public void connect()
             throws java.io.IOException,
                    PermissionDeniedException
Connect this return channel to the current target. If this ResourceProxy does not have the underlying resource reserved then a PermissionDeniedException will be thrown. Where the underlying resource is reserved but at the time the method is called, it is known that connection is impossible then an IOException will be thrown. Apart from this, this method is asynchronous and completion or failure is reported through the event listener on this class. If a connection is already established when this method is called then the method call shall have no effect.

Throws:
PermissionDeniedException - if this application does not own the resource
java.io.IOException - if connection is known to be impossible at the time when the method is called

disconnect

public void disconnect()
                throws PermissionDeniedException
Disconnect this return channel from the current target. This method is asynchronous and completion is reported through the event listener on this class. This method does not release the underlying resource from the ResourceProxy. If no connection is established then this method shall have no effect.

Throws:
PermissionDeniedException - if this application does not own the resource

getCurrentTarget

public ConnectionParameters getCurrentTarget()
                                      throws IncompleteTargetException
Get the current target for connections.

If this ConnectionRCInterface is connected then this method shall return the target to which the connection was made. If this ConnectionRCInterface is not connected then this method shall return the last target set by the setTarget method (if any) otherwise the default.

This returns either the default target or the last target set by this application calling the setTarget method on this instance before the connection was established. This applies regardless of whether the connection was established by another MHP application or if some of the connection parameters have been supplied by the server.

Returns:
the current set of connection target parameters
Throws:
IncompleteTargetException - if the current target is not completely configured
java.lang.SecurityException - if the application is not allowed to read the current target as defined by the security policy of the platform

setTarget

public void setTarget(ConnectionParameters target)
               throws IncompleteTargetException,
                      PermissionDeniedException
Set a non-default target for connections.

If this method is called for a ConnectionRCInterface which is connected then successful calls to this method shall not interrupt that connection. The newly set target shall just be stored until either the next time a connection is established with that ConnectionRCInterface instance or until a subsequent call to setTarget on that ConnectionRCInterface.

The details of the current connection target shall be obtained from the newly set target during the call to this method. Changes to that instance after the call to this method shall have no effect on the ConnectionRCInterface unless/until setTarget is called again for that instance or it is released and reserved again.

Parameters:
target - the new set of connection target parameters
Throws:
IncompleteTargetException - if the application owns the resource but the target is not completely specified
PermissionDeniedException - this exception shall never be thrown
java.lang.SecurityException - if the application is not allowed to modify the target as defined by the security policy of the platform

setTargetToDefault

public void setTargetToDefault()
                        throws PermissionDeniedException
Set the target for connections to the default.

Throws:
PermissionDeniedException - if this application does not own the resource
java.lang.SecurityException - if the application is not allowed to connect to the default target

getConnectedTime

public int getConnectedTime()
Return the time an interface has been connected

Returns:
the time in seconds for which this interface has been connected or -1 if the device is not connected

getClient

public ResourceClient getClient()
Return the object which asked to be notified about withdrawal of the underlying resource. This is the object provided as the first parameter to the last call to the reserve method on this object. If this object does not have the underlying resource reserved then null is returned.

Specified by:
getClient in interface ResourceProxy
Returns:
the object which asked to be notified about withdrawal of the underlying physical resource from this resource proxy or null

addConnectionListener

public void addConnectionListener(ConnectionListener l)
Add a listener for events related to connections of this interface.

Parameters:
l - the listener for the connection related events

removeConnectionListener

public void removeConnectionListener(ConnectionListener l)
Remove a listener for events related to connections of this interface. If the listener specified is not currently receiving these events then this method has no effect.

Parameters:
l - the listener for the connection related events