com.sun.dtv.net
Class NetworkDevice

java.lang.Object
  com.sun.dtv.net.NetworkDevice

All Implemented Interfaces:

ScarceResource

public class NetworkDevice
extends Object
implements ScarceResource

Represents every physical instance of any network mean on which IP (TCP, UDP) communication can be achieved by the platform. That includes any type of modems and networking interfaces.

Every device is handled as a scarce resource allowing an exclusive control usage: that means that devices that would support multiple formats but only allow one to run at any given time, the platform must resolve the conflict transparently to the application.

Relation to java.net

This NetworkDevice class extends the java.net by allowing any DTV application that is granted with the corresponding permissions, to control any given network device: control is defined by the ability to configure/connect/disconnect that device:

• The control exclusiveness is therefore required for the whole platform: the implementation must not allow any applications (Java and non-Java) other then a given owner of a network resource to control it at the same time.
• Reciprocally, the implementation must ensure that the state of exclusive control is consistent throughout all application environments (Java and non-Java): i.e. if a native application has taken an exclusive control over a network device, the corresponding Java scarce resource isAvailable() will return false.

Similarly the communication over any already connected network device by mean of a Java or non-Java application is granted to any Java applications using java.net as well as to any non-Java application.

When Java applications uses any networking facilities provided by java.net without beforehand explicitly using this NetworkDevice control API, the implementation must initiate a connection using the platform's "default" profile that includes the default network device as well as the default settings (see next section).

Properties

The following list of properties extends the property tree defined in the User by adding a common vocabulary that must be used when defining a given profile before being handed over to the connect method. The table lists property names followed by a description and lists the type of connection that a given property is relevant for.

property	description	relevant types	default right
<path>.number	Phone number to dial to establish a connection. The number is a string that may contain any characters, in particular also "visual separation characters" such as " ", "-", "(" or ")". It may also contain other dialing specific characters such as those for pausing or DTMF controls like "#" or "*".	TYPE_DIAL_UP, TYPE_ISDN, TYPE_MOBILE_PHONES_*	"read,remove"
<path>.dns.1	The IP address of a DNS server for name resolution.	Any TYPE_ where a fixed IP can be defined	"read,remove"
<path>.dns.2	An alternative DNS server (may be empty)	Any TYPE_ where a fixed IP can be defined	"read,remove"

where <path> is equivalent to: "com.sun.dtv.net.if.profiles.<profile>" and where "<profile>" is the name of the profile to be chosen when connecting. Implementations must support a profile named "default" which provides all required settings for a communication mean preferred by the system. The platform also holds a platform wide default inactivity timeout system property in millisecond in "com.sun.dtv.net.default.timeout" (available from java.lang.System.getProperty).

All properties defined here must be supported by the platform. An implementation may extend this list, however the last name of these properties must be prefixed with "x-". For example: "com.sun.dtv.net.if.profiles.net-1.x-notbefore" adds an hypothetical notbefore property in the net-1 profile.

As described in User, the process of creating or reading underlies the permission framework and the application must therefore be granted the corresponding access right. The properties defined above have a default read access right by all applications.

Security

The permission framework is managed by SecurityManager through ScarceResourcePermission and NetworkDevicePermission which both allows to configure permissions on resources and actions at application granularity:

ScarceResourcePermission defines two actions: "reserve" and "force" to control access to the network resource's methods including connect.

NetworkDevicePermission defines one action "dial" to control telephone numbers to be dialed in the particular cases of dial up based network devices.

In any cases, the application is allowed to connect using the platform's default profile.

Permission Name

Conforming to the convention for names for scarce resources permissions, the permission name for this scarce resource is defined by "networkdevice.any". The permission name domain starting with "networkdevice." is reserved by this specification for future purposes. This currently applies on ScarceResourcePermission and NetworkDevicePermission.

Permission Example

 ScarceResourcePermission("networkdevice.any", "reserve,force");
 NetworkDevicePermission("networkdevice.any", "dial=+49*");
 

Code Sample

