GUACAMOLE-524: Internally replace Connectable with an ABI-compatible version.
authorMichael Jumper <mjumper@apache.org>
Tue, 22 Jan 2019 20:24:25 +0000 (12:24 -0800)
committerMichael Jumper <mjumper@apache.org>
Tue, 22 Jan 2019 20:29:03 +0000 (12:29 -0800)
Defining an ABI-compatible version of Connectable at the guacamole-ext
level is problematic as concrete implementations of the interface will
suddenly compile despite having no implementation of connect() at all.

We can instead rely on the web application to ensure binary
compatibility, leaving guacamole-ext to define the interface that new
code should use.

guacamole-ext/src/main/java/org/apache/guacamole/net/auth/Connectable.java
guacamole-ext/src/main/java/org/apache/guacamole/net/auth/simple/SimpleConnection.java
guacamole/src/main/java/org/apache/guacamole/net/auth/Connectable.java [new file with mode: 0644]

index c597fe6..407ad7a 100644 (file)
@@ -19,7 +19,6 @@
 
 package org.apache.guacamole.net.auth;
 
-import java.util.Collections;
 import java.util.Map;
 import org.apache.guacamole.GuacamoleException;
 import org.apache.guacamole.net.GuacamoleTunnel;
@@ -30,36 +29,14 @@ import org.apache.guacamole.protocol.GuacamoleClientInformation;
  */
 public interface Connectable {
 
-    /**
-     * Establishes a connection to guacd using the information associated with
-     * this object. The connection will be provided the given client
-     * information.
-     *
-     * @deprecated
-     *     This function has been deprecated in favor of
-     *     {@link #connect(org.apache.guacamole.protocol.GuacamoleClientInformation, java.util.Map)},
-     *     which allows for connection parameter tokens to be injected and
-     *     applied by cooperating extensions, replacing the functionality
-     *     previously provided through the {@link org.apache.guacamole.token.StandardTokens}
-     *     class. It continues to be defined on this interface for
-     *     compatibility. <strong>New implementations should instead implement
-     *     {@link #connect(org.apache.guacamole.protocol.GuacamoleClientInformation, java.util.Map)}.</strong>
-     *
-     * @param info
-     *     Information associated with the connecting client.
-     *
-     * @return
-     *     A fully-established GuacamoleTunnel.
-     *
-     * @throws GuacamoleException
-     *     If an error occurs while connecting to guacd, or if permission to
-     *     connect is denied.
+    /*
+     * IMPORTANT:
+     * ----------
+     * The web application (guacamole) defines its own version of this
+     * interface containing defaults which allow backwards compatibility with
+     * 1.0.0. Any changes to this interface MUST be properly reflected in that
+     * copy of the interface such that they are binary compatible.
      */
-    @Deprecated
-    default GuacamoleTunnel connect(GuacamoleClientInformation info)
-            throws GuacamoleException {
-        return this.connect(info, Collections.emptyMap());
-    }
 
     /**
      * Establishes a connection to guacd using the information associated with
@@ -68,17 +45,6 @@ public interface Connectable {
      * apply the given tokens when configuring the connection, such as with a
      * {@link org.apache.guacamole.token.TokenFilter}.
      *
-     * <p>A default implementation which invokes the old, deprecated
-     * {@link #connect(org.apache.guacamole.protocol.GuacamoleClientInformation)}
-     * is provided solely for compatibility with extensions which implement only
-     * the deprecated function. This default implementation is useful only
-     * for extensions relying on the deprecated function and will be removed
-     * when the deprecated function is removed.
-     *
-     * <p><strong>New implementations should always implement this function
-     * in favor of the deprecated
-     * {@link #connect(org.apache.guacamole.protocol.GuacamoleClientInformation)}.</strong>
-     *
      * @see <a href="http://guacamole.apache.org/doc/gug/configuring-guacamole.html#parameter-tokens">Parameter Tokens</a>
      *
      * @param info
@@ -97,13 +63,8 @@ public interface Connectable {
      *     If an error occurs while connecting to guacd, or if permission to
      *     connect is denied.
      */
-    default GuacamoleTunnel connect(GuacamoleClientInformation info,
-            Map<String, String> tokens) throws GuacamoleException {
-
-        // Allow old implementations of Connectable to continue to work
-        return this.connect(info);
-
-    }
+    public GuacamoleTunnel connect(GuacamoleClientInformation info,
+            Map<String, String> tokens) throws GuacamoleException;
 
     /**
      * Returns the number of active connections associated with this object.
index bf62e8b..26cc7dc 100644 (file)
@@ -196,8 +196,32 @@ public class SimpleConnection extends AbstractConnection {
         // Do nothing - there are no attributes
     }
 
-    @Override
-    @SuppressWarnings("deprecation")
+    /**
+     * Establishes a connection to guacd using the information associated with
+     * this object. The connection will be provided the given client
+     * information.
+     *
+     * <p>This definition is the legacy connect() definition from 1.0.0 and
+     * older. It is redefined here for the sake of ABI compatibility with
+     * 1.0.0 but is no longer defined within the
+     * {@link org.apache.guacamole.net.auth.Connectable} interface.
+     *
+     * @deprecated
+     *     This definition exists solely for binary compatibility. It should
+     *     never be used by new code. New implementations should instead use
+     *     {@link #connect(org.apache.guacamole.protocol.GuacamoleClientInformation, java.util.Map)}.
+     *
+     * @param info
+     *     Information associated with the connecting client.
+     *
+     * @return
+     *     A fully-established GuacamoleTunnel.
+     *
+     * @throws GuacamoleException
+     *     If an error occurs while connecting to guacd, or if permission to
+     *     connect is denied.
+     */
+    @Deprecated
     public GuacamoleTunnel connect(GuacamoleClientInformation info)
             throws GuacamoleException {
 
diff --git a/guacamole/src/main/java/org/apache/guacamole/net/auth/Connectable.java b/guacamole/src/main/java/org/apache/guacamole/net/auth/Connectable.java
new file mode 100644 (file)
index 0000000..849d49a
--- /dev/null
@@ -0,0 +1,109 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.guacamole.net.auth;
+
+import java.util.Collections;
+import java.util.Map;
+import org.apache.guacamole.GuacamoleException;
+import org.apache.guacamole.net.GuacamoleTunnel;
+import org.apache.guacamole.protocol.GuacamoleClientInformation;
+
+/**
+ * Internal, ABI-compatible version of the Connectable interface from
+ * guacamole-ext which defines fallback defaults for older versions of the API.
+ * As this interface will take precedence in the servlet container's
+ * classloader over the definition from guacamole-ext, this allows backwards
+ * compatibility with the 1.0.0 API while keeping the actual API definition
+ * within guacamole-ext strict.
+ *
+ * <p>For this to work, this interface definition <strong>MUST</strong> be 100%
+ * ABI-compatible with the Connectable interface defined by guacamole-ext in
+ * 1.0.0 and onward.
+ */
+public interface Connectable {
+
+    /**
+     * Establishes a connection to guacd using the information associated with
+     * this object. The connection will be provided the given client
+     * information.
+     *
+     * <p>This definition is the legacy connect() definition from 1.0.0 and
+     * older. It is redefined here for the sake of ABI compatibility with
+     * 1.0.0 but is no longer defined within guacamole-ext.
+     *
+     * @deprecated
+     *     This definition exists solely for binary compatibility. It should
+     *     never be used by new code. New implementations should instead use
+     *     the current version of connect() as defined by guacamole-ext.
+     *
+     * @param info
+     *     Information associated with the connecting client.
+     *
+     * @return
+     *     A fully-established GuacamoleTunnel.
+     *
+     * @throws GuacamoleException
+     *     If an error occurs while connecting to guacd, or if permission to
+     *     connect is denied.
+     */
+    @Deprecated
+    default GuacamoleTunnel connect(GuacamoleClientInformation info)
+            throws GuacamoleException {
+
+        // Pass through usages of the old API to the new API
+        return this.connect(info, Collections.emptyMap());
+
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * <p>This definition is the current version of connect() as defined by
+     * guacamole-ext.
+     *
+     * <p>A default implementation which invokes the old, deprecated
+     * {@link #connect(org.apache.guacamole.protocol.GuacamoleClientInformation)}
+     * is provided solely for compatibility with extensions which implement only
+     * the old version of this function. This default implementation is useful
+     * only for extensions relying on the older API and will be removed when
+     * support for that version of the API is removed.
+     *
+     * @see
+     *     The definition of getActiveConnections() in the current version of
+     *     the Connectable interface, as defined by guacamole-ext.
+     */
+    default GuacamoleTunnel connect(GuacamoleClientInformation info,
+            Map<String, String> tokens) throws GuacamoleException {
+
+        // Allow old implementations of Connectable to continue to work
+        return this.connect(info);
+
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @see
+     *     The definition of getActiveConnections() in the current version of
+     *     the Connectable interface, as defined by guacamole-ext.
+     */
+    int getActiveConnections();
+    
+}