Merge pull request #367 from mikulucky/master

Feature Toogle PR

feature-toggle/etc/feature-toggle.ucls

@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<class-diagram version="1.1.9" icons="true" automaticImage="PNG" always-add-relationships="true" generalizations="true" 
+  realizations="true" associations="true" dependencies="true" nesting-relationships="true" router="FAN">  
+  <interface id="1" language="java" name="com.iluwatar.featuretoggle.pattern.Service" project="feature-toggle" 
+    file="/feature-toggle/src/main/java/com/iluwatar/featuretoggle/pattern/Service.java" binary="false" 
+    corner="BOTTOM_RIGHT">    
+    <position height="-1" width="-1" x="238" y="187"/>    
+    <display autosize="true" stereotype="true" package="true" initial-value="true" signature="true" 
+      sort-features="false" accessors="true" visibility="true">      
+      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
+      <operations public="true" package="true" protected="true" private="true" static="true"/>    
+    </display>  
+  </interface>  
+  <class id="2" language="java" 
+    name="com.iluwatar.featuretoggle.pattern.propertiesversion.PropertiesFeatureToggleVersion" project="feature-toggle" 
+    file="/feature-toggle/src/main/java/com/iluwatar/featuretoggle/pattern/propertiesversion/PropertiesFeatureToggleVersion.java" 
+    binary="false" corner="BOTTOM_RIGHT">    
+    <position height="-1" width="-1" x="241" y="449"/>    
+    <display autosize="true" stereotype="true" package="true" initial-value="true" signature="true" 
+      sort-features="false" accessors="true" visibility="true">      
+      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
+      <operations public="true" package="true" protected="true" private="true" static="true"/>    
+    </display>  
+  </class>  
+  <class id="3" language="java" name="com.iluwatar.featuretoggle.pattern.tieredversion.TieredFeatureToggleVersion" 
+    project="feature-toggle" 
+    file="/feature-toggle/src/main/java/com/iluwatar/featuretoggle/pattern/tieredversion/TieredFeatureToggleVersion.java" 
+    binary="false" corner="BOTTOM_RIGHT">    
+    <position height="149" width="230" x="502" y="119"/>    
+    <display autosize="false" stereotype="true" package="true" initial-value="true" signature="true" 
+      sort-features="false" accessors="true" visibility="true">      
+      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
+      <operations public="true" package="true" protected="true" private="true" static="true"/>    
+    </display>  
+  </class>  
+  <class id="4" language="java" name="com.iluwatar.featuretoggle.user.User" project="feature-toggle" 
+    file="/feature-toggle/src/main/java/com/iluwatar/featuretoggle/user/User.java" binary="false" corner="BOTTOM_RIGHT">    
+    <position height="-1" width="-1" x="616" y="453"/>    
+    <display autosize="true" stereotype="true" package="true" initial-value="true" signature="true" 
+      sort-features="false" accessors="true" visibility="true">      
+      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
+      <operations public="true" package="true" protected="true" private="true" static="true"/>    
+    </display>  
+  </class>  
+  <class id="5" language="java" name="com.iluwatar.featuretoggle.user.UserGroup" project="feature-toggle" 
+    file="/feature-toggle/src/main/java/com/iluwatar/featuretoggle/user/UserGroup.java" binary="false" 
+    corner="BOTTOM_RIGHT">    
+    <position height="-1" width="-1" x="956" y="187"/>    
+    <display autosize="true" stereotype="true" package="true" initial-value="true" signature="true" 
+      sort-features="false" accessors="true" visibility="true">      
+      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
+      <operations public="true" package="true" protected="true" private="true" static="true"/>    
+    </display>  
+  </class>  
+  <dependency id="6">    
+    <end type="SOURCE" refId="1"/>    
+    <end type="TARGET" refId="4"/>  
+  </dependency>  
+  <dependency id="7">    
+    <end type="SOURCE" refId="3"/>    
+    <end type="TARGET" refId="5"/>  
+  </dependency>  
+  <association id="8">    
+    <bendpoint x="911" y="415"/>    
+    <end type="SOURCE" refId="5" navigable="false">      
+      <attribute id="9" name="freeGroup">        
+        <position height="19" width="63" x="846" y="368"/>      
+      </attribute>      
+      <multiplicity id="10" minimum="0" maximum="2147483647">        
+        <position height="17" width="23" x="707" y="418"/>      
+      </multiplicity>    
+    </end>    
+    <end type="TARGET" refId="4" navigable="true"/>    
+    <display labels="true" multiplicity="true"/>  
+  </association>  
+  <realization id="11">    
+    <end type="SOURCE" refId="2"/>    
+    <end type="TARGET" refId="1"/>  
+  </realization>  
+  <dependency id="12">    
+    <end type="SOURCE" refId="2"/>    
+    <end type="TARGET" refId="4"/>  
+  </dependency>  
+  <dependency id="13">    
+    <end type="SOURCE" refId="3"/>    
+    <end type="TARGET" refId="4"/>  
+  </dependency>  
+  <association id="14">    
+    <bendpoint x="953" y="459"/>    
+    <end type="SOURCE" refId="5" navigable="false">      
+      <attribute id="15" name="paidGroup">        
+        <position height="19" width="66" x="963" y="419"/>      
+      </attribute>      
+      <multiplicity id="16" minimum="0" maximum="2147483647">        
+        <position height="17" width="23" x="711" y="463"/>      
+      </multiplicity>    
+    </end>    
+    <end type="TARGET" refId="4" navigable="true"/>    
+    <display labels="true" multiplicity="true"/>  
+  </association>  
+  <realization id="17">    
+    <end type="SOURCE" refId="3"/>    
+    <end type="TARGET" refId="1"/>  
+  </realization>  
+  <classifier-display autosize="true" stereotype="true" package="true" initial-value="true" signature="true" 
+    sort-features="false" accessors="true" visibility="true">    
+    <attributes public="true" package="true" protected="true" private="true" static="true"/>    
+    <operations public="true" package="true" protected="true" private="true" static="true"/>  
+  </classifier-display>  
+  <association-display labels="true" multiplicity="true"/>
+</class-diagram>

