From 588b106ada386fd5ffb23fa26afd6623cf581c48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ilkka=20Sepp=C3=A4l=C3=A4?= Date: Sun, 13 Jun 2021 10:50:29 +0300 Subject: [PATCH] Update factory example --- factory/README.md | 82 +++++++++--------- factory/etc/factory.urm.png | Bin 25438 -> 29351 bytes factory/etc/factory.urm.puml | 33 +++---- .../main/java/com/iluwatar/factory/App.java | 13 +-- .../iluwatar/factory/{Car.java => Coin.java} | 4 +- .../{CarsFactory.java => CoinFactory.java} | 8 +- .../factory/{CarType.java => CoinType.java} | 11 ++- .../factory/{Ferrari.java => CopperCoin.java} | 6 +- .../factory/{Ford.java => GoldCoin.java} | 6 +- ...sFactoryTest.java => CoinFactoryTest.java} | 9 +- 10 files changed, 85 insertions(+), 87 deletions(-) rename factory/src/main/java/com/iluwatar/factory/{Car.java => Coin.java} (96%) rename factory/src/main/java/com/iluwatar/factory/{CarsFactory.java => CoinFactory.java} (87%) rename factory/src/main/java/com/iluwatar/factory/{CarType.java => CoinType.java} (89%) rename factory/src/main/java/com/iluwatar/factory/{Ferrari.java => CopperCoin.java} (90%) rename factory/src/main/java/com/iluwatar/factory/{Ford.java => GoldCoin.java} (90%) rename factory/src/test/java/com/iluwatar/factory/{CarsFactoryTest.java => CoinFactoryTest.java} (88%) diff --git a/factory/README.md b/factory/README.md index 147ae546c..dd5582bec 100644 --- a/factory/README.md +++ b/factory/README.md @@ -16,16 +16,17 @@ tags: ## Intent -Providing a static method encapsulated in a class called factory, in order to hide the -implementation logic and makes client code focus on usage rather then initialization new objects. +Providing a static method encapsulated in a class called the factory, to hide the implementation +logic and make client code focus on usage rather than initializing new objects. ## Explanation -Real world example +Real-world example -> Lets say we have a web application connected to SQLServer, but now we want to switch to Oracle. To -> do so without modifying existing source code, we need to implements Simple Factory pattern, in -> which a static method can be invoked to create connection to a given database. +> Imagine an alchemist who is about to manufacture coins. The alchemist must be able to create both +> gold and copper coins and switching between them must be possible without modifying the existing +> source code. The factory pattern makes it possible by providing a static construction method which +> can be called with relevant parameters. Wikipedia says @@ -34,16 +35,16 @@ Wikipedia says **Programmatic Example** -We have an interface `Car` and two implementations `Ford` and `Ferrari`. +We have an interface `Coin` and two implementations `GoldCoin` and `CopperCoin`. ```java -public interface Car { +public interface Coin { String getDescription(); } -public class Ford implements Car { +public class GoldCoin implements Coin { - static final String DESCRIPTION = "This is Ford."; + static final String DESCRIPTION = "This is a gold coin."; @Override public String getDescription() { @@ -51,9 +52,9 @@ public class Ford implements Car { } } -public class Ferrari implements Car { +public class CopperCoin implements Coin { - static final String DESCRIPTION = "This is Ferrari."; + static final String DESCRIPTION = "This is a copper coin."; @Override public String getDescription() { @@ -62,51 +63,48 @@ public class Ferrari implements Car { } ``` -Enumeration above represents types of cars that we support (`Ford` and `Ferrari`). +Enumeration above represents types of coins that we support (`GoldCoin` and `CopperCoin`). ```java -public enum CarType { - - FORD(Ford::new), - FERRARI(Ferrari::new); - - private final Supplier constructor; - - CarType(Supplier constructor) { - this.constructor = constructor; - } - - public Supplier getConstructor() { - return this.constructor; - } +@RequiredArgsConstructor +@Getter +public enum CoinType { + + COPPER(CopperCoin::new), + GOLD(GoldCoin::new); + + private final Supplier constructor; } ``` -Then we have the static method `getCar` to create car objects encapsulated in the factory class -`CarsFactory`. + +Then we have the static method `getCoin` to create coin objects encapsulated in the factory class +`CoinFactory`. ```java -public class CarsFactory { - - public static Car getCar(CarType type) { +public class CoinFactory { + + public static Coin getCoin(CoinType type) { return type.getConstructor().get(); } } ``` -Now on the client code we can create different types of cars using the factory class. +Now on the client code we can create different types of coins using the factory class. ```java -var car1 = CarsFactory.getCar(CarType.FORD); -var car2 = CarsFactory.getCar(CarType.FERRARI); -LOGGER.info(car1.getDescription()); -LOGGER.info(car2.getDescription()); +LOGGER.info("The alchemist begins his work."); +var coin1 = CoinFactory.getCoin(CoinType.COPPER); +var coin2 = CoinFactory.getCoin(CoinType.GOLD); +LOGGER.info(coin1.getDescription()); +LOGGER.info(coin2.getDescription()); ``` Program output: ```java -This is Ford. -This is Ferrari. +The alchemist begins his work. +This is a copper coin. +This is a gold coin. ``` ## Class Diagram @@ -115,7 +113,7 @@ This is Ferrari. ## Applicability -Use the Simple Factory pattern when you only care about the creation of a object, not how to create +Use the factory pattern when you only care about the creation of a object, not how to create and manage it. Pros @@ -127,13 +125,13 @@ Cons * The code becomes more complicated than it should be. -## Real world examples +## Known uses * [java.util.Calendar#getInstance()](https://docs.oracle.com/javase/8/docs/api/java/util/Calendar.html#getInstance--) * [java.util.ResourceBundle#getBundle()](https://docs.oracle.com/javase/8/docs/api/java/util/ResourceBundle.html#getBundle-java.lang.String-) * [java.text.NumberFormat#getInstance()](https://docs.oracle.com/javase/8/docs/api/java/text/NumberFormat.html#getInstance--) * [java.nio.charset.Charset#forName()](https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html#forName-java.lang.String-) -* [java.net.URLStreamHandlerFactory#createURLStreamHandler(String)](https://docs.oracle.com/javase/8/docs/api/java/net/URLStreamHandlerFactory.html) (Returns different singleton objects, depending on a protocol) +* [java.net.URLStreamHandlerFactory#createURLStreamHandler(String)](https://docs.oracle.com/javase/8/docs/api/java/net/URLStreamHandlerFactory.html) (returns different singleton objects, depending on a protocol) * [java.util.EnumSet#of()](https://docs.oracle.com/javase/8/docs/api/java/util/EnumSet.html#of(E)) * [javax.xml.bind.JAXBContext#createMarshaller()](https://docs.oracle.com/javase/8/docs/api/javax/xml/bind/JAXBContext.html#createMarshaller--) and other similar methods. diff --git a/factory/etc/factory.urm.png b/factory/etc/factory.urm.png index 2ba39a571c4efd3d5cfd45854f0d26c843fafd8e..4b3420792e06f2f55e1d49d0fcac29e6fe8c2dd7 100644 GIT binary patch literal 29351 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 diff --git a/factory/etc/factory.urm.puml b/factory/etc/factory.urm.puml index 9eded6328..eb08a4596 100644 --- a/factory/etc/factory.urm.puml +++ b/factory/etc/factory.urm.puml @@ -5,31 +5,32 @@ package com.iluwatar.factory { + App() + main(args : String[]) {static} } - interface Car { + interface Coin { + getDescription() : String {abstract} } - class CarsFactory { - + CarsFactory() - + getCar(type : CarType) : Car {static} + class CoinFactory { + + CoinFactory() + + getCoin(type : CoinType) : Coin {static} } - ~enum CarType { - + FERRARI {static} - + FORD {static} - + valueOf(name : String) : CarType {static} - + values() : CarType[] {static} + enum CoinType { + + COPPER {static} + + GOLD {static} + - constructor : Supplier + + getConstructor() : Supplier + + valueOf(name : String) : CoinType {static} + + values() : CoinType[] {static} } - class Ferrari { + class CopperCoin { ~ DESCRIPTION : String {static} - + Ferrari() + + CopperCoin() + getDescription() : String } - class Ford { + class GoldCoin { ~ DESCRIPTION : String {static} - + Ford() + + GoldCoin() + getDescription() : String } } -CarType ..+ CarsFactory -Ferrari ..|> Car -Ford ..|> Car +CopperCoin ..|> Coin +GoldCoin ..|> Coin @enduml \ No newline at end of file diff --git a/factory/src/main/java/com/iluwatar/factory/App.java b/factory/src/main/java/com/iluwatar/factory/App.java index 732f5458f..6c10fafcb 100644 --- a/factory/src/main/java/com/iluwatar/factory/App.java +++ b/factory/src/main/java/com/iluwatar/factory/App.java @@ -30,8 +30,8 @@ import lombok.extern.slf4j.Slf4j; * create and return objects of varying classes, in order to hide the implementation logic * and makes client code focus on usage rather then objects initialization and management. * - *

