doc/net.tex

   1 \documentclass[twocolumn,a4paper]{article}      % -*- latex -*-
   2
   3 \author{
   4         Mark Probst\\
   5         {\tt http://www.complang.tuwien.ac.at/\char'176schani/}
   6         }
   7 \title{\texttt{java.net} in Cacao}
   8
   9 \newcommand{\globvarslabel}[1]{\mbox{\texttt{#1}}\hfil}
  10 \newenvironment{globvars}
  11     {\begin{list}{}%
  12            {\renewcommand{\makelabel}{\globvarslabel}%
  13            }%
  14     }%
  15     {\end{list}}
  16
  17 \newcommand{\structdesclabel}[1]{\mbox{\texttt{#1}}\hfil}
  18 \newenvironment{structdesc}
  19     {\begin{list}{}%
  20            {\renewcommand{\makelabel}{\structdesclabel}%
  21            }%
  22     }%
  23     {\end{list}}
  24
  25 \newcommand{\class}[1]{\subsection{\texttt{#1}}}
  26 \newcommand{\method}[1]{\subsubsection*{\texttt{#1}}}
  27
  28 \begin{document}
  29
  30 \maketitle
  31
  32 \section{Overview}
  33
  34 The \texttt{java.net} package provides an API for accessing the TCP/IP
  35 protocol stack in Java 1.2.
  36
  37 \section{Native Methods}
  38
  39 Native method implementations reside in the directory
  40 \texttt{native}. The classes in \texttt{java.net} requiring native
  41 functions are: \texttt{DatagramPacket}, \texttt{InetAddress},
  42 \texttt{InetAddressImpl}, \texttt{PlainDatagramSocketImpl},
  43 \texttt{PlainSocketImpl}, \texttt{SocketInputStream} and
  44 \texttt{SocketOutputStream}.
  45
  46 The implementation of the native methods uses the BSD Sockets API. For
  47 a thorough description, see~\cite{stevens1}.
  48
  49 \textbf{Note:} Due to SUN Java 1.2's way of initializing native
  50 libraries (it assumes they are available as shared libraries, searches
  51 for them and fails initialization if they are not found) and the fact
  52 that Cacao does not (yet?) support native methods through shared
  53 libraries but instead links them statically, there must be a file
  54 \texttt{/tmp/dummy} existent in order for \texttt{java.net} to work.
  55
  56 \section{Threads}
  57
  58 Since Cacao does not use native threads to implement Java threads, the
  59 standard socket system calls can not be used directly since they
  60 prevent thread switching. Therefore, we use the method for I/O
  61 described in the Threads document.
  62
  63 \section{Native Methods}
  64
  65 All IP addresses passed over the native interface are in network byte
  66 order.
  67
  68 \class{InetAddress}
  69
  70 \method{init}
  71
  72 Does nothing.
  73
  74 \class{InetAddressImpl}
  75
  76 \method{getHostByAddr}
  77
  78 Returns as a \texttt{String} the name of the host with the given IP
  79 address. If the address cannot be resolved, raises an
  80 \texttt{UnknowHostException}.
  81
  82 \method{getInetFamily}
  83
  84 Returns \texttt{AF\_INET}.
  85
  86 \method{getLocalHostName}
  87
  88 Returns as a \texttt{String} the name of the local host as determined
  89 by \texttt{gethostname()} or, if that fails, returns
  90 \texttt{"localhost"}.
  91
  92 \method{lookupAllHostAddr}
  93
  94 Looks up all IP addresses of the given host name and returns them as
  95 an array of byte arrays of length 4. The array has as many elements as
  96 there are addresses. The index \texttt{[1][3]} contains the least
  97 significant byte of the second address, for example. If the host name
  98 cannot be resolved, raises an \texttt{UnknowHostException}.
  99
 100 \method{makeAnyLocalAddress}
 101
 102 Fills in the \texttt{address} and \texttt{family} instance variables
 103 of \texttt{this} with the values \texttt{INADDR\_ANY} and
 104 \texttt{AF\_INET}, respectively.
 105
 106 \class{DatagramPacket}
 107
 108 \method{init}
 109
 110 Does nothing.
 111
 112 \class{PlainDatagramSocketImpl}
 113
 114 \method{bind}
 115
 116 Binds the socket to the given port and IP address. Raises a
 117 \texttt{SocketException} on failure.
 118
 119 \method{datagramSocketClose}
 120
 121 If the file descriptor of the socket is not \texttt{-1}, calls
 122 \texttt{close()} on it and sets it to \texttt{-1}. If \texttt{close()}
 123 fails, raises a \texttt{SocketException}.
 124
 125 \method{datagramSocketCreate}
 126
 127 Creates a new datagram socket and sets the file descriptor instance
 128 variable to it. If creation fails, raises a \texttt{SocketException}.
 129
 130 \method{getTTL}
 131
 132 Calls \texttt{getTimeToLive}.
 133
 134 \method{getTimeToLive}
 135
 136 Returns the time-to-live of the socket, as determined by
 137 \texttt{getsockopt()}. If that fails, raises an \texttt{IOException}.
 138
 139 \method{init}
 140
 141 Does nothing.
 142
 143 \method{join}
 144
 145 Adds membership of the multicast group with the given IP address.
 146
 147 \method{leave}
 148
 149 Drops membership of the multicast group with the given IP address.
 150
 151 \method{peek}
 152
 153 Sets the given \texttt{InetAddress}'s \texttt{address} instance
 154 variable to the sender address of the next to be \texttt{receive}d
 155 datagram packet and returns its length, possibly blocking the thread.
 156 In case of failure, raises a \texttt{SocketException}.
 157
 158 \method{receive}
 159
 160 Copies the next datagram packet into the \texttt{data} instance
 161 variable of the \texttt{buf} instance variable of the given
 162 packet. The length of this array is read from the \texttt{length}
 163 instance variable of the packet. The length of the packet, the source
 164 port and source IP address are copied into the \texttt{length},
 165 \texttt{port} and \texttt{address} instance variables of the given
 166 packet, respectively. May block the thread. Raises a
 167 \texttt{SocketException} in case of failure.
 168
 169 \method{send}
 170
 171 Sends the given datagram packet. Raises a \texttt{SocketException} in
 172 case of failure. May block the thread.
 173
 174 \method{setTTL}
 175
 176 Calls \texttt{setTimeToLive}.
 177
 178 \method{setTimeToLive}
 179
 180 Sets the time-to-live of the socket to the given value using
 181 \texttt{setsockopt()}. Raises an \texttt{IOException} in case of
 182 failure.
 183
 184 \method{socketGetOption}
 185
 186 Determines one of the following socket options:
 187
 188 \medskip
 189 \begin{tabular}{|l|p{5cm}|} \hline
 190 Value           & Description \\ \hline
 191 \texttt{0x1001} & Send buffer size \\
 192 \texttt{0x1001} & Receive buffer size \\
 193 \texttt{0x0010} & Interface for outgoing multicast packets as IP address \\
 194 \texttt{0x000f} & IP address the socket is bound to \\ \hline
 195 \end{tabular}
 196 \medskip
 197
 198 Returns the value of the option as a Java \texttt{int}, or raises a
 199 \texttt{SocketException} in case of failure.
 200
 201 \method{socketSetOption}
 202
 203 Sets one of the following socket options:
 204
 205 \medskip
 206 \begin{tabular}{|l|p{3cm}|l|} \hline
 207 Value           & Description & Java type \\ \hline
 208 \texttt{0x0004} & \texttt{SO\_REUSEADDR}, see~\cite{stevens1}, pages~194ff & \texttt{Integer} \\
 209 \texttt{0x1001} & Send buffer size & \texttt{Integer} \\
 210 \texttt{0x1001} & Receive buffer size & \texttt{Integer} \\
 211 \texttt{0x0010} & Interface for outgoing multicast packets & \texttt{InetAddress} \\ \hline
 212 \end{tabular}
 213 \medskip
 214
 215 The value to be set must be passed to the native method as a Java
 216 object of the class specified in the table above. Raises a
 217 \texttt{SocketException} in case of failure.
 218
 219 \class{PlainSocketImpl}
 220
 221 \method{initProto}
 222
 223 Does nothing.
 224
 225 \method{socketAccept}
 226
 227 Calls \texttt{accept()} on the socket in \texttt{this} with the port
 228 and address from the \texttt{localport} and \texttt{address} instance
 229 variables of the first non-implicit parameter (a
 230 \texttt{SocketImpl}). If successful, sets the socket of the
 231 \texttt{SocketImpl} to the new socket, determines the address and port
 232 of the peer and copies those into the \texttt{address} and
 233 \texttt{port} instance variables of the \texttt{SocketImpl},
 234 respectively. In case of failure (whether with \texttt{accept()} or
 235 \texttt{getpeername()}), raises an \texttt{IOException}.
 236
 237 \method{socketAvailable}
 238
 239 Returns the number of bytes that can be read without blocking or
 240 raises an \texttt{IOException} in case of failure.
 241
 242 \method{socketBind}
 243
 244 Sets the \texttt{SO\_REUSEADDR} option on the socket and binds it to
 245 the given address and port. Copies the address and the port bound to
 246 into the \texttt{address} and \texttt{localport} instance variables of
 247 \texttt{this}, respectively. In case of failure raises an
 248 \texttt{IOException}.
 249
 250 \method{socketClose}
 251
 252 If the file descriptor of the socket is not \texttt{-1}, calls
 253 \texttt{close()} on it and sets it to \texttt{-1}. If \texttt{close()}
 254 fails, raises a \texttt{IOException}.
 255
 256 \method{socketConnect}
 257
 258 Connects the socket to the given address and port. Copies the address,
 259 the port and the new local port into the \texttt{address},
 260 \texttt{port} and \texttt{localport} instance variables of this,
 261 respectively.
 262
 263 \method{socketCreate}
 264
 265 Creates a new stream socket if the \texttt{bool} parameter is
 266 \texttt{true}, otherwise a datagram socket and sets the file
 267 descriptor instance variable to it. If creation fails, raises an
 268 \texttt{IOException}.
 269
 270 \method{socketGetOption}
 271
 272 Determines one of the following socket options:
 273
 274 \medskip
 275 \begin{tabular}{|l|p{5cm}|} \hline
 276 Value           & Description \\ \hline
 277 \texttt{0x0080} & \texttt{SO\_LINGER}, see~\cite{stevens1}, pages~187ff.
 278                   If \texttt{l\_onoff} is \texttt{0}, returns \texttt{-1},
 279                   otherwise the value of \texttt{l\_linger}. \\
 280 \texttt{0x0001} & Nagle algorithm disabled? \\
 281 \texttt{0x1001} & Send buffer size \\
 282 \texttt{0x1001} & Receive buffer size \\
 283 \texttt{0x000f} & IP address the socket is bound to \\ \hline
 284 \end{tabular}
 285 \medskip
 286
 287 Returns the value of the option as a Java \texttt{int}, or raises a
 288 \texttt{SocketException} in case of failure.
 289
 290 \method{socketListen}
 291
 292 Calls \texttt{listen()} on the socket with the given backlog
 293 parameter. Raises an \texttt{IOException} in case of failure.
 294
 295 \method{socketSetOption}
 296
 297 Sets one of the following socket options:
 298
 299 \medskip
 300 \begin{tabular}{|l|p{3cm}|l|} \hline
 301 Value           & Description & Java type \\ \hline
 302 \texttt{0x0080} & \texttt{SO\_LINGER}, see~\cite{stevens1}, pages~187ff.
 303                   If the \texttt{bool} parameter is \texttt{true}, sets
 304                   \texttt{l\_onoff} to \texttt{1} and \texttt{l\_linger}
 305                   to the given value. Otherwise, sets \texttt{l\_onoff} to \texttt{0}. & \texttt{Integer} \\
 306 \texttt{0x0001} & Disable Nagle algorithm? Uses only the \texttt{bool} parameter. & n/a \\
 307 \texttt{0x1001} & Send buffer size & \texttt{Integer} \\
 308 \texttt{0x1001} & Receive buffer size & \texttt{Integer} \\ \hline
 309 \end{tabular}
 310 \medskip
 311
 312 The value to be set must be passed to the native method as a Java
 313 object of the class specified in the table above. Raises a
 314 \texttt{SocketException} in case of failure.
 315
 316 \class{SocketInputStream}
 317
 318 \method{init}
 319
 320 Does nothing.
 321
 322 \method{socketRead}
 323
 324 Receives at most the given number of bytes into the given array
 325 beginning at the given offset. Returns the number of bytes read or
 326 \texttt{-1} in case of EOF. May block the thread. Raises an
 327 \texttt{IOException} in case of failure.
 328
 329 \class{SocketOutputStream}
 330
 331 \method{init}
 332
 333 Does nothing.
 334
 335 \method{socketWrite}
 336
 337 Sends exactly the given number of butes from the given array beginning
 338 at the given offset. May block the thread. In case of failure, returns
 339 \texttt{IOException}.
 340
 341 \bibliography{net}
 342 \bibliographystyle{plain}
 343
 344 \end{document}