org.dvb.net.rc

Class ConnectionRCInterface

java.lang.Object

org.dvb.net.rc.RCInterface

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

Constructors

Modifier	Constructor and Description
protected	ConnectionRCInterface() Constructor for instances of this class.

Method Summary

Methods

Modifier and Type	Method and Description
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, 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,
           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

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

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

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

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

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