feature-toggle/index.md

@@ -0,0 +1,32 @@
+---
+layout: pattern
+title: Feature Toggle
+folder: feature-toggle
+permalink: /patterns/feature-toggle/
+categories: Behavioral
+tags:
+ - Java
+ - Difficulty-Beginner
+---
+
+## Also known as
+Feature Flag
+
+## Intent
+Used to switch code execution paths based on properties or groupings. Allowing new features to be released, tested
+and rolled out. Allowing switching back to the older feature quickly if needed. It should be noted that this pattern,
+can easily introduce code complexity. There is also cause for concern that the old feature that the toggle is eventually
+going to phase out is never removed, causing redundant code smells and increased maintainability.
+
+![alt text](./etc/feature-toggle.png "Feature Toggle")
+
+## Applicability
+Use the Feature Toogle pattern when
+
+* Giving different features to different users.
+* Rolling out a new feature incrementally.
+* Switching between development and production environments.
+
+## Credits
+
+* [Martin Fowler 29 October 2010 (2010-10-29).](http://martinfowler.com/bliki/FeatureToggle.html)

feature-toggle/pom.xml

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    The MIT License
+    Copyright (c) 2014 Ilkka Seppälä
+
+    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.
+
+-->
+
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xmlns="http://maven.apache.org/POM/4.0.0"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <artifactId>java-design-patterns</artifactId>
+        <groupId>com.iluwatar</groupId>
+        <version>1.10.0-SNAPSHOT</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>feature-toggle</artifactId>
+
+
+    <dependencies>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <scope>test</scope>
+        </dependency>
+
+    </dependencies>
+</project>

feature-toggle/src/main/java/com/iluwatar/featuretoggle/App.java

@@ -0,0 +1,96 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014 Ilkka Seppälä
+ * <p>
+ * 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:
+ * <p>
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * <p>
+ * 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 com.iluwatar.featuretoggle;
+
+import com.iluwatar.featuretoggle.pattern.Service;
+import com.iluwatar.featuretoggle.pattern.propertiesversion.PropertiesFeatureToggleVersion;
+import com.iluwatar.featuretoggle.user.User;
+import com.iluwatar.featuretoggle.user.UserGroup;
+
+import java.util.Properties;
+
+/**
+ * The Feature Toggle pattern allows for complete code executions to be turned on or off with ease. This allows features
+ * to be controlled by either dynamic methods just as {@link User} information or by {@link Properties}. In the App
+ * below there are two examples. Firstly the {@link Properties} version of the feature toggle, where the enhanced
+ * version of the welcome message which is personalised is turned either on or off at instance creation. This method
+ * is not as dynamic as the {@link User} driven version where the feature of the personalised welcome message is
+ * dependant on the {@link UserGroup} the {@link User} is in. So if the user is a memeber of the
+ * {@link UserGroup#isPaid(User)} then they get an ehanced version of the welcome message.
+ *
+ * Note that this pattern can easily introduce code complexity, and if not kept in check can result in redundant
+ * unmaintained code within the codebase.
+ *
+ */
+public class App {
+
+  /**
+   *  Block 1 shows the {@link PropertiesFeatureToggleVersion} being run with {@link Properties} setting the feature
+   *  toggle to enabled.
+   *
+   *  Block 2 shows the {@link PropertiesFeatureToggleVersion} being run with {@link Properties} setting the feature
+   *  toggle to disabled. Notice the difference with the printed welcome message the username is not included.
+   *
+   *  Block 3 shows the {@link com.iluwatar.featuretoggle.pattern.tieredversion.TieredFeatureToggleVersion} being
+   *  set up with two users on who is on the free level, while the other is on the paid level. When the
+   *  {@link Service#getWelcomeMessage(User)} is called with the paid {@link User} note that the welcome message
+   *  contains their username, while the same service call with the free tier user is more generic. No username is
+   *  printed.
+   *
+   *  @see User
+   *  @see UserGroup
+   *  @see Service
+   *  @see PropertiesFeatureToggleVersion
+   *  @see com.iluwatar.featuretoggle.pattern.tieredversion.TieredFeatureToggleVersion;
+   */
+  public static void main(String[] args) {
+
+    final Properties properties = new Properties();
+    properties.put("enhancedWelcome", true);
+    Service service = new PropertiesFeatureToggleVersion(properties);
+    final String welcomeMessage = service.getWelcomeMessage(new User("Jamie No Code"));
+    System.out.println(welcomeMessage);
+
+    // ---------------------------------------------
+
+    final Properties turnedOff = new Properties();
+    turnedOff.put("enhancedWelcome", false);
+    Service turnedOffService = new PropertiesFeatureToggleVersion(turnedOff);
+    final String welcomeMessageturnedOff = turnedOffService.getWelcomeMessage(new User("Jamie No Code"));
+    System.out.println(welcomeMessageturnedOff);
+
+    // --------------------------------------------
+
+    final User paidUser = new User("Jamie Coder");
+    final User freeUser = new User("Alan Defect");
+
+    UserGroup.addUserToPaidGroup(paidUser);
+    UserGroup.addUserToFreeGroup(freeUser);
+
+    final String welcomeMessagePaidUser = service.getWelcomeMessage(paidUser);
+    final String welcomeMessageFreeUser = service.getWelcomeMessage(freeUser);
+    System.out.println(welcomeMessageFreeUser);
+    System.out.println(welcomeMessagePaidUser);
+  }
+}

feature-toggle/src/main/java/com/iluwatar/featuretoggle/pattern/Service.java

@@ -0,0 +1,54 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014 Ilkka Seppälä
+ * <p>
+ * 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:
+ * <p>
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * <p>
+ * 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 com.iluwatar.featuretoggle.pattern;
+
+import com.iluwatar.featuretoggle.user.User;
+
+/**
+ * Simple interfaces to allow the calling of the method to generate the welcome message for a given user. While there is
+ * a helper method to gather the the status of the feature toggle. In some cases there is no need for the
+ * {@link Service#isEnhanced()} in {@link com.iluwatar.featuretoggle.pattern.tieredversion.TieredFeatureToggleVersion}
+ * where the toggle is determined by the actual {@link User}.
+ *
+ * @see com.iluwatar.featuretoggle.pattern.propertiesversion.PropertiesFeatureToggleVersion
+ * @see com.iluwatar.featuretoggle.pattern.tieredversion.TieredFeatureToggleVersion
+ * @see User
+ */
+public interface Service {
+
+  /**
+   * Generates a welcome message for the passed user.
+   *
+   * @param user the {@link User} to be used if the message is to be personalised.
+   * @return Generated {@link String} welcome message
+   */
+  String getWelcomeMessage(User user);
+
+  /**
+   * Returns if the welcome message to be displayed will be the enhanced version.
+   *
+   * @return Boolean {@value true} if enhanced.
+   */
+  boolean isEnhanced();
+
+}