[JENKINS-36871] Fix up javadoc and copyright headers

jenkinsci · Aug 3, 2016 · fc646c3 · fc646c3
1 parent d999b95
commit fc646c3
Show file tree

Hide file tree

Showing 14 changed files with 619 additions and 43 deletions.
diff --git a/src/main/java/org/jenkinsci/remoting/engine/Jnlp3ConnectionState.java b/src/main/java/org/jenkinsci/remoting/engine/Jnlp3ConnectionState.java
@@ -1,35 +1,90 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2016, CloudBees, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 package org.jenkinsci.remoting.engine;
 
 import java.io.IOException;
 import java.net.Socket;
-import java.security.cert.X509Certificate;
 import java.util.List;
-import java.util.Map;
 import javax.annotation.Nonnull;
-import org.jenkinsci.remoting.protocol.impl.ConnectionRefusalException;
 
+/**
+ * Represents the connection state of a {@link JnlpProtocol3Handler} connection.
+ *
+ * @since FIXME
+ */
+@Deprecated
 public class Jnlp3ConnectionState extends LegacyJnlpConnectionState {
 
+    /**
+     * The channel ciphers.
+     */
     private ChannelCiphers channelCiphers;
+    /**
+     * The new cookie.
+     */
     private String newCookie;
 
+    /**
+     * {@inheritDoc}
+     */
     protected Jnlp3ConnectionState(@Nonnull Socket socket,
                                    List<? extends JnlpConnectionStateListener> listeners) throws IOException {
         super(socket, listeners);
     }
 
+    /**
+     * Returns the channel ciphers.
+     *
+     * @return the channel ciphers.
+     */
     public ChannelCiphers getChannelCiphers() {
         return channelCiphers;
     }
 
+    /**
+     * Returns the new cookie for this connection.
+     *
+     * @return the new cookie for this connection.
+     */
     public String getNewCookie() {
         return newCookie;
     }
 
+    /**
+     * Sets the channel ciphers.
+     *
+     * @param channelCiphers the channel ciphers.
+     */
     /*package*/ void setChannelCiphers(ChannelCiphers channelCiphers) {
         this.channelCiphers = channelCiphers;
     }
 
+    /**
+     * Sets the new cookie.
+     *
+     * @param newCookie the new cookie.
+     */
     /*package*/ void setNewCookie(String newCookie) {
         this.newCookie = newCookie;
     }

diff --git a/src/main/java/org/jenkinsci/remoting/engine/Jnlp4ConnectionState.java b/src/main/java/org/jenkinsci/remoting/engine/Jnlp4ConnectionState.java
@@ -1,20 +1,61 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2016, CloudBees, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 package org.jenkinsci.remoting.engine;
 
 import java.net.Socket;
 import java.security.cert.X509Certificate;
 import java.util.List;
+import javax.annotation.CheckForNull;
 import javax.annotation.Nonnull;
 import org.jenkinsci.remoting.protocol.impl.ConnectionRefusalException;
 
+/**
+ * Represents the connection state for a {@link JnlpProtocol4Handler} connection.
+ *
+ * @since FIXME
+ */
 public class Jnlp4ConnectionState extends JnlpConnectionState {
 
+    /**
+     * The client certificate.
+     */
+    @CheckForNull
     private X509Certificate certificate;
 
+    /**
+     * {@inheritDoc}
+     */
     protected Jnlp4ConnectionState(@Nonnull Socket socket,
                                    List<? extends JnlpConnectionStateListener> listeners) {
         super(socket, listeners);
     }
 
+    /**
+     * Gets the client certificate (if available).
+     * @return the client certificate (if available).
+     */
+    @CheckForNull
     public X509Certificate getCertificate() {
         return certificate;
     }
@@ -23,6 +64,7 @@ public X509Certificate getCertificate() {
      * Advances the connection state to indicate that a connection has been "secured" and the property exchange
      * is about to take place.
      *
+     * @param certificate the client certificate.
      * @throws ConnectionRefusalException if the connection has been refused.
      */
     void fireBeforeProperties(X509Certificate certificate) throws ConnectionRefusalException {

diff --git a/src/main/java/org/jenkinsci/remoting/engine/JnlpClientDatabase.java b/src/main/java/org/jenkinsci/remoting/engine/JnlpClientDatabase.java
@@ -1,11 +1,83 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2016, CloudBees, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 package org.jenkinsci.remoting.engine;
 
+import java.security.cert.X509Certificate;
+import javax.annotation.Nonnull;
+
 /**
- * @author Stephen Connolly
+ * Represents a database of clients that are permitted to connect.
+ *
+ * @since FIXME
  */
-public interface JnlpClientDatabase {
+public abstract class JnlpClientDatabase {
+
+    /**
+     * Check if the supplied client name exists.
+     * @param clientName the client name.
+     * @return {@code true} if and only if the named client exists.
+     */
+    public abstract boolean exists(String clientName);
+
+    /**
+     * Gets the secret for the supplied client name.
+     * @param clientName the client name.
+     * @return the secret or {@code null}. Should not return {@code null} if {@link #exists(String)} but this may occur
+     * if there is a race between establishing a connection and the client being removed from the database.
+     */
+    public abstract String getSecretOf(@Nonnull String clientName);
 
-    boolean exists(String clientName);
+    /**
+     * Performs client certificate validation.
+     * @param clientName the client name.
+     * @param certificate the certificate.
+     * @return the validation.
+     */
+    @Nonnull
+    public ValidationResult validateCertificate(@Nonnull String clientName, @Nonnull X509Certificate certificate) {
+        return ValidationResult.UNCHECKED;
+    }
 
-    String getSecretOf(String clientName);
+    /**
+     * The types of certificate validation results.
+     */
+    enum ValidationResult {
+        /**
+         * The certificate is invalid, reject the connection.
+         */
+        INVALID,
+        /**
+         * The certificate was not checked, fall back to secret validation.
+         */
+        UNCHECKED,
+        /**
+         * The certificate is valid, but check the secret also.
+         */
+        REVERIFY_SECRET,
+        /**
+         * The certificate is valid and proven to originate from the named client, skip secret validation.
+         */
+        IDENTITY_PROVED;
+    }
 }
diff --git a/src/main/java/org/jenkinsci/remoting/engine/JnlpConnectionState.java b/src/main/java/org/jenkinsci/remoting/engine/JnlpConnectionState.java
@@ -1,3 +1,26 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2016, CloudBees, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 package org.jenkinsci.remoting.engine;
 
 import hudson.remoting.Channel;
@@ -30,8 +53,17 @@ public class JnlpConnectionState {
     private static final ThreadLocal<Iterator<JnlpConnectionStateListener>> fireIterator
             = new ThreadLocal<Iterator<JnlpConnectionStateListener>>();
 
+    /**
+     * The property name for the secret key.
+     */
     public static final String SECRET_KEY = "Secret-Key";
+    /**
+     * The property name for the client name key.
+     */
     public static final String CLIENT_NAME_KEY = "Node-Name";
+    /**
+     * The proprty name for the cookie name key.
+     */
     public static final String COOKIE_KEY = "Cookie";
 
     /**
@@ -82,6 +114,12 @@ public class JnlpConnectionState {
     @CheckForNull
     private ListenerState stash;
 
+    /**
+     * Constructor.
+     *
+     * @param socket    the {@link Socket}.
+     * @param listeners the {@link JnlpConnectionStateListener} instances.
+     */
     protected JnlpConnectionState(@Nonnull Socket socket, List<? extends JnlpConnectionStateListener> listeners) {
         this.socket = socket;
         this.listeners = new ArrayList<JnlpConnectionStateListener>(listeners);
@@ -161,6 +199,7 @@ public Channel getChannel() {
 
     /**
      * Gets the reason for the channel being closed if available.
+     *
      * @return the reason or {@code null} if termination was normal.
      * @throws IllegalStateException if invoked before
      *                               {@link JnlpConnectionStateListener#channelClosed(JnlpConnectionState)}
@@ -227,14 +266,31 @@ public void reject(ConnectionRefusalException reason) {
         rejection = reason;
     }
 
-    public <S extends ListenerState> S stash() {
+    /**
+     * Retrieves the previously stashed state.
+     * @param clazz the expected class of the stashed state.
+     * @param <S> the expected class of the stashed state.
+     * @return the stashed state.
+     * @throws IllegalStateException if invoked before {@link #approve()}
+     * @see #setStash(ListenerState)
+     */
+    @CheckForNull
+    public <S extends ListenerState> S getStash(Class<S> clazz) {
         if (lifecycle.compareTo(State.APPROVED) < 0) {
             throw new IllegalStateException("The connection has not been approved yet");
         }
-        return (S) stash;
+        return clazz.cast(stash);
     }
 
-    public <S extends ListenerState> void stash(S stash) {
+    /**
+     * Stores some listener specific state for later retrieval.
+     *
+     * @param stash the state to stash.
+     * @param <S>   the expected class of the stashed state.
+     * @throws IllegalStateException if invoked before {@link #approve()}
+     * @see #getStash(Class)
+     */
+    public <S extends ListenerState> void setStash(@CheckForNull S stash) {
         if (lifecycle.compareTo(State.APPROVED) < 0) {
             throw new IllegalStateException("The connection has not been approved yet");
         }
@@ -369,6 +425,7 @@ public void invoke(JnlpConnectionStateListener listener, JnlpConnectionState eve
 
     /**
      * Advances the connection state to indicate that the channel has been closed.
+     *
      * @param cause
      */
     /*package*/ void fireChannelClosed(IOException cause) {
@@ -462,6 +519,12 @@ private enum State {
         DISCONNECTED
     }
 
+    /**
+     * Marker base class for all stashed state data.
+     *
+     * @see JnlpConnectionState#setStash(ListenerState)
+     * @see JnlpConnectionState#getStash(Class)
+     */
     public interface ListenerState {
 
     }