GUACAMOLE-5: Define sharing profiles and their relationship to connections.

guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AbstractConnection.java

@@ -19,6 +19,9 @@
 
 package org.apache.guacamole.net.auth;
 
+import java.util.Collections;
+import java.util.Set;
+import org.apache.guacamole.GuacamoleException;
 import org.apache.guacamole.protocol.GuacamoleConfiguration;
 
 /**
@@ -76,4 +79,10 @@ public abstract class AbstractConnection extends AbstractIdentifiable
         this.configuration = configuration;
     }
 
+    @Override
+    public Set<String> getSharingProfileIdentifiers()
+            throws GuacamoleException {
+        return Collections.<String>emptySet();
+    }
+
 }

guacamole-ext/src/main/java/org/apache/guacamole/net/auth/AbstractSharingProfile.java

@@ -0,0 +1,119 @@
+/*
+ * 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.HashMap;
+import java.util.Map;
+
+/**
+ * Base implementation of a sharing profile which can be used to share a
+ * Guacamole connection.
+ *
+ * @author Michael Jumper
+ */
+public abstract class AbstractSharingProfile implements SharingProfile {
+
+    /**
+     * The human-readable name of this sharing profile.
+     */
+    private String name;
+
+    /**
+     * The unique identifier associated with this sharing profile.
+     */
+    private String identifier;
+
+    /**
+     * The identifier of the primary connection that this sharing profile can
+     * be used to share.
+     */
+    private String primaryConnectionIdentifier;
+
+    /**
+     * All connection parameters with this sharing profile.
+     */
+    private final Map<String, String> parameters = new HashMap<String, String>();
+
+    @Override
+    public String getName() {
+        return name;
+    }
+
+    @Override
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    @Override
+    public String getIdentifier() {
+        return identifier;
+    }
+
+    @Override
+    public void setIdentifier(String identifier) {
+        this.identifier = identifier;
+    }
+
+    @Override
+    public String getPrimaryConnectionIdentifier() {
+        return primaryConnectionIdentifier;
+    }
+
+    @Override
+    public void setPrimaryConnectionIdentifier(String primaryConnectionIdentifier) {
+        this.primaryConnectionIdentifier = primaryConnectionIdentifier;
+    }
+
+    @Override
+    public Map<String, String> getParameters() {
+        return parameters;
+    }
+
+    @Override
+    public void setParameters(Map<String, String> parameters) {
+        this.parameters.clear();
+        this.parameters.putAll(parameters);
+    }
+
+    @Override
+    public int hashCode() {
+        if (identifier == null) return 0;
+        return identifier.hashCode();
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+
+        // Not equal if null or not an SharingProfile
+        if (obj == null) return false;
+        if (!(obj instanceof AbstractSharingProfile)) return false;
+
+        // Get identifier
+        String objIdentifier = ((AbstractSharingProfile) obj).identifier;
+
+        // If null, equal only if this identifier is null
+        if (objIdentifier == null) return identifier == null;
+
+        // Otherwise, equal only if strings are identical
+        return objIdentifier.equals(identifier);
+
+    }
+
+}

guacamole-ext/src/main/java/org/apache/guacamole/net/auth/Connection.java

@@ -21,6 +21,7 @@ package org.apache.guacamole.net.auth;
 
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import org.apache.guacamole.GuacamoleException;
 import org.apache.guacamole.protocol.GuacamoleConfiguration;
 
@@ -119,4 +120,21 @@ public interface Connection extends Identifiable, Connectable {
      */
     public List<? extends ConnectionRecord> getHistory() throws GuacamoleException;
 
+    /**
+     * Returns identifiers of all readable sharing profiles that can be used to
+     * join this connection when it is active. The level of access granted to a
+     * joining user is dictated by the connection parameters associated with
+     * the sharing profile, not necessarily the parameters of the primary
+     * connection being joined.
+     *
+     * @return
+     *     A Set of identifiers representing the sharing profiles for this
+     *     connection.
+     *
+     * @throws GuacamoleException
+     *     If an error occurs while fetching the sharing profiles for this
+     *     connection.
+     */
+    public Set<String> getSharingProfileIdentifiers() throws GuacamoleException;
+
 }

