--- /dev/null
+\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}
projects / cacao.git / commitdiff