From: schani Date: Mon, 27 Nov 2000 16:01:22 +0000 (+0000) Subject: Added documentation for java.net. X-Git-Url: http://wien.tomnetworks.com/gitweb/?p=cacao.git;a=commitdiff_plain;h=7dfba2ffa341fa7ef409e32a2e308be5282da0bd Added documentation for java.net. --- diff --git a/doc/net.bib b/doc/net.bib new file mode 100644 index 000000000..ae42eb7c1 --- /dev/null +++ b/doc/net.bib @@ -0,0 +1,6 @@ +@BOOK{stevens1, +AUTHOR = {W. Richard Stevens}, +TITLE = {UNIX Network Programming}, +VOLUME = 1, +PUBLISHER = {Prentice Hall}, +YEAR = 1998} diff --git a/doc/net.tex b/doc/net.tex new file mode 100644 index 000000000..3a15a4436 --- /dev/null +++ b/doc/net.tex @@ -0,0 +1,344 @@ +\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}