public class AccessPoint
extends java.lang.Object
NetworkInterface
.
Typically, AccessPoints are provided by the system but an application
can provide the parameters needed for a specific network configuration.
Note that network configurations and behavior vary widely and
are dependent on device specific implementations and network infrastructure;
as a result applications should be prepared to cope with
failures and recover as gracefully and completely as possible.
To select an AccessPoint for a specific network connection
use the open
methods of Connector
and provide
the AccessPoint as a ConnectionOption
.
AccessPoint provides information such as name and network type as well
as properties of the network via the getProperty
method.
The values of all properties are strings but may
have additional formatting depending on the value.
For example, the signalstrength
property can be parsed as an integer.
The network type reflects the underlying bearer technology.
The data access protocol as appropriate to the bearer technology
is available from the protocol
property.
The network technologies are "3GPP", "CDMA", "WIFI", "WIRED", "DIALUP", and
"LOOPBACK" and are case-sensitive.
The following network types and data access protocols should be used
for easy recognition by application code.
Network Type | Description | Data Access Protocols |
---|---|---|
"3GPP" | Any of the 3GPP networking bearers | "GPRS" , "EDGE" , "UTRAN" , "HSDPA" ,
"HSDPA/HSUDA" , or "LTE" |
"CDMA" | Any of the CDMA standards | "IS-95" , "1xRTT" , "EVDO" |
"WIFI" | Wi-Fi 802.11 B/G/N - | N/A |
"WIRED" | Any wired connection | N/A |
"DIALUP" | Dial-up networking using PPP or equivalent CSD connection on a packet network | N/A |
"LOOPBACK" | Loopback networking to the local host itself | N/A |
An implementation may provide additional network types and should reuse property names and behavior appropriate to the network characteristics.
Existing AccessPoints are listed using the
getAccessPoints
method
and include both AccessPoints provided by the system based on
system configuration information as well as AccessPoints
created using the AccessPoint.of
factory method.
Note that AccessPoints may be created and removed dynamically by
the system or applications and an AccessPoint becomes invalid when it is
removed. An invalid AccessPoint retains the type and
the properties associated with a disconnected AccessPoint.
Applications should not retain references to invalid AccessPoints.
AccessPointListeners
can be added and removed
from AccessPoints to be notified of connect, disconnect, and removal
state changes of the underlying networking stack.
The factory method AccessPoint.of
uses ConnectionOptions
to find or create a matching AccessPoint.
The method will return an existing AccessPoint with the same ConnectionOptions
if one exists.
The remove
method is used
to remove an AccessPoint created by AccessPoint.of
if it is a removable access point and
is not connected.
System provided AccessPoints are managed by the implementation and can not be removed.
Note that AccessPoint methods are protected by AccessPointPermission
since the methods and properties may contain sensitive user information
or can affect the operation of the networking state.
3GPP network type specific properties are:
Property | Description | Required/Optional |
---|---|---|
apn | 3GPP Access Point Name | Required if connected |
apnoperator | The name of the operator providing the APN;
if no other value is available for the operator name, the concatenation
of the MCC and MNC components of the IMSI,
as strings separated by " " (space 0x20), must be returned.
|
Required if connected |
signalstrength | Current signal strength; value 0..100 | Required if connected |
protocol | Current access protocol; one of "GPRS" , "EDGE" ,
"UTRAN" , "HSDPA" , "HSDPA/HSUDA" ,
or "LTE" |
Required if connected |
dnsserver | IPv4 and/or IPv6 address(es) of DNS Server(s) | Optional |
ipaddr | IPv4 and/or IPv6 address(es) of the AccessPoint | Required if connected |
passwordsupplied | a password is already known for the AccessPoint that was or
will be used to make the connection; true or false ;
if absent same as false |
Optional |
To find or create a 3GPP AccessPoint using AccessPoint.of
the type is "3GPP"
and the ConnectionOptions are:
ConnectionOption<String>
;
the AccessPoint name is set to the apn
;
the name "*"
(asterisk 0x2a) is reserved for the purpose
of allowing the implementation to select the apn
, potentially by
negotiating with the 3GPP network when activating the connection;
when connected, the apn
property of the AccessPoint
will return the selected apn;
many apns are pre-defined and provisioned by the network operator and
additional APNs can be created as needed
apn
property above.
ConnectionOption<String>
,
the network connection may fail if required by the network and is not supplied
ConnectionOption<char[]>
,
the network connection may fail if required by the network and is not supplied;
the value should be overwritten after use to protect the password
apn
and apnoperator
exists and is not connected, the username
is updated and
password
is stored securely for use by connect.
If an AccessPoint with the apn
does not exist one is created
with the provided values and returned.
CDMA network type specific properties are:
Property | Description | Value |
---|---|---|
protocol | Current access protocol;
one of "IS-95" , "1xRTT" , or "EVDO" |
Required if connected |
signalstrength | Current signal strength; value 0..100 | Required if connected |
dnsserver | IPv4 and/or IPv6 address of DNS Server(s) | Optional |
ipaddr | IPv4 and/or IPv6 address(es) of the AccessPoint | Required if connected |
CDMA AccessPoints are system AccessPoints and can not be created by applications.
To find a CDMA AccessPoint using AccessPoint.of
the type is "CDMA"
.
WIFI B/G/N network type specific properties are:
Property | Description | Value |
---|---|---|
ssid | SSID of the network access point | Required |
authtype | If present, one of "none" , "WEP" , "WPA" ,
"WPA2" or the name of a recognized authentication type for Wi-Fi;
authtype is case-sensitive |
Optional |
signalstrength | Current signal strength; value 0..100 | Required if connected |
dnsserver | IPv4 and/or IPv6 address of DNS Server(s) | Optional |
ipaddr | IPv4 and/or IPv6 address(es) of the AccessPoint | Required if connected |
passwordsupplied | a password is already known for the AccessPoint that was or
will be used to make the connection; true or false ;
if absent same as false |
Optional |
To find or create a Wi-Fi AccessPoint using AccessPoint.of
the type is "WIFI"
and the ConnectionOptions are:
ssid
- required, a ConnectionOption<String>
;
the AccessPoint name is set to the ssid
authtype
- optional, a ConnectionOption<String>
,
one of "none"
, "WEP"
, "WPA"
, "WPA2"
,
or the name of a recognized authentication type for Wi-Fi
ConnectionOption<char[]>
,
the network connection may fail if required by the network and is not supplied;
the value should be overwritten after use to protect the password
ssid
exists and is not connected,
the authtype
is updated and password
is stored securely
for use by connect. If an AccessPoint with the same ssid
does not exist, one is created; in both cases the AccessPoint matching the
ssid
is returned.
Wired network type specific properties are:
Property | Description | Value |
---|---|---|
dnsserver | IPv4 and/or IPv6 address of DNS Server(s) | Optional |
ipaddr | IPv4 and/or IPv6 address(es) of the AccessPoint | Required if connected |
Wired AccessPoints are system AccessPoints and can not be created by applications.
To find a Wired AccessPoint using AccessPoint.of
use type "WIRED"
.
Dial-up or CSD network type specific properties are:
Property | Description | Value |
---|---|---|
phonenumber | The phone number used to connect the AccessPoint and establish TCP/IP networking; as a String as needed to place a call from the device. | Required |
dnsserver | IPv4 and/or IPv6 address of DNS Server(s) | Optional |
ipaddr | IPv4 and/or IPv6 address(es) of the AccessPoint | Required if connected |
passwordsupplied | a password is already known for the AccessPoint that was or
will be used to make the connection; true or false ;
if absent same as false |
Optional |
To find or create a Dial-up Modem AccessPoint using AccessPoint.of
the type is "DIALUP"
and the ConnectionOptions are:
phonenumber
- required, a ConnectionOption<String>
ConnectionOption<String>
,
the network connection may fail if required by the network and is not supplied
ConnectionOption<char[]>
,
the network connection may fail if required by the network and is not supplied;
the value should be overwritten after use to protect the password
number
exists and is not connected,
the username
is updated and password
is stored securely
for use by connect. If an AccessPoint with the same phonenumber
does not exist, one is created; in both cases the AccessPoint matching the
phonenumber
is returned.
Loopback network type specific properties are:
Property | Description | Value |
---|---|---|
ipaddr | IPv4 and/or IPv6 address(es) of the AccessPoint | Required if connected |
Loopback AccessPoints are system AccessPoints and can not be created by applications.
Note that a Loopback AccessPoint can only be used to connect to the local host
and has no name service.
To find a Loopback AccessPoint using AccessPoint.of
use type "LOOPBACK"
.
setTimeout
the
AccessPoint will be automatically disconnected if the AccessPoint(s)
are not used for network traffic for the given amount of time.
For most network types, timeouts are not useful but if the connection
is charged by time such as a GPRS CSD (circuit switched data) or
dial-up modem then the timeouts are useful to save costs or other
system resources when the network is not needed.
Connector.open
.
A list of all valid AccessPoints can be obtained from getAccessPoints
;
The AccessPoint is used as the value for the "AccessPoint" ConnectionOption.
See the following example:
.
// Get a list of all connected AccessPoints
AccessPoint[] aps = AccessPoint.getAccessPoints(true);
// Create an option named "AccessPoint" for the first AccessPoint
ConnectionOption<AccessPoint> accessPointOption = new ConnectionOption<>("AccessPoint", aps[0]);
// Open the connection using the specific AccessPoint
Connection c = Connector.open("http://www.oracle.com/index.html", accessPointOption);
See the description of Connector
for details.
.
// Create options for a WiFi connection with SSID = "mynet" and password "abc"
ConnectionOption<String> ssid = new ConnectionOption<>("ssid", "mynet");
ConnectionOption<char[]> password = new ConnectionOption<>("password", new char[]{'a', 'b', 'c'});
AccessPoint ap = AccessPoint.of("WIFI", ssid, password);
// Open a connection using the AccessPoint
String url = "http://...";
ConnectionOption<AccessPoint> accessPointOption = new ConnectionOption("AccessPoint", ap);
try (HttpConnection c = (HttpConnection)Connector.open(url, accessPointOption);
DataOutputStream os = c.openDataOutputStream()) {
os.writeUTF("Hello World\n");
} // Try-with-resources closes output stream and the connection
// Disconnect the AccessPoint
ap.disconnect();
// Remove the AccessPoint
AccessPoint.remove(ap);
Modifier and Type | Method and Description |
---|---|
void |
addListener(AccessPointListener listener)
Adds a new AccessPoint listener.
|
boolean |
connect()
Connects the AccessPoint if not connected.
|
boolean |
disconnect()
Disconnects the AccessPoint if connected.
|
static AccessPoint[] |
getAccessPoints(boolean connectedOnly)
Returns the existing AccessPoints.
|
java.lang.String |
getName()
Returns the name of this AccessPoint.
|
NetworkInterface |
getNetworkInterface()
Returns the
NetworkInterface connecting this AccessPoint. |
java.lang.String |
getProperty(java.lang.String property)
Return an AccessPoint property value.
|
java.lang.String[] |
getPropertyNames()
Returns all property names for this AccessPoint.
|
java.lang.String[] |
getPropertyValues(java.lang.String property)
Return the values for an AccessPoint property.
|
int |
getTimeout()
Returns the timeout for this AccessPoint.
|
java.lang.String |
getType()
Returns the network type of this AccessPoint.
|
boolean |
isConnected()
Checks whether this AccessPoint is connected.
|
boolean |
isRemovable()
Checks if this AccessPoint can be removed.
|
static AccessPoint |
of(java.lang.String type,
ConnectionOption... options)
Returns an AccessPoint for a network type with the required ConnectionOptions.
|
static boolean |
remove(AccessPoint accessPoint)
Remove the AccessPoint.
|
void |
removeListener(AccessPointListener listener)
Removes the AccessPointListener.
|
void |
setTimeout(int milliseconds)
Set the timeout for this AccessPoint.
|
public void addListener(AccessPointListener listener)
listener
- AccessPointListener to subscribejava.lang.NullPointerException
- if listener is null
public boolean connect() throws java.io.IOException
NetworkInterface
with the same type is located
and its NetworkInterface.connect
method is invoked to initialize the NetworkInterface with
the AccessPoint. If more than one NetworkInterface with the
same type is found and not connected then the choice of NetworkInterface
is implementation specific. To control which NetworkInterface is
used to connect an AccessPoint use the
NetworkInterface.connect
method.
The connect
method blocks until the connection succeeds or
an exception is thrown. When and if the connection of the AccessPoint
to the NetworkInterface is successful an
AccessPointListener.EVENT_TYPE_CONNECTED
event is delivered to the listeners, if any, of the AccessPoint.
true
if was connected;
false
if was disconnectedjava.io.IOException
- if the initialization of the AccessPoint fails or
if a NetworkInterface of the same type is not availablejava.lang.IllegalStateException
- if this AccessPoint is invalid and
can not be used to make connectionsjava.lang.SecurityException
- if the SecurityManager policy does not permit
AccessPointPermission("manage")
isConnected()
,
NetworkInterface.connect(AccessPoint)
public boolean disconnect() throws java.io.IOException
A disconnected AccessPoint cannot be used for network communications
for either already opened or new
connections
.
Connection methods that cannot be completed without network access
throw java.io.IOException if the network is not available.
Note that whether a method does or does not require network access
to complete may depend not only on a protocol, but also on a particular
implementation technique for some protocols (for example, caching for HTTP).
When the disconnect from the network is successful an
AccessPointListener.EVENT_TYPE_DISCONNECTED
event is delivered to the AccessPoint listeners.
true
if was connected;
false
if disconnectedjava.io.IOException
- if an error occursjava.lang.SecurityException
- if the SecurityManager policy does not permit
AccessPointPermission("manage")
isConnected()
,
NetworkInterface.disconnect(AccessPoint)
public static AccessPoint[] getAccessPoints(boolean connectedOnly)
getAccessPoints
.connectedOnly
- if true
only AccessPoints in the connected state are returned,
otherwise all valid AccessPoints are returnednull
remove(javax.microedition.io.AccessPoint)
public java.lang.String getName()
null
and not emptypublic NetworkInterface getNetworkInterface()
NetworkInterface
connecting this AccessPoint.NetworkInterface
if this AccessPoint is connected;
otherwise null
isConnected()
,
NetworkInterface
public java.lang.String getProperty(java.lang.String property)
getPropertyValues(java.lang.String)
.
The properties of an AccessPoint that has been removed
reflect
the disconnected
state of the AccessPoint.
property
- name of the property to retrieve; not nullnull
if property is not supportedjava.lang.SecurityException
- if the SecurityManager policy does not permit
AccessPointPermission("property")
java.lang.NullPointerException
- if property
is null
getPropertyValues(java.lang.String)
,
getPropertyNames()
public java.lang.String[] getPropertyNames()
Modifications to the returned String array must not
change the behavior of past or future calls to getPropertyNames
.
java.lang.SecurityException
- if the SecurityManager policy does not permit
AccessPointPermission("property")
getPropertyValues(java.lang.String)
,
getProperty(java.lang.String)
public java.lang.String[] getPropertyValues(java.lang.String property)
"ipaddr"
and
"dnsserver"
may have multiple values.
The individual values are returned as separate strings.
A single valued property is returned in a one element array.
The properties of the AccessPoint that has been removed
reflect
the disconnected
state of the AccessPoint.
Modifications to the returned String array must not
change the behavior of past or future calls to getPropertyValues
.
property
- name of the property to retrieve; not nulljava.lang.NullPointerException
- if property
is null
java.lang.SecurityException
- if the SecurityManager policy does not permit
AccessPointPermission("property")
getProperty(java.lang.String)
,
getPropertyNames()
public int getTimeout()
java.lang.UnsupportedOperationException
- if timeouts and automatic
disconnection are not supportedsetTimeout(int)
public java.lang.String getType()
"3GPP"
, "CDMA"
,
"WIFI"
, "WIRED"
, "DIALUP"
, and "LOOPBACK"
.
Additional network types may be provided by the implementation.null
and not emptypublic boolean isConnected()
Connector.open
.java.lang.IllegalStateException
- if this AccessPoint is invalid and
can not be used to make connections.connect()
,
disconnect()
,
getNetworkInterface()
public boolean isRemovable()
of factory method
can be removed.
System AccessPoints can not be removed
.true
if the AccessPoint can be removed;
false
if the AccessPoint was created by the system.public static AccessPoint of(java.lang.String type, ConnectionOption... options)
SSID
.
Refer to the sections above for the ConnectionsOptions for each network type,
"3GPP", "CDMA",
"WIFI", "WIRED",
"DIALUP" and "LOOPBACK".
If any of the required ConnectionOptions are missing or invalid for the type then the appropriate exception is thrown. The type and ConnectionOptions are used to find an AccessPoint from the set of AccessPoints with the same type and required properties.
If an AccessPoint exists and is not connected, the optional ConnectionOption
values are used to update the AccessPoint and the AccessPoint is returned.
For example, to provide or replace the password
.
If the AccessPoint is connected, and the supplied optional
ConnectionOptions are equal to the current values, the AccessPoint is returned;
otherwise the settings can not be changed and
an IllegalStateException
is thrown.
If an AccessPoint does not exist and the network type is supported
then an AccessPoint is created with the ConnectionOptions and returned.
If creating an AccessPoint for this network type is not supported
an UnsupportedOperationException
is thrown.
If more than one AccessPoint matches the request then it is implementation specific which one is found and returned.
type
- the type of the AccessPoint; not null
and not empty;
refer to the table of well known network typesoptions
- ConnectionOptions required for the network type;
if a ConnectionOption with the same name appears
more than once, only the last one is usedjava.lang.IllegalArgumentException
- if the network type is not supported or
if any of the ConnectionOptions required for the type are missing or
if any of the ConnectionOptions are incompatible with the network type
or the value of any ConnectionOption is invalidjava.lang.UnsupportedOperationException
- if the optional
ConnectionOptions can not be changed;
for example if the username or password are pre-configured or
if a matching AccessPoint cannot be found and creating AccessPoints is not supportedjava.lang.IllegalStateException
- if the AccessPoint is connected and
any ConnectionOption value is not equal to the current valuejava.lang.NullPointerException
- if type
or any ConnectionOption
is null
java.lang.SecurityException
- if the SecurityManager policy does not permit
AccessPointPermission("manage")
getAccessPoints(boolean)
,
connect()
public static boolean remove(AccessPoint accessPoint)
AccessPoint.of
and is not
connected the AccessPoint will be removed.
The listeners of the AccessPoint will be called with the
AccessPointListener.EVENT_TYPE_REMOVED
event.
An AccessPoint that has been removed is invalid and can not be used.
The properties of an AccessPoint that has been removed
reflect
the disconnected
state of the AccessPoint.
Subsequently, no events will occur on the AccessPoint and
listeners will no longer be called.
accessPoint
- the AccessPoint to remove, not nulltrue
if isRemovable
is true
, and
isConnected
is false
,
and the AccessPoint was removed;
false
otherwisejava.lang.NullPointerException
- if accessPoint
is null
java.lang.SecurityException
- if the SecurityManager policy does not permit
AccessPointPermission("manage")
isRemovable()
,
of(java.lang.String, javax.microedition.io.ConnectionOption...)
public void removeListener(AccessPointListener listener)
listener
- AccessPointListener to remove registration for; non-nulljava.lang.NullPointerException
- if listener is null
public void setTimeout(int milliseconds)
disconnected
.
The timer starts when it is detected there are no GCF Connections open
using this AccessPoint.
Calling setTimeout
when no GCF Connections are open must restart the timer.milliseconds
- the duration in milliseconds to keep the AccessPoint connected;
the value zero is equivalent to an infinite timeoutjava.lang.IllegalArgumentException
- if milliseconds
is less than zerojava.lang.UnsupportedOperationException
- if timeouts and automatic
disconnection are not supportedjava.lang.SecurityException
- if the SecurityManager policy does not permit
AccessPointPermission("manage")
getTimeout()
,
disconnect()
Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. Use of this specification is subject to license terms.