A typical code sample would be:

 import com.sun.dtv.resources.ScarceResource;
 import com.sun.dtv.resources.ScarceResourceListener;
 import com.sun.dtv.net.NetworkDevice;
 import com.sun.dtv.net.NetworkDeviceStatusListener;
 import com.sun.dtv.platform.User;
 import java.util.Properties;

 public class Sample implements ScarceResourceListener,
                                NetworkDeviceStatusListener {

     // Interface : ScarceResourceListener
    
     void released(ScarceResource resource) {}
     void releasedForced(ScarceResource resource) {}
     boolean releasedRequested(ScarceResource resource) { return true; }

     // Interface : NetworkDeviceStatusListener
 
     void connected(NetworkDevice device, NetworkInterface netif) {
         // is now connected and 'netif' knows what IP config we have
         {
             // do here your networking; ideally in a thread
             // ...
             device.disconnect();
         }
     }
     void connectionFailed(NetworkDevice device, String reason) {
         // could not connect because of 'reason'
     }
     void currentDataRate(NetworkDevice device, long dataRate) {
         // data rate has changed
     }
     void disconnected(NetworkDevice device) {
         // the device has been disconnected and 
     }
     boolean timingOut(NetworkDevice device) {
         return true;
     }

     // This is the core

     void coreEngine() {
         //...
         try {
            NetworkDevice device 
                = NetworkDevice.reserveOne(false,
                                           1000, 
                                           this, 
                                           Network.TYPE_DIAL_UP);

            // Ok, got a resource
            Properties props
                = User.get("com.sun.dtv.net.if.profiles.test.*");
            if (props.isEmpty()) {
                // assuming application has 'write' access
                User.setProperty("com.sun.dtv.net.if.profiles.test.number",
                                 "+1-555-123-456-789");
                // other user properties here ...
                User.setProperties(props);
            }
            device.connect(null, 
                           "com.sun.dtv.net.if.profiles.test", 
                           this, 
                           5000);
         }
         catch (TimeoutException e) {
            // no resource available
         }
     }
 }
 

Field Summary

static int	TYPE_ADSL Specific type of network device: ADSL.
static int	TYPE_ANY Special type used in reserve representing any possible network device type.
static int	TYPE_DIAL_UP Specific type of network device: Dial up.
static int	TYPE_DOCSIS Specific type of network device: DOCSIS.
static int	TYPE_ETHERNET_DHCP Specific type of network device: Ethernet (DHCP).
static int	TYPE_ETHERNET_FIXED_IP Specific type of network device: Ethernet (Fixed IP).
static int	TYPE_ETHERNET_PPPOE Specific type of network device: Ethernet (PPPoE).
static int	TYPE_FTTH Specific type of network device: FTTH.
static int	TYPE_ISDN Specific type of network device: ISDN.
static int	TYPE_MOBILE_PHONE Specific type of network device: mobile phone (in this case, the mobile technology is not informed).
static int	TYPE_MOBILE_PHONE_CDAM_EVDO Specific type of network device: CDMA/EVDO mobile phone.
static int	TYPE_MOBILE_PHONE_CDMA_1XRTT Specific type of network device: CDMA/1xRTT mobile phone.
static int	TYPE_MOBILE_PHONE_CDMA_EVDO Specific type of network device: CDMA/EVDO mobile phone.
static int	TYPE_MOBILE_PHONE_GSM_EDGE Specific type of network device: GSM/EDGE mobile phone.
static int	TYPE_MOBILE_PHONE_GSM_GPRS Specific type of network device: GSM/GPRS mobile phone.
static int	TYPE_OTHER Other specific types of network device.
static int	TYPE_WIFI Specific type of network device: WiFi.
static int	TYPE_WIMAX Specific type of network device: WiMAX.

Method Summary

static void	addResourceTypeListener(ResourceTypeListener listener) Adds a ResourceTypeListener to the implementation.
void	connect(Authenticator auth, String profile, NetworkDeviceStatusListener listener, long inactivityTimeout) Initiates the connection of the given network device to the network.
void	disconnect() Disconnects any connection that the given network device is having to the network.
String	getConnectionProfile() Returns the connection profile in use in case the device is connected or null if the device is not connected.
static NetworkDevice[]	getInstances(int type) Returns an array of handlers representing each a NetworkDevice resource available on the platform that meet the criteria defined by type.
long	getMaximumSpeed() Returns the maximum and theoretical downstream data rate of this resource.
NetworkInterface	getNetworkInterface() Returns the associated network interface if connected and null otherwise.
int	getType() Returns the type of this network device resource.
boolean	isAvailable() Checks whether the given resource is currently available for reservation.
boolean	isConnected() Returns true if the network device has been connected using the connect() method.
void	release() Releases this resource.
static void	removeResourceTypeListener(ResourceTypeListener listener) Removes a previously attached listener.
void	reserve(boolean force, long timeoutms, ScarceResourceListener listener) Requests reservation of the given scarce resource instance.
static NetworkDevice	reserveOne(boolean force, long timeoutms, ScarceResourceListener listener, int type) Returns a reserved instance out of the pool of all NetworkDevice instances of the given type.

