From c842f88eb74e12a4bb79cb7daee7c93d82744582 Mon Sep 17 00:00:00 2001 From: Joseph McCarthy Date: Mon, 28 Dec 2015 19:23:00 +0000 Subject: [PATCH] Add java documentation #324 --- .../simple/AbstractPrinterController.java | 22 ++++++++++++++++++- .../com/iluwatar/delegation/simple/App.java | 12 ++++++++++ .../iluwatar/delegation/simple/Printer.java | 14 ++++++++++++ .../delegation/simple/PrinterController.java | 8 +++++++ .../simple/printers/CanonPrinter.java | 9 ++++++++ .../simple/printers/EpsonPrinter.java | 9 ++++++++ .../delegation/simple/printers/HPPrinter.java | 9 ++++++++ 7 files changed, 82 insertions(+), 1 deletion(-) diff --git a/delegation/src/main/java/com/iluwatar/delegation/simple/AbstractPrinterController.java b/delegation/src/main/java/com/iluwatar/delegation/simple/AbstractPrinterController.java index 22a126948..679c1a3a6 100644 --- a/delegation/src/main/java/com/iluwatar/delegation/simple/AbstractPrinterController.java +++ b/delegation/src/main/java/com/iluwatar/delegation/simple/AbstractPrinterController.java @@ -1,13 +1,33 @@ package com.iluwatar.delegation.simple; -public abstract class AbstractPrinterController implements Printer{ +/** + * Extra layer of abstraction for the controller to allow the controller in this example {@link PrinterController} to + * be as clean as possible. This just provides the default constructor and a simple getter method. The generic of T allows + * any implementation of {@link Printer} + * + * @param Printer + * @see Printer + * @see PrinterController + */ +public abstract class AbstractPrinterController implements Printer { + private T printer; + /** + * @param printer instance of T {@link Printer} this instance is the delegate + */ public AbstractPrinterController(T printer) { this.printer = printer; } + /** + * Helper method to return the current instance of T {@link Printer} in order for + * the controller to call operations on the {@link Printer} + * + * @return instance of Printer + * @see Printer + */ protected T getPrinter() { return printer; } diff --git a/delegation/src/main/java/com/iluwatar/delegation/simple/App.java b/delegation/src/main/java/com/iluwatar/delegation/simple/App.java index 87ef8cdb4..47cf27e8e 100644 --- a/delegation/src/main/java/com/iluwatar/delegation/simple/App.java +++ b/delegation/src/main/java/com/iluwatar/delegation/simple/App.java @@ -4,10 +4,22 @@ import com.iluwatar.delegation.simple.printers.CanonPrinter; import com.iluwatar.delegation.simple.printers.EpsonPrinter; import com.iluwatar.delegation.simple.printers.HPPrinter; +/** + * In this example the delegates are {@link EpsonPrinter}, {@link HPPrinter} and {@link CanonPrinter} they all implement + * {@link Printer}. The {@link AbstractPrinterController} and through inheritance {@link PrinterController} also implement + * {@link Printer}. However neither provide the functionality of {@link Printer} by printing to the screen, they actually + * call upon the instance of {@link Printer} that they were instantiated with. Therefore delegating the behaviour to + * another class. + */ public class App { public static final String MESSAGE_TO_PRINT = "hello world"; + /** + * Program entry point + * + * @param args command line args + */ public static void main(String[] args) { AbstractPrinterController hpPrinterController = new PrinterController(new HPPrinter()); AbstractPrinterController canonPrinterController = new PrinterController(new CanonPrinter()); diff --git a/delegation/src/main/java/com/iluwatar/delegation/simple/Printer.java b/delegation/src/main/java/com/iluwatar/delegation/simple/Printer.java index 1bc0dd13d..aa3bebfda 100644 --- a/delegation/src/main/java/com/iluwatar/delegation/simple/Printer.java +++ b/delegation/src/main/java/com/iluwatar/delegation/simple/Printer.java @@ -1,6 +1,20 @@ package com.iluwatar.delegation.simple; +/** + * Interface that both the Controller and the Delegate will implement. + * + * @see com.iluwatar.delegation.simple.printers.CanonPrinter + * @see com.iluwatar.delegation.simple.printers.EpsonPrinter + * @see com.iluwatar.delegation.simple.printers.HPPrinter + * @see AbstractPrinterController + */ public interface Printer { + /** + * Method that takes a String to print to the screen. This will be implemented on both the + * controller and the delegate allowing the controller to call the same method on the delegate class. + * + * @param message to be printed to the screen + */ void print(final String message); } diff --git a/delegation/src/main/java/com/iluwatar/delegation/simple/PrinterController.java b/delegation/src/main/java/com/iluwatar/delegation/simple/PrinterController.java index f282be128..98be53a2b 100644 --- a/delegation/src/main/java/com/iluwatar/delegation/simple/PrinterController.java +++ b/delegation/src/main/java/com/iluwatar/delegation/simple/PrinterController.java @@ -6,6 +6,14 @@ public class PrinterController extends AbstractPrinterController { super(printer); } + /** + * This method is implemented from {@link Printer} however instead on providing an + * implementation, it instead calls upon the class passed through the constructor. This is the delegate, + * hence the pattern. Therefore meaning that the caller does not care of the implementing class only the owning + * controller. + * + * @param message to be printed to the screen + */ @Override public void print(String message) { getPrinter().print(message); diff --git a/delegation/src/main/java/com/iluwatar/delegation/simple/printers/CanonPrinter.java b/delegation/src/main/java/com/iluwatar/delegation/simple/printers/CanonPrinter.java index 76afd5309..a55e1984d 100644 --- a/delegation/src/main/java/com/iluwatar/delegation/simple/printers/CanonPrinter.java +++ b/delegation/src/main/java/com/iluwatar/delegation/simple/printers/CanonPrinter.java @@ -2,8 +2,17 @@ package com.iluwatar.delegation.simple.printers; import com.iluwatar.delegation.simple.Printer; +/** + * Specialised Implementation of {@link Printer} for a Canon Printer, in + * this case the message to be printed is appended to "Canon Printer : " + * + * @see Printer + */ public class CanonPrinter implements Printer { + /** + * {@inheritDoc} + */ @Override public void print(String message) { System.out.println("Canon Printer : " + message); diff --git a/delegation/src/main/java/com/iluwatar/delegation/simple/printers/EpsonPrinter.java b/delegation/src/main/java/com/iluwatar/delegation/simple/printers/EpsonPrinter.java index cc371fd68..bc53e2cae 100644 --- a/delegation/src/main/java/com/iluwatar/delegation/simple/printers/EpsonPrinter.java +++ b/delegation/src/main/java/com/iluwatar/delegation/simple/printers/EpsonPrinter.java @@ -2,8 +2,17 @@ package com.iluwatar.delegation.simple.printers; import com.iluwatar.delegation.simple.Printer; +/** + * Specialised Implementation of {@link Printer} for a Epson Printer, in + * this case the message to be printed is appended to "Epson Printer : " + * + * @see Printer + */ public class EpsonPrinter implements Printer{ + /** + * {@inheritDoc} + */ @Override public void print(String message) { System.out.println("Epson Printer : " + message); diff --git a/delegation/src/main/java/com/iluwatar/delegation/simple/printers/HPPrinter.java b/delegation/src/main/java/com/iluwatar/delegation/simple/printers/HPPrinter.java index 7c57ee43b..e801ecdf0 100644 --- a/delegation/src/main/java/com/iluwatar/delegation/simple/printers/HPPrinter.java +++ b/delegation/src/main/java/com/iluwatar/delegation/simple/printers/HPPrinter.java @@ -2,8 +2,17 @@ package com.iluwatar.delegation.simple.printers; import com.iluwatar.delegation.simple.Printer; +/** + * Specialised Implementation of {@link Printer} for a HP Printer, in + * this case the message to be printed is appended to "HP Printer : " + * + * @see Printer + */ public class HPPrinter implements Printer { + /** + * {@inheritDoc} + */ @Override public void print(String message) { System.out.println("HP Printer : " + message);