Revert "docs: add JackieNim as a contributor (iluwatar#1749)"

This reverts commit 1dd2628

Author: wangihzyue

facet/README.md

@@ -0,0 +1,66 @@
+---
+layout: pattern
+title: Facet
+folder: facet
+permalink: /patterns/facet/
+categories: Behavioural
+tags:
+ - Security
+---
+
+## Intent
+
+Use facet pattern to realize security, in order to ensure some privillage only can be granted to some certain users.
+
+## Explanation
+
+Real world example
+
+> Lets say if some client can only be able to read information of an object, then the client should be provided with a read-only facet and for write operation should be forbiddened.
+
+Wikipedia says
+
+> Facets are used as a security pattern in CapabilityOrientedProgramming, in order to satisfy the PrincipleOfLeastAuthority.
+
+**Programmatic Example**
+
+For a facet, use method to create, query the registered class and set the registered class.
+```java
+public abstract class Facet {
+  public static Facet create();
+  public static Class[] query(Facet f, Class[] interfaces);
+  public static Facet narrow(Facet f, Class[] interfaces);
+} 
+```
+For a sentry, use method to connect the facet and context to make request.
+```java
+public interface Sentry {
+  public abstract boolean execute(User user, Class interfaceClass);
+}
+```
+For the context, it abstracts the logic for make access control decisions on behalf of a Facet.
+```java
+public interface Context {
+  public boolean validateInterface(Class interfaceClass);
+}
+```
+After validation, execute the method.
+```java
+public interface SecurityMethods {
+  public static String delegate(User user);
+}
+```
+
+## Class Diagram
+
+![alt text](./etc/facet.urm.png "Facet pattern class diagram")
+
+## Applicability
+
+Use the Facet pattern when you care about the privilege for different user.
+
+* restrict an interface to obtain a smaller interface that provides less authority.
+
+## Real world examples
+
+* [java.sql.Connection](https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html)

facet/etc/facet.urm.png

@@ -0,0 +1,68 @@
+@startuml
+package com.iluwatar.facet {
+  class AccessController {
+    + AccessController()
+    + checkPermission(user : User) : boolean {static}
+  }
+  class Administrator {
+    + Administrator()
+  }
+  class App {
+    - LOGGER : Logger {static}
+    + App()
+    + main(args : String[]) {static}
+  }
+  class Client {
+    + Client()
+  }
+  interface Context {
+    + setUser(User) {abstract}
+    + validateInterface(Class<T>) : boolean {abstract}
+  }
+  class CurrentContext {
+    - user : User
+    + CurrentContext()
+    + setUser(user : User)
+    + validateInterface(interfaceClass : Class<T>) : boolean
+  }
+  class DefaultSentry {
+    - context : Context
+    + DefaultSentry(context : Context)
+    + execute(user : User, interfaceClass : Class<T>) : boolean
+  }
+  class Facet {
+    - classes : Class[]
+    - sentry : Sentry
+    - user : User
+    - Facet()
+    + create(sentry : Sentry, classes : Class[]) : Facet {static}
+    + invokeSecurityMethod(interfaceClass : Class<T>) : String
+    + narrow(facet : Facet, interfaces : Class[]) : Facet {static}
+    + query(facet : Facet) : Class[] {static}
+    + setUser(user : User)
+  }
+  interface SecurityMethods {
+    + delegate(user : User) : String {static}
+  }
+  class SecurityMethodsImplementation {
+    + SecurityMethodsImplementation()
+    + delegate(user : User) : String {static}
+  }
+  interface Sentry {
+    + context : Context {static}
+    + execute(User, Class<T>) : boolean {abstract}
+  }
+  interface User {
+  }
+}
+DefaultSentry -->  "-context" Context
+Facet -->  "-sentry" Sentry
+CurrentContext -->  "-user" User
+Sentry -->  "-context" Context
+Facet -->  "-user" User
+Administrator ..|> User 
+Client ..|> User 
+CurrentContext ..|> Context 
+DefaultSentry ..|> Sentry 
+SecurityMethodsImplementation ..|> SecurityMethods 
+@enduml

facet/etc/facet.urm.puml

