AM-3581 - social login v2 - JSDK effort #1137 - issue 1137 - Social Provider - UserInfoAttributeMapping

Author: rbhojan

api/src/main/java/com/stormpath/sdk/provider/CreateProviderRequestBuilder.java

@@ -15,6 +15,8 @@
  */
 package com.stormpath.sdk.provider;
 
+import com.stormpath.sdk.provider.social.UserInfoMappingRules;
+
 /**
  * A Builder to construct {@link CreateProviderRequest}s.
  *
@@ -41,6 +43,17 @@ public interface CreateProviderRequestBuilder<T extends CreateProviderRequestBui
      */
     T setClientSecret(String clientSecret);
 
+    /**
+     * set rules for mapping fields from userInfo provided by the social provider to Stormpath Account attributes
+     * for Accounts created in the associated Stormpath Directory.
+     *
+     * @param userInfoMappingRules rules for mapping fields from userInfo provided by the social provider to Stormpath
+     *                             Account attributes.
+     * @return the current builder instance for method chaining.
+     * @since 1.3.0
+     */
+    T setUserInfoMappingRules(UserInfoMappingRules userInfoMappingRules);
+
     /**
      * Creates a new {@code CreateProviderRequest} instance based on the current builder state.
      *

api/src/main/java/com/stormpath/sdk/provider/OAuthProvider.java

@@ -15,6 +15,8 @@
  */
 package com.stormpath.sdk.provider;
 
+import com.stormpath.sdk.provider.social.UserInfoMappingRules;
+
 import java.util.List;
 
 /**
@@ -42,4 +44,11 @@ public interface OAuthProvider extends Provider {
      * @since 1.2.0
      */
     List<String> getScope();
+
+    /**
+     * Returns the userInfoMappingRules configured for the oauth provider
+     * @return the userInfoMappingRules configured for the oauth provider
+     * @since 1.3.0
+     */
+    UserInfoMappingRules getUserInfoMappingRules();
 }

api/src/main/java/com/stormpath/sdk/provider/social/SocialUserInfoMappingRules.java

@@ -0,0 +1,48 @@
+/*
+* Copyright 2015 Stormpath, Inc.
+*
+* Licensed 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 com.stormpath.sdk.provider.social;
+
+import com.stormpath.sdk.lang.Classes;
+
+/**
+ * Static utility/helper methods for working with userInfo from Social Provider related resources.
+ * Most methods are <a href="http://en.wikipedia.org/wiki/Factory_method_pattern">factory method</a>s used for
+ * creating {@link UserInfoMappingRule} and {@link UserInfoMappingRules} entities.
+ *
+ * @since 1.3.0
+ */
+public final class SocialUserInfoMappingRules {
+
+    /**
+     * Returns a new {@link UserInfoMappingRuleBuilder} instance, used to construct {@link UserInfoMappingRule} objects,
+     * to be added to the {@link UserInfoMappingRules#getItems() getItems()} collection of {@link UserInfoMappingRules} class.
+     *
+     * @return a new {@link UserInfoMappingRuleBuilder} instance, used to construct {@link UserInfoMappingRule} objects.
+     */
+    public static UserInfoMappingRuleBuilder ruleBuilder() {
+        return (UserInfoMappingRuleBuilder) Classes.newInstance("com.stormpath.sdk.impl.provider.social.DefaultUserInfoMappingRuleBuilder");
+    }
+
+    /**
+     * Returns a new {@link UserInfoMappingRulesBuilder} instance, used to construct {@link UserInfoMappingRules},
+     * to be added to the {@link com.stormpath.sdk.provider.OAuthProvider} entity, for example, when creating a new Social Directory.
+     *
+     * @return a new {@link UserInfoMappingRulesBuilder} instance, used to construct {@link UserInfoMappingRules}.
+     */
+    public static UserInfoMappingRulesBuilder rulesBuilder() {
+        return (UserInfoMappingRulesBuilder) Classes.newInstance("com.stormpath.sdk.impl.provider.social.DefaultUserInfoMappingRulesBuilder");
+    }
+}

api/src/main/java/com/stormpath/sdk/provider/social/UserInfoMappingRuleBuilder.java

