ARTEMIS-2109: fix javadoc errors, remove doclint config for JDK8, remove superfluous plugin versions, update to 3.0.1 javadoc plugin

Using 3.0.1 like the current apache parent pom [not being used], and also as newer ones break build.
This commit is contained in:
Robbie Gemmell 2020-06-05 15:21:38 +01:00
parent efe0f468de
commit d2c46762e8
35 changed files with 62 additions and 92 deletions

View File

@ -19,7 +19,7 @@ import java.nio.charset.StandardCharsets;
/**
* <p>Encodes and decodes to and from Base64 notation.</p>
* <p>Homepage: <a href="http://iharder.net/base64">http://iharder.net/base64</a>.</p>
* <p>The <tt>options</tt> parameter, which appears in a few places, is used to pass
* <p>The <code>options</code> parameter, which appears in a few places, is used to pass
* several pieces of information to the encoder. In the "higher level" methods such as
* encodeBytes( bytes, options ) the options parameter can be used to indicate such
* things as first gzipping the bytes before encoding them, not inserting linefeeds
@ -66,9 +66,9 @@ import java.nio.charset.StandardCharsets;
* when data that's being decoded is gzip-compressed and will decompress it
* automatically. Generally things are cleaner. You'll probably have to
* change some method calls that you were making to support the new
* options format (<tt>int</tt>s that you "OR" together).</li>
* options format (<code>int</code>s that you "OR" together).</li>
* <li>v1.5.1 - Fixed bug when decompressing and decoding to a
* byte[] using <tt>decode( String s, boolean gzipCompressed )</tt>.
* byte[] using <code>decode( String s, boolean gzipCompressed )</code>.
* Added the ability to "suspend" encoding in the Output Stream so
* you can turn on and off the encoding if you need to embed base64
* data in an otherwise "normal" stream (like an XML file).</li>
@ -484,7 +484,7 @@ public class Base64 {
* Serializes an object and returns the Base64-encoded
* version of that serialized object. If the object
* cannot be serialized or there is another error,
* the method will return <tt>null</tt>.
* the method will return <code>null</code>.
* The object is not GZip-compressed before being encoded.
*
* @param serializableObject The object to encode
@ -499,7 +499,7 @@ public class Base64 {
* Serializes an object and returns the Base64-encoded
* version of that serialized object. If the object
* cannot be serialized or there is another error,
* the method will return <tt>null</tt>.
* the method will return <code>null</code>.
* <p>
* Valid options:<pre>
* GZIP: gzip-compresses object before encoding it.
@ -931,7 +931,7 @@ public class Base64 {
/**
* Attempts to decode Base64 data and deserialize a Java
* Object within. Returns <tt>null</tt> if there was an error.
* Object within. Returns <code>null</code> if there was an error.
*
* @param encodedObject The Base64 data to decode
* @return The decoded and deserialized object
@ -972,7 +972,7 @@ public class Base64 {
*
* @param dataToEncode byte array of data to encode in base64 form
* @param filename Filename for saving encoded data
* @return <tt>true</tt> if successful, <tt>false</tt> otherwise
* @return <code>true</code> if successful, <code>false</code> otherwise
* @since 2.1
*/
public static boolean encodeToFile(final byte[] dataToEncode, final String filename) {
@ -1000,7 +1000,7 @@ public class Base64 {
*
* @param dataToDecode Base64-encoded data as a string
* @param filename Filename for saving decoded data
* @return <tt>true</tt> if successful, <tt>false</tt> otherwise
* @return <code>true</code> if successful, <code>false</code> otherwise
* @since 2.1
*/
public static boolean decodeToFile(final String dataToDecode, final String filename) {
@ -1116,7 +1116,7 @@ public class Base64 {
} // end encodeFromFile
/**
* Reads <tt>infile</tt> and encodes it to <tt>outfile</tt>.
* Reads <code>infile</code> and encodes it to <code>outfile</code>.
*
* @param infile Input file
* @param outfile Output file
@ -1153,7 +1153,7 @@ public class Base64 {
} // end encodeFileToFile
/**
* Reads <tt>infile</tt> and decodes it to <tt>outfile</tt>.
* Reads <code>infile</code> and decodes it to <code>outfile</code>.
*
* @param infile Input file
* @param outfile Output file
@ -1193,7 +1193,7 @@ public class Base64 {
/**
* A {@link Base64.InputStream} will read data from another
* <tt>java.io.InputStream</tt>, given in the constructor,
* <code>java.io.InputStream</code>, given in the constructor,
* and encode/decode to/from Base64 notation on the fly.
*
* @see Base64
@ -1224,7 +1224,7 @@ public class Base64 {
/**
* Constructs a {@link Base64.InputStream} in DECODE mode.
*
* @param in the <tt>java.io.InputStream</tt> from which to read data.
* @param in the <code>java.io.InputStream</code> from which to read data.
* @since 1.3
*/
public InputStream(final java.io.InputStream in) {
@ -1244,7 +1244,7 @@ public class Base64 {
* <p>
* Example: <code>new Base64.InputStream( in, Base64.DECODE )</code>
*
* @param in the <tt>java.io.InputStream</tt> from which to read data.
* @param in the <code>java.io.InputStream</code> from which to read data.
* @param options Specified options
* @see Base64#ENCODE
* @see Base64#DECODE
@ -1404,7 +1404,7 @@ public class Base64 {
/**
* A {@link Base64.OutputStream} will write data to another
* <tt>java.io.OutputStream</tt>, given in the constructor,
* <code>java.io.OutputStream</code>, given in the constructor,
* and encode/decode to/from Base64 notation on the fly.
*
* @see Base64
@ -1437,7 +1437,7 @@ public class Base64 {
/**
* Constructs a {@link Base64.OutputStream} in ENCODE mode.
*
* @param out the <tt>java.io.OutputStream</tt> to which data will be written.
* @param out the <code>java.io.OutputStream</code> to which data will be written.
* @since 1.3
*/
public OutputStream(final java.io.OutputStream out) {
@ -1457,7 +1457,7 @@ public class Base64 {
* <p>
* Example: <code>new Base64.OutputStream( out, Base64.ENCODE )</code>
*
* @param out the <tt>java.io.OutputStream</tt> to which data will be written.
* @param out the <code>java.io.OutputStream</code> to which data will be written.
* @param options Specified options.
* @see Base64#ENCODE
* @see Base64#DECODE

View File

@ -44,21 +44,21 @@ import static org.apache.activemq.artemis.utils.ByteUtil.intFromBytes;
*
* <p>Examples of IP addresses and their byte representations:
* <ul>
* <li>The IPv4 loopback address, {@code "127.0.0.1"}.<br/>
* <li>The IPv4 loopback address, {@code "127.0.0.1"}.<br>
* {@code 7f 00 00 01}
*
* <li>The IPv6 loopback address, {@code "::1"}.<br/>
* <li>The IPv6 loopback address, {@code "::1"}.<br>
* {@code 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 01}
*
* <li>From the IPv6 reserved documentation prefix ({@code 2001:db8::/32}),
* {@code "2001:db8::1"}.<br/>
* {@code "2001:db8::1"}.<br>
* {@code 20 01 0d b8 00 00 00 00 00 00 00 00 00 00 00 01}
*
* <li>An IPv6 "IPv4 compatible" (or "compat") address,
* {@code "::192.168.0.1"}.<br/>
* {@code "::192.168.0.1"}.<br>
* {@code 00 00 00 00 00 00 00 00 00 00 00 00 c0 a8 00 01}
*
* <li>An IPv6 "IPv4 mapped" address, {@code "::ffff:192.168.0.1"}.<br/>
* <li>An IPv6 "IPv4 mapped" address, {@code "::ffff:192.168.0.1"}.<br>
* {@code 00 00 00 00 00 00 00 00 00 00 ff ff c0 a8 00 01}
* </ul>
*

View File

@ -171,7 +171,7 @@ public class SpawnedVMSupport {
* @param logOutput
* @param logErrorOutput
* @param useLogging
* @param debugPort if <=0 it means no debug
* @param debugPort if &lt;=0 it means no debug
* @param args
* @return
* @throws IOException

View File

@ -64,7 +64,7 @@ public final class ConcurrentAppendOnlyChunkedList<T> {
private volatile long cachedLastIndex = 0;
/**
* @throws IllegalArgumentException if {@code chunkSize} is <0 or not a power of 2
* @throws IllegalArgumentException if {@code chunkSize} is &lt;0 or not a power of 2
*/
public ConcurrentAppendOnlyChunkedList(final int chunkSize) {
if (chunkSize <= 0) {

View File

@ -33,9 +33,9 @@ import static org.apache.activemq.artemis.utils.Preconditions.checkNotNull;
/**
* Map from long to an Object.
*
* Provides similar methods as a ConcurrentMap<long,Object> with 2 differences:
* Provides similar methods as a {@literal ConcurrentMap<long,Object>} with 2 differences:
* <ol>
* <li>No boxing/unboxing from long -> Long
* <li>No boxing/unboxing from {@literal long -> Long}
* <li>Open hash map with linear probing, no node allocations to store the values
* </ol>
*

View File

@ -34,7 +34,7 @@ import static org.apache.activemq.artemis.utils.Preconditions.checkArgument;
* Provides similar methods as a ConcurrentSet&lt;Long&gt; but since it's an open hash map with linear probing, no node
* allocations are required to store the values.
* <p>
* Items <strong>MUST</strong> be >= 0.
* Items <strong>MUST</strong> be &gt;= 0.
*/
public class ConcurrentLongHashSet {

View File

@ -28,7 +28,7 @@ import java.util.NoSuchElementException;
import java.util.Set;
/**
* A hash set implementation of {@link Set<Long>} that uses open addressing values.
* A hash set implementation of {@literal Set<Long>} that uses open addressing values.
* To minimize the memory footprint, this class uses open addressing rather than chaining.
* Collisions are resolved using linear probing. Deletions implement compaction, so cost of
* remove can approach O(N) for full maps, which makes a small loadFactor recommended.

View File

@ -28,7 +28,7 @@ import java.util.function.Predicate;
* it's a linked list of arrays/chunks of {@code T}.<br>
* Differently from an {@code UnrolledLinkedList} this list doesn't optimize addition and removal to achieve a balanced
* utilization among chunks ie a chunk is removed only if empty and chunks can't be merged.
* This list has been optimized for small-sized chunks (ideally <= 32 elements): this allow search/removal to
* This list has been optimized for small-sized chunks (ideally &lt;= 32 elements): this allow search/removal to
* be performed with a greedy approach despite a sparse chunk utilization (ie chunks contains few sparse elements).<br>
*
* From the memory footprint's point of view, this list won't remove the last remaining array although empty to optimize

View File

@ -52,8 +52,6 @@ public class UpdatableIterator<E> implements ResettableIterator<E>, RepeatableIt
* It is important that on nulling off the changedIterator, we atomically compare and set as the
* changedIterator could be further updated by another thread whilst we are resetting,
* the subsequent update simply would be picked up on the next reset.
*
* @return this (itself).
*/
@Override
public void reset() {

View File

@ -22,7 +22,7 @@ package org.apache.activemq.artemis.utils.critical;
* You update a long every time you enter a critical path
* you update a different long with a System.nanoTime every time you leave that path.
*
* If the enterCritical > leaveCritical at any point, then you need to measure the timeout.
* If the enterCritical &gt; leaveCritical at any point, then you need to measure the timeout.
* if the system stops responding, then you have something irresponsive at the system.
*/
public interface CriticalComponent {

View File

@ -146,7 +146,6 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<configuration>
<useStandardDocletOptions>true</useStandardDocletOptions>
<minmemory>128m</minmemory>

View File

@ -179,7 +179,7 @@ public interface Message {
byte STREAM_TYPE = 6;
/** The message will contain another message persisted through {@link org.apache.activemq.artemis.spi.core.protocol.EmbedMessageUtil}*/
/** The message will contain another message persisted through {@literal org.apache.activemq.artemis.spi.core.protocol.EmbedMessageUtil}*/
byte EMBEDDED_TYPE = 7;
/** This is to embedd Large Messages from other protocol */

View File

@ -211,7 +211,6 @@ public class CoreMessage extends RefCountMessage implements ICoreMessage {
* This will return the proper buffer to represent the data of the Message. If compressed it will decompress.
* If large, it will read from the file or streaming.
* @return
* @throws ActiveMQException
*/
@Override
public ActiveMQBuffer getDataBuffer() {

View File

@ -18,7 +18,7 @@ package org.apache.activemq.artemis.core.server;
/**
* This class essentially mirrors {@code RoutingType} except it has some additional members to support special
* configuration semantics for diverts & bridges. These additional members weren't put in {@code RoutingType}
* configuration semantics for diverts and bridges. These additional members weren't put in {@code RoutingType}
* so as to not confuse users.
*/
public enum ComponentConfigurationRoutingType {

View File

@ -40,7 +40,7 @@ public class JDBCUtils {
}
/**
* Append to {@code errorMessage} a detailed description of the provided {@link SQLException}.<br/>
* Append to {@code errorMessage} a detailed description of the provided {@link SQLException}.<br>
* The information appended are:
* <ul>
* <li>SQL STATEMENTS</li>
@ -61,7 +61,7 @@ public class JDBCUtils {
}
/**
* Append to {@code errorMessage} a detailed description of the provided {@link SQLException}.<br/>
* Append to {@code errorMessage} a detailed description of the provided {@link SQLException}.<br>
* The information appended are:
* <ul>
* <li>SQL EXCEPTIONS details ({@link SQLException#getSQLState},

View File

@ -89,7 +89,6 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<configuration>
<useStandardDocletOptions>true</useStandardDocletOptions>
<minmemory>128m</minmemory>

View File

@ -104,7 +104,6 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<configuration>
<useStandardDocletOptions>true</useStandardDocletOptions>
<minmemory>128m</minmemory>

View File

@ -527,7 +527,6 @@ public final class TimedBuffer extends CriticalComponentImpl {
* Sub classes (tests basically) can use this to override how the sleep is being done
*
* @param sleepNanos
* @throws InterruptedException
*/
protected void sleep(long sleepNanos) {
LockSupport.parkNanos(sleepNanos);

View File

@ -30,7 +30,7 @@ import java.nio.ByteBuffer;
public interface ByteBufferPool {
/**
* It returns a {@link ByteBuffer} with {@link ByteBuffer#capacity()}>={@code size}.<br>
* It returns a {@link ByteBuffer} with {@link ByteBuffer#capacity()} &gt;= {@code size}.<br>
* The {@code buffer} is zeroed until {@code size} if {@code zeroed=true}, with {@link ByteBuffer#position()}=0 and {@link ByteBuffer#limit()}={@code size}.
*/
ByteBuffer borrow(int size, boolean zeroed);

View File

@ -1846,7 +1846,8 @@ public class JournalImpl extends JournalBase implements TestableJournal, Journal
/**
* <p>Load data accordingly to the record layouts</p>
* <p>Basic record layout:</p>
* <table border=1 summary="">
* <table border=1>
* <caption></caption>
* <tr><td><b>Field Name</b></td><td><b>Size</b></td></tr>
* <tr><td>RecordType</td><td>Byte (1)</td></tr>
* <tr><td>FileID</td><td>Integer (4 bytes)</td></tr>
@ -1860,7 +1861,8 @@ public class JournalImpl extends JournalBase implements TestableJournal, Journal
* </table>
* <p> The check-size is used to validate if the record is valid and complete </p>
* <p>Commit/Prepare record layout:</p>
* <table border=1 summary="">
* <table border=1>
* <caption></caption>
* <tr><td><b>Field Name</b></td><td><b>Size</b></td></tr>
* <tr><td>RecordType</td><td>Byte (1)</td></tr>
* <tr><td>FileID</td><td>Integer (4 bytes)</td></tr>

View File

@ -32,10 +32,10 @@ import org.apache.activemq.artemis.api.core.RoutingType;
*
* <pre><code>
* public class SimpleTest {
* @Rule
* &#64;Rule
* public ActiveMQConsumerResource client = new ActiveMQProducerResource( "vm://0", "test.queue" );
*
* @Test
* &#64;Test
* public void testSomething() throws Exception {
* // Use the embedded client here
* ClientMessage message = client.receiveMessage();

View File

@ -32,10 +32,10 @@ import org.apache.activemq.artemis.api.core.client.ServerLocator;
*
* <pre><code>
* public class SimpleTest {
* @Rule
* &#64;Rule
* public ActiveMQDynamicProducerResource producer = new ActiveMQDynamicProducerResource( "vm://0");
*
* @Test
* &#64;Test
* public void testSomething() throws Exception {
* // Use the embedded ClientProducer here
* producer.sendMessage( "test.address", "String Body" );

View File

@ -33,10 +33,10 @@ import org.apache.activemq.artemis.api.core.client.ServerLocator;
*
* <pre><code>
* public class SimpleTest {
* @Rule
* &#64;Rule
* public ActiveMQProducerResource producer = new ActiveMQProducerResource( "vm://0", "test.queue");
*
* @Test
* &#64;Test
* public void testSomething() throws Exception {
* // Use the embedded ClientProducer here
* producer.sendMessage( "String Body" );

View File

@ -55,10 +55,10 @@ import org.slf4j.LoggerFactory;
*
* <pre><code>
* public class SimpleTest {
* @Rule
* &#64;Rule
* public EmbeddedActiveMQResource server = new EmbeddedActiveMQResource();
*
* @Test
* &#64;Test
* public void testSomething() throws Exception {
* // Use the embedded server here
* }

View File

@ -66,10 +66,10 @@ import org.slf4j.LoggerFactory;
*
* <pre><code>
* public class SimpleTest {
* @Rule
* &#64;Rule
* public EmbeddedJMSResource server = new EmbeddedJMSResource();
*
* @Test
* &#64;Test
* public void testSomething() throws Exception {
* // Use the embedded server here
* }

View File

@ -208,7 +208,7 @@ public class AMQPMessageIdHelper {
* the object to be converted
* @return the AMQP messageId style object
*
* @throws IllegalArgument
* @throws ActiveMQAMQPIllegalStateException
* if the provided baseId String indicates an encoded type but can't
* be converted to that type.
*/

View File

@ -288,7 +288,6 @@ public class MQTTConnection implements RemotingConnection {
* Sets the client ID associated with this connection
*
* @param cID
* @return
*/
@Override
public void setClientID(String cID) {

View File

@ -222,7 +222,6 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<configuration>
<useStandardDocletOptions>true</useStandardDocletOptions>
<minmemory>128m</minmemory>

View File

@ -139,7 +139,6 @@ public class LegacyJMSConfiguration implements Deployable {
* Parse the topic node as a TopicConfiguration object
*
* @param node
* @return topic configuration
* @throws Exception
*/
public void parseTopicConfiguration(final Node node) throws Exception {
@ -153,7 +152,6 @@ public class LegacyJMSConfiguration implements Deployable {
* Parse the Queue Configuration node as a QueueConfiguration object
*
* @param node
* @return jms queue configuration
* @throws Exception
*/
public void parseQueueConfiguration(final Node node) throws Exception {

View File

@ -2362,7 +2362,6 @@ public final class FileConfigurationParser extends XMLConfigurationUtil {
/**
* @param e
* @return
*/
protected void parseWildcardConfiguration(final Element e, final Configuration mainConfig) {
WildcardConfiguration conf = mainConfig.getWildcardConfiguration();

View File

@ -55,12 +55,12 @@ public class SimpleAddressManager implements AddressManager {
private final StorageManager storageManager;
/**
* HashMap<Address, Binding>
* {@code HashMap<Address, Binding>}
*/
protected final ConcurrentMap<SimpleString, Bindings> mappings = new ConcurrentHashMap<>();
/**
* HashMap<QueueName, Binding>
* {@code HashMap<QueueName, Binding>}
*/
private final ConcurrentMap<SimpleString, Binding> nameMap = new ConcurrentHashMap<>();

View File

@ -278,7 +278,7 @@ public interface ServerSession extends SecurityAuth {
* This method invokes {@link ActiveMQServer#createQueue(QueueConfiguration)} with a few client-specific additions:
* <p><ul>
* <li>set the routing type based on the prefixes configured on the acceptor used by the client
* <li>strip any prefixes from the address & queue names (if applicable)
* <li>strip any prefixes from the address and queue names (if applicable)
* <li>check authorization based on the client's credentials
* <li>enforce queue creation resource limit
* <li>set up callbacks to clean up temporary queues once the client disconnects

21
pom.xml
View File

@ -882,13 +882,6 @@
</activation>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<additionalparam>-Xdoclint:none</additionalparam>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
@ -916,17 +909,6 @@
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<additionalparam>-Xdoclint:none</additionalparam>
</configuration>
</plugin>
</plugins>
</build>
</profile>
<profile>
<id>java9on</id>
@ -1448,7 +1430,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.10.4</version>
<version>3.0.1</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
@ -1836,7 +1818,6 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.10.4</version>
<configuration>
<minmemory>128m</minmemory>
<maxmemory>1024m</maxmemory>

View File

@ -180,9 +180,9 @@ public class AmqpSession extends AmqpAbstractResource<Session> {
*
* @param address
* the address to which the sender will produce its messages.
* @param senderSettlementMode
* @param senderMode
* controls the settlement mode used by the created Sender
* @param receiverSettlementMode
* @param receiverMode
* controls the desired settlement mode used by the remote Receiver
*
* @return a newly created sender that is ready for use.
@ -200,9 +200,9 @@ public class AmqpSession extends AmqpAbstractResource<Session> {
*
* @param address
* the address to which the sender will produce its messages.
* @param senderSettlementMode
* @param senderMode
* controls the settlement mode used by the created Sender
* @param receiverSettlementMode
* @param receiverMode
* controls the desired settlement mode used by the remote Receiver
* @param outcomes
* specifies the outcomes supported by the sender
@ -387,9 +387,9 @@ public class AmqpSession extends AmqpAbstractResource<Session> {
*
* @param address
* the address to which the receiver will subscribe for its messages.
* @param senderSettlementMode
* @param senderMode
* controls the desired settlement mode used by the remote Sender
* @param receiverSettlementMode
* @param receiverMode
* controls the settlement mode used by the created Receiver
*
* @return a newly created receiver that is ready for use.
@ -491,9 +491,8 @@ public class AmqpSession extends AmqpAbstractResource<Session> {
}
/**
* Create a receiver instance using the given Source
* Create a receiver instance using the given receiverId
*
* @param source the caller created and configured Source used to create the receiver link.
* @return a newly created receiver that is ready for use.
* @throws Exception if an error occurs while creating the receiver.
*/

View File

@ -231,7 +231,7 @@ public class IdGenerator {
/**
* When using the {@link java.net.InetAddress#getHostName()} method in an
* environment where neither a proper DNS lookup nor an <tt>/etc/hosts</tt>
* environment where neither a proper DNS lookup nor an <code>/etc/hosts</code>
* entry exists for a given host, the following exception will be thrown:
* <code>
* java.net.UnknownHostException: &lt;hostname&gt;: &lt;hostname&gt;
@ -241,7 +241,7 @@ public class IdGenerator {
* Instead of just throwing an UnknownHostException and giving up, this
* method grabs a suitable hostname from the exception and prevents the
* exception from being thrown. If a suitable hostname cannot be acquired
* from the exception, only then is the <tt>UnknownHostException</tt> thrown.
* from the exception, only then is the <code>UnknownHostException</code> thrown.
*
* @return The hostname
* @throws UnknownHostException if the given host cannot be looked up.