Methods inherited from class java.lang.Object

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

Field Detail

TYPE_ANY

public static final int TYPE_ANY

Special type used in reserve representing any possible network device type.

See Also:

Constant Field Values

TYPE_OTHER

public static final int TYPE_OTHER

Other specific types of network device.

See Also:

Constant Field Values

TYPE_DIAL_UP

public static final int TYPE_DIAL_UP

Specific type of network device: Dial up.

See Also:

Constant Field Values

TYPE_ADSL

public static final int TYPE_ADSL

Specific type of network device: ADSL.

See Also:

Constant Field Values

TYPE_ISDN

public static final int TYPE_ISDN

Specific type of network device: ISDN.

See Also:

Constant Field Values

TYPE_MOBILE_PHONE

public static final int TYPE_MOBILE_PHONE

Specific type of network device: mobile phone (in this case, the mobile technology is not informed).

See Also:

Constant Field Values

TYPE_MOBILE_PHONE_GSM_EDGE

public static final int TYPE_MOBILE_PHONE_GSM_EDGE

Specific type of network device: GSM/EDGE mobile phone.

See Also:

Constant Field Values

TYPE_MOBILE_PHONE_CDMA_1XRTT

public static final int TYPE_MOBILE_PHONE_CDMA_1XRTT

Specific type of network device: CDMA/1xRTT mobile phone.

See Also:

Constant Field Values

TYPE_MOBILE_PHONE_CDAM_EVDO

public static final int TYPE_MOBILE_PHONE_CDAM_EVDO

Specific type of network device: CDMA/EVDO mobile phone.

See Also:

Constant Field Values

TYPE_MOBILE_PHONE_GSM_GPRS

public static final int TYPE_MOBILE_PHONE_GSM_GPRS

Specific type of network device: GSM/GPRS mobile phone.

See Also:

Constant Field Values

TYPE_MOBILE_PHONE_CDMA_EVDO

public static final int TYPE_MOBILE_PHONE_CDMA_EVDO

Specific type of network device: CDMA/EVDO mobile phone.

See Also:

Constant Field Values

TYPE_ETHERNET_PPPOE

public static final int TYPE_ETHERNET_PPPOE

Specific type of network device: Ethernet (PPPoE).

See Also:

Constant Field Values

TYPE_ETHERNET_FIXED_IP

public static final int TYPE_ETHERNET_FIXED_IP

Specific type of network device: Ethernet (Fixed IP).

See Also:

Constant Field Values

TYPE_ETHERNET_DHCP

public static final int TYPE_ETHERNET_DHCP

Specific type of network device: Ethernet (DHCP).

See Also:

Constant Field Values

TYPE_WIMAX

public static final int TYPE_WIMAX

Specific type of network device: WiMAX.

See Also:

Constant Field Values

TYPE_WIFI

public static final int TYPE_WIFI

Specific type of network device: WiFi.

See Also:

Constant Field Values

TYPE_DOCSIS

public static final int TYPE_DOCSIS

Specific type of network device: DOCSIS.

See Also:

Constant Field Values

TYPE_FTTH

public static final int TYPE_FTTH

Specific type of network device: FTTH.

See Also:

Constant Field Values

Method Detail

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:

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.

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.

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.

In the case the network device is connected when this method is being called, the implementation must call implicitly disconnect() before returning.

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.

getInstances

public static NetworkDevice[] getInstances(int type)
                                    throws IllegalArgumentException

Returns an array of handlers representing each a NetworkDevice resource available on the platform that meet the criteria defined by type. 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 devices exist, this method returns a zero-length array.

The criteria type allows the application to focus on a restricted subset of NetworkDevice resources.

Parameters:

type - Any of the TYPE_ constants defined by this class. In particular the TYPE_ANY let the implementation lists all network devices whatever its type is.

Returns:

An array of instances of resources of type NetworkDevice.

Throws:

IllegalArgumentException - If type is none of the value of any TYPE_ constant defined by this class.

reserveOne

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

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

The parameter type allows to reduce and focus the pool to choose a NetworkDevice instance from.

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.

type - Any of the TYPE_ constants defined by this class. In particular the TYPE_ANY let the implementation choose from any network devices whatever its type is.

Returns:

The instance of type NetworkDevice 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)