In this example the CarFactory is the factory class and it provides a static method to - * create different cars. + *

In this example an alchemist manufactures coins. CoinFactory is the factory class and it + * provides a static method to create different types of coins. */ @Slf4j @@ -41,9 +41,10 @@ public class App { * Program main entry point. */ public static void main(String[] args) { - var car1 = CarsFactory.getCar(CarType.FORD); - var car2 = CarsFactory.getCar(CarType.FERRARI); - LOGGER.info(car1.getDescription()); - LOGGER.info(car2.getDescription()); + LOGGER.info("The alchemist begins his work."); + var coin1 = CoinFactory.getCoin(CoinType.COPPER); + var coin2 = CoinFactory.getCoin(CoinType.GOLD); + LOGGER.info(coin1.getDescription()); + LOGGER.info(coin2.getDescription()); } } diff --git a/factory/src/main/java/com/iluwatar/factory/Car.java b/factory/src/main/java/com/iluwatar/factory/Coin.java similarity index 96% rename from factory/src/main/java/com/iluwatar/factory/Car.java rename to factory/src/main/java/com/iluwatar/factory/Coin.java index e1e248fb4..3b4c1a52a 100644 --- a/factory/src/main/java/com/iluwatar/factory/Car.java +++ b/factory/src/main/java/com/iluwatar/factory/Coin.java @@ -24,9 +24,9 @@ package com.iluwatar.factory; /** - * Car interface. + * Coin interface. */ -public interface Car { +public interface Coin { String getDescription(); diff --git a/factory/src/main/java/com/iluwatar/factory/CarsFactory.java b/factory/src/main/java/com/iluwatar/factory/CoinFactory.java similarity index 87% rename from factory/src/main/java/com/iluwatar/factory/CarsFactory.java rename to factory/src/main/java/com/iluwatar/factory/CoinFactory.java index 941552065..3ff862a23 100644 --- a/factory/src/main/java/com/iluwatar/factory/CarsFactory.java +++ b/factory/src/main/java/com/iluwatar/factory/CoinFactory.java @@ -24,14 +24,14 @@ package com.iluwatar.factory; /** - * Factory of cars. + * Factory of coins. */ -public class CarsFactory { +public class CoinFactory { /** - * Factory method takes as parameter a car type and initiate the appropriate class. + * Factory method takes as a parameter the coin type and calls the appropriate class. */ - public static Car getCar(CarType type) { + public static Coin getCoin(CoinType type) { return type.getConstructor().get(); } } diff --git a/factory/src/main/java/com/iluwatar/factory/CarType.java b/factory/src/main/java/com/iluwatar/factory/CoinType.java similarity index 89% rename from factory/src/main/java/com/iluwatar/factory/CarType.java rename to factory/src/main/java/com/iluwatar/factory/CoinType.java index 074ea32bc..49e0c8166 100644 --- a/factory/src/main/java/com/iluwatar/factory/CarType.java +++ b/factory/src/main/java/com/iluwatar/factory/CoinType.java @@ -28,15 +28,14 @@ import lombok.Getter; import lombok.RequiredArgsConstructor; /** - * Enumeration for different types of cars. + * Enumeration for different types of coins. */ @RequiredArgsConstructor @Getter -public enum CarType { +public enum CoinType { - FORD(Ford::new), - FERRARI(Ferrari::new); - - private final Supplier constructor; + COPPER(CopperCoin::new), + GOLD(GoldCoin::new); + private final Supplier constructor; } diff --git a/factory/src/main/java/com/iluwatar/factory/Ferrari.java b/factory/src/main/java/com/iluwatar/factory/CopperCoin.java similarity index 90% rename from factory/src/main/java/com/iluwatar/factory/Ferrari.java rename to factory/src/main/java/com/iluwatar/factory/CopperCoin.java index c11ee3679..284355360 100644 --- a/factory/src/main/java/com/iluwatar/factory/Ferrari.java +++ b/factory/src/main/java/com/iluwatar/factory/CopperCoin.java @@ -24,11 +24,11 @@ package com.iluwatar.factory; /** - * Ferrari implementation. + * CopperCoin implementation. */ -public class Ferrari implements Car { +public class CopperCoin implements Coin { - static final String DESCRIPTION = "This is Ferrari."; + static final String DESCRIPTION = "This is a copper coin."; @Override public String getDescription() { diff --git a/factory/src/main/java/com/iluwatar/factory/Ford.java b/factory/src/main/java/com/iluwatar/factory/GoldCoin.java similarity index 90% rename from factory/src/main/java/com/iluwatar/factory/Ford.java rename to factory/src/main/java/com/iluwatar/factory/GoldCoin.java index d1091a00b..71eb8debb 100644 --- a/factory/src/main/java/com/iluwatar/factory/Ford.java +++ b/factory/src/main/java/com/iluwatar/factory/GoldCoin.java @@ -24,11 +24,11 @@ package com.iluwatar.factory; /** - * Ford implementation. + * GoldCoin implementation. */ -public class Ford implements Car { +public class GoldCoin implements Coin { - static final String DESCRIPTION = "This is Ford."; + static final String DESCRIPTION = "This is a gold coin."; @Override public String getDescription() { diff --git a/factory/src/test/java/com/iluwatar/factory/CarsFactoryTest.java b/factory/src/test/java/com/iluwatar/factory/CoinFactoryTest.java similarity index 88% rename from factory/src/test/java/com/iluwatar/factory/CarsFactoryTest.java rename to factory/src/test/java/com/iluwatar/factory/CoinFactoryTest.java index c29cbbeb4..fadccff55 100644 --- a/factory/src/test/java/com/iluwatar/factory/CarsFactoryTest.java +++ b/factory/src/test/java/com/iluwatar/factory/CoinFactoryTest.java @@ -27,12 +27,11 @@ import static org.junit.jupiter.api.Assertions.*; import org.junit.jupiter.api.Test; -class CarsFactoryTest { +class CoinFactoryTest { @Test - void shouldReturnFerrariInstance() { - final var ferrari = CarsFactory.getCar(CarType.FERRARI); - assertTrue(ferrari instanceof Ferrari); + void shouldReturnGoldCoinInstance() { + final var goldCoin = CoinFactory.getCoin(CoinType.GOLD); + assertTrue(goldCoin instanceof GoldCoin); } - }