public interface DatagramConnection extends Connection
The parameter string describing the target of a connection takes the following generic form:
{protocol}://[{host}]:[{port}]Note that there are further constraints on the connect string as described below and by protocols derived from this interface and not all combinations of optional parts are permitted.
A datagram connection can be opened in a "client" mode or "server" mode. If the "{host}" part is missing then the connection is opened as a "server" (by "server", we mean that a client initiates communication). When the "{host}" part is specified, the connection is opened as a "client".
Examples:
A datagram connection for accepting datagrams
datagram://:1234
A datagram connection for sending to a server:
datagram://123.156.189.12:1234
A datagram connection for sending to a server using an IPv6 address:
datagram://[2001:db8::7]:2345
Note that the port number in "server mode" (unspecified host name) is that of the receiving port and may be omitted. The port number in "client mode" (host name specified) must be present and is that of the target port. The reply-to port in both cases is never specified. In "server mode", the same port number is used for both receiving and sending. In "client mode", the reply-to port is always dynamically allocated. A receiving port is always opened and security checks occur to insure that the application is allowed by the security policy to listen for and receive datagrams.
Also note that the allocation of datagram objects is done in a
more abstract way than in Java 2 Standard Edition (J2SE).
Instead of providing a concrete DatagramPacket
class,
an abstract Datagram
interface is provided. This
is to allow a single platform to support several different datagram
interfaces simultaneously. Datagram objects must be allocated by
calling the newDatagram
methods of the
DatagramConnection
object.
The resulting object is defined using another interface type
called javax.microedition.io.Datagram
.
The DatagramConnection
supports additional settings during Connector.open
to
specify non-standard behavior of the connection.
The following connection settings are supported on all platforms.
Name | Type | Values | Sample Value |
---|---|---|---|
Timeout | Integer | 2000 | |
AccessPoint | AccessPoint | See AccessPoint.getAccessPoints | |
EnableRoaming | Boolean | true or false |
|
IPVersion | String | "ipv4" | "ipv6" | "ipv6" |
The ConnectionOption Timeout
can be used to specify a timeout in milliseconds on blocking
receive operations on this connection.
With this option set to a non-zero timeout, a receive() call on the connection
will block for only this amount of time.
If the timeout expires a java.io.InterruptedIOException
is thrown.
The timeout value must be greater than or equal to 0. A timeout value of zero is interpreted as an infinite timeout.
If a platform does not support timeouts, the Timeout
setting is silently ignored
and the read/write operations behave as if it was set to 0.
The ConnectionOption AccessPoint
is used to supply a specific AccessPoint
instance that must be used for the connection.
The connect
method of the AccessPoint will be
called to connect the AccessPoint.
If the access point is not valid or can not be connected, Connector.Open
throws a ConnectionNotFoundException
.
ConnectionOption values are validated during Connector.open
and any exceptions reported.
In the case an AccessPoint is not present in the parameters to
Connector.open, Connector.open must use one of the AccessPoints
already connected that supports the requested ConnectionOptions.
If no AccessPoint is available the implementation may initialize a
network connection and create an AccessPoint for it.
Otherwise, a ConnectionNotFoundException is thrown.
The AccessPoint for a connection is available from getAccessPoint
.
The ConnectionOption EnableRoaming
with a value of true
is used to enable making connections via a NetworkInterface that returns
true
from isRoaming
.
The value false
disables creating connections via a roaming
NetworkInterface. A ConnectionNotFoundException
is
thrown if a roaming enabled connection was requested but cannot be found.
If the ConnectionOption is not present, it is implementation specific, whether
the use of roaming connections is permitted.
The ConnectionOption IPVersion
may be used on dual stack IPv4/IPv6 platforms
and AccessPoints,
for setting the preferred protocol stack (IPv4 or IPv6) as well as the preferred
address family types (inet4 or inet6) for the connection. Possible values are either
"ipv4" or "ipv6".
The host name to IP address lookup mechanism also uses IPVersion
.
If an IP Address of the requested address type is not available, whether via DNS
or other hostname translation service a java.net.UnknownHostException
is thrown.
If the exception occurs in Connector.open a
ConnectionNotFoundException
is thrown with the UnknownHostException
as the cause.
In case of a conflict between the IPVersion
ConnectionOption and
a literal host address in the URL string or another ConnectionOption
Connector.Open
throws a ConnectionNotFoundException
.
If the platform or AccessPoint does not support the selected IP version,
Connector.Open
throws a ConnectionNotFoundException
.
Modifier and Type | Method and Description |
---|---|
AccessPoint |
getAccessPoint()
Gets the AccessPoint for this connection.
|
int |
getMaximumLength()
Get the maximum length a datagram can be.
|
int |
getNominalLength()
Get the nominal length of a datagram.
|
Datagram |
newDatagram(byte[] buf,
int size)
Create a new datagram object.
|
Datagram |
newDatagram(byte[] buf,
int size,
java.lang.String addr)
Create a new datagram object.
|
Datagram |
newDatagram(int size)
Create a new datagram object.
|
Datagram |
newDatagram(int size,
java.lang.String addr)
Create a new datagram object.
|
void |
receive(Datagram dgram)
Receive a datagram.
|
void |
send(Datagram dgram)
Send a datagram.
|
close
AccessPoint getAccessPoint()
int getMaximumLength() throws java.io.IOException
newDatagram
method, and the
maximum size of the datagram that can be sent
or received.java.io.IOException
- If an I/O error occurs.int getNominalLength() throws java.io.IOException
java.io.IOException
- If an I/O error occurs.Datagram newDatagram(byte[] buf, int size) throws java.io.IOException
buf
- The buffer to be used for the datagramsize
- The size of the buffer needed
for the datagramjava.io.IOException
- If an I/O error occurs.java.lang.IllegalArgumentException
- if the size is negative or
larger than the maximum size or the given
buffer's length, or if the buffer parameter
is invalidDatagram newDatagram(byte[] buf, int size, java.lang.String addr) throws java.io.IOException
buf
- The buffer to be used for the datagramsize
- The size of the buffer needed
for the datagramaddr
- The I/O address to which the datagram
will be sent, in the form
"datagram://{host}:{port}"
.java.io.IOException
- If an I/O error occurs.java.lang.IllegalArgumentException
- if the size is negative or
larger than the maximum size or the given
buffer's length, or if the address or
buffer parameter is invalidDatagram newDatagram(int size) throws java.io.IOException
size
- The size of the buffer needed
for the datagramjava.io.IOException
- If an I/O error occurs.java.lang.IllegalArgumentException
- if the size is negative
or larger than the maximum sizeDatagram newDatagram(int size, java.lang.String addr) throws java.io.IOException
size
- The size of the buffer needed
for the datagramaddr
- The I/O address to which the datagram
will be sent, in the form
"datagram://{host}:{port}"
.java.io.IOException
- If an I/O error occurs.java.lang.IllegalArgumentException
- if the size is negative or
larger than the maximum size, or if the
address parameter is invalidvoid receive(Datagram dgram) throws java.io.IOException
Datagram
object is filled with
the data received, starting at the location determined by
the offset
state variable, and the data is
ready to be read using the methods of the
DataInput
interface.
This method blocks until a datagram is received. The internal
length
state variable in the Datagram
object is set to the length of the received datagram. If the
received data is longer than the initial length
state variable
of the internal buffer, data is truncated.
This method does not change the internal read/write state
variable of the Datagram
object. Use method
Datagram.reset
to change the pointer before
calling receive, if necessary.
If the application has permission to receive the datagram, the Datagram is filled with the data and address. If access is not permitted, the datagram is discarded without modifying the Datagram instance and the receive method does not return.
dgram
- A datagram.java.lang.NullPointerException
- if dgram
is null
.java.io.IOException
- If an I/O error occurs.java.io.InterruptedIOException
- Timeout or interrupt occurred.void send(Datagram dgram) throws java.io.IOException
Datagram
object includes
the information indicating the data to be sent, its length,
and the address of the receiver. The method sends length
bytes starting at the current offset
of the
Datagram
object, where length
and offset
are internal state variables
of the Datagram
object.dgram
- A datagram.java.lang.NullPointerException
- if dgram
is null
.java.io.IOException
- If an I/O error occurs;
for example if the Datagram's length exceeds the maximum size.java.lang.IllegalArgumentException
- if dgram.getAddress()
is null
.java.lang.SecurityException
- if the caller is not permitted to
send the datagram.Copyright (c) 2014, Oracle and/or its affiliates. All Rights Reserved. Use of this specification is subject to license terms.