DATACOUCH-21 - Documentation and Formatting improvements

Author: daschl

src/main/java/org/springframework/data/couchbase/cache/CouchbaseCache.java

@@ -22,9 +22,11 @@
 import org.springframework.cache.support.SimpleValueWrapper;
 
 /**
- * The CouchbaseCache class implements the Spring Cache interface
- * on top of Couchbase Server and the Couchbase Java SDK.
+ * The {@link CouchbaseCache} class implements the Spring Cache interface on top of Couchbase Server and the Couchbase
+ * Java SDK.
  *
+ * @see <a href="http://static.springsource.org/spring/docs/current/spring-framework-reference/html/cache.html">
+ *   Official Spring Cache Reference</a>
  * @author Michael Nitschinger
  */
 public class CouchbaseCache implements Cache {
@@ -65,7 +67,7 @@ public final String getName() {
    * @return the actual CouchbaseClient instance.
    */
   public final CouchbaseClient getNativeCache() {
-    return this.client;
+    return client;
   }
 
   /**
@@ -76,7 +78,7 @@ public final CouchbaseClient getNativeCache() {
    */
   public final ValueWrapper get(final Object key) {
     String documentId = key.toString();
-    Object result = this.client.get(documentId);
+    Object result = client.get(documentId);
     return (result != null ? new SimpleValueWrapper(result) : null);
   }
 
@@ -88,7 +90,7 @@ public final ValueWrapper get(final Object key) {
    */
   public final void put(final Object key, final Object value) {
     String documentId = key.toString();
-    this.client.set(documentId, 0, value);
+    client.set(documentId, 0, value);
   }
 
   /**
@@ -98,7 +100,7 @@ public final void put(final Object key, final Object value) {
    */
   public final void evict(final Object key) {
     String documentId = key.toString();
-    this.client.delete(documentId);
+    client.delete(documentId);
   }
 
   /**
@@ -108,7 +110,7 @@ public final void evict(final Object key) {
    * Also note that "flush" may not be enabled on the bucket.
    */
   public final void clear() {
-    this.client.flush();
+    client.flush();
   }
 
 }

src/main/java/org/springframework/data/couchbase/cache/CouchbaseCacheManager.java

@@ -25,11 +25,10 @@
 import org.springframework.cache.support.AbstractCacheManager;
 
 /**
- * The CouchbaseCacheManager orchestrates CouchbaseCache instances.
+ * The {@link CouchbaseCacheManager} orchestrates {@link CouchbaseCache} instances.
  * 
- * Since more than one current CouchbaseClient connection can be used
- * for caching, the CouchbaseCacheManager orchestrates and handles
- * them for the Spring Cache abstraction layer.
+ * Since more than one current {@link CouchbaseClient} connection can be used for caching, the
+ * {@link CouchbaseCacheManager} orchestrates and handles them for the Spring Cache abstraction layer.
  *
  * @author Michael Nitschinger
  */
@@ -55,7 +54,7 @@ public CouchbaseCacheManager(final HashMap<String, CouchbaseClient> clients) {
    * @return the actual CouchbaseClient instances.
    */
   public final HashMap<String, CouchbaseClient> getClients() {
-    return this.clients;
+    return clients;
   }
 
   /**
@@ -67,7 +66,7 @@ public final HashMap<String, CouchbaseClient> getClients() {
   protected final Collection<? extends Cache> loadCaches() {
     Collection<Cache> caches = new LinkedHashSet<Cache>();
 
-    for (Map.Entry<String, CouchbaseClient> cache : this.clients.entrySet()) {
+    for (Map.Entry<String, CouchbaseClient> cache : clients.entrySet()) {
       caches.add(new CouchbaseCache(cache.getKey(), cache.getValue()));
     }
 

src/main/java/org/springframework/data/couchbase/config/AbstractCouchbaseConfiguration.java

@@ -25,7 +25,7 @@
 import org.springframework.context.annotation.Configuration;
 import org.springframework.core.type.filter.AnnotationTypeFilter;
 import org.springframework.data.annotation.Persistent;
-import org.springframework.data.couchbase.core.CouchbaseMappingContext;
+import org.springframework.data.couchbase.core.mapping.CouchbaseMappingContext;
 import org.springframework.data.couchbase.core.CouchbaseTemplate;
 import org.springframework.data.couchbase.core.convert.MappingCouchbaseConverter;
 import org.springframework.data.couchbase.core.mapping.Document;
@@ -42,30 +42,36 @@ public abstract class AbstractCouchbaseConfiguration {
 
   /**
    * Return the {@link CouchbaseClient} instance to connect to.
+   *
+   * @throws Exception on Bean construction failure.
    */
   @Bean
   public abstract CouchbaseClient couchbaseClient() throws Exception;
 
   /**
    * Creates a {@link CouchbaseTemplate}.
+   *
+   * @throws Exception on Bean construction failure.
    */
   @Bean
   public CouchbaseTemplate couchbaseTemplate() throws Exception {
     return new CouchbaseTemplate(couchbaseClient(), mappingCouchbaseConverter());
   }
 
   /**
-   * Creates a {@link MappingCouchbaseConverter} using the configured {@link
-   * #couchbaseMappingContext}.
+   * Creates a {@link MappingCouchbaseConverter} using the configured {@link #couchbaseMappingContext}.
+   *
+   * @throws Exception on Bean construction failure.
    */
   @Bean
   public MappingCouchbaseConverter mappingCouchbaseConverter() throws Exception {
     return new MappingCouchbaseConverter(couchbaseMappingContext());
   }
 
   /**
-   * Creates a {@link CouchbaseMappingContext} equipped with entity classes
-   * scanned from the mapping base package.
+   * Creates a {@link CouchbaseMappingContext} equipped with entity classes scanned from the mapping base package.
+   *
+   * @throws Exception on Bean construction failure.
    */
   @Bean
   public CouchbaseMappingContext couchbaseMappingContext() throws Exception {
@@ -76,12 +82,14 @@ public CouchbaseMappingContext couchbaseMappingContext() throws Exception {
 
   /**
    * Scans the mapping base package for classes annotated with {@link Document}.
+   *
+   * @throws ClassNotFoundException if intial entity sets could not be loaded.
    */
   protected Set<Class<?>> getInitialEntitySet() throws ClassNotFoundException {
     String basePackage = getMappingBasePackage();
     Set<Class<?>> initialEntitySet = new HashSet<Class<?>>();
 
-    if(StringUtils.hasText(basePackage)) {
+    if (StringUtils.hasText(basePackage)) {
 			ClassPathScanningCandidateComponentProvider componentProvider =
         new ClassPathScanningCandidateComponentProvider(false);
 			componentProvider.addIncludeFilter(
@@ -100,15 +108,14 @@ protected Set<Class<?>> getInitialEntitySet() throws ClassNotFoundException {
   }
 
   /**
-   * Return the base package to scan for mapped {@link Document}s. Will return
-   * the package name of the configuration class (the concrete class, not this
-   * one here) by default. So if you have a {@code com.acme.AppConfig} extending
-   * {@link AbstractCouchbaseConfiguration} the base package will be considered
-   * {@code com.acme} unless the method is overridden to implement alternate
-   * behavior.
+   * Return the base package to scan for mapped {@link Document}s. Will return the package name of the configuration
+   * class (the concrete class, not this one here) by default.
+   *
+   * <p>So if you have a {@code com.acme.AppConfig} extending {@link AbstractCouchbaseConfiguration} the base package
+   * will be considered {@code com.acme} unless the method is overridden to implement alternate behavior.</p>
    *
-   * @return the base package to scan for mapped {@link Document} classes or
-   *         {@literal null} to not enable scanning for entities.
+   * @return the base package to scan for mapped {@link Document} classes or {@literal null} to not enable scanning for
+   *         entities.
    */
   protected String getMappingBasePackage() {
     return getClass().getPackage().getName();

src/main/java/org/springframework/data/couchbase/config/BeanNames.java

@@ -17,12 +17,18 @@
 package org.springframework.data.couchbase.config;
 
 /**
+ * Contains default bean names that will be used when no "id" is supplied to the beans.
+ *
  * @author Michael Nitschinger
  */
 public class BeanNames {
-  static final String MAPPING_CONTEXT = "mappingContext";
+  /**
+   * Refers to the "<couchbase:couchbase />" bean.
+   */
   static final String COUCHBASE = "couchbase";
-  static final String DB_FACTORY = "couchbaseDbFactory";
-  static final String DEFAULT_CONVERTER_BEAN_NAME = "mappingConverter";
+
+  /**
+   * Refers to the "<couchbase:template />" bean.
+   */
   static final String COUCHBASE_TEMPLATE = "couchbaseTemplate";
 }

src/main/java/org/springframework/data/couchbase/config/CouchbaseJmxParser.java

@@ -28,12 +28,22 @@
 import org.w3c.dom.Element;
 
 /**
- * Enables Parsing of "<couchbase:jmx />" configurations.
+ * Enables Parsing of the "<couchbase:jmx />" configuration bean.
+ *
+ * In order to enable JMX, different JmxComponents need to be registered. The dependency to the original
+ * {@link com.couchbase.client.CouchbaseClient} object is solved by through the "couchbase-ref" attribute.
  *
  * @author Michael Nitschinger
  */
 public class CouchbaseJmxParser implements BeanDefinitionParser {
 
+  /**
+   * Parse the element and dispatch the registration of the JMX components.
+   *
+   * @param element the XML element which contains the attributes.
+   * @param parserContext encapsulates the parsing state and configuration.
+   * @return null, because no bean instance needs to be returned.
+   */
   public BeanDefinition parse(final Element element, final ParserContext parserContext) {
     String name = element.getAttribute("couchbase-ref");
     if (!StringUtils.hasText(name)) {
@@ -43,7 +53,14 @@ public BeanDefinition parse(final Element element, final ParserContext parserCon
     return null;
   }
 
-  protected void registerJmxComponents(String refName, Element element, ParserContext parserContext) {
+  /**
+   * Register the JMX components in the context.
+   *
+   * @param refName the reference name to the couchbase client.
+   * @param element the XML element which contains the attributes.
+   * @param parserContext encapsulates the parsing state and configuration.
+   */
+  protected void registerJmxComponents(final String refName, final Element element, final ParserContext parserContext) {
     Object eleSource = parserContext.extractSource(element);
     CompositeComponentDefinition compositeDef = new CompositeComponentDefinition(element.getTagName(), eleSource);
 
@@ -53,8 +70,17 @@ protected void registerJmxComponents(String refName, Element element, ParserCont
     parserContext.registerComponent(compositeDef);
   }
 
-  protected void createBeanDefEntry(Class<?> clazz, CompositeComponentDefinition compositeDef,
-    String refName, Object eleSource, ParserContext parserContext) {
+  /**
+   * Creates Bean Definitions for JMX components and adds them as a nested component.
+   *
+   * @param clazz the class type to register.
+   * @param compositeDef component that can hold nested components.
+   * @param refName the reference name to the couchbase client.
+   * @param eleSource source element to reference.
+   * @param parserContext encapsulates the parsing state and configuration.
+   */
+  protected void createBeanDefEntry(final Class<?> clazz, final CompositeComponentDefinition compositeDef,
+    final String refName, final Object eleSource, final ParserContext parserContext) {
     BeanDefinitionBuilder builder = BeanDefinitionBuilder.genericBeanDefinition(clazz);
     builder.getRawBeanDefinition().setSource(eleSource);
     builder.addConstructorArgReference(refName);

src/main/java/org/springframework/data/couchbase/config/CouchbaseNamespaceHandler.java

@@ -24,11 +24,17 @@
 /**
  * {@link org.springframework.beans.factory.xml.NamespaceHandler} for Couchbase configuration.
  *
+ * This handler acts as a container for one or more bean parsers and registers them. During parsing, the elements
+ * get analyzed and the appropriate registered parser is called.
+ *
  * @author Michael Nitschinger
  */
 public class CouchbaseNamespaceHandler extends NamespaceHandlerSupport {
 
-  public void init() {
+  /**
+   * Register bean definition parsers in the namespace handler.
+   */
+  public final void init() {
     RepositoryConfigurationExtension extension = new CouchbaseRepositoryConfigurationExtension();
 
     registerBeanDefinitionParser("repositories", new RepositoryBeanDefinitionParser(extension));

src/main/java/org/springframework/data/couchbase/config/CouchbaseParser.java

@@ -31,19 +31,32 @@
 import java.util.ArrayList;
 import java.util.List;
 
-
 /**
- * Parser for "<couchbase:couchbase />" definitions.
+ * Parser for "<couchbase:couchbase />" bean definitions.
+ *
+ * The outcome of this bean definition parser will be a constructed {@link CouchbaseClient}.
  *
  * @author Michael Nitschinger
  */
 public class CouchbaseParser extends AbstractSingleBeanDefinitionParser {
 
+  /**
+   * Defines the bean class that will be constructed.
+   *
+   * @param element the XML element which contains the attributes.
+   * @return the class type to instantiate.
+   */
   @Override
   protected Class getBeanClass(final Element element) {
     return CouchbaseClient.class;
   }
 
+  /**
+   * Parse the bean definition and build up the bean.
+   *
+   * @param element the XML element which contains the attributes.
+   * @param bean the builder which builds the bean.
+   */
   @Override
   protected void doParse(final Element element, final BeanDefinitionBuilder bean) {
     String host = element.getAttribute("host");
@@ -57,12 +70,30 @@ protected void doParse(final Element element, final BeanDefinitionBuilder bean)
       StringUtils.hasText(password) ? password : CouchbaseFactoryBean.DEFAULT_PASSWORD);
   }
 
+  /**
+   * Resolve the bean ID and assign a default if not set.
+   *
+   * @param element the XML element which contains the attributes.
+   * @param definition the bean definition to work with.
+   * @param parserContext encapsulates the parsing state and configuration.
+   * @return the ID to work with.
+   */
+  @Override
   protected String resolveId(final Element element, final AbstractBeanDefinition definition,
     final ParserContext parserContext) {
     String id = super.resolveId(element, definition, parserContext);
     return StringUtils.hasText(id) ? id : BeanNames.COUCHBASE;
   }
 
+  /**
+   * Convert a list of hosts into a URI format that can be used by the {@link CouchbaseClient}.
+   *
+   * To make it simple to use, the list of hosts can be passed in as a comma separated list. This list gets parsed
+   * and converted into a URI format that is suitable for the underlying {@link CouchbaseClient} object.
+   *
+   * @param hosts the host list to convert.
+   * @return the converted list with URIs.
+   */
   private List<URI> convertHosts(final String hosts) {
     String[] split = hosts.split(",");
     List<URI> nodes = new ArrayList<URI>();

src/main/java/org/springframework/data/couchbase/config/CouchbaseTemplateParser.java

@@ -25,21 +25,46 @@
 import org.w3c.dom.Element;
 
 /**
+ * Parser for "<couchbase:template />" bean definitions.
+ *
+ * The outcome of this bean definition parser will be a constructed {@link CouchbaseTemplate}.
+ *
  * @author Michael Nitschinger
  */
 public class CouchbaseTemplateParser extends AbstractSingleBeanDefinitionParser {
 
+  /**
+   * Resolve the bean ID and assign a default if not set.
+   *
+   * @param element the XML element which contains the attributes.
+   * @param definition the bean definition to work with.
+   * @param parserContext encapsulates the parsing state and configuration.
+   * @return the ID to work with.
+   */
+  @Override
   protected String resolveId(final Element element, final AbstractBeanDefinition definition,
     final ParserContext parserContext) {
     String id = super.resolveId(element, definition, parserContext);
     return StringUtils.hasText(id) ? id : BeanNames.COUCHBASE_TEMPLATE;
   }
 
+  /**
+   * Defines the bean class that will be constructed.
+   *
+   * @param element the XML element which contains the attributes.
+   * @return the class type to instantiate.
+   */
   @Override
   protected Class getBeanClass(final Element element) {
     return CouchbaseTemplate.class;
   }
 
+  /**
+   * Parse the bean definition and build up the bean.
+   *
+   * @param element the XML element which contains the attributes.
+   * @param bean the builder which builds the bean.
+   */
   @Override
   protected void doParse(final Element element, final BeanDefinitionBuilder bean) {
     String converterRef = element.getAttribute("converter-ref");