From 23e9a418871ddd294d4602e629a67c58b6d747c9 Mon Sep 17 00:00:00 2001 From: Bill Erickson Date: Wed, 23 Apr 2014 16:16:57 -0400 Subject: [PATCH] hatch : API docs Signed-off-by: Bill Erickson --- src/org/evergreen_ils/hatch/FileIO.java | 60 +++++++++++++++++++- src/org/evergreen_ils/hatch/Hatch.java | 41 +++++++++++++- .../evergreen_ils/hatch/HatchWebSocketHandler.java | 64 ++++++++++++++++++++-- .../evergreen_ils/hatch/HatchWebSocketServlet.java | 8 +-- src/org/evergreen_ils/hatch/PrintManager.java | 35 +++++++++++- 5 files changed, 193 insertions(+), 15 deletions(-) diff --git a/src/org/evergreen_ils/hatch/FileIO.java b/src/org/evergreen_ils/hatch/FileIO.java index 5451723..a5556b3 100644 --- a/src/org/evergreen_ils/hatch/FileIO.java +++ b/src/org/evergreen_ils/hatch/FileIO.java @@ -22,13 +22,28 @@ import org.eclipse.jetty.util.log.Logger; public class FileIO { + /** All files are read from and written to this directory */ String basePath; + + // logger private static final Logger logger = Log.getLogger("FileIO"); + /** + * Constructs a new FileIO with the provided base path. + * + * @param directory Directory to use as the base path for all file + * operations. + */ public FileIO(String directory) { basePath = directory; } + /** + * Locates the requested file by name within our configured base path. + * + * @param key The relative file name (key) + * @return The File object if found. + */ protected File getFile(String key) { File dir = new File(basePath); if (!dir.exists()) { @@ -40,6 +55,14 @@ public class FileIO { return new File(dir, key); } + /** + * Sets the content of a file. + * + * @param key The relative file name (key) + * @param text The new file content + * + * @return success or failure + */ public boolean set(String key, String text) { logger.info("set => " + key); File file = getFile(key); @@ -69,6 +92,15 @@ public class FileIO { return true; } + /** + * Appends content to a file. + * + * If the file does not exist, it is first created. + * + * @param key The relative file name (key) + * @param text The content to append to the file + * @return success or failure + */ public boolean append(String key, String text) { logger.info("append => " + key); File file = getFile(key); @@ -97,6 +129,12 @@ public class FileIO { return true; } + /** + * Gets the text contents of a file. + * + * @param key The relative file name (key) + * @return The text content of the file + */ public String get(String key) { logger.info("get => " + key); File file = getFile(key); @@ -121,8 +159,14 @@ public class FileIO { return buf.toString(); } - public boolean delete(String key) { - logger.info("delete => " + key); + /** + * Removes (deletes) a file. + * + * @param The relative file name (key) + * @return success or failure + */ + public boolean remove(String key) { + logger.info("remove => " + key); File file = getFile(key); try { if (file.exists() && !file.delete()) { @@ -138,10 +182,22 @@ public class FileIO { } } + /** + * Returns the full list of stored keys. + * + * @return Array of relative file names + */ public String[] keys() { return keys(null); } + /** + * Returns all keys begining with the specified prefix. + * + * @param prefix The initial substring used to limit the return set + * of keys. + * @return Array of keys + */ public String[] keys(String prefix) { logger.info("keys => " + prefix); File dir = new File(basePath); diff --git a/src/org/evergreen_ils/hatch/Hatch.java b/src/org/evergreen_ils/hatch/Hatch.java index 91e0fc0..898ea53 100644 --- a/src/org/evergreen_ils/hatch/Hatch.java +++ b/src/org/evergreen_ils/hatch/Hatch.java @@ -51,12 +51,38 @@ import java.util.Map; import java.io.FileInputStream; +/** + * Main class for Hatch. + * + * This class operates as a two-headed beast, whose heads will occasionally + * communicate with each other. + * + * It runs a JavaFX thread for printing HTML documents and runs a Jetty + * server thread for handling communication with external clients. + * + * Most of the work performed happens solely in the Jetty server thread. + * Attempts to print, however, are passed into the JavaFX thread so that + * the HTML may be loaded into a WebView for printing, which must happen + * within the JavaFX thread. + * + * Messages are passed from the Jetty thread to the JavaFX thread via a + * blocking thread queue, observed by a separate Service thread, whose + * job is only to pull messages from the queue. + * + */ public class Hatch extends Application { + /** Browser Region for rendering and printing HTML */ private BrowserView browser; + + /** BrowserView requires a stage for rendering */ private Stage primaryStage; + + /** Our logger instance */ static final Logger logger = Log.getLogger("Hatch"); + /** Message queue for passing messages from the Jetty thread into + * the JavaFX Application thread */ private static LinkedBlockingQueue requestQueue = new LinkedBlockingQueue(); @@ -97,6 +123,9 @@ public class Hatch extends Application { } + /** + * JavaFX startup call + */ @Override public void start(Stage primaryStage) { this.primaryStage = primaryStage; @@ -104,6 +133,9 @@ public class Hatch extends Application { startMsgTask(); } + /** + * Queues a message for processing by the queue processing thread. + */ public static void enqueueMessage(Map params) { logger.debug("queueing print message"); requestQueue.offer(params); @@ -137,8 +169,7 @@ public class Hatch extends Application { /** * Fire off the Service task, which checks for queued messages. * - * When a queued message is found, it's analyzed and passed off - * to the correct message handler + * When a queued message is found, it's sent off for printing. */ public void startMsgTask() { @@ -163,6 +194,12 @@ public class Hatch extends Application { service.start(); } + /** + * Hatch main. + * + * Reads the Jetty configuration, starts the Jetty server thread, + * then launches the JavaFX Application thread. + */ public static void main(String[] args) throws Exception { // build a server from our hatch.xml configuration file diff --git a/src/org/evergreen_ils/hatch/HatchWebSocketHandler.java b/src/org/evergreen_ils/hatch/HatchWebSocketHandler.java index 7c59a18..ee7f54c 100644 --- a/src/org/evergreen_ils/hatch/HatchWebSocketHandler.java +++ b/src/org/evergreen_ils/hatch/HatchWebSocketHandler.java @@ -37,12 +37,26 @@ import java.util.Map; @WebSocket public class HatchWebSocketHandler { + /** A single connection to a WebSockets client */ private Session session; + + /** List of Origin domains from which we allow connections */ private static String[] trustedDomains; + + /** True if we trust all Origin domains */ private static boolean trustAllDomains = false; + + /** Root directory for all FileIO operations */ private static String profileDirectory; + + /** Our logger instance */ private static final Logger logger = Log.getLogger("WebSocketHandler"); + /** + * Apply trusted domains. + * + * @param domains Array of domains which we should trust + */ public static void setTrustedDomains(String[] domains) { trustedDomains = domains; @@ -63,16 +77,21 @@ public class HatchWebSocketHandler { } } + /** + * Sets the profile directory + * + * @param directory Directory path as a String + */ public static void setProfileDirectory(String directory) { profileDirectory = directory; } /** - * config is passed in from our WebSocketServlet container, - * hence the public+static. Possible to access directly? + * Runs the initial, global configuration for this handler. + * TODO: move this into setProfileDirectory() (which will need to + * be force-called regardless of config)? */ - //public static void configure(ServletConfig config) { public static void configure() { logger.info("WebSocketHandler.configure()"); @@ -86,6 +105,13 @@ public class HatchWebSocketHandler { } } + /** + * Compares the Origin of the current WebSocket connection to the list + * of allowed domains to determine if the current connection should + * be allowed. + * + * @return True if the Origin domain is allowed, false otherwise. + */ protected boolean verifyOriginDomain() { logger.info("received connection from IP " + session.getRemoteAddress().getAddress()); @@ -110,22 +136,46 @@ public class HatchWebSocketHandler { } + /** + * WebSocket onConnect handler. + * + * Verify the Origin domain before any communication may take place + */ @OnWebSocketConnect public void onConnect(Session session) { this.session = session; if (!verifyOriginDomain()) session.close(); } + /** + * WebSocket onClose handler. + * + * Clears our current session. + */ @OnWebSocketClose public void onClose(int statusCode, String reason) { logger.info("onClose() statusCode=" + statusCode + ", reason=" + reason); this.session = null; } + /** + * Send a message to our connected client. + * + * @param json A JSON-encodable object to send to the caller. + * @param msgid The message identifier + */ protected void reply(Object json, Long msgid) { reply(json, msgid, true); } + /** + * Send a message to our connected client. + * + * @param json A JSON-encodable object to send to the caller. + * @param msgid The message identifier + * @param success If false, the response will be packaged as an error + * message. + */ protected void reply(Object json, Long msgid, boolean success) { Map response = new HashMap(); @@ -147,6 +197,12 @@ public class HatchWebSocketHandler { } } + /** + * WebSocket onMessage handler. + * + * Processes the incoming message and passes the request off to the + * necessary handler. Messages must be encoded as JSON strings. + */ @OnWebSocketMessage @SuppressWarnings("unchecked") // direct casting JSON-parsed objects public void onMessage(String message) { @@ -241,7 +297,7 @@ public class HatchWebSocketHandler { if (action.equals("remove")) { io = new FileIO(profileDirectory); - if (io.delete(key)) { + if (io.remove(key)) { reply("Removal of " + key + " successful", msgid); } else { reply("Removal of " + key + " failed", msgid, false); diff --git a/src/org/evergreen_ils/hatch/HatchWebSocketServlet.java b/src/org/evergreen_ils/hatch/HatchWebSocketServlet.java index 2d6a686..b7e07ec 100644 --- a/src/org/evergreen_ils/hatch/HatchWebSocketServlet.java +++ b/src/org/evergreen_ils/hatch/HatchWebSocketServlet.java @@ -15,19 +15,17 @@ */ package org.evergreen_ils.hatch; -import org.eclipse.jetty.util.log.Log; -import org.eclipse.jetty.util.log.Logger; - import javax.servlet.annotation.WebServlet; import javax.servlet.ServletConfig; import javax.servlet.ServletException; import org.eclipse.jetty.websocket.servlet.WebSocketServlet; import org.eclipse.jetty.websocket.servlet.WebSocketServletFactory; +/** + * Links HatchWebSocketHandler in as a Servlet handler. + */ public class HatchWebSocketServlet extends WebSocketServlet { - static final Logger logger = Log.getLogger("WebSocketServlet"); - @Override public void configure(WebSocketServletFactory factory) { factory.register(HatchWebSocketHandler.class); diff --git a/src/org/evergreen_ils/hatch/PrintManager.java b/src/org/evergreen_ils/hatch/PrintManager.java index 9e564b7..13c8f24 100644 --- a/src/org/evergreen_ils/hatch/PrintManager.java +++ b/src/org/evergreen_ils/hatch/PrintManager.java @@ -46,11 +46,18 @@ import java.util.LinkedHashSet; public class PrintManager { + /** Our logger instance */ static final Logger logger = Log.getLogger("PrintManager"); /** * Shows the print dialog, allowing the user to modify settings, * but performs no print. + * + * @param params Print request parameters. This is the top-level + * request object, containing the action, etc. Within 'params' + * will be a sub-object under the "config" key, which contains + * the Printer configuration options (if any are already set). + * @return A Map of printer settings extracted from the print dialog. */ public Map configurePrinter( Map params) throws IllegalArgumentException { @@ -71,6 +78,9 @@ public class PrintManager { /** * Print the requested page using the provided settings + * + * @param engine The WebEngine instance to print + * @param params Print request parameters */ public void print(WebEngine engine, Mapparams) { @@ -104,7 +114,10 @@ public class PrintManager { } /** - * Constructs a PrinterJob based on the provided settings + * Constructs a PrinterJob based on the provided settings. + * + * @param settings The printer configuration Map. + * @return The newly created printer job. */ public PrinterJob buildPrinterJob( Map settings) throws IllegalArgumentException { @@ -129,6 +142,10 @@ public class PrintManager { /** * Builds a PageLayout for the requested printer, using the * provided settings. + * + * @param settings The printer configuration settings + * @param printer The printer from which to spawn the PageLayout + * @return The newly constructed PageLayout object. */ protected PageLayout buildPageLayout( Map settings, Printer printer) { @@ -176,6 +193,9 @@ public class PrintManager { /** * Applies the provided settings to the PrinterJob. + * + * @param settings The printer configuration settings map. + * @param job A PrinterJob, constructed from buildPrinterJob() */ protected void applySettingsToJob( Map settings, PrinterJob job) { @@ -247,6 +267,9 @@ public class PrintManager { /** * Extracts and flattens the various configuration values from a * PrinterJob and its associated printer and stores the values in a Map. + * + * @param job The PrinterJob whose attributes are to be extracted. + * @return The extracted printer settings map. */ protected Map extractSettingsFromJob(PrinterJob job) { Map settings = new HashMap(); @@ -317,7 +340,9 @@ public class PrintManager { } /** - * Returns a list of all known Printer's + * Returns all known Printer's. + * + * @return Array of all printers */ protected Printer[] getPrinters() { ObservableSet printerObserver = Printer.getAllPrinters(); @@ -330,6 +355,8 @@ public class PrintManager { /** * Returns a list of all known printers, with their attributes * encoded as a simple key/value Map. + * + * @return Map of printer information. */ protected List> getPrintersAsMaps() { Printer[] printers = getPrinters(); @@ -355,6 +382,10 @@ public class PrintManager { /** * Returns the Printer with the specified name. + * + * @param name The printer name + * @return The printer whose name matches the provided name, or null + * if no such printer is found. */ protected Printer getPrinterByName(String name) { Printer[] printers = getPrinters(); -- 2.11.0