@@ -31,7 +31,7 @@
         <artifactId>java-design-patterns</artifactId>
         <version>1.25.0-SNAPSHOT</version>
     </parent>
-    <artifactId>compose-method</artifactId>
+    <artifactId>facet</artifactId>
     <dependencies>
         <dependency>
             <groupId>org.junit.jupiter</groupId>
@@ -49,7 +49,7 @@
                         <configuration>
                             <archive>
                                 <manifest>
-                                    <mainClass>com.iluwatar.compose-method.App</mainClass>
+                                    <mainClass>com.iluwatar.facet.App</mainClass>
                                 </manifest>
                             </archive>
                         </configuration>

compose-method/pom.xml renamed to facet/pom.xml

@@ -0,0 +1,27 @@
+package com.iluwatar.facet;
+
+/**
+ * to control the permission.
+ */
+public class AccessController {
+  private AccessController() {
+    throw new IllegalStateException("utility class");
+  }
+
+  /**
+   * check the permission to use the method.
+   *
+   * @param user the identity of the user.
+   * @return boolean to judge whether can use the method.
+   */
+  public static boolean checkPermission(User user) {
+    if (user == null) {
+      return false;
+    } else if (user instanceof Administrator) {
+      return true;
+    } else if (user instanceof Client) {
+      return false;
+    }
+    return false;
+  }
+}

facet/src/main/java/com/iluwatar/facet/AccessController.java

@@ -0,0 +1,10 @@
+package com.iluwatar.facet;
+
+/**
+ * the administrator.
+ */
+public class Administrator implements User {
+  public Administrator() {
+    //admin information.
+  }
+}

facet/src/main/java/com/iluwatar/facet/Administrator.java

@@ -0,0 +1,36 @@
+package com.iluwatar.facet;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * use client and administrator to check whether it can successfully secure.
+ * for the client, it wants to execute the secured method. Then the facet will ask
+ * the sentry to validate the execution. But because the identity is user,
+ * it requirement is illegal. So the result is null. For admin to execute the
+ * secured method. It will be executed.
+ */
+@Slf4j
+public class App {
+  /**
+   * Program entry point.
+   *
+   * @param args command line args.
+   */
+  public static void main(String[] args) {
+    var clientSentry = new DefaultSentry(new CurrentContext());
+    var clientFacet = Facet.create(clientSentry, new Class[0]);
+    Facet.narrow(clientFacet, new Class[]{SecurityMethods.class});
+    clientFacet.setUser(new Client());
+    var administratorSentry = new DefaultSentry(new CurrentContext());
+    var administratorFacet =
+            Facet.create(administratorSentry, new Class[0]);
+    Facet.narrow(administratorFacet, new Class[]{SecurityMethods.class});
+    administratorFacet.setUser(new Administrator());
+    LOGGER.info("client invoke result: {}",
+            clientFacet.invokeSecurityMethod(SecurityMethods.class));
+    LOGGER.info("administrator invoke result: {}",
+            administratorFacet.invokeSecurityMethod(SecurityMethods.class));
+    LOGGER.info("client classes: {}", Facet.query(clientFacet));
+    LOGGER.info("admin classes: {}", Facet.query(administratorFacet));
+  }
+}

facet/src/main/java/com/iluwatar/facet/App.java

@@ -0,0 +1,10 @@
+package com.iluwatar.facet;
+
+/**
+ * The client.
+ */
+public class Client implements User {
+  public Client() {
+    //client information.
+  }
+}

facet/src/main/java/com/iluwatar/facet/Client.java

@@ -0,0 +1,10 @@
+package com.iluwatar.facet;
+
+/**
+ * A Context abstracts the logic for making access control decisions on behalf of a Facet.
+ */
+public interface Context {
+  public boolean validateInterface(Class<? extends SecurityMethods> interfaceClass);
+
+  public void setUser(User user);
+}

facet/src/main/java/com/iluwatar/facet/Context.java

