\documentclass[twocolumn,a4paper]{article}      % -*- latex -*-

\author{
	Mark Probst\\
	{\tt http://www.complang.tuwien.ac.at/\char'176schani/}
	}
\title{\texttt{java.net} in Cacao}

\newcommand{\globvarslabel}[1]{\mbox{\texttt{#1}}\hfil}
\newenvironment{globvars}
    {\begin{list}{}%
           {\renewcommand{\makelabel}{\globvarslabel}%
           }%
    }%
    {\end{list}}

\newcommand{\structdesclabel}[1]{\mbox{\texttt{#1}}\hfil}
\newenvironment{structdesc}
    {\begin{list}{}%
           {\renewcommand{\makelabel}{\structdesclabel}%
           }%
    }%
    {\end{list}}

\newcommand{\class}[1]{\subsection{\texttt{#1}}}
\newcommand{\method}[1]{\subsubsection*{\texttt{#1}}}

\begin{document}

\maketitle

\section{Overview}

The \texttt{java.net} package provides an API for accessing the TCP/IP
protocol stack in Java 1.2.

\section{Native Methods}

Native method implementations reside in the directory
\texttt{native}. The classes in \texttt{java.net} requiring native
functions are: \texttt{DatagramPacket}, \texttt{InetAddress},
\texttt{InetAddressImpl}, \texttt{PlainDatagramSocketImpl},
\texttt{PlainSocketImpl}, \texttt{SocketInputStream} and
\texttt{SocketOutputStream}.

The implementation of the native methods uses the BSD Sockets API. For
a thorough description, see~\cite{stevens1}. 

\textbf{Note:} Due to SUN Java 1.2's way of initializing native
libraries (it assumes they are available as shared libraries, searches
for them and fails initialization if they are not found) and the fact
that Cacao does not (yet?) support native methods through shared
libraries but instead links them statically, there must be a file
\texttt{/tmp/dummy} existent in order for \texttt{java.net} to work.

\section{Threads}

Since Cacao does not use native threads to implement Java threads, the
standard socket system calls can not be used directly since they
prevent thread switching. Therefore, we use the method for I/O
described in the Threads document.

\section{Native Methods}

All IP addresses passed over the native interface are in network byte
order.

\class{InetAddress}

\method{init}

Does nothing.

\class{InetAddressImpl}

\method{getHostByAddr}

Returns as a \texttt{String} the name of the host with the given IP
address. If the address cannot be resolved, raises an
\texttt{UnknowHostException}.

\method{getInetFamily}

Returns \texttt{AF\_INET}.

\method{getLocalHostName}

Returns as a \texttt{String} the name of the local host as determined
by \texttt{gethostname()} or, if that fails, returns
\texttt{"localhost"}.

\method{lookupAllHostAddr}

Looks up all IP addresses of the given host name and returns them as
an array of byte arrays of length 4. The array has as many elements as
there are addresses. The index \texttt{[1][3]} contains the least
significant byte of the second address, for example. If the host name
cannot be resolved, raises an \texttt{UnknowHostException}.

\method{makeAnyLocalAddress}

Fills in the \texttt{address} and \texttt{family} instance variables
of \texttt{this} with the values \texttt{INADDR\_ANY} and
\texttt{AF\_INET}, respectively.

\class{DatagramPacket}

\method{init}

Does nothing.

\class{PlainDatagramSocketImpl}

\method{bind}

Binds the socket to the given port and IP address. Raises a
\texttt{SocketException} on failure.

\method{datagramSocketClose}

If the file descriptor of the socket is not \texttt{-1}, calls
\texttt{close()} on it and sets it to \texttt{-1}. If \texttt{close()}
fails, raises a \texttt{SocketException}.

\method{datagramSocketCreate}

Creates a new datagram socket and sets the file descriptor instance
variable to it. If creation fails, raises a \texttt{SocketException}.

\method{getTTL}

Calls \texttt{getTimeToLive}.

\method{getTimeToLive}

Returns the time-to-live of the socket, as determined by
\texttt{getsockopt()}. If that fails, raises an \texttt{IOException}.

\method{init}

Does nothing.

\method{join}

Adds membership of the multicast group with the given IP address.

\method{leave}

Drops membership of the multicast group with the given IP address.

\method{peek}

Sets the given \texttt{InetAddress}'s \texttt{address} instance
variable to the sender address of the next to be \texttt{receive}d
datagram packet and returns its length, possibly blocking the thread.
In case of failure, raises a \texttt{SocketException}.

\method{receive}

Copies the next datagram packet into the \texttt{data} instance
variable of the \texttt{buf} instance variable of the given
packet. The length of this array is read from the \texttt{length}
instance variable of the packet. The length of the packet, the source
port and source IP address are copied into the \texttt{length},
\texttt{port} and \texttt{address} instance variables of the given
packet, respectively. May block the thread. Raises a
\texttt{SocketException} in case of failure.

\method{send}

Sends the given datagram packet. Raises a \texttt{SocketException} in
case of failure. May block the thread.

\method{setTTL}

Calls \texttt{setTimeToLive}.

\method{setTimeToLive}

Sets the time-to-live of the socket to the given value using
\texttt{setsockopt()}. Raises an \texttt{IOException} in case of
failure.

\method{socketGetOption}

Determines one of the following socket options:

\medskip
\begin{tabular}{|l|p{5cm}|} \hline
Value           & Description \\ \hline
\texttt{0x1001} & Send buffer size \\
\texttt{0x1001} & Receive buffer size \\
\texttt{0x0010} & Interface for outgoing multicast packets as IP address \\
\texttt{0x000f} & IP address the socket is bound to \\ \hline
\end{tabular}
\medskip

Returns the value of the option as a Java \texttt{int}, or raises a
\texttt{SocketException} in case of failure.

\method{socketSetOption}

Sets one of the following socket options:

\medskip
\begin{tabular}{|l|p{3cm}|l|} \hline
Value           & Description & Java type \\ \hline
\texttt{0x0004} & \texttt{SO\_REUSEADDR}, see~\cite{stevens1}, pages~194ff & \texttt{Integer} \\
\texttt{0x1001} & Send buffer size & \texttt{Integer} \\
\texttt{0x1001} & Receive buffer size & \texttt{Integer} \\
\texttt{0x0010} & Interface for outgoing multicast packets & \texttt{InetAddress} \\ \hline
\end{tabular}
\medskip

The value to be set must be passed to the native method as a Java
object of the class specified in the table above. Raises a
\texttt{SocketException} in case of failure.

\class{PlainSocketImpl}

\method{initProto}

Does nothing.

\method{socketAccept}

Calls \texttt{accept()} on the socket in \texttt{this} with the port
and address from the \texttt{localport} and \texttt{address} instance
variables of the first non-implicit parameter (a
\texttt{SocketImpl}). If successful, sets the socket of the
\texttt{SocketImpl} to the new socket, determines the address and port
of the peer and copies those into the \texttt{address} and
\texttt{port} instance variables of the \texttt{SocketImpl},
respectively. In case of failure (whether with \texttt{accept()} or
\texttt{getpeername()}), raises an \texttt{IOException}.

\method{socketAvailable}

Returns the number of bytes that can be read without blocking or
raises an \texttt{IOException} in case of failure.

\method{socketBind}

Sets the \texttt{SO\_REUSEADDR} option on the socket and binds it to
the given address and port. Copies the address and the port bound to
into the \texttt{address} and \texttt{localport} instance variables of
\texttt{this}, respectively. In case of failure raises an
\texttt{IOException}.

\method{socketClose}

If the file descriptor of the socket is not \texttt{-1}, calls
\texttt{close()} on it and sets it to \texttt{-1}. If \texttt{close()}
fails, raises a \texttt{IOException}.

\method{socketConnect}

Connects the socket to the given address and port. Copies the address,
the port and the new local port into the \texttt{address},
\texttt{port} and \texttt{localport} instance variables of this,
respectively.

\method{socketCreate}

Creates a new stream socket if the \texttt{bool} parameter is
\texttt{true}, otherwise a datagram socket and sets the file
descriptor instance variable to it. If creation fails, raises an
\texttt{IOException}.

\method{socketGetOption}

Determines one of the following socket options:

\medskip
\begin{tabular}{|l|p{5cm}|} \hline
Value           & Description \\ \hline
\texttt{0x0080} & \texttt{SO\_LINGER}, see~\cite{stevens1}, pages~187ff.
                  If \texttt{l\_onoff} is \texttt{0}, returns \texttt{-1},
                  otherwise the value of \texttt{l\_linger}. \\
\texttt{0x0001} & Nagle algorithm disabled? \\
\texttt{0x1001} & Send buffer size \\
\texttt{0x1001} & Receive buffer size \\
\texttt{0x000f} & IP address the socket is bound to \\ \hline
\end{tabular}
\medskip

Returns the value of the option as a Java \texttt{int}, or raises a
\texttt{SocketException} in case of failure.

\method{socketListen}

Calls \texttt{listen()} on the socket with the given backlog
parameter. Raises an \texttt{IOException} in case of failure.

\method{socketSetOption}

Sets one of the following socket options:

\medskip
\begin{tabular}{|l|p{3cm}|l|} \hline
Value           & Description & Java type \\ \hline
\texttt{0x0080} & \texttt{SO\_LINGER}, see~\cite{stevens1}, pages~187ff.
                  If the \texttt{bool} parameter is \texttt{true}, sets
                  \texttt{l\_onoff} to \texttt{1} and \texttt{l\_linger}
                  to the given value. Otherwise, sets \texttt{l\_onoff} to \texttt{0}. & \texttt{Integer} \\
\texttt{0x0001} & Disable Nagle algorithm? Uses only the \texttt{bool} parameter. & n/a \\
\texttt{0x1001} & Send buffer size & \texttt{Integer} \\
\texttt{0x1001} & Receive buffer size & \texttt{Integer} \\ \hline
\end{tabular}
\medskip

The value to be set must be passed to the native method as a Java
object of the class specified in the table above. Raises a
\texttt{SocketException} in case of failure.

\class{SocketInputStream}

\method{init}

Does nothing.

\method{socketRead}

Receives at most the given number of bytes into the given array
beginning at the given offset. Returns the number of bytes read or
\texttt{-1} in case of EOF. May block the thread. Raises an
\texttt{IOException} in case of failure.

\class{SocketOutputStream}

\method{init}

Does nothing.

\method{socketWrite}

Sends exactly the given number of butes from the given array beginning
at the given offset. May block the thread. In case of failure, returns
\texttt{IOException}.

\bibliography{net}
\bibliographystyle{plain}

\end{document}