Generated by
JDiff

java.net Documentation Differences

This file contains all the changes in documentation in the package java.net as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Class Authenticator

The class Authenticator represents an object that knows how to obtain authentication for a network connection. Usually it will do this by prompting the user for information.

Applications use this class by creating a subclass and registering an instance of that subclass with the system with setDefault(). When authentication is required the system will invoke a method on the subclass (like getPasswordAuthentication). The subclass's method can query about the authentication being requested with a number of inherited methods (getRequestingXXX()) and form an appropriate message for the user.

All methods that request authentication have a default implementation that fails. @see java.net.Authenticator#setDefault(java.net.Authenticator) @see java.net.Authenticator#getPasswordAuthentication() @author Bill Foote @version 1.20 0225 12/0203/0001 @since 1.2

Class Authenticator, void setDefault(Authenticator)

Sets the authenticator that will be used by the networking code when a proxy or an HTTP server asks for authenticator. If an Authenticator has already been established as the current authenticator no action will be taken. If the argument is null and no authenticator has been established then no action is taken and the method simply returnsauthentication.

First if there is a security manager its checkPermission method is called with a NetPermission("setDefaultAuthenticator") permission. This may result in a java.lang.SecurityException. @param Typically this method willa The authenticator to be calledset. exactly once atIf a is systemnull startup.then @paramany a Thepreviously set authenticator is removed. @throws SecurityException if a security manager exists and its checkPermission method doesn't allow setting the default authenticator. @see SecurityManager#checkPermission @see java.net.NetPermission


Class ContentHandler

The abstract class ContentHandler is the superclass of all classes that read an Object from a URLConnection.

An application does not generally call the getContent method in this class directly. Instead an application calls the getContent method in class URL or in URLConnection. The application's content handler factory (an instance of a class that implements the interface ContentHandlerFactory set up by a call to setContentHandler) is called with a String giving the MIME type of the object being received on the socket. The factory returns an instance of a subclass of ContentHandler and its getContent method is called to create the object.

If no content handler could be found URLConnection will look for a content handler in a user-defineable set of places. By default it looks in sun.net.www.content but users can define a vertical-bar delimited set of class prefixes to search through in addition by defining the java.content.handler.pkgs property. The class name must be of the form:

 {package-prefix}.{major}.{minor} e.g. YoyoDyne.experimental.text.plain 
If the loading of the content handler class would be performed by a classloader that is outside of the the delegation chain of the caller the JVM will need the RuntimePermission "getClassLoader". @author James Gosling @version 1.14 0215 12/0203/0001 @see java.net.ContentHandler#getContent(java.net.URLConnection) @see java.net.ContentHandlerFactory @see java.net.URL#getContent() @see java.net.URLConnection @see java.net.URLConnection#getContent() @see java.net.URLConnection#setContentHandlerFactory(java.net.ContentHandlerFactory) @since JDK1.0

Class ContentHandlerFactory

This interface defines a factory for content handlers. An implementation of this interface should map a MIME type into an instance of ContentHandler.

This interface is used by the URLStreamHandler class to create a ContentHandler for a MIME type. @author James Gosling @version 1.9 0210 12/0203/0001 @see java.net.ContentHandler @see java.net.URLStreamHandler @since JDK1.0


Class DatagramPacket

This class represents a datagram packet.

Datagram packets are used to implement a connectionless packet delivery service. Each message is routed from one machine to another based solely on information contained within that packet. Multiple packets sent from one machine to another might be routed differently and might arrive in any order. Packet delivery is not guaranteed. @author Pavani Diwanji @author Benjamin Renaud @version 1.30 0240 12/0203/0001 @since JDK1.0

Class DatagramPacket, byte[] getData()

Returns the data buffer. The data received or the data to be sent. @returnstarts from the dataoffset receivedin orthe buffer and runs for length long. @return the databuffer used to bereceive sent.or send data @see #setData(byte[] int int)
Class DatagramPacket, void setData(byte[])

Set the data buffer for this packet. IfWith the lengthoffset of the packet length is greater than the lengththis of argumentDatagramPacket set to this0 methodand the length is resetset to the the length of the argumentbuf. @param buf the buffer to set for this packet. @exception NullPointerException if the argument is null. @see #getLength @see #getData @since JDK1.1
Class DatagramPacket, void setData(byte[], int, int)

Set the data buffer for this packet. This sets the data length and offset of the packet. @param buf the buffer to set for this packet @param offset the offset into the data @param length the length of the data and/or the length of the buffer used to receive data @exception NullPointerException if the argument is null @see #getData @see #getOffset @see #getLength @since JDK1.2
Class DatagramPacket, void setLength(int)

Set the length for this packet. The length of the packet is the number of bytes from the packet's data buffer that will be sent or the number of bytes of the packet's data buffer that will be used for receiving data. The length must be lesser or equal to the offset plus the length of the packet's buffer. @param length the length to set for this packet. @exception IllegalArgumentException if the length is negative of if the length is greater than the packet's data buffer length. @see #getLength @see #setData @since JDK1.1
Class DatagramPacket, void setPort(int)

Sets the port number on the remote host to which this datagram is being sent. @param iport the port number @since JDK1.1 @see #setPortgetPort(int)

Class DatagramSocket

This class represents a socket for sending and receiving datagram packets.

A datagram socket is the sending or receiving point for a packet delivery service. Each packet sent or received on a datagram socket is individually addressed and routed. Multiple packets sent from one machine to another may be routed differently and may arrive in any order.

UDP broadcasts sends and receives are always enabled on a DatagramSocket. In order to receive broadcast packets a DatagramSocket should be bound to the wildcard address. In some implementations broadcast packets may also be received when a DatagramSocket is bound to a more specific address.

Example: DatagramSocket s = new DatagramSocket(null); s.bind(new InetSocketAddress(8888)); Which is equivalent to: DatagramSocket s = new DatagramSocket(8888); Both cases will create a DatagramSocket able to receive broadcasts on UDP port 8888. @author Pavani Diwanji @version 1.49 0284 12/0203/0001 @see java.net.DatagramPacket @see java.nio.channels.DatagramChannel @since JDK1.0

Class DatagramSocket, constructor DatagramSocket()

Constructs a datagram socket and binds it to any available port on the local host machine. The socket will be bound to the wildcard address an IP address chosen by the kernel.

If there is a security manager its checkListen method is first called with 0 as its argument to ensure the operation is allowed. This could result in a SecurityException. @exception SocketException if the socket could not be opened or the socket could not bind to the specified local port. @exception SecurityException if a security manager exists and its checkListen method doesn't allow the operation. @see SecurityManager#checkListen

Class DatagramSocket, constructor DatagramSocket(int)

Constructs a datagram socket and binds it to the specified port on the local host machine. The socket will be bound to the wildcard address an IP address chosen by the kernel.

If there is a security manager its checkListen method is first called with the port argument as its argument to ensure the operation is allowed. This could result in a SecurityException. @param port port to use. @exception SocketException if the socket could not be opened or the socket could not bind to the specified local port. @exception SecurityException if a security manager exists and its checkListen method doesn't allow the operation. @see SecurityManager#checkListen

Class DatagramSocket, constructor DatagramSocket(int, InetAddress)

Creates a datagram socket bound to the specified local address. The local port must be between 0 and 65535 inclusive. If the IP address is 0.0.0.0 the socket will be bound to the wildcard address an IP address chosen by the kernel.

If there is a security manager its checkListen method is first called with the port argument as its argument to ensure the operation is allowed. This could result in a SecurityException. @param port local port to use @param laddr local address to bind @exception SocketException if the socket could not be opened or the socket could not bind to the specified local port. @exception SecurityException if a security manager exists and its checkListen method doesn't allow the operation. @see SecurityManager#checkListen @since JDK1.1

Class DatagramSocket, void close()

Closes this datagram socket.

