From 61abfe4b248fd326c0b655be1e877224e0c86bf4 Mon Sep 17 00:00:00 2001
From: "Niels Erik G. Nielsen" <nielserik@indexdata.com>
Date: Fri, 15 Mar 2013 20:56:14 -0400
Subject: [PATCH] Documentation

---
 .../pz2utils4jsf/config/Configurable.java          |   33 ++++++++++++++++++++
 .../pz2utils4jsf/config/ConfigurationReader.java   |   18 +++++++++++
 .../pz2utils4jsf/config/WebXmlConfigReader.java    |    6 ++++
 .../pz2utils4jsf/pazpar2/StraightPz2Client.java    |    1 +
 4 files changed, 58 insertions(+)

diff --git a/src/main/java/com/indexdata/pz2utils4jsf/config/Configurable.java b/src/main/java/com/indexdata/pz2utils4jsf/config/Configurable.java
index 26586ba..ca10556 100644
--- a/src/main/java/com/indexdata/pz2utils4jsf/config/Configurable.java
+++ b/src/main/java/com/indexdata/pz2utils4jsf/config/Configurable.java
@@ -5,11 +5,44 @@ import java.util.Map;
 
 import com.indexdata.pz2utils4jsf.errors.ConfigurationException;
 
+/**
+ * Interface to be implemented by any part of an application that wish to
+ * use a ConfigurationReader for it's configuration. The Configurables that
+ * come with the project are a Pazpar2 client and a Service Proxy client
+ * 
+ * @author Niels Erik
+ *
+ */
 public interface Configurable {
 
+  /**
+   * Configures the Configurable using the configuration obtained by the 
+   * provided configuration reader
+   * @param reader used for reading the configuration 
+   * @throws ConfigurationException
+   */
   public void configure(ConfigurationReader reader) throws ConfigurationException;
+  
+  /**
+   * Returns the default parameters that the configurable has defined for itself
+   * Should be invoked by the configuration reader before it possibly overrides
+   * some parameters obtained from the external configuration source  
+   * @return
+   */
   public Map<String,String> getDefaults();
+  
+  /**
+   * Returns the name of the module, can be used by a configuration reader that 
+   * has distinguishes between sets of configuration properties by component name
+   * @return name of the part that is to be configured
+   */
   public String getModuleName();
+  
+  /**
+   * The components documentation of how it was configured. 
+   * 
+   * @return a list of Strings describing configuration details
+   */
   public List<String> documentConfiguration(); 
   
 }
diff --git a/src/main/java/com/indexdata/pz2utils4jsf/config/ConfigurationReader.java b/src/main/java/com/indexdata/pz2utils4jsf/config/ConfigurationReader.java
index 528e8bd..ea94af5 100644
--- a/src/main/java/com/indexdata/pz2utils4jsf/config/ConfigurationReader.java
+++ b/src/main/java/com/indexdata/pz2utils4jsf/config/ConfigurationReader.java
@@ -5,9 +5,27 @@ import java.util.List;
 
 import com.indexdata.pz2utils4jsf.errors.ConfigurationException;
 
+/**
+ * Interface to be implemented by classes that read configurations from a source -
+ * i.e. from web.xml, the file system, a database or hard-coded. 
+ * 
+ * @author Niels Erik
+ *
+ */
 public interface ConfigurationReader extends Serializable {
     
+  /**
+   * Returns a Configuration to be used by the given Configurable
+   * 
+   * @param configurable the configurable to be configured by a configuration obtained by this reader
+   * @return a Configuration, basically a set of key-value pairs
+   * @throws ConfigurationException
+   */
   public Configuration getConfiguration(Configurable configurable) throws ConfigurationException;
   
+  /**
+   * Returns documentation for the key-value pairs obtained by this reader
+   * @return
+   */
   public List<String> document();
 }
diff --git a/src/main/java/com/indexdata/pz2utils4jsf/config/WebXmlConfigReader.java b/src/main/java/com/indexdata/pz2utils4jsf/config/WebXmlConfigReader.java
index f3669ae..ac0e045 100644
--- a/src/main/java/com/indexdata/pz2utils4jsf/config/WebXmlConfigReader.java
+++ b/src/main/java/com/indexdata/pz2utils4jsf/config/WebXmlConfigReader.java
@@ -19,6 +19,12 @@ import org.apache.log4j.Logger;
 
 import com.indexdata.pz2utils4jsf.errors.ConfigurationException;
 
+/**
+ * Reads a configuration from the context parameters of the deployment descriptor (web.xml)
+ * 
+ * @author Niels Erik
+ *
+ */
 @Named @SessionScoped @Alternative
 public class WebXmlConfigReader implements ConfigurationReader {
 
diff --git a/src/main/java/com/indexdata/pz2utils4jsf/pazpar2/StraightPz2Client.java b/src/main/java/com/indexdata/pz2utils4jsf/pazpar2/StraightPz2Client.java
index 3ae05ec..475aa15 100644
--- a/src/main/java/com/indexdata/pz2utils4jsf/pazpar2/StraightPz2Client.java
+++ b/src/main/java/com/indexdata/pz2utils4jsf/pazpar2/StraightPz2Client.java
@@ -48,6 +48,7 @@ public class StraightPz2Client implements SearchClient {
   
   public StraightPz2Client() {}
   
+  @Override
   public void configure(ConfigurationReader configReader) throws ConfigurationException {    
     logger.info(Utils.objectId(this) + " is configuring using the provided " + Utils.objectId(configReader));
     try {
-- 
1.7.10.4