41bb726c

appendix K

java.net Package Reference

CONTENTS

The java.net package contains classes and interfaces used for networking. This includes classes to create and manipulate sockets, data packets, and URLs.

ContentHandlerFactory

This interface signals when an unknown service exception has occurred.

createContentHandler

public abstract ContentHandler createContentHandler(String mimetype)
The createContentHandler method creates a new content handler to read the content from a URLStreamHandler using the specified MIME type.
Parameters: mimetype-a String object containing the MIME type of the content.
Returns: A ContentHandler object that will read data from a URL connection and construct an object.

SocketImplFactory

This interface is used by the socket class to specify socket implementations.

createSocketImpl

SocketImpl createSocketImpl()
The createSocketImple method creates a SocketImpl instance that is an implementation of a socket.
Returns: A SocketImpl object that provides a socket implementation.

URLStreamHandlerFactory

This interface is used by the URL class to create stream handlers for various stream types.

createURLStreamHandler

URLStreamHandler createURLStreamHandler(String protocol)
The createURLStreamHandler method creates a URLStreamHandler instance for use by the URL class based on the specified protocol.
Parameters: protocol-a String object that specifies the protocol to be used by the URLStreamHandler class.
Returns: A URLStreamHandler object that is created with the protocol specified in the input parameter.

ContentHandler

Extends: Object
The ContentHandler class is used as a base class for classes that will handle specific MIME content types.

getContent

abstract public Object getContent(URLConnection urlc)
The getContent method accepts a URLConnection argument positioned at the beginning of an input stream and constructs an object from the input stream.
Parameters: urlc-a URLConnection object representing the input stream to be read in by the content handler.
Returns: An object that was constructed from the specified URL connection.
Throws: IOException if the input stream could not be read.

DatagramPacket

Extends: Object
The DatagramPacket class is used to store packet data such as data, length, Internet address, and port.

DatagramPacket Constructor

public DatagramPacket(byte ibuf[], int ilength)
This DatagramPacket constructor constructs a DatagramPacket object to be used for receiving datagrams.
Parameters:
ibuf-an array of bytes that will be used to store the datagram packet.
ilength-an integer value specifying the size of the datagram packet.

DatagramPacket Constructor

public DatagramPacket(byte ibuf[], int ilength, InetAddress iaddr, int iport)
This DatagramPacket constructor constructs a DatagramPacket object to be sent.
Parameters:
ibuf-an array of bytes that will be used to store the datagram packet.
ilength-an integer value specifying the size of the datagram packet.
iaddr-the destination IP address.
iport-the destination port.

getAddress

public InetAddress getAddress()
The getAddress method returns the IP address value of the DatagramPacket.
Returns: An InetAddress object containing the IP address of the datagram packet.

getPort

public int getPort()
The getPort method returns the port value of the DatagramPacket.
Returns: An integer value containing the port address of the datagram packet.

getData

public byte[] getData()
The getData method returns the array of datagram packet values.
Returns: An array of bytes containing the contents of the datagram packet.

getLength

public int getLength()
The getLength method returns the length of the datagram packet.
Returns: An integer value containing the length of the datagram packet.

DatagramSocket

Extends: Object
The DatagramSocket class is used to designate a dedicated socket for implementing unreliable datagrams.

DatagramSocket Constructor

public DatagramSocket() throws SocketException
The DatagramSocket constructor is used to implement an unreliable Datagram connection.
Throws: SocketException if the socket could not be created.

DatagramSocket Constructor

public DatagramSocket(int port) throws SocketException
This DatagramSocket constructor implements an unreliable datagram connection using the specified port value.
Parameters: port-an integer value specifying the port to be used for the socket.
Throws: SocketException if the socket could not be created.

send

public void send(DatagramPacket p) throws IOException
The send method sends a datagram packet to the destination address specified in the datagram packet's address value.
Parameters: p-a DatagramPacket object containing data to be sent through the socket.
Throws: IOException if an I/O exception has occurred.

receive

public synchronized void receive(DatagramPacket p) throws IOException
The receive method receives a datagram packet. This method will block until the datagram packet has been received.
Parameters: p-the datagram packet to be received.
Throws: IOException if an I/O exception has occurred.

getLocalPort