@@ -0,0 +1,21 @@
+package com.iluwatar.facet;
+
+/**
+ * Current context used to abstract the logic for making access control decisions
+ * on behalf of a Facet.
+ */
+public class CurrentContext implements Context {
+  @Override
+  public boolean validateInterface(Class<? extends SecurityMethods> interfaceClass) {
+    if (interfaceClass.equals(SecurityMethods.class)) {
+      return AccessController.checkPermission(user);
+    }
+    return true;
+  }
+
+  private User user;
+
+  public void setUser(User user) {
+    this.user = user;
+  }
+}

facet/src/main/java/com/iluwatar/facet/CurrentContext.java

@@ -0,0 +1,20 @@
+package com.iluwatar.facet;
+
+/**
+ * The default sentry is to consider the interface and context being
+ * used to make the request and selects one of its comprising objects to handle it.
+ */
+public class DefaultSentry implements Sentry {
+  private final Context context;
+
+  public DefaultSentry(Context context) {
+    this.context = context;
+  }
+
+
+  @Override
+  public boolean execute(User user, Class<? extends SecurityMethods> interfaceClass) {
+    this.context.setUser(user);
+    return this.context.validateInterface(interfaceClass);
+  }
+}

facet/src/main/java/com/iluwatar/facet/DefaultSentry.java

@@ -0,0 +1,54 @@
+package com.iluwatar.facet;
+
+/**
+ * implements a set of interfaces and it is exposed to the user.
+ */
+public class Facet {
+  private final Sentry sentry;
+  private Class<? extends SecurityMethods>[] classes;
+  private User user;
+
+  /**
+   * create a facet.
+   *
+   * @param sentry  set sentry corresponds to such facet.
+   * @param classes set supported interfaces for this facet.
+   * @return created facet.
+   */
+  public static Facet create(Sentry sentry, Class<? extends SecurityMethods>[] classes) {
+    return new Facet(sentry, classes);
+  }
+
+  private Facet(Sentry sentry, Class<? extends SecurityMethods>[] classes) {
+    this.sentry = sentry;
+    this.classes = classes;
+  }
+
+  public static Class<? extends SecurityMethods>[] query(Facet facet) {
+    return facet.classes;
+  }
+
+  public void setUser(User user) {
+    this.user = user;
+  }
+
+  public static Facet narrow(Facet facet, Class<? extends SecurityMethods>[] interfaces) {
+    facet.classes = interfaces.clone();
+    return facet;
+  }
+
+  /**
+   * invoke method.
+   *
+   * @param interfaceClass the interface for the class.
+   * @return the result of this invoke.
+   */
+  public String invokeSecurityMethod(Class<? extends SecurityMethods> interfaceClass) {
+    for (var j = 0; j < this.classes.length; j++) {
+      if (interfaceClass.equals(classes[j]) && this.sentry.execute(this.user, interfaceClass)) {
+        return SecurityMethodsImplementation.delegate(user);
+      }
+    }
+    return null;
+  }
+}

facet/src/main/java/com/iluwatar/facet/Facet.java

@@ -0,0 +1,7 @@
+package com.iluwatar.facet;
+
+/**
+ * the interface for security methods.
+ */
+public interface SecurityMethods {
+}

facet/src/main/java/com/iluwatar/facet/SecurityMethods.java

@@ -0,0 +1,25 @@
+package com.iluwatar.facet;
+
+/**
+ * implementation of the secure method.
+ */
+public class SecurityMethodsImplementation implements SecurityMethods {
+  private SecurityMethodsImplementation() {
+    throw new IllegalStateException("utility class");
+  }
+
+  /**
+   * the method to be secured.
+   *
+   * @param user according to different user to return different result.
+   * @return the execution result of this method.
+   */
+  public static String delegate(User user) {
+    if (user instanceof Client) {
+      return "Client create something.";
+    } else if (user instanceof Administrator) {
+      return "Administrator create something.";
+    }
+    return "";
+  }
+}

facet/src/main/java/com/iluwatar/facet/SecurityMethodsImplementation.java

@@ -0,0 +1,9 @@
+package com.iluwatar.facet;
+
+/**
+ * The sentry interface to consider the interface and context being
+ * used to make the request and select one of its comprising objects to handle it.
+ */
+public interface Sentry {
+  public abstract boolean execute(User user, Class<? extends SecurityMethods> interfaceClass);
+}