diff --git a/prototype/README.md b/prototype/README.md index 472e8330c..9128ccb2c 100644 --- a/prototype/README.md +++ b/prototype/README.md @@ -10,16 +10,19 @@ tags: --- ## Intent -Specify the kinds of objects to create using a prototypical instance, and create new objects by copying this prototype. + +Specify the kinds of objects to create using a prototypical instance, and create new objects by +copying this prototype. ## Explanation -First it should be noted that Prototype pattern is not used to gain performance benefits. It's only used for creating -new objects from prototype instance. +First it should be noted that Prototype pattern is not used to gain performance benefits. It's only +used for creating new objects from prototype instance. Real world example -> Remember Dolly? The sheep that was cloned! Lets not get into the details but the key point here is that it is all about cloning. +> Remember Dolly? The sheep that was cloned! Lets not get into the details but the key point here is +> that it is all about cloning. In plain words @@ -27,9 +30,12 @@ In plain words Wikipedia says -> The prototype pattern is a creational design pattern in software development. It is used when the type of objects to create is determined by a prototypical instance, which is cloned to produce new objects. +> The prototype pattern is a creational design pattern in software development. It is used when the +> type of objects to create is determined by a prototypical instance, which is cloned to produce new +> objects. -In short, it allows you to create a copy of an existing object and modify it to your needs, instead of going through the trouble of creating an object from scratch and setting it up. +In short, it allows you to create a copy of an existing object and modify it to your needs, instead +of going through the trouble of creating an object from scratch and setting it up. **Programmatic Example** @@ -52,7 +58,7 @@ class Sheep implements Cloneable { } ``` -Then it can be cloned like below +Then it can be cloned like below: ```java var original = new Sheep("Jolly"); @@ -65,15 +71,20 @@ System.out.println(cloned.getName()); // Dolly ``` ## Class diagram + ![alt text](./etc/prototype.urm.png "Prototype pattern class diagram") ## Applicability -Use the Prototype pattern when a system should be independent of how its products are created, composed and represented; and -* When the classes to instantiate are specified at run-time, for example, by dynamic loading -* To avoid building a class hierarchy of factories that parallels the class hierarchy of products -* When instances of a class can have one of only a few different combinations of state. It may be more convenient to install a corresponding number of prototypes and clone them rather than instantiating the class manually, each time with the appropriate state -* When object creation is expensive compared to cloning +Use the Prototype pattern when a system should be independent of how its products are created, +composed, represented and + +* When the classes to instantiate are specified at run-time, for example, by dynamic loading. +* To avoid building a class hierarchy of factories that parallels the class hierarchy of products. +* When instances of a class can have one of only a few different combinations of state. It may be +more convenient to install a corresponding number of prototypes and clone them rather than +instantiating the class manually, each time with the appropriate state. +* When object creation is expensive compared to cloning. ## Real world examples diff --git a/proxy/README.md b/proxy/README.md index ddcc4e784..edf223b23 100644 --- a/proxy/README.md +++ b/proxy/README.md @@ -10,16 +10,20 @@ tags: --- ## Also known as + Surrogate ## Intent -Provide a surrogate or placeholder for another object to control -access to it. + +Provide a surrogate or placeholder for another object to control access to it. ## Explanation + Real world example -> Imagine a tower where the local wizards go to study their spells. The ivory tower can only be accessed through a proxy which ensures that only the first three wizards can enter. Here the proxy represents the functionality of the tower and adds access control to it. +> Imagine a tower where the local wizards go to study their spells. The ivory tower can only be +> accessed through a proxy which ensures that only the first three wizards can enter. Here the proxy +> represents the functionality of the tower and adds access control to it. In plain words @@ -27,11 +31,17 @@ In plain words Wikipedia says -> A proxy, in its most general form, is a class functioning as an interface to something else. A proxy is a wrapper or agent object that is being called by the client to access the real serving object behind the scenes. Use of the proxy can simply be forwarding to the real object, or can provide additional logic. In the proxy extra functionality can be provided, for example caching when operations on the real object are resource intensive, or checking preconditions before operations on the real object are invoked. +> A proxy, in its most general form, is a class functioning as an interface to something else. +> A proxy is a wrapper or agent object that is being called by the client to access the real serving +> object behind the scenes. Use of the proxy can simply be forwarding to the real object, or can +> provide additional logic. In the proxy extra functionality can be provided, for example caching +> when operations on the real object are resource intensive, or checking preconditions before +> operations on the real object are invoked. **Programmatic Example** -Taking our wizard tower example from above. Firstly we have the wizard tower interface and the ivory tower class +Taking our wizard tower example from above. Firstly we have the `WizardTower` interface and the +`IvoryTower` class. ```java public interface WizardTower { @@ -50,7 +60,7 @@ public class IvoryTower implements WizardTower { } ``` -Then a simple wizard class +Then a simple `Wizard` class. ```java public class Wizard { @@ -68,7 +78,7 @@ public class Wizard { } ``` -Then we have the proxy to add access control to wizard tower +Then we have the `WizardTowerProxy` to add access control to `WizardTower`. ```java public class WizardTowerProxy implements WizardTower { @@ -97,28 +107,41 @@ public class WizardTowerProxy implements WizardTower { } ``` -And here is tower entering scenario +And here is the tower entering scenario. ```java var proxy = new WizardTowerProxy(new IvoryTower()); -proxy.enter(new Wizard("Red wizard")); // Red wizard enters the tower. -proxy.enter(new Wizard("White wizard")); // White wizard enters the tower. -proxy.enter(new Wizard("Black wizard")); // Black wizard enters the tower. -proxy.enter(new Wizard("Green wizard")); // Green wizard is not allowed to enter! -proxy.enter(new Wizard("Brown wizard")); // Brown wizard is not allowed to enter! +proxy.enter(new Wizard("Red wizard")); +proxy.enter(new Wizard("White wizard")); +proxy.enter(new Wizard("Black wizard")); +proxy.enter(new Wizard("Green wizard")); +proxy.enter(new Wizard("Brown wizard")); +``` + +Program output: + +``` +Red wizard enters the tower. +White wizard enters the tower. +Black wizard enters the tower. +Green wizard is not allowed to enter! +Brown wizard is not allowed to enter! ``` ## Class diagram + ![alt text](./etc/proxy.urm.png "Proxy pattern class diagram") ## Applicability -Proxy is applicable whenever there is a need for a more -versatile or sophisticated reference to an object than a simple pointer. Here -are several common situations in which the Proxy pattern is applicable + +Proxy is applicable whenever there is a need for a more versatile or sophisticated reference to an +object than a simple pointer. Here are several common situations in which the Proxy pattern is +applicable. * Remote proxy provides a local representative for an object in a different address space. * Virtual proxy creates expensive objects on demand. -* Protection proxy controls access to the original object. Protection proxies are useful when objects should have different access rights. +* Protection proxy controls access to the original object. Protection proxies are useful when +objects should have different access rights. ## Typical Use Case @@ -136,7 +159,8 @@ are several common situations in which the Proxy pattern is applicable * [java.lang.reflect.Proxy](http://docs.oracle.com/javase/8/docs/api/java/lang/reflect/Proxy.html) * [Apache Commons Proxy](https://commons.apache.org/proper/commons-proxy/) -* Mocking frameworks Mockito, Powermock, EasyMock +* Mocking frameworks [Mockito](https://site.mockito.org/), +[Powermock](https://powermock.github.io/), [EasyMock](https://easymock.org/) ## Related patterns diff --git a/proxy/src/main/java/com/iluwatar/proxy/IvoryTower.java b/proxy/src/main/java/com/iluwatar/proxy/IvoryTower.java index 658b19949..2523af8b8 100644 --- a/proxy/src/main/java/com/iluwatar/proxy/IvoryTower.java +++ b/proxy/src/main/java/com/iluwatar/proxy/IvoryTower.java @@ -1,40 +1,40 @@ -/* - * The MIT License - * Copyright © 2014-2019 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. - */ - -package com.iluwatar.proxy; - -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; - -/** - * The object to be proxyed. - */ -public class IvoryTower implements WizardTower { - - private static final Logger LOGGER = LoggerFactory.getLogger(IvoryTower.class); - - public void enter(Wizard wizard) { - LOGGER.info("{} enters the tower.", wizard); - } - -} +/* + * The MIT License + * Copyright © 2014-2019 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. + */ + +package com.iluwatar.proxy; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +/** + * The object to be proxied. + */ +public class IvoryTower implements WizardTower { + + private static final Logger LOGGER = LoggerFactory.getLogger(IvoryTower.class); + + public void enter(Wizard wizard) { + LOGGER.info("{} enters the tower.", wizard); + } + +}