public int getLocalPort()
The getLocalPort method returns the port on the local machine that this socket is bound to.
Returns: An integer value containing the port value that this socket is bound to.

close

public synchronized void close()
The close method closes the datagram socket.

InetAddress

Extends: Object
The InetAddress class is used to represent Internet addresses.

getHostName

public String getHostName()
The getHostName method returns the name of the host for this InetAddress. If the host is null, the returned string will contain any of the local machine's available network addresses.
Returns: A String object containing the name of the host for this InetAddress.

getAddress

public byte[] getAddress()
The getAddress method returns an array of bytes containing the raw IP address in network byte order.
Returns: A byte array containing the raw IP address of this InetAddress in network byte order.

getHostAddress

public String getHostAddress()
The getHostAddress method returns the IP address string %d.%d.%d.%d.
Returns: A String value containing the raw IP address using the standard IP address format.

hashCode

public int hashCode()
The hashCode method returns a hash code for this InetAddress.
Returns: An integer value representing this InetAddress's hash code.

equals

public boolean equals(Object obj)
The equals method is used to compare this InetAddress object to the specified object.
Parameters: obj-the object to be compared with the address.
Returns: A boolean value that will be true if the objects are equal; false if not.

toString

public String toString()
The toString method is used to return a string representation of the InetAddress.
Returns: A String value containing information about the InetAddress.

getByName

public static synchronized InetAddress getByName(String host)
throws UnknownHostException
The getByName method returns an InetAddress object based on the specified hostname.
Parameters: host-a string object specifying the name of the host.
Returns: An InetAddress object containing the Internet address information for the specified host.
Throws: UnknownHostException if the specified host is invalid or unknown.

getAllByName

public static synchronized InetAddress getAllByName(String host)[]
throws UnknownHostException
The getAllByName method returns an array of InetAddress objects representing all of the addresses for the specified host.
Parameters: host-a String object specifying the name of the host.
Returns: An array of all corresponding InetAddresses for the specified host.
Throws: UnknownHostException if the specified host is invalid or unknown.

getLocalHost

public static InetAddress getLocalHost() throws UnknownHostException
The getLocalHost() returns an InetAddress object representing the address of the local host.
Returns: An InetAddress object containing the Internet address information for the local host.

ServerSocket

Extends: Object
The ServerSocket class is used to encapsulate a server socket.

ServerSocket Constructor

public ServerSocket(int port) throws IOException
The ServerSocket constructor creates a server socket on the specified port.
Parameters: port-an integer value specifying the port to create the socket on.
Throws: IOException if an I/O exception has occurred.

ServerSocket Constructor

public ServerSocket(int port, int backlog) throws IOException
This ServerSocket constructor creates a server socket on the specified port and listens to it for a specified time.
Parameters: port-an integer value specifying the port to create the socket on.
Throws: IOException if an I/O exception has occurred.

getInetAddress

public InetAddress getInetAddress()
The getInetAddress method returns an InetAddress object specifying the address to which this socket is connected.
Returns: An InetAddress object containing the address information to which the socket is connected.

getLocalPort

public int getLocalPort()
The getLocalPort method returns the local port on which the socket is currently listening.
Returns: An integer value representing the port on the local machine which the server socket is listening to.

accept

public Socket accept() throws IOException
The accept method is used to accept a connection. This method will block all others until a connection is made.
Returns: A Socket object after the connection has been accepted.
Throws: IOException if an I/O error occurred when waiting for the connection.

close

public void close() throws IOException
The close method closes the socket's connection.
Throws: IOException if an I/O error occurred while closing the server socket.

toString

public String toString()
The toString method returns a string representation of the ServerSocket.
Returns: A String object containing the implementation address and implementation port of the server socket.

setSocketFactory

public static synchronized void setSocketFactory(SocketImplFactory fac)
throws IOException, SocketException
The setSocketFactory method sets the server SocketImplFactory for use by this ServerSocket. This factory can only be set once.
Parameters: fac-a SocketImplFactory derived object to be used by this server socket.
Throws: IOException if there was an I/O error when setting the SocketImplFactory.
A SocketException if the SocketImplFactory has already been set.

Socket

Extends: Object
The Socket class is used to implement socket functionality. The setSocketImplFactory method is used to change the socket's implementation based on specific firewalls.

