oncrpc4j-core: fix various javadoc issues

fix errors reported by maven javadoc plugin
(mvn javadoc:javadoc)

Acked-by: Paul Millar
Target: master

Author: kofemann

oncrpc4j-core/src/main/java/org/dcache/oncrpc4j/portmap/OncRpcEmbeddedPortmap.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009 - 2018 Deutsches Elektronen-Synchroton,
+ * Copyright (c) 2009 - 2019 Deutsches Elektronen-Synchroton,
  * Member of the Helmholtz Association, (DESY), HAMBURG, GERMANY
  *
  * This library is free software; you can redistribute it and/or modify
@@ -40,7 +40,7 @@
 import org.dcache.oncrpc4j.rpc.RpcTransport;
 
 /**
- * An instance of this class will create an embedded rpc portmap
+ * An instance of this class will create an embedded RPC portmap
  * service if OS does not provides one.
  */
 public class OncRpcEmbeddedPortmap {
@@ -50,10 +50,27 @@ public class OncRpcEmbeddedPortmap {
     private static final RpcAuth _auth = new RpcAuthTypeNone();
     private OncRpcSvc optionalEmbeddedServer = null;
 
+    /**
+     * Start a new embedded portmap service when another one is not running.
+     * The embedded portmap is stared only when there was no reply from an existing
+     * portmap service within 2 (two) seconds timeout. To test existing service an
+     * RPC ping request is sent over UDP to well know port {@code 111}.
+     *
+     * @see #OncRpcEmbeddedPortmap(long, TimeUnit)
+     */
     public OncRpcEmbeddedPortmap() {
         this(2, TimeUnit.SECONDS);
     }
 
+    /**
+     * Start a new embedded portmap service when another one is not running.
+     * The embedded portmap is stared only when there was no reply from an existing
+     * portmap service within given timeout. To test existing service an RPC ping
+     * request is sent over UDP to well know port {@code 111}.
+     *
+     * @param timeoutValue the timeout value given in the {@code timeoutUnit}
+     * @param timeoutUnit the unit of the {@code timeoutValue} argument
+     */
     public OncRpcEmbeddedPortmap(long timeoutValue, TimeUnit timeoutUnit) {
 
         // we start embedded portmap only if there no other one is running
@@ -103,7 +120,7 @@ public boolean isEmbeddedPortmapper() {
 	}
     /**
      * Shutdown embedded <tt>portmap</tt> service if running.
-     * @throws IOException
+     * @throws IOException if embedded service failed to shutdown.
      */
     public void shutdown() throws IOException {
         if (optionalEmbeddedServer != null) {

oncrpc4j-core/src/main/java/org/dcache/oncrpc4j/rpc/OncRpcProgram.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009 - 2018 Deutsches Elektronen-Synchroton,
+ * Copyright (c) 2009 - 2019 Deutsches Elektronen-Synchroton,
  * Member of the Helmholtz Association, (DESY), HAMBURG, GERMANY
  *
  * This library is free software; you can redistribute it and/or modify
@@ -56,8 +56,8 @@ public int getVersion() {
 
     /**
      * Construct a new OncRpcProgram for with a given program number and version.
-     * @param number
-     * @param version 
+     * @param number RPC program number.
+     * @param version RPC program version.
      */
     public OncRpcProgram(int number, int version) {
         _number = number;

oncrpc4j-core/src/main/java/org/dcache/oncrpc4j/rpc/OncRpcSvc.java

@@ -201,9 +201,9 @@ public void register(OncRpcProgram prog, RpcDispatchable handler) {
     }
 
     /**
-     * Unregister program.
+     * Unregister given RPC program.
      *
-     * @param prog
+     * @param prog RPC program to unregister.
      */
     public void unregister(OncRpcProgram prog) {
         _log.info("Unregistering program {}", prog);
@@ -212,7 +212,7 @@ public void unregister(OncRpcProgram prog) {
 
     /**
      * Add programs to existing services.
-     * @param services
+     * @param services RPC programs to be served by this service.
      * @deprecated use {@link OncRpcSvcBuilder#withRpcService} instead.
      */
     @Deprecated
@@ -449,9 +449,9 @@ public RpcTransport connect(InetSocketAddress socketAddress, long timeout, TimeU
     }
 
     /**
-     * Returns the address of the endpoint this service is bound to,
+     * Returns the socket address of the endpoint to which this service is bound,
      * or <code>null</code> if it is not bound yet.
-     * @param protocol
+     * @param protocol protocol identifier as specified in {@link IpProtocolType}.
      * @return a {@link InetSocketAddress} representing the local endpoint of
      * this service, or <code>null</code> if it is not bound yet.
      */

oncrpc4j-core/src/main/java/org/dcache/oncrpc4j/rpc/ReplyQueue.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009 - 2018 Deutsches Elektronen-Synchroton,
+ * Copyright (c) 2009 - 2019 Deutsches Elektronen-Synchroton,
  * Member of the Helmholtz Association, (DESY), HAMBURG, GERMANY
  *
  * This library is free software; you can redistribute it and/or modify
@@ -102,7 +102,7 @@ public void handleDisconnect(SocketAddress addr) {
      * Get {@link CompletionHandler} for the provided xid.
      * On completion key will be unregistered.
      *
-     * @param xid of rpc request.
+     * @param xid of RPC request.
      * @return completion handler for given xid or {@code null} if xid is unknown.
      */
     public CompletionHandler<RpcReply, RpcTransport> get(int xid) {

oncrpc4j-core/src/main/java/org/dcache/oncrpc4j/rpc/RpcAuthStat.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009 - 2018 Deutsches Elektronen-Synchroton,
+ * Copyright (c) 2009 - 2019 Deutsches Elektronen-Synchroton,
  * Member of the Helmholtz Association, (DESY), HAMBURG, GERMANY
  *
  * This library is free software; you can redistribute it and/or modify
@@ -76,9 +76,11 @@ private RpcAuthStat() {
 
     /**
      * Get human readable {@link String} representation of error code.
+     * @param status RPC authentication status code.
+     * @return string representing the provided {@code status}
      */
-    public static String toString(int i) {
-        switch (i) {
+    public static String toString(int status) {
+        switch (status) {
             case AUTH_OK:
                 return "OK";
             case AUTH_BADCRED:
@@ -110,6 +112,6 @@ public static String toString(int i) {
             case RPCSEC_GSS_CTXPROBLEM:
                 return "RPCSEC_GSS_CTXPROBLEM";
         }
-        return "Unknow state " + i;
+        return "Unknow state " + status;
     }
 }

oncrpc4j-core/src/main/java/org/dcache/oncrpc4j/rpc/RpcCall.java

@@ -193,10 +193,9 @@ public RpcCall(int xid, int prog, int ver, int proc, RpcAuth cred, Xdr xdr, RpcT
 
     /**
      * Accept message. Have to be called prior processing RPC call.
-     * @throws IOException
-     * @throws OncRpcException
+     * @throws IOException if messages can't be accepted.
      */
-    public void accept() throws IOException, OncRpcException {
+    public void accept() throws IOException {
          _rpcvers = _xdr.xdrDecodeInt();
          if (_rpcvers != RPCVERS) {
             throw new RpcMismatchReply(_rpcvers, 2);
@@ -236,15 +235,16 @@ public RpcAuth getCredential() {
     }
 
     /**
-     * Get RPC {@XdrTransport} used by this call.
-     * @return transport
+     * Get RPC {@link RpcTransport} used by this call.
+     * @return transport used by this RPC call.
      */
     public RpcTransport getTransport() {
         return _transport;
     }
 
     /**
-     * Get xid associated with this rpc message.
+     * Get xid associated with this RPC message.
+     * @return xid RPC message unique identifier.
      */
     public int getXid() {
         return _xid;
@@ -271,8 +271,8 @@ public String toString() {
      * caller (AUTH_ERROR).
      *
      * @see RpcRejectStatus
-     * @param status
-     * @param reason
+     * @param status status why request was rejected.
+     * @param reason {@code status} specific reply object.
      */
     public void reject(int status, XdrAble reason) {
         XdrEncodingStream xdr = _xdr;
@@ -389,8 +389,8 @@ public void failRpcSystem() {
      * @param timeoutValue timeout value. 0 means no timeout
      * @param timeoutUnits units for timeout value
      * @param auth auth to use for the call
-     * @throws OncRpcException
-     * @throws IOException
+     * @throws OncRpcException if RPC error occurs
+     * @throws IOException if I/O error occurs
      * @since 2.4.0
      */
     public void call(int procedure, XdrAble args, CompletionHandler<RpcReply, RpcTransport> callback, long timeoutValue, TimeUnit timeoutUnits, RpcAuth auth)
@@ -431,8 +431,7 @@ public void call(int procedure, XdrAble args, CompletionHandler<RpcReply, RpcTra
      * @param timeoutUnits units for timeout value
      * @param auth auth to use for this call. null for constructor-provided default
      * @return the xid for the call
-     * @throws OncRpcException
-     * @throws IOException
+     * @throws IOException if I/O or RPC error occurs
      */
     private int callInternal(int procedure, XdrAble args, CompletionHandler<RpcReply, RpcTransport> callback,
                              long timeoutValue, TimeUnit timeoutUnits, RpcAuth auth)
@@ -495,8 +494,8 @@ public void failed(Throwable t, InetSocketAddress attachment) {
      * @param type The expected type of the reply
      * @param auth auth to use for the call
      * @return A CompletableFuture representing the result of the operation.
-     * @throws OncRpcException
-     * @throws IOException
+     * @throws OncRpcException if RPC error occurs
+     * @throws IOException if I/O error occurs
      * @since 2.4.0
      */
     public <T extends XdrAble> CompletableFuture<T> call(int procedure, XdrAble args, final Class<T> type, final RpcAuth auth)
@@ -510,9 +509,6 @@ public <T extends XdrAble> CompletableFuture<T> call(int procedure, XdrAble args
         }
     }
 
-    /**
-     */
-
     /**
      * Send asynchronous RPC request to a remove server.
      *
@@ -529,8 +525,8 @@ public <T extends XdrAble> CompletableFuture<T> call(int procedure, XdrAble args
      * @param args The argument of the procedure.
      * @param type The expected type of the reply
      * @return A CompletableFuture representing the result of the operation.
-     * @throws OncRpcException
-     * @throws IOException
+     * @throws OncRpcException if RPC error occurs
+     * @throws IOException if I/O error occurs
      * @since 2.4.0
      */
     public <T extends XdrAble> CompletableFuture<T> call(int procedure, XdrAble args, final Class<T> type)
@@ -547,8 +543,9 @@ public <T extends XdrAble> CompletableFuture<T> call(int procedure, XdrAble args
      * @param timeoutValue timeout value. 0 means no timeout
      * @param timeoutUnits units for timeout value
      * @param auth auth to use for the call
-     * @throws OncRpcException
-     * @throws IOException
+     * @throws OncRpcException if RPC error occurs
+     * @throws IOException if I/O error occurs
+     * @throws TimeoutException if timeout elapses before reply is received.
      */
     public void call(int procedure, XdrAble args, XdrAble result, long timeoutValue, TimeUnit timeoutUnits, RpcAuth auth)
             throws IOException, TimeoutException {
@@ -571,6 +568,8 @@ public void call(int procedure, XdrAble args, XdrAble result, long timeoutValue,
 
     /**
      * convenience version of {@link #call(int, XdrAble, XdrAble, long, TimeUnit, RpcAuth)} with default auth
+     * @throws IOException if I/O or RPC error occurs.
+     * @throws TimeoutException if timeout elapses before reply is received.
      */
     public void call(int procedure, XdrAble args, XdrAble result, long timeoutValue, TimeUnit timeoutUnits)
             throws IOException, TimeoutException {
@@ -579,6 +578,7 @@ public void call(int procedure, XdrAble args, XdrAble result, long timeoutValue,
 
     /**
      * convenience version of {@link #call(int, XdrAble, XdrAble, long, TimeUnit, RpcAuth)} with no timeout
+     * @throws IOException if I/O or RPC error occurs.
      */
     public void call(int procedure, XdrAble args, XdrAble result, RpcAuth auth)
             throws IOException {
@@ -591,6 +591,7 @@ public void call(int procedure, XdrAble args, XdrAble result, RpcAuth auth)
 
     /**
      * convenience version of {@link #call(int, XdrAble, XdrAble, long, TimeUnit, RpcAuth)} with no timeout or auth
+     * @throws IOException if I/O or RPC error occurs.
      */
     public void call(int procedure, XdrAble args, XdrAble result)
             throws IOException {
@@ -689,7 +690,7 @@ private int nextXid() {
 
     /**
      * Register {@link CompletionHandler} to receive notification when message
-     * send is complete. NOTICE: when processing rpc call on the server side
+     * send is complete. NOTICE: when processing RPC call on the server side
      * the @{code registerSendListener} has the same effect as {@link #registerSendOnceListener}
      * as a new instance of {@link RpcCall} is used to process the request.
      * @param listener the message sent listener

oncrpc4j-core/src/main/java/org/dcache/oncrpc4j/rpc/RpcTransport.java

@@ -69,10 +69,10 @@ public interface RpcTransport {
 
     /**
      * Get {@link RpcTransport} for to sent/receive requests in opposite direction.
-     * The returned transport can be used by servers to send rpc calls to clients and
-     * can be used by clients to receive rpc calls from servers.
+     * The returned transport can be used by servers to send RPC calls to clients and
+     * can be used by clients to receive RPC calls from servers.
      *
-     * @return
+     * @return {@code RpcTransport} connected to the remote peer.
      */
     public RpcTransport getPeerTransport();
 

oncrpc4j-core/src/main/java/org/dcache/oncrpc4j/rpc/gss/GssProtocolFilter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009 - 2018 Deutsches Elektronen-Synchroton,
+ * Copyright (c) 2009 - 2019 Deutsches Elektronen-Synchroton,
  * Member of the Helmholtz Association, (DESY), HAMBURG, GERMANY
  *
  * This library is free software; you can redistribute it and/or modify
@@ -47,27 +47,24 @@
  * A {@link Filter} that handles RPCSEC_GSS requests.
  * Filter is responsible to establish and destroy GSS context.
  * For requests with established contexts RPC requests repacked into
- * GSS aware {@link RpsGssCall}.
+ * GSS aware {@link RpcGssCall}.
  *
  * @since 0.0.4
  */
 public class GssProtocolFilter extends BaseFilter {
 
     private final static Logger _log = LoggerFactory.getLogger(GssProtocolFilter.class);
+
     /**
-     * Return value from either accept or init stating that
-     * the context creation phase is complete for this peer.
-     * @see #init
-     * @see #accept
+     * GSS handshake status returned to the client to indicate that the context
+     * creation phase is complete.
      */
     public static final int COMPLETE = 0;
+
     /**
-     * Return value from either accept or init stating that
-     * another token is required from the peer to continue context
-     * creation. This may be returned several times indicating
-     * multiple token exchanges.
-     * @see #init
-     * @see #accept
+     * GSS handshake status returned to the client to indicate that another
+     * token is required to compete context creation. This status code can be
+     * returned several times when multiple token exchanges required.
      */
     public static final int CONTINUE_NEEDED = 1;
 
@@ -162,7 +159,7 @@ public NextAction handleRead(FilterChainContext ctx) throws IOException {
      * According to rfc2203 verifier should contain the checksum of the RPC header
      * up to and including the credential.
      *
-     * @param auth
+     * @param auth RPC request authentication credentials.
      * @param context gss context
      * @throws GSSException if cant validate the checksum
      */

oncrpc4j-core/src/main/java/org/dcache/oncrpc4j/rpc/gss/RpcAuthGss.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009 - 2018 Deutsches Elektronen-Synchroton,
+ * Copyright (c) 2009 - 2019 Deutsches Elektronen-Synchroton,
  * Member of the Helmholtz Association, (DESY), HAMBURG, GERMANY
  *
  * This library is free software; you can redistribute it and/or modify
@@ -117,10 +117,10 @@ public void xdrDecode(XdrDecodingStream xdr) throws OncRpcException, IOException
         /*
          * header size is RPC header + credential.
          *
-         * rpc header is 7 int32: xid type rpcversion prog vers proc auth_flavour
+         * RPC header is 7 int32: xid type rpcversion prog vers proc auth_flavour
          * credential is 1 int32 + it's value : len + opaque
          *
-         * set position to the beginning of rpc message and limit to the end of credential.
+         * set position to the beginning of RPC message and limit to the end of credential.
          */
         _header.limit( _header.position() + len);
         _header.position( _header.position() - 8*4);