From 8f451e761c251dcb4b01a2a11ee759e2ec3c1105 Mon Sep 17 00:00:00 2001 From: "Niels Erik G. Nielsen" Date: Thu, 6 Jun 2013 08:48:27 -0400 Subject: [PATCH] Javadoc --- .../mkjsf/pazpar2/commands/BytargetCommand.java | 6 + .../mkjsf/pazpar2/commands/CommandParameter.java | 135 +++++++++++++++++++- .../mkjsf/pazpar2/commands/Expression.java | 66 +++++++++- .../mkjsf/pazpar2/commands/Pazpar2Command.java | 8 +- 4 files changed, 205 insertions(+), 10 deletions(-) diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/BytargetCommand.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/BytargetCommand.java index 89a5bbd..daea58a 100644 --- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/BytargetCommand.java +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/BytargetCommand.java @@ -2,6 +2,12 @@ package com.indexdata.mkjsf.pazpar2.commands; import com.indexdata.mkjsf.pazpar2.commands.sp.ServiceProxyCommand; +/** + * Represents a Pazpar2 'bytarget' command + * + * @author Niels Erik + * + */ public class BytargetCommand extends Pazpar2Command implements ServiceProxyCommand { private static final long serialVersionUID = 9070458716105294392L; diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/CommandParameter.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/CommandParameter.java index f14e836..eaff692 100644 --- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/CommandParameter.java +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/CommandParameter.java @@ -10,6 +10,18 @@ import java.util.List; import org.apache.log4j.Logger; +/** + * Represents a Pazpar2 command parameter with a name, an operator, + * a simple value and/or one or more complex values (expressions). + *

Examples

+ * + * @author Niels Erik + * + */ public class CommandParameter implements Serializable { private static Logger logger = Logger.getLogger(CommandParameter.class); @@ -26,6 +38,14 @@ public class CommandParameter implements Serializable { this.name = name; } + /** + * Instantiates a parameter with a simple value and one or more expressions + * + * @param name + * @param operator + * @param value + * @param expressions + */ public CommandParameter (String name, String operator, String value, Expression... expressions) { logger.trace("Instantiating command parameter " + name + " with value [" + value + "] and expressions: [" + expressions + "]"); this.name = name; @@ -36,6 +56,12 @@ public class CommandParameter implements Serializable { } } + /** + * Instantiates a parameter with one or more expressions + * @param name + * @param operator + * @param expressions + */ public CommandParameter (String name, String operator, Expression... expressions) { logger.trace("Instantiating command parameter " + name + " with expressions: [" + expressions + "]"); this.name = name; @@ -46,6 +72,12 @@ public class CommandParameter implements Serializable { } + /** + * Instantiates a parameter with a simple value + * @param name + * @param operator + * @param value + */ public CommandParameter (String name, String operator, String value) { if (!nologparams.contains(name)) logger.trace("Instantiating command parameter '" + name + "' with String: [" + value + "]"); this.name = name; @@ -53,6 +85,12 @@ public class CommandParameter implements Serializable { this.value = value; } + /** + * Instantiates a parameter with a numeric value + * @param name + * @param operator + * @param value + */ public CommandParameter (String name, String operator, int value) { logger.trace("Instantiating command parameter '" + name + "' with int: [" + value + "]"); this.name = name; @@ -60,15 +98,34 @@ public class CommandParameter implements Serializable { this.value = value+""; } - + /** + * Returns the name (left of operator) of this parameter + * + * @return name (left of operator) of this parameter + */ public String getName () { return name; } + /** + * Returns a list of all current expressions + * + * @return a list of all current expressions + */ public List getExpressions () { return expressions; } - + + /** + * Returns expressions selected by their left-hand keys - as in 'expressionField=value'. + *

+ * If the parameter has expressions expr1=x,expr2=y,expr3=z,expr1=u then invoking this method + * with {"expr1","expr3"} would return expr1=x,expr3=z,expr1=u but not expr2=y. + *

+ * @param expressionFields The expression types to return + * @return a list of expressions with the given keys to the left of the operator + * + */ public List getExpressions(String... expressionFields) { List requestedFields = Arrays.asList(expressionFields); List exprs = new ArrayList(); @@ -80,11 +137,21 @@ public class CommandParameter implements Serializable { return exprs; } + /** + * Adds an expression to the end of the list of current expressions (if any) + * + * @param expression to add + */ public void addExpression(Expression expression) { logger.debug("Adding expression [" + expression + "] to '" + name + "'"); this.expressions.add(expression); } + /** + * Removes a single expression identified by all its characteristics + * + * @param expression to remove + */ public void removeExpression(Expression expression) { for (Expression expr : expressions) { if (expr.toString().equals(expression.toString())) { @@ -94,6 +161,15 @@ public class CommandParameter implements Serializable { } } + /** + * Removes all expressions that appear after the provided expression and that + * have the given keys to the left of their operators - as in 'expressionField=value'. + *

+ * This method is intended for bread crumb-like UI controls + *

+ * @param expression The expression to use a starting point for removal (not inclusive) + * @param expressionFields The expression fields to remove + */ public void removeExpressionsAfter (Expression expression, String... expressionFields) { List exprFieldsToRemove = Arrays.asList(expressionFields); int fromIdx = 0; @@ -114,6 +190,16 @@ public class CommandParameter implements Serializable { } } + /** + * Removes expressions selected by their left-of-operator fields/keys - as in 'expressionField=value'. + *

+ * If the parameter has expressions expr1=x,expr2=y,expr3=z,expr1=u then invoking this method + * with {"expr1","expr3"} would remove expr1=x,expr3=z and expr1=u but leave expr2=y. + *

+ * @param expressionFields The expression types (by field) to remove + * @return a list of expressions with the given left-of-operator keys + * + */ public void removeExpressions (String... expressionFields) { List fieldsToRemove = Arrays.asList(expressionFields); Iterator i = expressions.iterator(); @@ -125,19 +211,41 @@ public class CommandParameter implements Serializable { } } } - + + /** + * + * @return true if an operator was defined for this parameter yet + */ public boolean hasOperator() { return operator != null; } + /** + * Returns true if this parameter has a simple value + * + * @return true if this parameter has a simple value + */ public boolean hasValue() { return value != null && value.length()>0; } + /** + * Returns true if this parameter has expressions (complex values) + * + * @return true if this parameter has expressions (complex values) + */ public boolean hasExpressions() { return expressions.size()>0; } + /** + * Returns true if this parameter has expressions of the given type, + * that is, expressions where the left-of-operator key equals 'expressionField' + * + * @param expressionField the type of expression to look for + * @return true if this parameter has expressions of the given type, + * that is, expressions where the left-of-operator key equals 'expressionField' + */ public boolean hasExpressions(String expressionField) { for (Expression expr : expressions) { if (expr.getField().equals(expressionField)) { @@ -147,6 +255,11 @@ public class CommandParameter implements Serializable { return false; } + /** + * Returns a URL encoded string of this parameter with name, operator, simple value and/or expressions + * + * @return URL encoded string of this parameter with name, operator, simple value and/or expressions + */ public String getEncodedQueryString () { try { return name + operator + URLEncoder.encode(getValueWithExpressions(),"UTF-8"); @@ -156,10 +269,20 @@ public class CommandParameter implements Serializable { } } + /** + * Returns the simple parameter value or null if no simple value was set for this parameter + * + * @return the simple parameter value, null if no simple value was set for this parameter + */ public String getSimpleValue() { return value; } + /** + * Returns the simple parameter value and/or any expressions, separated by 'AND' + * + * @return the simple parameter value and/or any expressions separated by 'AND' + */ public String getValueWithExpressions () { StringBuilder completeValue = new StringBuilder((value==null ? "" : value)); boolean first=true; @@ -190,6 +313,12 @@ public class CommandParameter implements Serializable { return getValueWithExpressions(); } + /** + * Clones the CommandParameter + * + * @return a deep, detached clone of this command parameter, for copying + * a parameter to a new state. + */ public CommandParameter copy() { logger.trace("Copying parameter '"+ name + "' for modification"); CommandParameter newParam = new CommandParameter(name); diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Expression.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Expression.java index f636f68..67cc3d4 100644 --- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Expression.java +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Expression.java @@ -4,6 +4,22 @@ import java.io.Serializable; import org.apache.log4j.Logger; +/** + * Represents a complex command parameter value, in form of an expression with + * an equality operator + *

+ * An expression consist of a left-of-operator field or key, an equality operator (= or ~), + * a right-of-operator value, and optionally a label describing the value for UI display. + *

+ * Examples: + *
    + *
  • pz:id=1234 "My Target"
    • + *
  • category~libcatalog "Library Catalogs"
    • + *
  • author="Steinbeck, John"
    • + *
+ * @author Niels Erik + * + */ public class Expression implements Serializable { private static final long serialVersionUID = -751704027842027769L; @@ -13,13 +29,31 @@ public class Expression implements Serializable { String rightEntity; String label; - public Expression (String leftEntity, String operator, String rightEntity, String label) { - this.leftEntity = leftEntity; + /** + * Instantiates an expression with a label + * + * @param leftEntity left-of-operator field name (or 'key') + * @param operator an equality operator + * @param rightEntity right-of-operator value + * @param label to be used for display, for instance in a UI control that adds or removes the expression + * from a command parameter + */ + public Expression (String field, String operator, String value, String label) { + this.leftEntity = field; this.operator = operator; - this.rightEntity = rightEntity; + this.rightEntity = value; this.label = label; } + /** + * Instantiates an expression by parsing the provided expression string, which must be + * on the form {name}({=}or{~}){value}. + *

+ * Currently only '=' and '~' are recognized as operators + *

+ * + * @param expressionString + */ public Expression (String expressionString) { String[] parts = expressionString.split("[=~]"); this.leftEntity = parts[0]; @@ -28,6 +62,11 @@ public class Expression implements Serializable { this.label=rightEntity; } + /** + * Clones the expression + * + * @return a clone of this expression + */ public Expression copy() { logger.trace("Copying " + this.toString()); return new Expression(leftEntity, operator, rightEntity, label); @@ -37,18 +76,39 @@ public class Expression implements Serializable { return leftEntity + operator + rightEntity; } + /** + * Returns the label describing the value of the expression or, + * if no label was provided, the value itself. + * + * @return label or right-of-operator value if no label provided + */ public String getLabel() { return label; } + /** + * Returns the left-of-operator field (or name or key). + * + * @return entity left of operator + */ public String getField () { return leftEntity; } + /** + * Returns the operator + * + * @return the operator of the expression + */ public String getOperator() { return operator; } + /** + * Returns the right-of-operator value of the expression + * + * @return entity right of operator + */ public String getValue() { return rightEntity; } diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Command.java b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Command.java index 99b330e..a4fa51f 100644 --- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Command.java +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Command.java @@ -334,10 +334,10 @@ public abstract class Pazpar2Command implements Serializable { public abstract ServiceProxyCommand getSp(); /** - * Implementing commands publishes whether they only - * apply to the Service Proxy - or can be executed - * against straight Pazpar2 as well. Convenient for a - * UI that switches between service types - whether + * Here implementing commands publish whether they only + * apply to the Service Proxy or can be executed + * against straight Pazpar2 as well. This is convenient for a + * UI that switches between service types either * deployment time or run time. * * @return false if the command applies to straight Pazpar2 -- 1.7.10.4