Socket Constructor

public Socket(String host, int port) throws UnknownHostException,
IOException
This Socket constructor creates a stream socket to the specified port on the specified host.
Parameters:
host-a String object containing the hostname to create the socket on.
port-an integer value representing the port to create the socket on.
Throws: UnknownHostException if the hostname is unrecognized or invalid.
An IOException if an I/O error occurred while creating the socket.

Socket Constructor

public Socket(String host, int port, boolean stream) throws
IOException
This Socket constructor creates a stream socket to the specified port on the specified host.
The boolean stream value can be used to specify a stream socket or a datagram socket.
Parameters:
host-a String object containing the hostname to create the socket on.
port-an integer value representing the port to create the socket on.
stream-a boolean value that is true if a stream socket is to be created; false if a datagram socket is to be created.
Throws: IOException if an I/O error occurred while creating the socket.

Socket Constructor

public Socket(InetAddress address, int port) throws IOException
This Socket constructor creates a stream socket to the specified port at the specified InetAddress.
Parameters:
address-an InetAddress object specifying the address to create the socket at.
port-an integer value representing the port to create the socket on.
Throws: IOException if an I/O error occurred while creating the socket.

Socket Constructor

public Socket(InetAddress address, int port, boolean stream)
throws IOException
This Socket constructor creates a stream socket to the specified port at the specified address. The boolean stream value can be used to specify a stream socket or a datagram socket.
Parameters:
address-an InetAddress object specifying the address to create the socket at.
port-an integer value representing the port to create the socket on.
stream-a boolean value that is true if a stream socket is to be created; false if a datagram socket is to be created.
Throws: IOException if an I/O error occurred while creating the socket.

getInetAddress

public InetAddress getInetAddress()
The getInetAddress method is used to return the address to which the socket is connected.
Returns: An InetAddress object containing information about the address to which the socket is connected.

getPort

public int getPort()
The getPort method returns the remote port to which the socket is connected.
Returns: An integer value representing the remote port number that the socket is con-
nected to.

getLocalPort

public int getLocalPort()
The getLocalPort method returns the local port to which the socket is connected.
Returns: An integer value representing the local port number that the socket is connected to.

getInputStream

public InputStream getInputStream() throws IOException
The getInputStream method returns an input stream for this socket.
Returns: An InputStream object to be used as the socket's input stream.
Throws: IOException if an I/O error occurred while retrieving the input stream.

getOutputStream

public OutputStream getOutputStream() throws IOException
The getOutputStream method returns an output stream for this socket.
Returns: An OutputStream object to be used as the socket's output stream.
Throws: IOException if an I/O error occurred while retrieving the output stream.

close

public synchronized void close() throws IOException
The close method closes the socket's connection.
Throws: IOException if an I/O error occurred while closing the socket.

toString

public String toString()
The toString method returns a string representation of the socket.
Returns: A String object containing the socket information.

setSocketImplFactory

public static synchronized void setSocketImplFactory(SocketImplFactory fac)
throws IOException
The setSocketImplFactory method sets the SocketImplFactory interface for this socket. The factory can only be specified once.
Parameters: fac-a SocketImplFactory derived object to be used by this socket.
Throws: IOException if an I/O error occurred while setting the SocketImplFactory.

SocketImpl

Extends: Object
The SocketImpl class is an abstract base class provided as a template for socket implementations.

toString

public String toString()
The toString method returns a string representation of the SocketImpl class.
Returns: A String object containing the port and address of this socket.

URL

Extends: Object
The URL class is used to represent a uniform resource locator. URL is a reference to an object on the Web such as an FTP site, an e-mail address, or an HTML page on a Web server.

URL Constructor

public URL(String protocol, String host, int port, String file) throws
MalformedURLException
This URL constructor creates a URL using the specified protocol, host, port, and host filename.
Parameters:
protocol-a String object specifying the protocol to be used.
host-a String object specifying the hostname.
port-an integer value specifying the port.
file-a String object specifying the file name on the host.
Throws: MalformedURLException if the protocol was unknown or invalid.

URL Constructor