connect

public void connect(Authenticator auth,
                    String profile,
                    NetworkDeviceStatusListener listener,
                    long inactivityTimeout)
             throws NullPointerException,
                    IllegalArgumentException,
                    SecurityException,
                    IllegalStateException

Initiates the connection of the given network device to the network. This task includes dialing the dial-in number for dial-ups and setting up the corresponding network interface so that IP communication is made possible (IP routing defined, DNS set up...).

This method expects to find the parameters necessary to the connection process in the user properties tree pointed to by profile. It is left to the platform to define which parameters are required for any given network resource: for example a specific network device may require a dial-up number, another one an APN (Access Point Name), etc. There may also be no parameters at all in the passed profile path but that path must exist.

The call to this method is expected to return immediately and the actual connection process may be deferred to a separate process. The implementation will then use listener to inform the application about the status of the connection: connected or connectionFailed.

Parameters:

auth - The object handling the authentication. The value may be null indicating that no login and/or password are provided. In case where the connection still requires an authentication, empty strings (i.e. "") will be used by the implementation.

profile - The property path in the user properties tree where the associated configuration is stored. This path must either be null or begin with "com.sun.dtv.net.if.profiles." and be followed by a unique name describing the name of given profile. Setting the value to null is equivalent to setting it to "com.sun.dtv.net.if.profiles.default".

listener - The listener that is triggered for connection status changes.

inactivityTimeout - A positive amount of time in millisecond of inactivity on that network channel until when the platform will trigger the timingOut() method of the corresponding listener. The value of -1 indicates that the implementation will ignore that timeout.

Throws:

NullPointerException - If listener is null.

IllegalArgumentException - If the property path given in profile is not defined in the user properties or if it does not begin with "com.sun.dtv.net.if.profiles.".

SecurityException - if the caller is not allowed to connect with the configuration provided as properties: that include the case where the number to be dialed (for dial up type of device) is not granted by a corresponding NetworkDevicePermission dial action.

IllegalStateException - If the resource is not currently owned by this application (i.e. has not previously been reserved).

See Also:

User, NetworkDeviceStatusListener.connected(com.sun.dtv.net.NetworkDevice, java.net.NetworkInterface), NetworkDeviceStatusListener.connectionFailed(com.sun.dtv.net.NetworkDevice, java.lang.String)

disconnect

public void disconnect()
                throws IllegalStateException

Disconnects any connection that the given network device is having to the network. This task includes hooking on the dial-up connection in case of dial-ups. This call does nothing if the network device is not connected.

This method will return right after flushing the outgoing data stream. It will return to a state that allows a subsequent call to the corresponding connect() call. Upon returning, the implementation triggers the listener's disconnected() method.

Throws:

IllegalStateException - If the resource is not currently owned by this application (i.e. has not previously been reserved).

See Also:

connect(java.net.Authenticator, java.lang.String, com.sun.dtv.net.NetworkDeviceStatusListener, long), NetworkDeviceStatusListener.disconnected(com.sun.dtv.net.NetworkDevice)

isConnected

public boolean isConnected()
                    throws IllegalStateException

Returns true if the network device has been connected using the connect() method. Otherwise this method returns false.

Returns:

true if the network device is connected, false otherwise.

Throws:

IllegalStateException - If the resource is not currently owned by this application (i.e. has not previously been reserved).

getConnectionProfile

public String getConnectionProfile()
                            throws IllegalStateException

Returns the connection profile in use in case the device is connected or null if the device is not connected. The profile is a property path in the user properties tree where the associated configuration is stored.

Returns:

A string containing the profile that has been used when connecting or null if the device is disconnected.

Throws:

IllegalStateException - If the resource is not currently owned by this application (i.e. has not previously been reserved).

getNetworkInterface

public NetworkInterface getNetworkInterface()

Returns the associated network interface if connected and null otherwise. This must be the same instance that is returned through the NetworkDeviceStatusListener at connection time.

Returns:

the associated network interface if connected and null otherwise.

getType

public int getType()

Returns the type of this network device resource.

The value must correspond to one of the constants defined by this class. If none of the values fits the resource, then this method returns TYPE_OTHER.

Only the value TYPE_ANY must not be returned.

Returns:

The type of this resource.

getMaximumSpeed

public long getMaximumSpeed()

Returns the maximum and theoretical downstream data rate of this resource. This unit is kbps (kilobits per second, where kilobits = 1000bits).

Returns:

The data rate in kbps.