@@ -0,0 +1,71 @@
+/*
+* Copyright 2015 Stormpath, Inc.
+*
+* Licensed 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 com.stormpath.sdk.provider.social;
+
+import java.util.Set;
+
+/**
+ * A Builder to construct {@link UserInfoMappingRule} resources.
+ * Usage Example:
+ *
+ *  UserInfoMappingRule rule = SocialUserInfoMappingRule.ruleBuilder()
+ *      .setName("name")
+ *      .setAccountAttributes("field1", "field2")
+ *      .build();
+ *
+ * @see UserInfoMappingRule
+ *
+ * @since 1.3.0
+ */
+public interface UserInfoMappingRuleBuilder {
+
+    /**
+     * Sets the SAML Attribute name, that when encountered, should have its value applied as Account field values.
+     * When this name is encountered when processing a SAML Attribute Statement, its associated value will be set as the
+     * value for all Stormpath Account field names specified in the
+     * {@link UserInfoMappingRule#getAccountAttributes() accountAttributes} collection.
+     *
+     * @param name the SAML Attribute name that when encountered, should have its value applied as Account field values.
+     */
+    UserInfoMappingRuleBuilder setName(String name);
+
+    /**
+     * Sets the Stormpath account fields that should be updated when encountering {@link UserInfoMappingRule#getName() named}
+     * field from the userInfo provided by the social provider.  If discovered, that SAML Attribute value will be set on
+     * all of the Stormpath account fields named in this collection.
+     *
+     * @param accountAttributes the account fields that should be updated when there's a match with a field name in userInfo
+     * provided by the social provider.
+     */
+    UserInfoMappingRuleBuilder setAccountAttributes(String... accountAttributes);
+
+    /**
+     * Sets the Stormpath account fields that should be updated when encountering {@link UserInfoMappingRule#getName() named}
+     * field from the userInfo provided by the social provider.  If discovered, that SAML Attribute value will be set on
+     * all of the Stormpath account fields named in this collection.
+     *
+     * @param accountAttributes the account fields that should be updated when there's a match with a field name in userInfo
+     * provided by the social provider.
+     */
+    UserInfoMappingRuleBuilder setAccountAttributes(Set<String> accountAttributes);
+
+    /**
+     * Builds a new {@link UserInfoMappingRule} based on the current state of this builder.
+     *
+     * @return a new {@link UserInfoMappingRule} to be included in the {@link UserInfoMappingRules} for a Social Provider.
+     */
+    UserInfoMappingRule build();
+}

api/src/main/java/com/stormpath/sdk/provider/social/UserInfoMappingRules.java

@@ -1,37 +1,32 @@
 package com.stormpath.sdk.provider.social;
 
 
+import com.stormpath.sdk.resource.Auditable;
 import com.stormpath.sdk.resource.Resource;
+import com.stormpath.sdk.resource.Saveable;
 
-import java.util.Set;
+import java.util.List;
 
-public interface UserInfoMappingRules extends Resource, Set<UserInfoMappingRule> {
-
-    /**
-     * Removes the {@link UserInfoMappingRule}(s) identified by {@code ruleNames}.
-     *
-     * @param ruleNames the name of the {@link UserInfoMappingRule}(s) to remove.
-     *
-     * @return  the {@code Set<AttributeStatementMappingRule>} after the "remove" operation is performed.
-     */
-    Set<UserInfoMappingRule> removeByName(String... ruleNames);
+public interface UserInfoMappingRules extends Resource, Saveable, Auditable {
 
     /**
      * Specifies the Set of all {@link UserInfoMappingRule}s that indicate how SAML Attribute Statements should
      * populate one or more Stormpath Account field values after a successful SAML login.
      *
-     * @param attributeStatementMappingRules the set of {@link UserInfoMappingRule AttributeStatementMappingRule}s to build a SAML provider.
+     * @param userInfoMappingRules the set of {@link UserInfoMappingRule userInfoMappingRules}s to build a Social provider.
      *
      * @return this instance for method chaining.
+     * @since 1.3.0
      */
-    void setItems(Set<UserInfoMappingRule> attributeStatementMappingRules);
+    void setItems(List<UserInfoMappingRule> userInfoMappingRules);
 
     /**
      * Returns the Set of all {@link UserInfoMappingRule}s that indicate how SAML Attribute Statements should
      * populate one or more Stormpath Account field values after a successful SAML login.
      *
      * @return the Set of all {@link UserInfoMappingRule}s that indicate how SAML Attribute Statements should
      * populate one or more Stormpath Account field values after a successful SAML login.
+     * @since 1.3.0
      */
-    Set<UserInfoMappingRule> getItems();
+    List<UserInfoMappingRule> getItems();
 }

api/src/main/java/com/stormpath/sdk/provider/social/UserInfoMappingRulesBuilder.java

@@ -0,0 +1,50 @@
+/*
+* Copyright 2015 Stormpath, Inc.
+*
+* Licensed 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 com.stormpath.sdk.provider.social;
+
+/**
+ * A Builder to construct {@link UserInfoMappingRulesBuilder} resources.
+ * Use example:
+ *
+ *  UserInfoMappingRulesBuilder userInfoMappingRulesBuilder = UserInfoMappingRulesBuilder.rulesBuilder()
+ *      .addUserInfoMappingRule(userInfoMappingRule1)
+ *      .addUserInfoMappingRule(userInfoMappingRule2)
+ *      ...
+ *      .build();
+ *
+ * @see UserInfoMappingRulesBuilder
+
+ * @since 1.3.0
+ */
+public interface UserInfoMappingRulesBuilder {
+    /**
+     * Adds a new {@link UserInfoMappingRule UserInfoMappingRule} to the set of {@link UserInfoMappingRule UserInfoMappingRule}s,
+     * indicating how a fields from the userInfo provided by the social provider should populate one or more Stormpath Account
+     * field values after a successful Social login.
+     *
+     * @param userInfoMappingRule the {@link UserInfoMappingRule UserInfoMappingRule} to add to the {@link UserInfoMappingRules UserInfoMappingRules} object.
+     *
+     * @return this instance for method chaining.
+     */
+    UserInfoMappingRulesBuilder addUserInfoMappingRule(UserInfoMappingRule userInfoMappingRule);
+
+    /**
+     * Builds a new {@link UserInfoMappingRules UserInfoMappingRules} instance based on the state of this builder.
+     *
+     * @return a new {@link UserInfoMappingRules UserInfoMappingRules} instance.
+     */
+    UserInfoMappingRules build();
+}