public URL(String protocol, String host, String file) throws
MalformedURLException
This URL constructor creates a URL using the specified protocol, host, and host file name. The port number will be the default port used for the specified protocol.
Parameters:
protocol-a String object specifying the protocol to be used.
host-a String object specifying the hostname.
file-a String object specifying the file name on the host.
Throws: MalformedURLException if the protocol was unknown or invalid.

URL Constructor

public URL(String spec) throws MalformedURLException
This URL constructor creates a URL using the specified unparsed URL.
Parameters: spec-a String object containing an unparsed URL string.
Throws: MalformedURLException if the specified unparsed URL was invalid.

URL Constructor

public URL(URL context, String spec) throws MalformedURLException
This URL constructor creates a URL using the specified context and unparsed URL. If the unparsed URL is an absolute URL it is used as is, otherwise it is used in combination with the specified context.
Parameters:
context-a URL object specifying the context to be used in combination with the unparsed URL string.
spec-a String object containing an unparsed URL string.
Throws: MalformedURLException if the specified unparsed URL was invalid.

getPort

public int getPort()
The getPort method returns the port number for this URL.
Returns: An integer value representing the port number for this URL, which is -1 if the port has not been set.

getProtocol

public String getProtocol()
The getProtocol method returns a string representing the protocol used by this URL.
Returns: A String object containing the protocol name.

getHost

public String getHost()
The getHost method returns a string containing the hostname.
Returns: A String object containing the hostname.

getFile

public String getFile()
The getFile method returns a string containing the host filename.
Returns: A String object containing the name of the file on the host.

getRef

public String getRef()
The getRef method returns the ref (if any) that was specified in the unparsed string used to create this URL.
Returns: A String object containing the URL's ref.

equals

public boolean equals(Object obj)
The equals method can be used to compare this URL to another object.
Parameters: obj-an object that will be compared with this URL.
Returns: A boolean value that will be true if the objects are equal, false if not.

hashCode

public int hashCode()
The hashCode method will return a hash code value for the URL.
Returns: An integer value representing the hash code value of this URL.

sameFile

public boolean sameFile(URL other)
The sameFile method can be used to determine if the specified file is the same file used to create this URL.
Parameters: other-a URL object specifying the location of another file.
Returns: A boolean value that will be true if the files are equal; false if not.

toString

public String toString()
The toString method returns a string representation of the URL.
Returns: A String object containing a textual representation of the URL including the protocol, host, port, and filename.

toExternalForm

public String toExternalForm()
The toExternalForm method is used to reverse the parsing of the URL.
Returns: A String object containing the textual representation of the fully qualified URL.

openConnection

public URLConnection openConnection() throws java.io.IOException
The openConnection method will open a URLConnection to the object specified by the URL.
Returns: A URLConnection object that represents a connection to the URL.
Throws: IOException if an I/O error occurred while creating the URL connection.

openStream

public final InputStream openStream() throws java.io.IOException
The openStream method opens an InputStream.
Returns: An InputStream representing an input stream for the URL.
Throws: IOException if an I/O error occurred while creating the input stream.

getContent

public final Object getContent() throws java.io.IOException
The getContent method retrieves the contents from the opened connection.
Returns: An object representing the contents that are retrieved from the connection.
Throws: IOException if an I/O error occurred while retrieving the content.

setURLStreamHandlerFactory

public static synchronized void setURLStreamHandlerFactory(
URLStreamHandlerFactory fac)
The setURLStreamHandlerFactory method sets the URLStreamHandlerFactory interface for this URL. The factory can only be specified once.
Parameters: fac-a URLStreamHandlerFactory interface to be used by this URL.
Throws: Error if this factory has already been specified.

URLConnection

Extends: Object
The URLConnection class is an abstract base class used to represent a URL connection. It must be subclassed in order to provide true functionality.

connect

abstract public void connect() throws IOException
The connect method is used to connect the URLConnection after it has been created. Operations that depend on being connected will call this method to automatically connect.
Throws: IOException if an I/O error occurred while the connection was attempted.

getURL

public URL getURL()
The getURL method returns the URL for this URL connection.
Returns: A URL object.

getContentLength

public int getContentLength()
The getContentLength method returns the length of the content.
Returns: An integer value containing the length of the content, which is -1 if the length is not known.

getContentType

public String getContentType()
The getContentType method returns the type of the content.
Returns: A String object containing the type of the content, which is null if the type is not known.