Any thread currently blocked in {#link receive} upon this socket will throw a SocketException

If this socket has an associated channel then the channel is closed as well. @revised 1.4 @spec JSR-51

Class DatagramSocket, InetAddress getLocalAddress()

Gets the local address to which the socket is bound.

If there is a security manager its checkConnect method is first called with the host address and -1 as its arguments to see if the operation is allowed. @exception SecurityException if a security managersee existsSecurityManager#checkConnect and@return itsthe checkConnectlocal methodaddress doesn'tto allowwhich the operation.socket @seeis SecurityManager#checkConnectbound @returnor an InetAddress representing theany local address toif whicheither the socket is not bound or the security manager checkConnect method does not allow the operation @since 1.1

Class DatagramSocket, int getReceiveBufferSize()

Get value of the SO_RCVBUF option for this DatagramSocket that is the buffer size used by the platform for input on this DatagramSocket. @return the value of the SO_RCVBUF option for this DatagramSocket @exception SocketException if there is an error in the underlying protocol such as a TCPan UDP error. @see #setReceiveBufferSize(int)
Class DatagramSocket, int getSendBufferSize()

Get value of the SO_SNDBUF option for this DatagramSocket that is the buffer size used by the platform for output on this DatagramSocket. @return the value of the SO_SNDBUF option for this DatagramSocket @exception SocketException if there is an error in the underlying protocol such as a TCPan UDP error. @see #setSendBufferSize
Class DatagramSocket, int getSoTimeout()

Retrive setting for SO_TIMEOUT. 0 returns implies that the option is disabled (i.e. timeout of infinity). @return the setting for SO_TIMEOUT @throws SocketException if there is an error in the underlying protocol such as a TCPan UDP error. @since JDK1.1 @see #setSoTimeout(int)
Class DatagramSocket, void receive(DatagramPacket)

Receives a datagram packet from this socket. When this method returns the DatagramPacket's buffer is filled with the data received. The datagram packet also contains the sender's IP address and the port number on the sender's machine.

This method blocks until a datagram is received. The length field of the datagram packet object contains the length of the received message. If the message is longer than the packet's length the message is truncated.

If there is a security manager a packet cannot be received if the security manager's checkAccept method does not allow it. @param p the DatagramPacket into which to place the incoming data. @exception IOException if an I/O error occurs. @exception SocketTimeoutException if setSoTimeout was previously called and the timeout has expired. @exception PortUnreachableException may be thrown if the socket is connected to a currently unreachable destination. Note there is no guarantee that the exception will be thrown. @exception java.nio.channels.IllegalBlockingModeException if this socket has an associated channel and the channel is in non-blocking mode. @see java.net.DatagramPacket @see java.net.DatagramSocket @revised 1.4 @spec JSR-51

Class DatagramSocket, void send(DatagramPacket)

Sends a datagram packet from this socket. The DatagramPacket includes information indicating the data to be sent its length the IP address of the remote host and the port number on the remote host.

If there is a security manager and the socket is not currently connected to a remote address this method first performs some security checks. First if p.getAddress().isMulticastAddress() is true this method calls the security manager's checkMulticast method with p.getAddress() as its argument. If the evaluation of that expression is false this method instead calls the security manager's checkConnect method with arguments p.getAddress().getHostAddress() and p.getPort(). Each call to a security manager method could result in a SecurityException if the operation is not allowed. @param p the DatagramPacket to be sent. @exception IOException if an I/O error occurs. @exception SecurityException if a security manager exists and its checkMulticast or checkConnect method doesn't allow the send. @exception PortUnreachableException may be thrown if the socket is connected to a currently unreachable destination. Note there is no guarantee that the exception will be thrown. @exception java.nio.channels.IllegalBlockingModeException if this socket has an associated channel and the channel is in non-blocking mode. @see java.net.DatagramPacket @see SecurityManager#checkMulticast(InetAddress) @see SecurityManager#checkConnect @revised 1.4 @spec JSR-51

Class DatagramSocket, void setReceiveBufferSize(int)

Sets the SO_RCVBUF option to the specified value for this DatagramSocket. The SO_RCVBUF option is used by the platform'sthe networking codenetwork implementation as a hint for the size to setsize the underlying network I/O buffers. Increasing buffer size can increase the performance of network I/O for high-volumeThe connectionSO_RCVBUF while decreasing it can help reducesetting may also be used by the backlog of incoming data. Fornetwork UDP this setsimplementation to determine the maximum size of athe packet that maycan be sentreceived on this DatagramSocketsocket.

Because SO_RCVBUF is a hint applications that want to verify what size the buffers were set to should call #getReceiveBufferSize()

Increasing SO_RCVBUF may allow the network implementation to buffer multiple packets when packets arrive faster than are being received using #receive()

Note: It is implementation specific if a packet larger than SO_RCVBUF can be received. @param size the size to which to set the receive buffer size. This value must be greater than 0. @exception SocketException if there is an error in the underlying protocol such as a TCPan UDP error. @exception IllegalArgumentException if the value is 0 or is negative. @see #getReceiveBufferSize()

Class DatagramSocket, void setSendBufferSize(int)

Sets the SO_SNDBUF option to the specified value for this DatagramSocket. The SO_SNDBUF option is used by the platform's networkingnetwork codeimplementation as a hint for the size to setsize the underlying network I/O buffers. Increasing buffer size can increase the performance of network I/O for high-volumeThe connectionSO_SNDBUF while decreasing it can help reducesetting may also be used by the backlog of incoming data. Fornetwork UDP this setsimplementation to determine the maximum size of athe packet that maycan be sent on this socket.

Because As SO_SNDBUF is a hint applications that want to verify what size the buffers were setbuffer tois should call #getSendBufferSize()

Increasing the buffer size may allow multiple outgoing packets to be queued by the network implementation when the send rate is high.

Note: If #send() is used to send a DatagramPacket that is larger than the setting of SO_SNDBUF then it is implementation specific if the packet is sent or discarded. @param size the size to which to set the send buffer size. This value must be greater than 0. @exception SocketException if there is an error in the underlying protocol such as a TCPan UDP error. @exception IllegalArgumentException if the value is 0 or is negative. @see #getSendBufferSize()

Class DatagramSocket, void setSoTimeout(int)

Enable/disable SO_TIMEOUT with the specified timeout in milliseconds. With this option set to a non-zero timeout a call to receive() for this DatagramSocket will block for only this amount of time. If the timeout expires a java.ionet.InterruptedIOExceptionSocketTimeoutException is raised though the ServerSocketDatagramSocket is still valid. The option must be enabled prior to entering the blocking operation to have effect. The timeout must be > 0. A timeout of zero is interpreted as an infinite timeout. @param timeout the specified timeout in milliseconds. @throws SocketException if there is an error in the underlying protocol such as aan TCPUDP error. @since JDK1.1 @see #getSoTimeout()

Class DatagramSocketImpl, int peek(InetAddress)

Peek at the packet to see who it is from. @param i an InetAddress object @return the address which the packet came from. @exception IOException if an I/O exception occurs @exception PortUnreachableException may be thrown if the socket is connected to a currently unreachable destination. Note there is no guarantee that the exception will be thrown.
Class DatagramSocketImpl, void receive(DatagramPacket)

Receive the datagram packet. @param p the Packet Received. @exception IOException if an I/O exception occurs while receiving the datagram packet. @exception PortUnreachableException may be thrown if the socket is connected to a currently unreachable destination. Note there is no guarantee that the exception will be thrown.
Class DatagramSocketImpl, void send(DatagramPacket)

Sends a datagram packet. The packet contains the data and the destination address to send the packet to. @param p the packet to be sent. @exception IOException if an I/O exception occurs while sending the datagram packet. @exception PortUnreachableException may be thrown if the socket is connected to a currently unreachable destination. Note there is no guarantee that the exception will be thrown.

Class FileNameMap

A simple interface which provides a mechanism to map between a file name and a MIME type string. @version 1.11 0212 12/0203/0001 @author Steven B. Byrne @since JDK1.1

Class HttpURLConnection, constructor HttpURLConnection(URL)

Constructor for the URLStreamHandlerHttpURLConnection. @param u the URL
Class HttpURLConnection, InputStream getErrorStream()

Returns the error stream if the connection failed but the server sent useful data nonetheless. The typical example is when an HTTP server responds with a 404 which will cause a FileNotFoundException to be thrown in connect but the server sent an HTML help page with suggestions as to what to do.

This method will not cause a connection to be initiated. If there the connection was not connected or if the server did not have an error while connecting or if the server did havehad an error but there no error data was sent this method will return null. This is the default. @return an error stream if any null if there have been no errors the connection is not connected or the server sent no useful data.

Class HttpURLConnection, int HTTP_SERVER_ERROR

HTTP Status-Code 500: Internal Server Error. @deprecated it is misplaced and shouldn't have existed.

Class InetAddress

This class represents an Internet Protocol (IP) address.

ApplicationsAn shouldIP address is either a 32-bit or 128-bit unsigned number used by IP a lower-level protocol on which protocols like UDP and TCP are built. The IP address architecture is defined by RFC 790: Assigned Numbers RFC 1918: Address Allocation for Private Internets RFC 2365: Administratively Scoped IP Multicast and RFC 2373: IP Version 6 Addressing Architecture. An instance of an InetAddress consists of an IP address and possibly its corresponding host name (depending on whether it is constructed with a host name or whether it has already done reverse host name resolution).

Address types

unicast An identifier for a single interface. A packet sent to a unicast address is delivered to the interface identified by that address.

The Unspecified Address -- Also called anylocal or wildcard address. It must never be assigned to any node. It indicates the absence of an address. One example of its use is as the methodstarget getLocalHostof getByNamebind which allows a server to accept a client connection on any interface in case the server host has multiple interfaces.

The unspecified address must not be used as the destination address of an IP packet.

The Loopback Addresses -- This is the address assigned to the loopback interface. Anything sent to this IP address loops around and becomes IP input on the local host. This address is often used when testing a client.

multicast An identifier for a set of interfaces (typically belonging to different nodes). A packet sent to a multicast address is delivered to all interfaces identified by that address.

IP address scope

Link-local addresses are designed to be used for addressing on a single link for purposes such as auto-address configuration neighbor discovery or getAllByNamewhen no routers are present.

Site-local addresses are designed to be used for addressing inside of a site without the need for a global prefix.

Global addresses are unique across the internet.

Textual representation of IP addresses

The textual representation of an IP address is address family specific.

For IPv4 address format please refer to Inet4Address#format; For IPv6 address format please refer to Inet6Address#format.

Host Name Resolution

Host name-to-IP address resolution is accomplished through the use createof a newcombination of local machine configuration information and network naming services such as the Domain Name System (DNS) and Network Information Service(NIS). The particular naming services(s) being used is by default the local machine configured one. For any host name its corresponding IP address is returned.

Reverse name resolution means that for any IP address the host associated with the IP address is returned.

The InetAddress instanceclass provides methods to resolve host names to their IP addresses and vise versa.

InetAddress Caching

The InetAddress class has a cache to store successful as well as unsuccessful host name resolutions. The positive caching is there to guard against DNS spoofing attacks; while the negative caching is used to improve performance.

By default the result of positive host name resolutions are cached forever because there is no general rule to decide when it is safe to remove cache entries. The result of unsuccessful host name resolution is cached for a very short period of time (10 seconds) to improve performance.

Under certain circumstances where it can be determined that DNS spoofing attacks are not possible a Java security property can be set to a different Time-to-live (TTL) value for positive caching. Likewise a system admin can configure a different negative caching TTL value when needed.

Two Java security properties control the TTL values used for positive and negative host name resolution caching:

networkaddress.cache.ttl (default: -1)
Indicates the caching policy for successful name lookups from the name service. The value is specified as as integer to indicate the number of seconds to cache the successful lookup.

A value of -1 indicates "cache forever".

networkaddress.cache.negative.ttl (default: 10)
Indicates the caching policy for un-successful name lookups from the name service. The value is specified as as integer to indicate the number of seconds to cache the failure for un-successful lookups.

A value of 0 indicates "never cache". A value of -1 indicates "cache forever".

@author Chris Warth @version 1.70 0291 12/0203/0001 @see java.net.InetAddress#getByAddress(byte[]) @see java.net.InetAddress#getByAddress(java.lang.String byte[]) @see java.net.InetAddress#getAllByName(java.lang.String) @see java.net.InetAddress#getByName(java.lang.String) @see java.net.InetAddress#getLocalHost() @since JDK1.0
Class InetAddress, InetAddress[] getAllByName(String)

DeterminesGiven all the IP addressesname of a host givenreturns an array of its IP addresses based on the host'sconfigured name service on the system.

The host name can either be a machine name such as "java.sun.com" or a stringtextual representation representingof its IP address. such asIf a "206.26.48literal IP address is supplied only the validity of the address format is checked.100

For host" specified in literal IPv6 address either the form defined in RFC 2732 or the literal IPv6 address format defined in RFC 2373 is accepted.

If there is a security manager and host is not null and host.length() is not equal to zero the security manager's checkConnect method is called with the hostname and -1 as its arguments to see if the operation is allowed. @param host the name of the host. @return an array of all the IP addresses for a given host name. @exception UnknownHostException if no IP address for the host could be found. @exception SecurityException if a security manager exists and its checkConnect method doesn't allow the operation. @see SecurityManager#checkConnect

Class InetAddress, InetAddress getByName(String)

Determines the IP address of a host given the host's name.

The host name can either be a machine name such as "java.sun.com" or a stringtextual representation representingof its IP address. such asIf a "206.26.48literal IP address is supplied only the validity of the address format is checked.100

For host" specified in literal IPv6 address either the form defined in RFC 2732 or the literal IPv6 address format defined in RFC 2373 is accepted. @param host the specified host or null for the local host. @return an IP address for the given host name. @exception UnknownHostException if no IP address for the host could be found. @exception SecurityException if a security manager exists and its checkConnect method doesn't allow the operation

Class InetAddress, String getHostAddress()

Returns the IP address string "%d.%d.%d.%d"in textual presentation. @return the raw IP address in a string format. @since JDK1.0.2
Class InetAddress, String getHostName()

Gets the host name for this IP address.

If this InetAddress was created with a host name this host name will be remembered and returned; otherwise a reverse name lookup will be performed and the result will be returned based on the system configured name lookup service. If a lookup of the name service is required call getCanonicalHostName

If there is a security manager its checkConnect method is first called with the hostname and -1 as its arguments to see if the operation is allowed. If the operation is not allowed it will return the textual representation of the IP address. @return the host name for this IP address. @exception SecurityExceptionor if athe security manager exists and itsoperation is not allowed by checkConnectthe methodsecurity check the textual doesn'trepresentation allowof the operationIP address. @see InetAddress#getCanonicalHostName @see SecurityManager#checkConnect

Class InetAddress, InetAddress getLocalHost()

Returns the local host.

If there is a security manager its checkConnect method is called with the local host name and -1 as its arguments to see if the operation is allowed. If the operation is not allowed an InetAddress representing the loopback address is returned. @return the IP address of the local host. @exception UnknownHostException if no IP address for the host could be found. @exception SecurityException if a security manager exists and its checkConnect method doesn't allow the operation. @see SecurityManager#checkConnect

Class InetAddress, boolean isMulticastAddress()

Utility routine to check if the InetAddress is an IP multicast address. IP multicast address is a Class D address i.e first four bits of the address are 1110. @return a boolean indicating if the InetAddress is an IP multicast address @since JDK1.1
Class InetAddress, String toString()

Converts this IP address to a String. The string returned is of the form: hostname / literal IP address. If the host name is unresolved no reverse name service loopup is performed. The hostname part will be represented by an empty string. @return a string representation of this IP address.

Class JarURLConnection

A URL Connection to a Java ARchive (JAR) file or an entry in a JAR file.

The syntax of a JAR URL is:

 jar:<url> /{entry} 

for example:

jar:http://www.foo.com/bar/baz.jar /COM/foo/Quux.class

Jar URLs should be used to refer to a JAR file or entries in a JAR file. The example above is a JAR URL which refers to a JAR entry. If the entry name is omitted the URL refers to the whole JAR file: jar:http://www.foo.com/bar/baz.jar /

Users should cast the generic URLConnection to a JarURLConnection when they know that the URL they created is a JAR URL and they need JAR-specific functionality. For example:

 URL url = new URL("jar:file:/home/duke/duke.jar /"); JarURLConnection jarConnection = (JarURLConnection)url.openConnection(); Manifest manifest = jarConnection.getManifest(); 

Examples:

A Jar entry
jar:http://www.foo.com/bar/baz.jar /COM/foo/Quux.class
A Jar file
jar:http://www.foo.com/bar/baz.jar /
A Jar directory
jar:http://www.foo.com/bar/baz.jar /COM/foo/

/ is refered to as the separator.

When constructing a JAR url via new URL(context spec) the following rules apply:

@see java.net.URL @see java.net.URLConnection @see java.util.jar.JarFile @see java.util.jar.JarInputStream @see java.util.jar.Manifest @see java.util.zip.ZipEntry @author Benjamin Renaud @since 1.2

Class MalformedURLException

Thrown to indicate that a malformed URL has occurred. Either no legal protocol could be found in a specification string or the string could not be parsed. @author Arthur van Hoff @version 1.13 0214 12/0203/0001 @since JDK1.0

Class MulticastSocket, constructor MulticastSocket()

Create a multicast socket.

If there is a security manager its checkListen method is first called with 0 as its argument to ensure the operation is allowed. This could result in a SecurityException.

When the socket is created the DatagramSocket#setReuseAddress(true) method is called to enable the SO_REUSEADDR socket option. @exception IOException if an I/O exception occurs while creating the MulticastSocket @exception SecurityException if a security manager exists and its checkListen method doesn't allow the operation. @see SecurityManager#checkListen @see java.net.DatagramSocket#setReuseAddress(boolean)

Class MulticastSocket, constructor MulticastSocket(int)

Create a multicast socket and bind it to a specific port.

If there is a security manager its checkListen method is first called with the port argument as its argument to ensure the operation is allowed. This could result in a SecurityException.

When the socket is created the DatagramSocket#setReuseAddress(true) method is called to enable the SO_REUSEADDR socket option. @param port port to use @exception IOException if an I/O exception occurs while creating the MulticastSocket @exception SecurityException if a security manager exists and its checkListen method doesn't allow the operation. @see SecurityManager#checkListen @see java.net.DatagramSocket#setReuseAddress(boolean)

Class MulticastSocket, byte getTTL()

Get the default time-to-live for multicast packets sent out on the socket. @exception IOException if an I/O exception occurs while getting the default time-to-live value @return the default time-to-live value @deprecated use the getTimeToLive method instead which returns an int instead of a byte. @see #setTTL(byte)
Class MulticastSocket, void joinGroup(InetAddress)

Joins a multicast group. Its behavior may be affected by setInterface or setNetworkInterface.

If there is a security manager this method first calls its checkMulticast method with the mcastaddr argument as its argument. @param mcastaddr is the multicast address to join @exception IOException if there is an error joining or when the address is not a multicast address. @exception SecurityException if a security manager exists and its checkMulticast method doesn't allow the join. @see SecurityManager#checkMulticast(InetAddress)

Class MulticastSocket, void leaveGroup(InetAddress)

Leave a multicast group. Its behavior may be affected by setInterface or setNetworkInterface.

If there is a security manager this method first calls its checkMulticast method with the mcastaddr argument as its argument. @param mcastaddr is the multicast address to leave @exception IOException if there is an error leaving or when the address is not a multicast address. @exception SecurityException if a security manager exists and its checkMulticast method doesn't allow the operation. @see SecurityManager#checkMulticast(InetAddress)

Class MulticastSocket, void send(DatagramPacket, byte)

Sends a datagram packet to the destination with a TTL (time- to-live) other than the default for the socket. This method need only be used in instances where a particular TTL is desired; otherwise it is preferable to set a TTL once on the socket and use that default TTL for all packets. This method does not alter the default TTL for the socket. Its behavior may be affected by setInterface.

If there is a security manager this method first performs some security checks. First if p.getAddress().isMulticastAddress() is true this method calls the security manager's checkMulticast method with p.getAddress() and ttl as its arguments. If the evaluation of that expression is false this method instead calls the security manager's checkConnect method with arguments p.getAddress().getHostAddress() and p.getPort(). Each call to a security manager method could result in a SecurityException if the operation is not allowed. @param p is the packet to be sent. The packet should contain the destination multicast ip address and the data to be sent. One does not need to be the member of the group to send packets to a destination multicast address. @param ttl optional time to live for multicast packet. default ttl is 1. @exception IOException is raised if an error occurs i.e error while setting ttl. @exception SecurityException if a security manager exists and its checkMulticast or checkConnect method doesn't allow the send. @deprecated Use the following code or its equivalent instead: ...... int ttl = mcastSocket.getTimeToLive(); mcastSocket.setTimeToLive(newttl); mcastSocket.send(p); mcastSocket.setTimeToLive(ttl); ...... @see DatagramSocket#send @see DatagramSocket#receive @see SecurityManager#checkMulticast(java.net.InetAddress byte) @see SecurityManager#checkConnect

Class MulticastSocket, void setTTL(byte)

Set the default time-to-live for multicast packets sent out on this socket. The TTL sets the IP time-to-live for DatagramPacketsMulticastSocket sent to a MulticastGroup which specifies howin manyorder "hops"to thatcontrol the packetscope will be forwarded onof the network before it expiresmulticasts.

The ttl is an unsigned 8-bit quantity and so must be in the range 0 < ttl < 0xFF . @param ttl the time-to-live @exception IOException if an I/O exception occurs while setting the default time-to-live value @deprecated use the setTimeToLive method instead which uses int instead of byte as the type for ttl. @see #getTTL()

Class MulticastSocket, void setTimeToLive(int)

Set the default time-to-live for multicast packets sent out on this socket. The TTL sets the IP time-to-live for DatagramPacketsMulticastSocket sent to a MulticastGroup which specifies howin manyorder "hops"to thatcontrol the packetscope will be forwarded onof the network before it expiresmulticasts.

The ttl must be in the range 0 < ttl < 255 or an IllegalArgumentException will be thrown. @exception IOException if an I/O exception occurs while setting the default time-to-live value @param ttl the time-to-live @see #getTimeToLive()


Class NetPermission

This class is for various network permissions. A NetPermission contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't.

The target name is the name of the network permission (see below). The naming convention follows the hierarchical property naming convention. Also an asterisk may appear at the end of the name following a "." or by itself to signify a wildcard match. For example: "foo.*" or "*" is valid "*foo" or "a*b" is not valid.

The following table lists all the possible NetPermission target names and for each provides a description of what the permission allows and a discussion of the risks of granting code the permission.

Permission Target Name What the Permission Allows Risks of Allowing this Permission
setDefaultAuthenticator The ability to set the way authentication information is retrieved when a proxy or HTTP server asks for authentication Malicious code can set an authenticator that monitors and steals user authentication input as it retrieves the input from the user.
requestPasswordAuthentication The ability to ask the authenticator registered with the system for a password Malicious code may steal this password.
specifyStreamHandler The ability to specify a stream handler when constructing a URL Malicious code may create a URL with resources that it would normally not have access to (like file:/foo/fum/) specifying a stream handler that gets the actual bytes from someplace it does have access to. Thus it might be able to trick the system into creating a ProtectionDomain/CodeSource for a class even though that class really didn't come from that location.
@see java.security.BasicPermission @see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.SecurityManager @version 1.39 0040 01/0212/0203 @author Marianne Mueller @author Roland Schemers


Class PasswordAuthentication

The class PasswordAuthentication is a data holder that is used by Authenticator. It is simply a repository for a user name and a password. @see java.net.Authenticator @see java.net.Authenticator#getPasswordAuthentication() @author Bill Foote @version 1.10 0213 12/0203/0001 @since 1.2

Class ProtocolException

Thrown to indicate that there is an error in the underlying protocol such as a TCP error. @author Chris Warth @version 1.13 0214 12/0203/0001 @since JDK1.0

Class ServerSocket

This class implements server sockets. A server socket waits for requests to come in over the network. It performs some operation based on that request and then possibly returns a result to the requester.

The actual work of the server socket is performed by an instance of the SocketImpl class. An application can change the socket factory that creates the socket implementation to configure itself to create sockets appropriate to the local firewall. @author unascribed @version 1.42 0869 12/1603/0001 @see java.net.SocketImpl @see java.net.ServerSocket#setSocketFactory(java.net.SocketImplFactory) @see java.nio.channels.ServerSocketChannel @since JDK1.0

Class ServerSocket, constructor ServerSocket(int, int)

Creates a server socket and binds it to the specified local port number with the specified backlog. A port number of 0 creates a socket on any free port.

The maximum queue length for incoming connection indications (a request to connect) is set to the backlog parameter. If a connection indication arrives when the queue is full the connection is refused.

If the application has specified a server socket factory that factory's createSocketImpl method is called to create the actual socket implementation. Otherwise a "plain" socket is created.

If there is a security manager its checkListen method is called with the port argument as its argument to ensure the operation is allowed. This could result in a SecurityException.

The backlog argument must be a positive value greater than 0. If the value passed if equal or less than 0 then the default value will be assumed.

@param port the specified port or 0 to use any free port. @param backlog the maximum length of the queue. @exception IOException if an I/O error occurs when opening the socket. @exception SecurityException if a security manager exists and its checkListen method doesn't allow the operation. @see java.net.SocketImpl @see java.net.SocketImplFactory#createSocketImpl() @see java.net.ServerSocket#setSocketFactory(java.net.SocketImplFactory) @see SecurityManager#checkListen

Class ServerSocket, constructor ServerSocket(int, int, InetAddress)

Create a server with the specified port listen backlog and local IP address to bind to. The bindAddr argument can be used on a multi-homed host for a ServerSocket that will only accept connect requests to one of its addresses. If bindAddr is null it will default accepting connections on any/all local addresses. The port must be between 0 and 65535 inclusive.

If there is a security manager this method calls its checkListen method with the port argument as its argument to ensure the operation is allowed. This could result in a SecurityException.

The backlog argument must be a positive value greater than 0. If the value passed if equal or less than 0 then the default value will be assumed.

@param port the local TCP port @param backlog the listen backlog @param bindAddr the local InetAddress the server will bind to @throws SecurityException if a security manager exists and its checkListen method doesn't allow the operation. @throws IOException if an I/O error occurs when opening the socket. @see SocketOptions @see SocketImpl @see SecurityManager#checkListen @since JDK1.1

Class ServerSocket, Socket accept()

Listens for a connection to be made to this socket and accepts it. The method blocks until a connection is made.

A new Socket s is created and if there is a security manager the security manager's checkAccept method is called with s.getInetAddress().getHostAddress() and s.getPort() as its arguments to ensure the operation is allowed. This could result in a SecurityException. @exception IOException if an I/O error occurs when waiting for a connection. @exception SecurityException if a security manager exists and its checkListen method doesn't allow the operation. @exception SocketTimeoutException if a timeout was previously set with setSoTimeout and the timeout has been reached. @exception java.nio.channels.IllegalBlockingModeException if this socket has an associated channel and the channel is in non-blocking mode. @return the new Socket @see SecurityManager#checkAccept @revised 1.4 @spec JSR-51

Class ServerSocket, void close()

Closes this socket. Any thread currently blocked in #accept() will throw a SocketException

If this socket has an associated channel then the channel is closed as well. @exception IOException if an I/O error occurs when closing the socket. @revised 1.4 @spec JSR-51

Class ServerSocket, int getLocalPort()

Returns the port on which this socket is listening. @return the port number to which this socket is listening or -1 if the socket is not bound yet.
Class ServerSocket, void implAccept(Socket)

Subclasses of ServerSocket use this method to override accept() to return their own subclass of socket. So a FooServerSocket will typically hand this method an empty FooSocket. On return from implAccept the FooSocket will be connected to a client. @param s the Socket @throws java.nio.channels.IllegalBlockingModeException if this socket has an associated channel and the channel is in non-blocking mode @throws IOException if an I/O error occurs when waiting for a connection. @since JDK1.1 @revised 1.4 @spec JSR-51
Class ServerSocket, void setSoTimeout(int)

Enable/disable SO_TIMEOUT with the specified timeout in milliseconds. With this option set to a non-zero timeout a call to accept() for this ServerSocket will block for only this amount of time. If the timeout expires a java.ionet.InterruptedIOExceptionSocketTimeoutException is raised though the ServerSocket is still valid. The option must be enabled prior to entering the blocking operation to have effect. The timeout must be > 0. A timeout of zero is interpreted as an infinite timeout. @param timeout the specified timeout in milliseconds @exception SocketException if there is an error in the underlying protocol such as a TCP error. @since JDK1.1 @see #getSoTimeout()

Class Socket

This class implements client sockets (also called just "sockets"). A socket is an endpoint for communication between two machines.

The actual work of the socket is performed by an instance of the SocketImpl class. An application by changing the socket factory that creates the socket implementation can configure itself to create sockets appropriate to the local firewall. @author unascribed @version 1.55 0290 12/0903/01 @see java.net.Socket#setSocketImplFactory(java.net.SocketImplFactory) @see java.net.SocketImpl @see java.nio.channels.SocketChannel @since JDK1.0

Class Socket, constructor Socket()

Creates an unconnected socket with the system-default type of SocketImpl. @since JDK1.1 @revised 1.4
Class Socket, constructor Socket(InetAddress, int, boolean)

Creates a socket and connects it to the specified port number at the specified IP address.

If the stream argument is true this creates a stream socket. If the stream argument is false it creates a datagram socket.

If the application has specified a server socket factory that factory's createSocketImpl method is called to create the actual socket implementation. Otherwise a "plain" socket is created.

If there is a security manager its checkConnect method is called with host.getHostAddress() and port as its arguments. This could result in a SecurityException.

If UDP socket is used TCP/IP related socket options will not apply. @param host the IP address. @param port the port number. @param stream if true create a stream socket; otherwise create a datagram socket. @exception IOException if an I/O error occurs when creating the socket. @exception SecurityException if a security manager exists and its checkConnect method doesn't allow the operation. @see java.net.Socket#setSocketImplFactory(java.net.SocketImplFactory) @see java.net.SocketImpl @see java.net.SocketImplFactory#createSocketImpl() @see SecurityManager#checkConnect @deprecated Use DatagramSocket instead for UDP transport.

Class Socket, constructor Socket(String, int, boolean)

Creates a stream socket and connects it to the specified port number on the named host.

If the stream argument is true this creates a stream socket. If the stream argument is false it creates a datagram socket.

If the application has specified a server socket factory that factory's createSocketImpl method is called to create the actual socket implementation. Otherwise a "plain" socket is created.

If there is a security manager its checkConnect method is called with the host address and port as its arguments. This could result in a SecurityException.

If a UDP socket is used TCP/IP related socket options will not apply. @param host the host name. @param port the port number. @param stream a boolean indicating whether this is a stream socket or a datagram socket. @exception IOException if an I/O error occurs when creating the socket. @exception SecurityException if a security manager exists and its checkConnect method doesn't allow the operation. @see java.net.Socket#setSocketImplFactory(java.net.SocketImplFactory) @see java.net.SocketImpl @see java.net.SocketImplFactory#createSocketImpl() @see SecurityManager#checkConnect @deprecated Use DatagramSocket instead for UDP transport.

Class Socket, void close()

Closes this socket.

Any thread currently blocked in an I/O operation upon this socket will throw a SocketException

Once a socket has been closed it is not available for further networking use (i.e. can't be reconnected or rebound). A new socket needs to be created.

If this socket has an associated channel then the channel is closed as well. @exception IOException if an I/O error occurs when closing this socket. @revised 1.4 @spec JSR-51 @see #isClosed

Class Socket, InetAddress getInetAddress()

Returns the address to which the socket is connected. @return the remote IP address to which this socket is connected or null if the socket is not connected.
Class Socket, InputStream getInputStream()

Returns an input stream for this socket.

If this socket has an associated channel then the resulting input stream delegates all of its operations to the channel. If the channel is in non-blocking mode then the input stream's read operations will throw an java.nio.channels.IllegalBlockingModeException @return an input stream for reading bytes from this socket. @exception IOException if an I/O error occurs when creating the input stream or if the socket is not connected. @revised 1.4 @spec JSR-51

Class Socket, InetAddress getLocalAddress()

Gets the local address to which the socket is bound. @return the local address to which the socket is bound or InetAddress.anyLocalAddress() if the socket is not bound yet. @since JDK1.1
Class Socket, int getLocalPort()

Returns the local port to which this socket is bound. @return the local port number to which this socket is connectedbound or -1 if the socket is not bound yet.
Class Socket, OutputStream getOutputStream()

Returns an output stream for this socket.

If this socket has an associated channel then the resulting output stream delegates all of its operations to the channel. If the channel is in non-blocking mode then the output stream's write operations will throw an java.nio.channels.IllegalBlockingModeException @return an output stream for writing bytes to this socket. @exception IOException if an I/O error occurs when creating the output stream or if the socket is not connected. @revised 1.4 @spec JSR-51

Class Socket, int getPort()

Returns the remote port to which this socket is connected. @return the remote port number to which this socket is connected or 0 if the socket is not connected yet.
Class Socket, int getReceiveBufferSize()

Gets the value of the SO_RCVBUF option for this Socket that is the buffer size used by the platform for input on this Socket. @return the value of the SO_RCVBUF option for this Socket. @exception SocketException if there is an error in the underlying protocol such as a TCP error. @see #setReceiveBufferSize(int) @since 1.2
Class Socket, int getSendBufferSize()

Get value of the SO_SNDBUF option for this Socket that is the buffer size used by the platform for output on this Socket. @return the value of the SO_SNDBUF option for this Socket. @exception SocketException if there is an error in the underlying protocol such as a TCP error. @see #setSendBufferSize(int) @since 1.2
Class Socket, void setReceiveBufferSize(int)

Sets the SO_RCVBUF option to the specified value for this Socket. The SO_RCVBUF option is used by the platform's networking code as a hint for the size to set the underlying network I/O buffers.

Increasing the receive buffer size can increase the performance of network I/O for high-volume connection while decreasing it can help reduce the backlog of incoming data. For

Because UDPSO_RCVBUF this sets the maximum size of a packet that may be sent on thisis a hint applications that want to verify what size the buffers were set Socket.to should call #getReceiveBufferSize()

BecauseThe value of SO_RCVBUF is a hintalso used applicationsto set the TCP receive window that wantis advertized to verifythe whatremote peer. Generally the window size can be modified at any time when a socket is connected. However if a receive window larger than 64K is required then this must be requested before the buffers were setsocket is connected to shouldthe callremote peer. There are two cases to be aware of:

  1. For sockets accepted from a ServerSocket this must be done by calling ServerSocket#getReceiveBufferSizesetReceiveBufferSize(int) before the ServerSocket is bound to a local address.

  2. For client sockets setReceiveBufferSize() must be called before connecting the socket to its remote peer.

@param size the size to which to set the receive buffer size. This value must be greater than 0. @exception IllegalArgumentException if the value is 0 or is negative. @exception SocketException if there is an error in the underlying protocol such as a TCP error. @see #getReceiveBufferSize() @see ServerSocket#setReceiveBufferSize(int) @since 1.2
Class Socket, void setSendBufferSize(int)

Sets the SO_SNDBUF option to the specified value for this Socket. The SO_SNDBUF option is used by the platform's networking code as a hint for the size to set the underlying network I/O buffers.

Increasing buffer size can increase the performance of network I/O for high-volume connection while decreasing it can help reduce the backlog of incoming data. For UDP this sets the maximum size of a packet that may be sent on this Socket. Because SO_SNDBUF is a hint applications that want to verify what size the buffers were set to should call #getSendBufferSize() @exception SocketException if there is an error in the underlying protocol such as a TCP error. @param size the size to which to set the send buffer size. This value must be greater than 0. @exception IllegalArgumentException if the value is 0 or is negative. @see #getSendBufferSize() @since 1.2

Class Socket, void setSoLinger(boolean, int)

Enable/disable SO_LINGER with the specified linger time in seconds. The maximum timeout value is platform specific. The setting only affects socket close. @param on whether or not to linger on. @param linger how long to linger for if on is true. @exception SocketException if there is an error in the underlying protocol such as a TCP error. @exception IllegalArgumentException if the linger value is negative. @since JDK1.1 @see #getSoLinger()
Class Socket, void setSoTimeout(int)

Enable/disable SO_TIMEOUT with the specified timeout in milliseconds. With this option set to a non-zero timeout a read() call on the InputStream associated with this Socket will block for only this amount of time. If the timeout expires a java.ionet.InterruptedIOExceptionSocketTimeoutException is raised though the Socket is still valid. The option must be enabled prior to entering the blocking operation to have effect. The timeout must be > 0. A timeout of zero is interpreted as an infinite timeout. @param timeout the specified timeout in milliseconds. @exception SocketException if there is an error in the underlying protocol such as a TCP error. @since JDK 1.1 @see #getSoTimeout()
Class Socket, void setTcpNoDelay(boolean)

Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm). @param on true to enable TCP_NODELAY false to disable. @exception SocketException if there is an error in the underlying protocol such as a TCP error. @since JDK1.1 @see #getTcpNoDelay()
Class Socket, void shutdownInput()

Places the input stream for this socket at "end of stream". Any data sent to the input stream side of the socket is acknowledged and then silently discarded.

If you read from a socket input stream after invoking shutdownInput() on the socket the stream will return EOF. @exception IOException if an I/O error occurs when shutting down this socket. @since 1.3 @see java.net.Socket#shutdownOutput() @see java.net.Socket#close() @see java.net.Socket#setSoLinger(boolean int) @see #isInputShutdown

Class Socket, void shutdownOutput()

Disables the output stream for this socket. For a TCP socket any previously written data will be sent followed by TCP's normal connection termination sequence. If you write to a socket output stream after invoking shutdownOutput() on the socket the stream will throw an IOException. @exception IOException if an I/O error occurs when shutting down this socket. @since 1.3 @see java.net.Socket#shutdownInput() @see java.net.Socket#close() @see java.net.Socket#setSoLinger(boolean int) @see #isOutputShutdown

Class SocketException

Thrown to indicate that there is an error in the underlying protocol such as a TCP error. @author Jonathan Payne @version 1.14 0215 12/0203/0001 @since JDK1.0

Class SocketImpl

The abstract class SocketImpl is a common superclass of all classes that actually implement sockets. It is used to create both client and server sockets.

A "plain" socket implements these methods exactly as described without attempting to go through a firewall or proxy. @author unascribed @version 1.30 0838 12/1603/0001 @since JDK1.0


Class SocketImplFactory

This interface defines a factory for socket implementations. It is used by the classes Socket and ServerSocket to create actual socket implementations. @author Arthur van Hoff @version 1.15 0216 12/0203/0001 @see java.net.Socket @see java.net.ServerSocket @since JDK1.0

Class SocketOptions

Interface of methods to get/set socket options. This interface is implemented by: SocketImpl and DatagramSocketImpl. Subclasses of these should override the methods of this interface in order to support their own options.

The methods and constants which specify options in this interface are for implementation only. If you're not subclassing SocketImpl or DatagramSocketImpl you won't use these directly. There are type-safe methods to get/set each of these options in Socket ServerSocket DatagramSocket and MulticastSocket.

A subset of the standard BSD-style socket options are supported in the base classes PlainSocketImpl and PlainDatagramSocketImpl. A brief description of each and their use is provided. @version 1.20 0228 12/0203/0001 @author David Brown


Class SocketPermission

This class represents access to a network via sockets. A SocketPermission consists of a host specification and a set of "actions" specifying ways to connect to that host. The host is specified as
 host = (hostname | IPaddressIPv4address | iPv6reference) [:portrange] portrange = portnumber | -portnumber | portnumber-[portnumber] 
The host is expressed as a DNS name as a numerical IP address or as "localhost" (for the local machine). The wildcard "*" may be included once in a DNS name host specification. If it is included it must be in the leftmost position as in "*.sun.com".

The format of the IPv6reference should follow that specified in RFC 2732: Format for Literal IPv6 Addresses in URLs:

 ipv6reference = "[" IPv6address "]" 
For example you can construct a SocketPermission instance as the following:
 String hostAddress = inetaddress.getHostAddress(); if (inetaddress instanceof Inet6Address) { sp = new SocketPermission("[" + hostAddress + "]:" + port action); } else { sp = new SocketPermission(hostAddress + ":" + port action); } 
or
 String host = url.getHost(); sp = new SocketPermission(host + ":" + port action); 

The full uncompressed form of an IPv6 literal address is also valid.

The port or portrange is optional. A port specification of the form "N-" where N is a port number signifies all ports numbered N and above while a specification of the form "-N" indicates all ports numbered N and below.

The possible ways to connect to the host are

 accept connect listen resolve 
The "listen" action is only meaningful when used with "localhost". The "resolve" (resolve host/ip name service lookups) action is implied when any of the other actions are present.

As an example of the creation and meaning of SocketPermissions note that if the following permission:

 p1 = new SocketPermission("puffin.eng.sun.com:7777" "connect accept"); 
is granted to some code it allows that code to connect to port 7777 on puffin.eng.sun.com and to accept connections on that port.

Similarly if the following permission:

 p1 = new SocketPermission("puffin.eng.sun.com:7777" "connect accept"); p2 = new SocketPermission("localhost:1024-" "accept connect listen"); 
is granted to some code it allows that code to accept connections on connect to or listen on any port between 1024 and 65535 on the local host.

Note: Granting code permission to accept or make connections to remote hosts may be dangerous because malevolent code can then more easily transfer and share confidential data among parties who may not otherwise have access to the data. @see java.security.Permissions @see SocketPermission @version 1.37 0050 01/0912/0103 @author Marianne Mueller @author Roland Schemers @serial exclude


Class URL

Class URL represents a Uniform Resource Locator a pointer to a "resource" on the World Wide Web. A resource can be something as simple as a file or a directory or it can be a reference to a more complicated object such as a query to a database or to a search engine. More information on the types of URLs and their formats can be found at:
http://wwwarchive.ncsa.uiuc.edu:80/demowebSDG/Software/Mosaic/Demo/url-primer.html

In general a URL can be broken into several parts. The previous example of a URL indicates that the protocol to use is http (HyperText Transfer Protocol) and that the information resides on a host machine named www.ncsa.uiuc.edu. The information on that host machine is named /demoweb/url-primer.html. The exact meaning of this name on the host machine is both protocol dependent and host dependent. The information normally resides in a file but it could be generated on the fly. This component of the URL is called the path component.

A URL can optionally specify a "port" which is the port number to which the TCP connection is made on the remote host machine. If the port is not specified the default port for the protocol is used instead. For example the default port for http is 80. An alternative port could be specified as:

 http://wwwarchive.ncsa.uiuc.edu:808080/demowebSDG/Software/Mosaic/Demo/url-primer.html 

The syntax of URL is defined by RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax amended by RFC 2732: Format for Literal IPv6 Addresses in URLs.

A URL may have appended to it a "fragment" also known as a "ref" or a "reference". The fragment is indicated by the sharp sign character "#" followed by more characters. For example

 http://java.sun.com/index.html#chapter1 

This fragment is not technically part of the URL. Rather it indicates that after the specified resource is retrieved the application is specifically interested in that part of the document that has the tag chapter1 attached to it. The meaning of a tag is resource specific.

An application can also specify a "relative URL" which contains only enough information to reach the resource relative to another URL. Relative URLs are frequently used within HTML pages. For example if the contents of the URL:

 http://java.sun.com/index.html 
contained within it the relative URL:
 FAQ.html 
it would be a shorthand for:
 http://java.sun.com/FAQ.html 

The relative URL need not specify all the components of a URL. If the protocol host name or port number is missing the value is inherited from the fully specified URL. The file component must be specified. The optional fragment is not inherited. @author James Gosling @version 1.94 02116 12/0203/0001 @since JDK1.0

Class URL, constructor URL(String, String, String)

Creates a URL from the specified protocol name host name and file name. The default port for the specified protocol is used.

This method is equivalent to calling the four-argument constructor with the arguments being protocol host -1 and file. No validation of the inputs is performed by this constructor. @param protocol the name of the protocol to use. @param host the name of the host. @param file the file on the host. @exception MalformedURLException if an unknown protocol is specified. @see java.net.URL#URL(java.lang.String java.lang.String int java.lang.String)

Class URL, constructor URL(String, String, int, String)

Creates a URL object from the specified protocol host port number and file.

host can be expressed as a host name or a literal IP address. If IPv6 literal address is used it should be enclosed in square brackets ('[' and ']') as specified by RFC 2732; However the literal IPv6 address format defined in RFC 2373: IP Version 6 Addressing Architecture is also accepted.

Specifying a port number of -1 indicates that the URL should use the default port for the protocol.

If this is the first URL object being created with the specified protocol a stream protocol handler object an instance of class URLStreamHandler is created for that protocol:

  1. If the application has previously set up an instance of URLStreamHandlerFactory as the stream handler factory then the createURLStreamHandler method of that instance is called with the protocol string as an argument to create the stream protocol handler.
  2. If no URLStreamHandlerFactory has yet been set up or if the factory's createURLStreamHandler method returns null then the constructor finds the value of the system property:
     java.protocol.handler.pkgs 
    If the value of that system property is not null it is interpreted as a list of packages separated by a vertical slash character '|'. The constructor tries to load the class named:
     <package>.<protocol>.Handler 
    where <package> is replaced by the name of the package and <protocol> is replaced by the name of the protocol. If this class does not exist or if the class exists but it is not a subclass of URLStreamHandler then the next package in the list is tried.
  3. If the previous step fails to find a protocol handler then the constructor tries to load the classfrom a named:system default package.
     sun.net.www.protocol<system default package>.<protocol>.Handler 
    If this class does not exist or if the class exists but it is not a subclass of URLStreamHandler then a MalformedURLException is thrown.

No validation of the inputs is performed by this constructor. @param protocol the name of the protocol to use. @param host the name of the host. @param port the port number on the host. @param file the file on the host @exception MalformedURLException if an unknown protocol is specified. @see java.lang.System#getProperty(java.lang.String) @see java.net.URL#setURLStreamHandlerFactory( java.net.URLStreamHandlerFactory) @see java.net.URLStreamHandler @see java.net.URLStreamHandlerFactory#createURLStreamHandler( java.lang.String)

Class URL, constructor URL(String, String, int, String, URLStreamHandler)

Creates a URL object from the specified protocol host port number file and handler. Specifying a port number of -1 indicates that the URL should use the default port for the protocol. Specifying a handler of null indicates that the URL should use a default stream handler for the protocol as outlined for: java.net.URL#URL(java.lang.String java.lang.String int java.lang.String)

If the handler is not null and there is a security manager the security manager's checkPermission method is called with a NetPermission("specifyStreamHandler") permission. This may result in a SecurityException. No validation of the inputs is performed by this constructor. @param protocol the name of the protocol to use. @param host the name of the host. @param port the port number on the host. @param file the file on the host @param handler the stream handler for the URL. @exception MalformedURLException if an unknown protocol is specified. @exception SecurityException if a security manager exists and its checkPermission method doesn't allow specifying a stream handler explicitly. @see java.lang.System#getProperty(java.lang.String) @see java.net.URL#setURLStreamHandlerFactory( java.net.URLStreamHandlerFactory) @see java.net.URLStreamHandler @see java.net.URLStreamHandlerFactory#createURLStreamHandler( java.lang.String) @see SecurityManager#checkPermission @see java.net.NetPermission

Class URL, constructor URL(URL, String)

Creates a URL by parsing the given spec within a specified context. The new URL is created from the given context URL and the spec argument as described in RFC2396 "Uniform Resource Identifiers : Generic * Syntax" :
 <scheme>://<authority><path> <query>#<fragment> 
The reference is parsed into the scheme authority path query and fragment parts. If the path component is empty and the scheme authority and query components are undefined then the new URL is a reference to the current document. Otherwise the any fragment and query parts present in the spec are used in the new URL.

If the scheme component is defined in the given spec and does not match the scheme of the context then the new URL is created as an absolute URL based on the spec alone. Otherwise the scheme component is inherited from the context URL.

If the authority component is present in the spec then the spec is treated as absolute and the spec authority and path will replace the context authority and path. If the authority component is absent in the spec then the authority of the new URL will be inherited from the context.

If the spec's path component begins with a slash character "/" then the path is treated as absolute and the spec path replaces the context path.

Otherwise the path is treated as a relative path and is appended to the context path as described in RFC2396. TheAlso in this case the path is canonicalized through the removal of directory changes made by occurences of ".." and ".".

For a more detailed description of URL parsing refer to RFC2396. @param context the context in which to parse the specification. @param spec the String to parse as a URL. @exception MalformedURLException if no protocol is specified or an unknown protocol is found. @see java.net.URL#URL(java.lang.String java.lang.String int java.lang.String) @see java.net.URLStreamHandler @see java.net.URLStreamHandler#parseURL(java.net.URL java.lang.String int int)

Class URL, boolean equals(Object)

Compares two URLs. Thethis result isURL for trueequality if andwith another onlyobject.

ifIf the argumentgiven object is not null and is a URL object that represents the samethen this method immediately returns URLfalse as this object.

Two URL objects are equal if they have the same protocol and reference the same hostequivalent hosts have the same port number on the host and the same file and anchorfragment onof the file.

Two hosts are considered equivalent if both host names can be resolved into the same IP addresses; else if either host name can't be resolved the host names must be equal without regard to case; or both host names equal to null.

Since hosts comparison requires name resolution this operation is a blocking operation.

Note: The defined behavior for equals is known to be inconsistent with virtual hosting in HTTP. @param obj the URL to compare against. @return true if the objects are the same; false otherwise.

Class URL, String getAuthority()

ReturnsGets the authority part of this URL. @return the authority part of this URL @since 1.3
Class URL, Object getContent()

ReturnsGets the contents of this URL. This method is a shorthand for:
 openConnection().getContent() 
@return the contents of this URL. @exception IOException if an I/O exception occurs. @see java.net.URLConnection#getContent()
Class URL, Object getContent(Class[])

ReturnsGets the contents of this URL. This method is a shorthand for:
 openConnection().getContent(Class[]) 
@param classes an array of Java types @return the content object of this URL that is the first match of the types specified in the classes array. null if none of the requested types are supported. @exception IOException if an I/O exception occurs. @see java.net.URLConnection#getContent(Class[]) @since 1.3
Class URL, String getFile()

ReturnsGets the file name of this URL. @return the file name of this URL. or an empty string if one does not exist
Class URL, String getHost()

ReturnsGets the host name of this URL if applicable. The format of the host conforms to RFC 2732 i.e. for a literal IPv6 address this method will return the IPv6 address enclosed in square brackets ('[' and ']'). @return the host name of this URL.
Class URL, String getPath()

ReturnsGets the path part of this URL. @return the path part of this URL or an empty string if one does not exist @since 1.3
Class URL, int getPort()

ReturnsGets the port number of this URL. Returns@return the port number or -1 if the port is not set. @return the port number
Class URL, String getProtocol()

ReturnsGets the protocol name of this URL. @return the protocol of this URL.
Class URL, String getQuery()

ReturnsGets the query part of this URL. @return the query part of this URL or null if one does not exist @since 1.3
Class URL, String getRef()

ReturnsGets the anchor (also known as the "reference") of this URL. @return the anchor (also known as the "reference") of this URL. or null if one does not exist
Class URL, String getUserInfo()

ReturnsGets the userInfo part of this URL. @return the userInfo part of this URL. or null if one does not exist
Class URL, int hashCode()

Creates an integer suitable for hash table indexing.

The hash code is based upon all the URL components relevant for URL comparison. As such this operation is a blocking operation.

@return a hash code for this URL.

Class URL, boolean sameFile(URL)

Compares two URLs excluding the "ref"fragment fieldscomponent.

Returns true if this URL and the other argument both referare equal to the same resource. The two URLswithout mighttaking not boththe contain the same anchorfragment component into consideration. @param other the URL to compare against. @return true if they reference the same remote object; false otherwise.

Class URL, void set(String, String, int, String, String, String, String, String)

Sets the specified 8 fields of the URL. This is not a public method so that only URLStreamHandlers can modify URL fields. URLs are otherwise constant. @param protocol the name of the protocol to use @param host the name of the host @param port the port number on the host @param authority the authority part for the url @param userInfo the username and password @param path the file on the host @param ref the internal reference in the URL @param query the query part of this URL @since 1.3

Class URLClassLoader

This class loader is used to load classes and resources from a search path of URLs referring to both JAR files and directories. Any URL that ends with a '/' is assumed to refer to a directory. Otherwise the URL is assumed to refer to a JAR file which will be opened as needed.

The AccessControlContext of the thread that created the instance of URLClassLoader will be used when subsequently loading classes and resources.

The classes that are loaded are by default granted permission only to access the URLs specified when the URLClassLoader was created. @author David Connelly @version 1.74 0412/2103/01 @since 1.2

Class URLClassLoader, Enumeration findResources(String)

Returns an Enumeration of URLs representing all of the resources on the URL search path having the specified name. @param name the resource name @exception IOException if an I/O exception occurs @return an Enumeration of URLs
Class URLClassLoader, PermissionCollection getPermissions(CodeSource)

Returns the permissions for the given codesource object. The implementation of this method first calls super.getPermissions to get the permissions granted by the policy and then adds additional permissions based on the URL of the codesource.

If the protocol is "file" and the path specifies a file then permission to read that file is granted. If protocol is "file" and the path is a directory permission is granted to read all files and (recursively) all files and subdirectories contained in that directory.

If the protocol is not "file" then to connect to and accept connections from the URL's host is granted. @param codesource the codesource @return the permissions granted to the codesource


Class URLConnection

The abstract class URLConnection is the superclass of all classes that represent a communications link between the application and a URL. Instances of this class can be used both to read from and to write to the resource referenced by the URL. In general creating a connection to a URL is a multistep process:

openConnection() connect()
Manipulate parameters that affect the connection to the remote resource. Interact with the resource; query header fields and contents.
---------------------------->
time
  1. The connection object is created by invoking the openConnection method on a URL.
  2. The setup parameters and general request properties are manipulated.
  3. The actual connection to the remote object is made using the connect method.
  4. The remote object becomes available. The header fields and the contents of the remote object can be accessed.

The setup parameters are modified using the following methods:

and the general request properties are modified using the method:

Default values for the AllowUserInteraction and UseCaches parameters can be set using the methods setDefaultAllowUserInteraction and setDefaultUseCaches.

Each of the above set methods has a corresponding get method to retrieve the value of the parameter or general request property. The specific parameters and general request properties that are applicable are protocol specific.

The following methods are used to access the header fields and the contents after the connection is made to the remote object:

Certain header fields are accessed frequently. The methods:

provide convenient access to these fields. The getContentType method is used by the getContent method to determine the type of the remote object; subclasses may find it convenient to override the getContentType method.

In the common case all of the pre-connection parameters and general request properties can be ignored: the pre-connection parameters and request properties default to sensible values. For most clients of this interface there are only two interesting methods: getInputStream and getObjectgetContent which are mirrored in the URL class by convenience methods.

More information on the request properties and header fields of an http connection can be found at:

 http://www.ietf.org/rfc/rfc2068.txt 
Note about fileNameMap: In versions prior to JDK 1.1.6 field fileNameMap of URLConnection was public. In JDK 1.1.6 and later fileNameMap is private; accessor and mutator methods getFileNameMap and setFileNameMap are added to access it. This change is also described on the Compatibility page. Calling the close() methods on the InputStream or OutputStream of an URLConnection after a request may free network resources associated with this instance unless particular protocol specifications specify different behaviours for it. @author James Gosling @version 1.74 0288 12/0203/0001 @see java.net.URL#openConnection() @see java.net.URLConnection#connect() @see java.net.URLConnection#getContent() @see java.net.URLConnection#getContentEncoding() @see java.net.URLConnection#getContentLength() @see java.net.URLConnection#getContentType() @see java.net.URLConnection#getDate() @see java.net.URLConnection#getExpiration() @see java.net.URLConnection#getHeaderField(int) @see java.net.URLConnection#getHeaderField(java.lang.String) @see java.net.URLConnection#getInputStream() @see java.net.URLConnection#getLastModified() @see java.net.URLConnection#getOutputStream() @see java.net.URLConnection#setAllowUserInteraction(boolean) @see java.net.URLConnection#setDefaultUseCaches(boolean) @see java.net.URLConnection#setDoInput(boolean) @see java.net.URLConnection#setDoOutput(boolean) @see java.net.URLConnection#setIfModifiedSince(long) @see java.net.URLConnection#setRequestProperty(java.lang.String java.lang.String) @see java.net.URLConnection#setUseCaches(boolean) @since JDK1.0
Class URLConnection, String getHeaderField(String)

Returns the namevalue of the specifiednamed header field.

If called on a connection that sets the same header multiple times with possibly different values only the last value is returned. @param name the name of a header field. @return the value of the named header field or null if there is no such field in the header.

Class URLConnection, String getRequestProperty(String)

Returns the value of the named general request property for this connection. @param key the keyword by which the request is known (e.g. "accept"). @return the value of the named general request property for this connection. If key is null then null is returned. @throws IllegalStateException if already connected @see #setRequestProperty(java.lang.String java.lang.String)
Class URLConnection, void setAllowUserInteraction(boolean)

Set the value of the allowUserInteraction field of this URLConnection. @param allowuserinteraction the new value. @throws IllegalStateException if already connected @see #getAllowUserInteraction()
Class URLConnection, void setDoInput(boolean)

Sets the value of the doInput field for this URLConnection to the specified value.

A URL connection can be used for input and/or output. Set the DoInput flag to true if you intend to use the URL connection for input false if not. The default is true unless DoOutput is explicitly set to true in which case DoInput defaults to false. @param doinput the new value. @throws IllegalStateException if already connected @see java.net.URLConnection#doInput @see #getDoInput()

Class URLConnection, void setDoOutput(boolean)

Sets the value of the doOutput field for this URLConnection to the specified value.

A URL connection can be used for input and/or output. Set the DoOutput flag to true if you intend to use the URL connection for output false if not. The default is false. @param dooutput the new value. @throws IllegalStateException if already connected @see #getDoOutput()

Class URLConnection, void setIfModifiedSince(long)

Sets the value of the ifModifiedSince field of this URLConnection to the specified value. @param ifmodifiedsince the new value. @throws IllegalStateException if already connected @see #getIfModifiedSince()
Class URLConnection, void setRequestProperty(String, String)

Sets the general request property. If a property with the key already exists overwrite its value with the new value.

NOTE: HTTP requires all request properties which can legally have multiple instances with the same key to use a comma-seperated list syntax which enables multiple properties to be appended into a single property. @param key the keyword by which the request is known (e.g. "accept"). @param value the value associated with it. @throws IllegalStateException if already connected @throws NullPointerException if key is null @see #getRequestProperty(java.lang.String)

Class URLConnection, void setUseCaches(boolean)

Sets the value of the useCaches field of this URLConnection to the specified value.

Some protocols do caching of documents. Occasionally it is important to be able to "tunnel through" and ignore the caches (e.g. the "reload" button in a browser). If the UseCaches flag on a connection is true the connection is allowed to use whatever caches it can. If false caches are to be ignored. The default value comes from DefaultUseCaches which defaults to true. @param usecaches a boolean indicating whether or not to allow caching @throws IllegalStateException if already connected @see #getUseCaches()

Class URLConnection, boolean doOutput

This variable is set by the setDoOutput method. Its value is returned by the getDoInputgetDoOutput method.

A URL connection can be used for input and/or output. Setting the doOutput flag to true indicates that the application intends to write data to the URL connection.

The default value of this field is false. @see java.net.URLConnection#getDoOutput() @see java.net.URLConnection#setDoOutput(boolean)


Class URLDecoder

TheUtility class containsfor a utilityHTML form methoddecoding. for convertingThis class fromcontains static methods for decoding a MIME format calledString from the "application/x-www-form-urlencoded" toMIME format.

To conversion process is the reverse of that used by the URLEncoder class. It is assumed that all characters in the encoded string are one of the following: "a" through "Stringz" "A" Tothrough "Z" convert"0" tothrough a"9" and "String-" "_" "." and "*". eachThe character "%" is allowed but is examinedinterpreted as the start of a special escaped sequence.

The following rules are applied in turnthe conversion:

There are two possible ways in which this decoder could deal with illegal strings. It could either leave illegal characters alone or it could throw an {@link java.lang.IllegalArgumentException}. Which approach the decoder takes is left to the implementation. @author Mark Chamness @author Michael McCloskey @version 1.9 0220 12/0203/0001 @since 1.2


Class URLEncoder

TheUtility class containsfor a utilityHTML form methodencoding. for converting aThis class contains Stringstatic intomethods for converting a MIME format calledString to the "application/x-www-form-urlencoded" MIME format. For more information about HTML form encoding consult the HTML specification.

To convertWhen encoding a String each character is examined in turnthe following rules apply:

For example using UTF-8 as the encoding scheme the string "The string ü@foo-bar" would get converted to "The+string+%C3%BC%40foo-bar" because in UTF-8 the character ü is encoded as two bytes C3 (hex) and BC (hex) and the character @ is encoded as one byte 40 (hex). @author Herb Jellinek @version 1.18 0225 12/0203/0001 @since JDK1.0


Class URLStreamHandler

The abstract class URLStreamHandler is the common superclass for all stream protocol handlers. A stream protocol handler knows how to make a connection for a particular protocol type such as http ftp or gopher.

In most cases an instance of a URLStreamHandler subclass is not created directly by an application. Rather the first time a protocol name is encountered when constructing a URL the appropriate stream protocol handler is automatically loaded. @author James Gosling @version 1.43 0455 12/2103/01 @see java.net.URL#URL(java.lang.String java.lang.String int java.lang.String) @since JDK1.0

Class URLStreamHandler, boolean equals(URL, URL)

Provides the default equals calculation. May be overidden by handlers for other protocols that have different requirements for equals(). This method requires that none of its arguments is null. This is guaranteed by the fact that it is only called by java.net.URL class. @param u1 a URL object @param u2 a URL object @return true if the two urls are considered equal ie. they refer to the same fragment in the same file.
Class URLStreamHandler, InetAddress getHostAddress(URL)

Get the IP address of our host. An empty host field or a DNS failure will result in a null return. @param u a URL object @return an InetAddress representing the host IP address.
Class URLStreamHandler, int hashCode(URL)

Provides the default hash calculation. May be overidden by handlers for other protocols that have different requirements for hashCode calculation. @param u a URL object @return an int suitable for hash table indexing
Class URLStreamHandler, boolean sameFile(URL, URL)

Compare two urls to see whether they refer to the same file i.e. having the same protocol host port and path. This method requires that none of its arguments is null. This is guaranteed by the fact that it is only called indirectly by java.net.URL class. @param u1 a URL object @param u2 a URL object @return true if u1 and u2 refer to the same file
Class URLStreamHandler, void setURL(URL, String, String, int, String, String, String, String, String)

Sets the fields of the URL argument to the indicated values. Only classes derived from URLStreamHandler are supposed to be able to call the set method on a URL. @param u the URL to modify. @param protocol the protocol name. @param host the remote host value for the URL. @param port the port on the remote machine. @param authority the authority part for the URL. @param userInfo the userInfo part of the URL. @param path the path component of the URL. @param query the query part for the URL. @param ref the reference. @see java.net.URL#set(java.lang.String java.lang.String int java.lang.String java.lang.String)

Class URLStreamHandlerFactory

This interface defines a factory for URL stream protocol handlers.

It is used by the URL class to create a URLStreamHandler for a specific protocol. @author Arthur van Hoff @version 1.15 0216 12/0203/0001 @see java.net.URL @see java.net.URLStreamHandler @since JDK1.0


Class UnknownHostException

Thrown to indicate that the IP address of a host could not be determined. @author Jonathan Payne @version 1.12 0213 12/0203/0001 @since JDK1.0

Class UnknownServiceException

Thrown to indicate that an unknown service exception has occurred. Either the MIME type returned by a URL connection does not make sense or the application is attempting to write to a read-only URL connection. @author unascribed @version 1.11 0212 12/0203/0001 @since JDK1.0