archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 15:24:43 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8021833: javadoc cleanup in java.net

Browse source 
<code> and <tt> converted to {@code }; package.html to package-info.java

Reviewed-by: darcy, chegar
This commit is contained in:
Jason Uh 2013-07-30 11:04:19 -07:00
parent 1cf74954ed
commit 3e4d534e16
55 changed files with 1398 additions and 1356 deletions
Download patch file Download diff file Expand all files Collapse all files

130
jdk/src/share/classes/java/net/ServerSocket.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 1995, 2011, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -37,7 +37,7 @@ import java.security.PrivilegedExceptionAction;
* based on that request, and then possibly returns a result to the requester.
* <p>
* The actual work of the server socket is performed by an instance
* of the <code>SocketImpl</code> class. An application can
* of the {@code 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.
@ -89,31 +89,31 @@ class ServerSocket implements java.io.Closeable {
/**
* Creates a server socket, bound to the specified port. A port number
* of <code>0</code> means that the port number is automatically
* of {@code 0} means that the port number is automatically
* allocated, typically from an ephemeral port range. This port
* number can then be retrieved by calling {@link #getLocalPort getLocalPort}.
* <p>
* The maximum queue length for incoming connection indications (a
* request to connect) is set to <code>50</code>. If a connection
* request to connect) is set to {@code 50}. If a connection
* indication arrives when the queue is full, the connection is refused.
* <p>
* If the application has specified a server socket factory, that
* factory's <code>createSocketImpl</code> method is called to create
* factory's {@code createSocketImpl} method is called to create
* the actual socket implementation. Otherwise a "plain" socket is created.
* <p>
* If there is a security manager,
* its <code>checkListen</code> method is called
* with the <code>port</code> argument
* its {@code checkListen} method is called
* with the {@code port} argument
* as its argument to ensure the operation is allowed.
* This could result in a SecurityException.
*
*
* @param port the port number, or <code>0</code> to use a port
* @param port the port number, or {@code 0} to use a port
* number that is automatically allocated.
*
* @exception IOException if an I/O error occurs when opening the socket.
* @exception SecurityException
* if a security manager exists and its <code>checkListen</code>
* if a security manager exists and its {@code checkListen}
* method doesn't allow the operation.
* @exception IllegalArgumentException if the port parameter is outside
* the specified range of valid port values, which is between
@ -131,42 +131,42 @@ class ServerSocket implements java.io.Closeable {
/**
* Creates a server socket and binds it to the specified local port
* number, with the specified backlog.
* A port number of <code>0</code> means that the port number is
* A port number of {@code 0} means that the port number is
* automatically allocated, typically from an ephemeral port range.
* This port number can then be retrieved by calling
* {@link #getLocalPort getLocalPort}.
* <p>
* The maximum queue length for incoming connection indications (a
* request to connect) is set to the <code>backlog</code> parameter. If
* request to connect) is set to the {@code backlog} parameter. If
* a connection indication arrives when the queue is full, the
* connection is refused.
* <p>
* If the application has specified a server socket factory, that
* factory's <code>createSocketImpl</code> method is called to create
* factory's {@code createSocketImpl} method is called to create
* the actual socket implementation. Otherwise a "plain" socket is created.
* <p>
* If there is a security manager,
* its <code>checkListen</code> method is called
* with the <code>port</code> argument
* its {@code checkListen} method is called
* with the {@code port} argument
* as its argument to ensure the operation is allowed.
* This could result in a SecurityException.
*
* The <code>backlog</code> argument is the requested maximum number of
* The {@code backlog} argument is the requested maximum number of
* pending connections on the socket. Its exact semantics are implementation
* specific. In particular, an implementation may impose a maximum length
* or may choose to ignore the parameter altogther. The value provided
* should be greater than <code>0</code>. If it is less than or equal to
* <code>0</code>, then an implementation specific default will be used.
* should be greater than {@code 0}. If it is less than or equal to
* {@code 0}, then an implementation specific default will be used.
* <P>
*
* @param port the port number, or <code>0</code> to use a port
* @param port the port number, or {@code 0} to use a port
* number that is automatically allocated.
* @param backlog requested maximum length of the queue of incoming
* connections.
*
* @exception IOException if an I/O error occurs when opening the socket.
* @exception SecurityException
* if a security manager exists and its <code>checkListen</code>
* if a security manager exists and its {@code checkListen}
* method doesn't allow the operation.
* @exception IllegalArgumentException if the port parameter is outside
* the specified range of valid port values, which is between
@ -189,32 +189,32 @@ class ServerSocket implements java.io.Closeable {
* If <i>bindAddr</i> is null, it will default accepting
* connections on any/all local addresses.
* The port must be between 0 and 65535, inclusive.
* A port number of <code>0</code> means that the port number is
* A port number of {@code 0} means that the port number is
* automatically allocated, typically from an ephemeral port range.
* This port number can then be retrieved by calling
* {@link #getLocalPort getLocalPort}.
*
* <P>If there is a security manager, this method
* calls its <code>checkListen</code> method
* with the <code>port</code> argument
* calls its {@code checkListen} method
* with the {@code port} argument
* as its argument to ensure the operation is allowed.
* This could result in a SecurityException.
*
* The <code>backlog</code> argument is the requested maximum number of
* The {@code backlog} argument is the requested maximum number of
* pending connections on the socket. Its exact semantics are implementation
* specific. In particular, an implementation may impose a maximum length
* or may choose to ignore the parameter altogther. The value provided
* should be greater than <code>0</code>. If it is less than or equal to
* <code>0</code>, then an implementation specific default will be used.
* should be greater than {@code 0}. If it is less than or equal to
* {@code 0}, then an implementation specific default will be used.
* <P>
* @param port the port number, or <code>0</code> to use a port
* @param port the port number, or {@code 0} to use a port
* number that is automatically allocated.
* @param backlog requested maximum length of the queue of incoming
* connections.
* @param bindAddr the local InetAddress the server will bind to
*
* @throws SecurityException if a security manager exists and
* its <code>checkListen</code> method doesn't allow the operation.
* its {@code checkListen} method doesn't allow the operation.
*
* @throws IOException if an I/O error occurs when opening the socket.
* @exception IllegalArgumentException if the port parameter is outside
@ -245,10 +245,10 @@ class ServerSocket implements java.io.Closeable {
}
/**
* Get the <code>SocketImpl</code> attached to this socket, creating
* Get the {@code SocketImpl} attached to this socket, creating
* it if necessary.
*
* @return the <code>SocketImpl</code> attached to that ServerSocket.
* @return the {@code SocketImpl} attached to that ServerSocket.
* @throws SocketException if creation fails.
* @since 1.4
*/
@ -310,17 +310,17 @@ class ServerSocket implements java.io.Closeable {
/**
*
* Binds the <code>ServerSocket</code> to a specific address
* Binds the {@code ServerSocket} to a specific address
* (IP address and port number).
* <p>
* If the address is <code>null</code>, then the system will pick up
* If the address is {@code null}, then the system will pick up
* an ephemeral port and a valid local address to bind the socket.
* <p>
* @param endpoint The IP address and port number to bind to.
* @throws IOException if the bind operation fails, or if the socket
* is already bound.
* @throws SecurityException if a <code>SecurityManager</code> is present and
* its <code>checkListen</code> method doesn't allow the operation.
* @throws SecurityException if a {@code SecurityManager} is present and
* its {@code checkListen} method doesn't allow the operation.
* @throws IllegalArgumentException if endpoint is a
* SocketAddress subclass not supported by this socket
* @since 1.4
@ -331,25 +331,25 @@ class ServerSocket implements java.io.Closeable {
/**
*
* Binds the <code>ServerSocket</code> to a specific address
* Binds the {@code ServerSocket} to a specific address
* (IP address and port number).
* <p>
* If the address is <code>null</code>, then the system will pick up
* If the address is {@code null}, then the system will pick up
* an ephemeral port and a valid local address to bind the socket.
* <P>
* The <code>backlog</code> argument is the requested maximum number of
* The {@code backlog} argument is the requested maximum number of
* pending connections on the socket. Its exact semantics are implementation
* specific. In particular, an implementation may impose a maximum length
* or may choose to ignore the parameter altogther. The value provided
* should be greater than <code>0</code>. If it is less than or equal to
* <code>0</code>, then an implementation specific default will be used.
* should be greater than {@code 0}. If it is less than or equal to
* {@code 0}, then an implementation specific default will be used.
* @param endpoint The IP address and port number to bind to.
* @param backlog requested maximum length of the queue of
* incoming connections.
* @throws IOException if the bind operation fails, or if the socket
* is already bound.
* @throws SecurityException if a <code>SecurityManager</code> is present and
* its <code>checkListen</code> method doesn't allow the operation.
* @throws SecurityException if a {@code SecurityManager} is present and
* its {@code checkListen} method doesn't allow the operation.
* @throws IllegalArgumentException if endpoint is a
* SocketAddress subclass not supported by this socket
* @since 1.4
@ -480,18 +480,18 @@ class ServerSocket implements java.io.Closeable {
* Listens for a connection to be made to this socket and accepts
* it. The method blocks until a connection is made.
*
* <p>A new Socket <code>s</code> is created and, if there
* <p>A new Socket {@code s} is created and, if there
* is a security manager,
* the security manager's <code>checkAccept</code> method is called
* with <code>s.getInetAddress().getHostAddress()</code> and
* <code>s.getPort()</code>
* the security manager's {@code checkAccept} method is called
* with {@code s.getInetAddress().getHostAddress()} and
* {@code 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
* <code>checkAccept</code> method doesn't allow the operation.
* {@code checkAccept} 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
@ -597,7 +597,7 @@ class ServerSocket implements java.io.Closeable {
* method.
*
* @return the server-socket channel associated with this socket,
* or <tt>null</tt> if this socket was not created
* or {@code null} if this socket was not created
* for a channel
*
* @since 1.4
@ -678,18 +678,18 @@ class ServerSocket implements java.io.Closeable {
* <p>
* When a TCP connection is closed the connection may remain
* in a timeout state for a period of time after the connection
* is closed (typically known as the <tt>TIME_WAIT</tt> state
* or <tt>2MSL</tt> wait state).
* is closed (typically known as the {@code TIME_WAIT} state
* or {@code 2MSL} wait state).
* For applications using a well known socket address or port
* it may not be possible to bind a socket to the required
* <tt>SocketAddress</tt> if there is a connection in the
* {@code SocketAddress} if there is a connection in the
* timeout state involving the socket address or port.
* <p>
* Enabling {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} prior to
* binding the socket using {@link #bind(SocketAddress)} allows the socket
* to be bound even though a previous connection is in a timeout state.
* <p>
* When a <tt>ServerSocket</tt> is created the initial setting
* When a {@code ServerSocket} is created the initial setting
* of {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is not defined.
* Applications can use {@link #getReuseAddress()} to determine the initial
* setting of {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR}.
@ -717,7 +717,7 @@ class ServerSocket implements java.io.Closeable {
/**
* Tests if {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is enabled.
*
* @return a <code>boolean</code> indicating whether or not
* @return a {@code boolean} indicating whether or not
* {@link SocketOptions#SO_REUSEADDR SO_REUSEADDR} is enabled.
* @exception SocketException if there is an error
* in the underlying protocol, such as a TCP error.
@ -732,7 +732,7 @@ class ServerSocket implements java.io.Closeable {
/**
* Returns the implementation address and implementation port of
* this socket as a <code>String</code>.
* this socket as a {@code String}.
* <p>
* If there is a security manager set, its {@code checkConnect} method is
* called with the local address and {@code -1} as its arguments to see
@ -773,14 +773,14 @@ class ServerSocket implements java.io.Closeable {
* application. The factory can be specified only once.
* <p>
* When an application creates a new server socket, the socket
* implementation factory's <code>createSocketImpl</code> method is
* implementation factory's {@code createSocketImpl} method is
* called to create the actual socket implementation.
* <p>
* Passing <code>null</code> to the method is a no-op unless the factory
* Passing {@code null} to the method is a no-op unless the factory
* was already set.
* <p>
* If there is a security manager, this method first calls
* the security manager's <code>checkSetFactory</code> method
* the security manager's {@code checkSetFactory} method
* to ensure the operation is allowed.
* This could result in a SecurityException.
*
@ -789,7 +789,7 @@ class ServerSocket implements java.io.Closeable {
* socket factory.
* @exception SocketException if the factory has already been defined.
* @exception SecurityException if a security manager exists and its
* <code>checkSetFactory</code> method doesn't allow the operation.
* {@code checkSetFactory} method doesn't allow the operation.
* @see java.net.SocketImplFactory#createSocketImpl()
* @see SecurityManager#checkSetFactory
*/
@ -807,7 +807,7 @@ class ServerSocket implements java.io.Closeable {
/**
* Sets a default proposed value for the
* {@link SocketOptions#SO_RCVBUF SO_RCVBUF} option for sockets
* accepted from this <tt>ServerSocket</tt>. The value actually set
* accepted from this {@code ServerSocket}. The value actually set
* in the accepted socket must be determined by calling
* {@link Socket#getReceiveBufferSize()} after the socket
* is returned by {@link #accept()}.
@ -851,13 +851,13 @@ class ServerSocket implements java.io.Closeable {
/**
* Gets the value of the {@link SocketOptions#SO_RCVBUF SO_RCVBUF} option
* for this <tt>ServerSocket</tt>, that is the proposed buffer size that
* will be used for Sockets accepted from this <tt>ServerSocket</tt>.
* for this {@code ServerSocket}, that is the proposed buffer size that
* will be used for Sockets accepted from this {@code ServerSocket}.
*
* <p>Note, the value actually set in the accepted socket is determined by
* calling {@link Socket#getReceiveBufferSize()}.
* @return the value of the {@link SocketOptions#SO_RCVBUF SO_RCVBUF}
* option for this <tt>Socket</tt>.
* option for this {@code Socket}.
* @exception SocketException if there is an error
* in the underlying protocol, such as a TCP error.
* @see #setReceiveBufferSize(int)
@ -891,24 +891,24 @@ class ServerSocket implements java.io.Closeable {
* compared, with larger values indicating stronger preferences. If the
* application prefers short connection time over both low latency and high
* bandwidth, for example, then it could invoke this method with the values
* <tt>(1, 0, 0)</tt>. If the application prefers high bandwidth above low
* {@code (1, 0, 0)}. If the application prefers high bandwidth above low
* latency, and low latency above short connection time, then it could
* invoke this method with the values <tt>(0, 1, 2)</tt>.
* invoke this method with the values {@code (0, 1, 2)}.
*
* <p> Invoking this method after this socket has been bound
* will have no effect. This implies that in order to use this capability
* requires the socket to be created with the no-argument constructor.
*
* @param connectionTime
* An <tt>int</tt> expressing the relative importance of a short
* An {@code int} expressing the relative importance of a short
* connection time
*
* @param latency
* An <tt>int</tt> expressing the relative importance of low
* An {@code int} expressing the relative importance of low
* latency
*
* @param bandwidth
* An <tt>int</tt> expressing the relative importance of high
* An {@code int} expressing the relative importance of high
* bandwidth
*
* @since 1.5