getContentEncoding

public String getContentEncoding()
The getContentEncoding method returns the encoding of the content.
Returns: A String object containing the encoding of the content, which is null if the encoding is not known.

getExpiration

public long getExpiration()
The getExpiration method will return the expiration of the object.
Returns: A long value containing the expiration of the object. This value will be 0 if the expiration is not known.

getDate

public long getDate()
The getDate method will return the date of the object.
Returns: A long value containing the date of the object. This value will be 0 if the date is not known.

getLastModified

public long getLastModified()
The getLastModified() will return the last modified date of the object.
Returns: A long value containing the last modified date of the object. This value will be 0 if the last modified date is not known.

getHeaderField

public String getHeaderField(String name)
The getHeaderField method returns the contents of the header field based on the specified field name.
Parameters: name-a String object specifying the name of the header field to be returned.
Returns: A String object containing the contents of the specified header field. This value will be null if the contents are not known.

getHeaderFieldInt

public int getHeaderFieldInt(String name, int Default)
The getHeaderFieldInt method returns the pre-parsed contents of the specified header field.
Parameters:
name-a String object specifying the name of the header field to be returned.
Default-an integer value containing the value to be returned if the field is missing.
Returns: An integer value containing the preparsed header field value.

getHeaderFieldDate

public long getHeaderFieldDate(String name, long Default)
The getHeaderFieldDate method returns the contents of the specified header field parsed as a date.
Parameters:
name-a String object specifying the name of the header field to be returned.
Default-an integer value containing the value to be returned if the field is missing.
Returns: A long value containing the header field value parsed as a date.

getHeaderFieldKey

public String getHeaderFieldKey(int n)
The getHeaderFieldKey method returns the key for the specified header field.
Parameters: n-the position of the header field to be returned.
Returns: A String object containing the key for the specified header field. This value will be null if there are fewer than n header fields.

getHeaderField

public String getHeaderField(int n)
The getHeaderField method returns the specified header field value.
Parameters: n-the position of the header field to be returned.
Returns: A String object containing the contents of the specified header field. This value will be null if there are fewer than n header fields.

getContent

public Object getContent() throws IOException
The getContent method returns the object referred to by this URLConnection.
Returns: An Object object that was referred to by this URL.
Throws: IOException if an I/O error occurred while retrieving the content.

getInputStream

public InputStream getInputStream() throws IOException
The getInputStream method returns an InputStream object to be used as an input stream to read from the object.
Returns: An InputStream object to be used to read from the object.
Throws: IOException if an I/O error occurred while creating the input stream.

getOutputStream

public OutputStream getOutputStream() throws IOException
The getOutputStream method returns an OutputStream object to be used as an output stream to write to the object.
Returns: An OutputStream object to be used to write to the object.
Throws: IOException if an I/O error occurred while creating the output stream.

toString

public String toString()
The toString method returns a string representation of the URLConnection.
Returns: A String object containing a textual representation of the URLConnection object.

setDoInput

public void setDoInput(boolean doinput)
The setDoInput method sets the functionality of the URL connection. If the parameter is true, the URL connection will be used for input. If it is false, it will be used for output.
Parameters: doinput-a boolean value that will be true if the URL connection is to be used for input; false if for output.

setDoOutput

public void setDoOutput(boolean dooutput)
The setDoOutput method sets the functionality of the URL connection. If the parameter is true, the URL connection will be used for output. If it is false, it will be used for input.
Parameters: dooutput-a boolean value that will be true if the URL connection is to be used for output; false if for input.

getDoOutput

public boolean getDoOutput()
The getDoOutput method returns the input/output functionality of the URLConnection.
Returns: A boolean value that will be true if the URL connection is used for output; false if it is used for input.

setAllowUserInteraction

public void setAllowUserInteraction(boolean allowuserinteraction)
The setAllowUserInteraction method allows the protocol to interact with the user.
Parameters: allowuserinteraction-a boolean value that should be true if user interaction is allowed; false if not.

getAllowUserInteraction

public boolean getAllowUserInteraction()
The getAllowUserInteraction method can be called to determine if user interaction is allowed.
Returns: A boolean value that will be true if user interaction is allowed; false if not.

