X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Fcom%2Findexdata%2Fmkjsf%2Fpazpar2%2Fcommands%2FPazpar2Command.java;fp=src%2Fmain%2Fjava%2Fcom%2Findexdata%2Fmkjsf%2Fpazpar2%2Fcommands%2FPazpar2Command.java;h=99b330e9bbdaf8a8f718c09b30fa13f3a7ec2ae7;hb=464c86e1706170a0be7be81d239d8c16fad78ec4;hp=7c0ec74edcec7e67851f9dc78e9096aae58f9ed2;hpb=d8b3b01004d7fa71658275822f569783f1c62047;p=mkjsf-moved-to-github.git 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 7c0ec74..99b330e 100644 --- a/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Command.java +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/commands/Pazpar2Command.java @@ -16,6 +16,21 @@ import com.indexdata.mkjsf.pazpar2.data.ResponseDataObject; import com.indexdata.mkjsf.pazpar2.data.ResponseParser; import com.indexdata.mkjsf.pazpar2.data.Responses; +/** + * Represents a generic Pazpar2 or Service Proxy command with all its current parameters, and has + * methods for executing the command against the currently selected Pazpar2 service
+ *Being an abstract class it only has generic methods for getting and setting parameters. + * Implementing classes are supposed to create named getters and setters for convenient access + * to parameters from the UI.
+ *Parameters can be set with or without notifying the state manager.
+ * + *
Note: Internally the application has to be able to set parameters without state changes + * - for instance to avoid eternal feedback when copying parameter from one state to the next. A + * setting from the UI should spawn a new search state however.
+ * + * @author Niels Erik + * + */ public abstract class Pazpar2Command implements Serializable { private static Logger logger = Logger.getLogger(Pazpar2Command.class); @@ -34,17 +49,42 @@ public abstract class Pazpar2Command implements Serializable { this.name = name; } + /** + * Commands must implement this method to provide an completely detached, deep clone of + * themselves. + * + * The clone is needed by the state manager to transfer commands with current setting + * from one state to the next. + * + * Whenever a non-standard attribute is added to a command class, the copy method must + * be updated to ensure that the new attribute is brought over as well. + * + * @return a Pazpar2 command of the given type + */ public abstract Pazpar2Command copy (); public String getCommandName() { return name; } + /** + * Executes the command with the currently selected parameters against + * the currently selected Pazpar2 service + * + * @return Response data object based on the Pazpar2 service response. + */ public ResponseDataObject run() { return run(Pz2Service.get().getSearchClient(), Pz2Service.get().getPzresp()); } + /** + * Executes the commands with the currently selected parameters, while adding + * the parameters provided + * @param parameters A list of parameters on the form [key=value] + * + * @return Response data object based on the Pazpar2 service response + */ public ResponseDataObject runWith(String... parameters) { for (String parameter : parameters) { StringTokenizer tokenizer = new StringTokenizer(parameter,"="); @@ -57,9 +97,10 @@ public abstract class Pazpar2Command implements Serializable { } /** - * For running the command in a thread. Client and Responses must be - * provided because at this point the CDI bean cannot be retrieved - * from within a thread. + * Executes the command in a thread. + * + * Note: Client and Responses must be provided because at this point + * CDI beans cannot be retrieved from within a thread. * * @param client * @param pzresp @@ -75,7 +116,13 @@ public abstract class Pazpar2Command implements Serializable { return responseObject; } - + + /** + * Sets a parameter on this command and notifies the state manager + * about the change + * + * @param parameter + */ public void setParameter (CommandParameter parameter) { Pazpar2Command copy = this.copy(); logger.trace(name + " command: setting parameter [" + parameter.getName() + "=" + parameter.getValueWithExpressions() + "]"); @@ -83,6 +130,12 @@ public abstract class Pazpar2Command implements Serializable { checkInState(copy); } + /** + * Sets multiple parameters on the command and notifies the state + * manager -- once -- about the change + * + * @param params + */ public void setParameters (CommandParameter... params) { Pazpar2Command copy = this.copy(); for (CommandParameter param : params) { @@ -92,39 +145,86 @@ public abstract class Pazpar2Command implements Serializable { checkInState(copy); } + /** + * Sets multiple parameters on this command without notifying the state manager. + * Typically used when one parameter setting should automatically trigger + * other parameters to be reset to defaults etc. Intended to avoid + * useless proliferation of states + * + * @param params + */ public void setParametersInState (CommandParameter... params) { for (CommandParameter param : params) { logger.trace(name + " command: setting parameter [" + param.getName() + "=" + param.getValueWithExpressions() + "] silently"); parameters.put(param.getName(),param); } } - + + /** + * Sets a parameter on this command without notifying the state manager. + * Typically used when one parameter setting should automatically trigger + * other parameters to be reset to defaults etc. Intended to avoid + * useless proliferation of states + * + * @param parameter + */ public void setParameterInState (CommandParameter parameter) { logger.trace(name + " command: setting parameter [" + parameter.getName() + "=" + parameter.getValueWithExpressions() + "] silently"); parameters.put(parameter.getName(),parameter); } + /** + * Retrieves a command parameter by parameter name + * + * @param name of the parameter + * @return CommandParameter + */ public CommandParameter getParameter (String name) { return parameters.get(name); } + /** + * Removes a parameter completely and notifies the state manager + * about the change + * + * @param name of the parameter to remove + */ public void removeParameter (String name) { Pazpar2Command copy = this.copy(); copy.parameters.remove(name); checkInState(copy); } + /** + * Removes multiple parameters completely and notifies the state manager + * -- once -- about the change + * + * @param name of the parameter to remove + */ public void removeParameters() { Pazpar2Command copy = this.copy(); copy.parameters = new HashMap