guacamole-ext/src/main/java/org/apache/guacamole/net/auth/ConnectionRecord.java

@@ -48,6 +48,32 @@ public interface ConnectionRecord {
      */
     public String getConnectionName();
 
+    /**
+     * Returns the identifier of the sharing profile that was used to access the
+     * connection associated with this connection record. If the connection was
+     * accessed directly (without involving a sharing profile), this will be
+     * null.
+     *
+     * @return
+     *     The identifier of the sharing profile used to access the connection
+     *     associated with this connection record, or null if the connection
+     *     was accessed directly.
+     */
+    public String getSharingProfileIdentifier();
+
+    /**
+     * Returns the name of the sharing profile that was used to access the
+     * connection associated with this connection record. If the connection was
+     * accessed directly (without involving a sharing profile), this will be
+     * null.
+     *
+     * @return
+     *     The name of the sharing profile used to access the connection
+     *     associated with this connection record, or null if the connection
+     *     was accessed directly.
+     */
+    public String getSharingProfileName();
+
     /**
      * Returns the date and time the connection began.
      *

guacamole-ext/src/main/java/org/apache/guacamole/net/auth/SharingProfile.java

@@ -0,0 +1,119 @@
+/*
+ * 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.Map;
+
+/**
+ * Represents the semantics which apply to an existing connection when shared,
+ * along with a human-readable name and unique identifier.
+ *
+ * @author Michael Jumper
+ */
+public interface SharingProfile extends Identifiable {
+
+    /**
+     * Returns the human-readable name assigned to this SharingProfile.
+     *
+     * @return
+     *     The name assigned to this SharingProfile.
+     */
+    public String getName();
+
+    /**
+     * Sets the human-readable name assigned to this SharingProfile.
+     *
+     * @param name
+     *     The name to assign.
+     */
+    public void setName(String name);
+
+    /**
+     * Returns the identifier of the primary connection associated with this
+     * connection. The primary connection is the connection that this sharing
+     * profile can be used to share.
+     *
+     * @return
+     *     The identifier of the primary connection associated with this
+     *     connection.
+     */
+    public String getPrimaryConnectionIdentifier();
+
+    /**
+     * Sets the identifier of the primary connection associated with this
+     * connection. The primary connection is the connection that this sharing
+     * profile can be used to share.
+     *
+     * @param identifier
+     *     The identifier of the primary connection associated with this
+     *     connection.
+     */
+    public void setPrimaryConnectionIdentifier(String identifier);
+
+    /**
+     * Returns a map which contains connection parameter name/value pairs as
+     * key/value pairs. Changes to this map will affect the parameters stored
+     * within this sharing profile. The differences in these parameters compared
+     * to those of the associated primary connection yield different levels of
+     * access to users joining the primary connection via this sharing profile.
+     * Note that because configurations may contain sensitive information, some
+     * data in this map may be omitted or tokenized.
+     *
+     * @return
+     *     A map which contains all connection parameter name/value pairs as
+     *     key/value pairs.
+     */
+    public Map<String, String> getParameters();
+
+    /**
+     * Replaces all current parameters with the parameters defined within the
+     * given map. Key/value pairs within the map represent parameter name/value
+     * pairs. The differences in these parameters compared to those of the
+     * associated primary connection yield different levels of access to users
+     * joining the primary connection via this sharing profile.
+     *
+     * @param parameters
+     *     A map which contains all connection parameter name/value pairs as
+     *     key/value pairs.
+     */
+    public void setParameters(Map<String, String> parameters);
+
+    /**
+     * Returns all attributes associated with this sharing profile. The returned
+     * map may not be modifiable.
+     *
+     * @return
+     *     A map of all attribute identifiers to their corresponding values,
+     *     for all attributes associated with this sharing profile, which may
+     *     not be modifiable.
+     */
+    Map<String, String> getAttributes();
+
+    /**
+     * Sets the given attributes. If an attribute within the map is not
+     * supported, it will simply be dropped. Any attributes not within the
+     * given map will be left untouched.
+     *
+     * @param attributes
+     *     A map of all attribute identifiers to their corresponding values.
+     */
+    void setAttributes(Map<String, String> attributes);
+
+}

guacamole-ext/src/main/java/org/apache/guacamole/net/auth/UserContext.java

@@ -106,6 +106,21 @@ public interface UserContext {
     Directory<ActiveConnection> getActiveConnectionDirectory()
             throws GuacamoleException;
 
+    /**
+     * Retrieves a Directory which can be used to view and manipulate
+     * sharing profiles and their configurations, but only as allowed by the
+     * permissions given to the user.
+     *
+     * @return
+     *     A Directory whose operations are bound by the permissions of the
+     *     user.
+     *
+     * @throws GuacamoleException
+     *     If an error occurs while creating the Directory.
+     */
+    Directory<SharingProfile> getSharingProfileDirectory()
+            throws GuacamoleException;
+
     /**
      * Retrieves all connection records visible to current user. The resulting
      * set of connection records can be further filtered and ordered using the
@@ -165,4 +180,15 @@ public interface UserContext {
      */
     Collection<Form> getConnectionGroupAttributes();
 
+    /**
+     * Retrieves a collection of all attributes applicable to sharing profiles.
+     * This collection will contain only those attributes which the current user
+     * has general permission to view or modify. If there are no such
+     * attributes, this collection will be empty.
+     *
+     * @return
+     *     A collection of all attributes applicable to sharing profile.
+     */
+    Collection<Form> getSharingProfileAttributes();
+
 }

guacamole-ext/src/main/java/org/apache/guacamole/net/auth/simple/SimpleUserContext.java

@@ -32,6 +32,7 @@ import org.apache.guacamole.net.auth.Connection;
 import org.apache.guacamole.net.auth.ConnectionGroup;
 import org.apache.guacamole.net.auth.ConnectionRecordSet;
 import org.apache.guacamole.net.auth.Directory;
+import org.apache.guacamole.net.auth.SharingProfile;
 import org.apache.guacamole.net.auth.User;
 import org.apache.guacamole.net.auth.UserContext;
 import org.apache.guacamole.protocol.GuacamoleConfiguration;
@@ -192,6 +193,12 @@ public class SimpleUserContext implements UserContext {
         return rootGroup;
     }
 
+    @Override
+    public Directory<SharingProfile> getSharingProfileDirectory()
+            throws GuacamoleException {
+        return new SimpleDirectory<SharingProfile>();
+    }
+
     @Override
     public Directory<ActiveConnection> getActiveConnectionDirectory()
             throws GuacamoleException {
@@ -219,4 +226,9 @@ public class SimpleUserContext implements UserContext {
         return Collections.<Form>emptyList();
     }
 
+    @Override
+    public Collection<Form> getSharingProfileAttributes() {
+        return Collections.<Form>emptyList();
+    }
+
 }

guacamole/src/main/java/org/apache/guacamole/rest/connection/APIConnectionWrapper.java

@@ -22,6 +22,7 @@ package org.apache.guacamole.rest.connection;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import org.apache.guacamole.GuacamoleException;
 import org.apache.guacamole.net.GuacamoleTunnel;
 import org.apache.guacamole.net.auth.Connection;
@@ -122,6 +123,11 @@ public class APIConnectionWrapper implements Connection {
         apiConnection.setAttributes(attributes);
     }
 
+    @Override
+    public Set<String> getSharingProfileIdentifiers() {
+        throw new UnsupportedOperationException("Operation not supported.");
+    }
+
     @Override
     public GuacamoleTunnel connect(GuacamoleClientInformation info) throws GuacamoleException {
         throw new UnsupportedOperationException("Operation not supported.");