setDefaultAllowUserInteraction

public static void setDefaultAllowUserInteraction( boolean defaultallowuserinteraction)
The setDefaultAllowUserInteraction method allows the default user interaction value to be set for all URL connections because it is a static method.
Parameters: defaultallowuserinteraction-a boolean value that should be true if user interaction is allowed; false if not.

getDefaultAllowUserInteraction

public static boolean getDefaultAllowUserInteraction()
The getDefaultAllowUserInteraction static method returns the default user interaction value.
Returns: A boolean value that will be true if user interaction is allowed; false if not.

setUseCaches

public void setUseCaches(boolean usecaches)
The setUseCaches method is used to control the use of caching by the protocol. Some protocols allow files to be cached.
Parameters: usecaches-a boolean value that will be true if caching is to be used by the protocol; false if not.

getUseCaches

public boolean getUseCaches()
The getUseCaches method can be called to determine if caching is to be used by the protocol.
Returns: A boolean value that will be true if caching is to be used by the protocol; false if not.

setIfModifiedSince

public void setIfModifiedSince(long ifmodifiedsince)
The setIfModifiedSince method is provided to set the internal ifmodifiedsince variable of the URLConnection class. Because some protocols allow caching of files, if the file to be retrieved is newer than ifmodifiedsince, it will need to retrieved from the URL (rather than the cache).
Parameters: ifmodifiedsince-a long value used to represent the ifmodifiedsince date.

getIfModifiedSince

public long getIfModifiedSince()
The getIfModifiedSince method returns the internal ifmodifiedsince date value. See the setIfModifiedSince method documentation.
Returns: A long value representing the ifmodifiedsince date value.

getDefaultUseCaches

public boolean getDefaultUseCaches()
The getDefaultUseCaches method can be called to determine if caches are used by default.
Returns: A boolean value that will be true if caches are used by default; false if not.

setDefaultUseCaches

public void setDefaultUseCaches(boolean defaultusecaches)
The setDefaultUseCaches method can be used to force all URLConnections to use caching by default because it is a static value.
Parameters: defaultusecaches-a boolean value that should be true if caches are to be used by default; false if not.

setRequestProperty

public void setRequestProperty(String key, String value)
The setRequestProperty method is used to set URLConnection properties.
Parameters:
key-a String object containing the key by which the property is known.
value-a String object containing the property value.

getRequestProperty

public String getRequestProperty(String key)
The getRequestProperty method returns the value for the specified property key.
Parameters: key-a String object containing the key by which the property is known.
Returns: A String object containing the specified property's value.

setDefaultRequestProperty

public static void setDefaultRequestProperty(String key, String value)
The setDefaultRequestProperty method sets the default value of a specified property. All current and future URL connections will be initialized with these properties.
Parameters:
key-a String object containing the key by which the property is known.
value-a String object containing the specified property's value.

getDefaultRequestProperty

public static String getDefaultRequestProperty(String key)
The getDefaultRequestProperty method gets the default value of a specified property.
Parameters: key-a String object containing the key by which the property is known.
Returns: A String object containing the specified property's value.

setContentHandlerFactory

public static synchronized void setContentHandlerFactory(
ContentHandlerFactory fac)
The setContentHandlerFactory method is used to set the ContentHandlerFactory interface for this URL connection. The factory can only be set once.
Parameters: fac-a ContentHandlerFactory-derived object.
Throws: Error if the ContentHandlerFactory has already been defined.

URLEncoder

Extends: Object
The URLEncoder class is used to encode text into x-www-form-urlencoded format.

encode

public static String encode(String s)
The encode method is used to translate a string into x-www-form-urlencoded format.
Parameters: s-a String object to be translated.
Returns: A String object in x-www-form-urlencoded format.

MalformedURLException

Extends: IOException
The MalformedURLException class is used to signal a malformed URL.

ProtocolException

Extends: IOException
This exception signals when a connect receives an EPROTO message. This exception is used by the Socket class.

SocketException

Extends: IOException
This exception signals when an error has occurred while trying to use a socket. This exception is used by the Socket class.

UnknownHostException

Extends: IOException
This exception signals that the host address specified by the client cannot be resolved.

UnknownServiceException

Extends: IOException
This exception signals when an unknown service exception has occurred.