DATAGEODE-306 - Edit Javadoc in Repository classes.

2020-09-23 14:57:46 -07:00
parent 11816674c1
commit b751f99524
4 changed files with 101 additions and 97 deletions
--- a/spring-data-geode/src/main/java/org/springframework/data/gemfire/mapping/annotation/Region.java
+++ b/spring-data-geode/src/main/java/org/springframework/data/gemfire/mapping/annotation/Region.java
@@ -29,10 +29,11 @@ import java.util.List;
 import org.springframework.core.annotation.AliasFor;

 /**
- * {@link Annotation} defining the {@link Region} in which the application persistent entity will be stored.
+ * {@link Annotation} declaring the {@link Region} in which the application persistent entity will be stored.
 *
 * @author Oliver Gierke
 * @author John Blum
+ * @see java.lang.annotation.Annotation
 * @see org.apache.geode.cache.Region
 */
@Target(ElementType.TYPE)
@@ -42,8 +43,13 @@ import org.springframework.core.annotation.AliasFor;
@SuppressWarnings("unused")
 public @interface Region {

-	List<Class<? extends Annotation>> REGION_ANNOTATION_TYPES =
-		Arrays.asList(ClientRegion.class, LocalRegion.class, PartitionRegion.class, ReplicateRegion.class, Region.class);
+	List<Class<? extends Annotation>> REGION_ANNOTATION_TYPES = Arrays.asList(
+		ClientRegion.class,
+		LocalRegion.class,
+		PartitionRegion.class,
+		ReplicateRegion.class,
+		Region.class
+	);

 	/**
 	 * Name, or fully-qualified bean name of the {@link org.apache.geode.cache.Region}
--- a/spring-data-geode/src/main/java/org/springframework/data/gemfire/repository/config/EnableGemfireRepositories.java
+++ b/spring-data-geode/src/main/java/org/springframework/data/gemfire/repository/config/EnableGemfireRepositories.java
@@ -28,14 +28,17 @@ import org.springframework.context.annotation.Import;
 import org.springframework.data.gemfire.mapping.GemfireMappingContext;
 import org.springframework.data.gemfire.repository.support.GemfireRepositoryFactoryBean;
 import org.springframework.data.gemfire.repository.support.SimpleGemfireRepository;
+import org.springframework.data.mapping.context.MappingContext;
+import org.springframework.data.repository.Repository;
 import org.springframework.data.repository.query.QueryLookupStrategy;
 import org.springframework.data.repository.query.QueryLookupStrategy.Key;

 /**
- * Annotation to enable Gemfire repositories.
+ * Annotation to enable Apache Geode, Spring Data {@link Repository Repositories}.
 *
 * @author Oliver Gierke
 * @author John Blum
+ * @see org.springframework.data.repository.Repository
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@@ -45,30 +48,34 @@ import org.springframework.data.repository.query.QueryLookupStrategy.Key;
 public @interface EnableGemfireRepositories {

 	/**
-	 * Alias for the {@link #basePackages()} attribute. Allows for more concise annotation declarations, e.g.
-	 * {@code @EnableGemfireRepositories("org.my.pkg")} instead of
-	 * {@code @EnableGemfireRepositories(basePackages="org.my.pkg")}.
+	 * Alias for the {@link #basePackages()} attribute.
 	 *
-	 * @return a String array specifying the packages to search for GemFire Repositories.
+	 * Allows for more concise annotation declarations, e.g. {@code @EnableGemfireRepositories("org.my.pkg")}
+	 * instead of {@code @EnableGemfireRepositories(basePackages="org.my.pkg")}.
+	 *
+	 * @return a {@link String} array specifying the packages to search for Apache Geode Repositories.
 	 * @see #basePackages()
 	 */
 	String[] value() default {};

 	/**
-	 * Base packages to scan for annotated components. {@link #value()} is an alias for (and mutually exclusive with) this
-	 * attribute. Use {@link #basePackageClasses()} for a type-safe alternative to String-based package names.
+	 * Base packages to scan for annotated components. {@link #value()} is an alias for (and mutually exclusive with)
+	 * this attribute.
 	 *
-	 * @return a String array specifying the packages to search for GemFire Repositories.
+	 * Use {@link #basePackageClasses()} for a type-safe alternative to String-based package names.
+	 *
+	 * @return a {@link String} array specifying the packages to search for Apache Geode Repositories.
 	 * @see #value()
 	 */
 	String[] basePackages() default {};

 	/**
-	 * Type-safe alternative to {@link #basePackages()} for specifying the packages to scan for annotated components. The
-	 * package of each class specified will be scanned. Consider creating a special no-op marker class or interface in
-	 * each package that serves no purpose other than being referenced by this attribute.
+	 * Type-safe alternative to {@link #basePackages()} to specify the packages to scan for annotated components.
 	 *
-	 * @return an array of classes used to determine the packages to scan for GemFire Repositories.
+	 * The package of each class specified will be scanned. Consider creating a special no-op marker class or interface
+	 * in each package that serves no other purpose than being referenced by this attribute.
+	 *
+	 * @return an array of {@link Class classes} used to determine the packages to scan for Apache Geode Repositories.
 	 */
 	Class<?>[] basePackageClasses() default {};

@@ -88,53 +95,64 @@ public @interface EnableGemfireRepositories {
 	Filter[] excludeFilters() default {};

 	/**
-	 * Returns the postfix to be used when looking up custom repository implementations. Defaults to {@literal Impl}. So
-	 * for a repository named {@code PersonRepository} the corresponding implementation class will be looked up scanning
-	 * for {@code PersonRepositoryImpl}.
+	 * Configures the name of the {@link GemfireMappingContext} bean definition to use when creating Repositories
+	 * discovered through this annotation. If not configured a default {@link GemfireMappingContext} will be created.
 	 *
-	 * @return a String indicating the postfix to append to the Repository interface name when looking up the custom
-	 * Repository implementing class.
+	 * @return the {@link String bean name} of the {@link MappingContext} used by a Repository to map entities to
+	 * the underlying data store (i.e. Apache Geode).
 	 */
-	String repositoryImplementationPostfix() default "Impl";
+	String mappingContextRef() default "";

 	/**
-	 * Configures the location of where to find the Spring Data named queries properties file. Will default to
-	 * {@code META-INFO/jpa-named-queries.properties}.
+	 * Configures the {@link String location} of where to find the Spring Data named queries properties file.
 	 *
-	 * @return a String indicating the location of the name queries properties file.
+	 * Defaults to {@code META-INFO/gemfire-named-queries.properties}.
+	 *
+	 * @return a {@link String} indicating the location of the named queries properties file.
 	 */
 	String namedQueriesLocation() default "";

 	/**
-	 * Returns the key of the {@link QueryLookupStrategy} to be used for lookup queries for query methods. Defaults to
-	 * {@link Key#CREATE_IF_NOT_FOUND}.
+	 * Returns the {@link Key} of the {@link QueryLookupStrategy} used to lookup queries for query methods.
 	 *
-	 * @return the Key used to determine the Query lookup and creation strategy.
+	 * Defaults to {@link Key#CREATE_IF_NOT_FOUND}.
+	 *
+	 * @return the {@link Key} used to determine the query lookup and creation strategy.
+	 * @see org.springframework.data.repository.query.QueryLookupStrategy.Key
 	 */
 	Key queryLookupStrategy() default Key.CREATE_IF_NOT_FOUND;

 	/**
-	 * Returns the {@link FactoryBean} class to be used for each repository instance. Defaults to
-	 * {@link GemfireRepositoryFactoryBean}.
-	 *
-	 * @return the {@link FactoryBean} class type used for each Repository interface.
-	 */
-	Class<?> repositoryFactoryBeanClass() default GemfireRepositoryFactoryBean.class;
-
-	/**
-	 * Configure the repository base class to be used to create repository proxies for this particular configuration.
+	 * Configure the {@link Repository} {@link Class base class} used to create {@link Repository} proxies
+	 * for this particular configuration.
 	 *
+	 * @return the {@link Repository} {@link Class base class} used to create {@link Repository} proxies.
+	 * @see org.springframework.data.gemfire.repository.support.SimpleGemfireRepository
 	 * @since 1.7
 	 */
 	Class<?> repositoryBaseClass() default SimpleGemfireRepository.class;

 	/**
-	 * Configures the name of the {@link GemfireMappingContext} bean definition to be used to create repositories
-	 * discovered through this annotation. If not configured a default one will be created.
+	 * Configures the {@link FactoryBean} {@link Class} used to create each {@link Repository} instance.
 	 *
-	 * @return the bean name of the {@link org.springframework.data.mapping.context.MappingContext} used by the
-	 * Repository to map entities to the underlying data store.
+	 * Defaults to {@link GemfireRepositoryFactoryBean}.
+	 *
+	 * @return the {@link FactoryBean} {@link Class} used to create each {@link Repository} instance.
+	 * @see org.springframework.data.gemfire.repository.support.GemfireRepositoryFactoryBean
 	 */
-	String mappingContextRef() default "";
+	Class<?> repositoryFactoryBeanClass() default GemfireRepositoryFactoryBean.class;
+
+	/**
+	 * Returns the {@link String postfix} used when looking up custom {@link Repository} implementations.
+	 *
+	 * Defaults to {@literal Impl}.
+	 *
+	 * For example, for a {@link Repository} named {@code PersonRepository}, the corresponding implementation class
+	 * will be looked up scanning for {@code PersonRepositoryImpl}.
+	 *
+	 * @return a {@link String} indicating the postfix to append to the {@link Repository} interface name
+	 * when looking up the custom {@link Repository} implementing class.
+	 */
+	String repositoryImplementationPostfix() default "Impl";

 }
--- a/spring-data-geode/src/main/java/org/springframework/data/gemfire/repository/config/GemfireRepositoriesRegistrar.java
+++ b/spring-data-geode/src/main/java/org/springframework/data/gemfire/repository/config/GemfireRepositoriesRegistrar.java
@@ -18,36 +18,48 @@ package org.springframework.data.gemfire.repository.config;
 import java.lang.annotation.Annotation;

 import org.springframework.context.annotation.ImportBeanDefinitionRegistrar;
+import org.springframework.data.repository.Repository;
 import org.springframework.data.repository.config.RepositoryBeanDefinitionRegistrarSupport;
 import org.springframework.data.repository.config.RepositoryConfigurationExtension;
+import org.springframework.lang.NonNull;

 /**
- * {@link ImportBeanDefinitionRegistrar} to setup Gemfire repositories via
- * {@link EnableGemfireRepositories}.
+ * {@link ImportBeanDefinitionRegistrar} to configure and setup Apache Geode {@link Repository Repositories}
+ * via {@link EnableGemfireRepositories}.
 *
 * @author Oliver Gierke
+ * @author John Blum
+ * @see org.springframework.context.annotation.ImportBeanDefinitionRegistrar
+ * @see org.springframework.data.repository.Repository
+ * @see org.springframework.data.repository.config.RepositoryBeanDefinitionRegistrarSupport
+ * @see org.springframework.data.repository.config.RepositoryConfigurationExtension
 */
 public class GemfireRepositoriesRegistrar extends RepositoryBeanDefinitionRegistrarSupport {

-	/*
-	 * (non-Javadoc)
+	/**
+	 * Identifies the {@link Annotation} enabling Apache Geode {@link Repository Repositories}.
 	 *
-	 * @see org.springframework.data.repository.config.
-	 * RepositoryBeanDefinitionRegistrarSupport#getAnnotation()
+	 * Defaults to {@link EnableGemfireRepositories}.
+	 *
+	 * @return the {@link Annotation} {@link Class} enabling Apache Geode {@link Repository Repositories}.
+	 * @see java.lang.annotation.Annotation
+	 * @see java.lang.Class
 	 */
 	@Override
-	protected Class<? extends Annotation> getAnnotation() {
+	protected @NonNull Class<? extends Annotation> getAnnotation() {
 		return EnableGemfireRepositories.class;
 	}

-	/*
-	 * (non-Javadoc)
+	/**
+	 * Returns the {@link RepositoryConfigurationExtension} implementing class to configure Apache Geode
+	 * {@link Repository Repositories}.
 	 *
-	 * @see org.springframework.data.repository.config.
-	 * RepositoryBeanDefinitionRegistrarSupport#getExtension()
+	 * @return the {@link RepositoryConfigurationExtension} implementing class to configure Apache Geode
+	 * {@link Repository Repositories}.
+	 * @see org.springframework.data.repository.config.RepositoryConfigurationExtension
 	 */
 	@Override
-	protected RepositoryConfigurationExtension getExtension() {
+	protected @NonNull RepositoryConfigurationExtension getExtension() {
 		return new GemfireRepositoryConfigurationExtension();
 	}
 }
--- a/spring-data-geode/src/main/java/org/springframework/data/gemfire/repository/config/GemfireRepositoryConfigurationExtension.java
+++ b/spring-data-geode/src/main/java/org/springframework/data/gemfire/repository/config/GemfireRepositoryConfigurationExtension.java
@@ -34,10 +34,11 @@ import org.springframework.data.repository.config.RepositoryConfigurationExtensi
 import org.springframework.data.repository.config.RepositoryConfigurationExtensionSupport;
 import org.springframework.data.repository.config.RepositoryConfigurationSource;
 import org.springframework.data.repository.config.XmlRepositoryConfigurationSource;
+import org.springframework.lang.NonNull;

 /**
- * {@link RepositoryConfigurationExtension} implementation handling Apache Geode and Pivotal GemFire specific extensions
- * in the Repository XML namespace and Annotation-based configuration meta-data.
+ * {@link RepositoryConfigurationExtension} implementation handling Apache Geode specific extensions
+ * in the {@link Repository} XML and Annotation-based configuration metadata.
 *
 * @author Oliver Gierke
 * @author John Blum
@@ -53,46 +54,26 @@ public class GemfireRepositoryConfigurationExtension extends RepositoryConfigura
 	static final String DEFAULT_MAPPING_CONTEXT_BEAN_NAME =
 		String.format("%1$s.%2$s", GemfireMappingContext.class.getName(), "DEFAULT");

-	/*
-	 * (non-Javadoc)
-	 * @see org.springframework.data.repository.config.RepositoryConfigurationExtensionSupport#getIdentifyingAnnotations()
-	 */
 	@Override
 	protected Collection<Class<? extends Annotation>> getIdentifyingAnnotations() {
 		return Region.REGION_ANNOTATION_TYPES;
 	}

-	/*
-	 * (non-Javadoc)
-	 * @see org.springframework.data.repository.config.RepositoryConfigurationExtensionSupport#getIdentifyingTypes()
-	 */
 	@Override
 	protected Collection<Class<?>> getIdentifyingTypes() {
 		return Collections.singleton(GemfireRepository.class);
 	}

-	/*
-	 * (non-Javadoc)
-	 * @see org.springframework.data.repository.config.RepositoryConfigurationExtensionSupport#getModulePrefix()
-	 */
 	@Override
 	protected String getModulePrefix() {
 		return GEMFIRE_MODULE_PREFIX;
 	}

-	/*
-	 * (non-Javadoc)
-	 * @see org.springframework.data.repository.config.RepositoryConfigurationExtension#getRepositoryFactoryBeanClassName()
-	 */
 	@Override
 	public String getRepositoryFactoryBeanClassName() {
 		return GemfireRepositoryFactoryBean.class.getName();
 	}

-	/*
-	 * (non-Javadoc)
-	 * @see org.springframework.data.repository.config.RepositoryConfigurationExtensionSupport#postProcess(BeanDefinitionBuilder, RepositoryConfigurationSource)
-	 */
 	@Override
 	public void postProcess(BeanDefinitionBuilder builder, RepositoryConfigurationSource source) {

@@ -101,46 +82,34 @@ public class GemfireRepositoryConfigurationExtension extends RepositoryConfigura
 		builder.addPropertyReference("cache", GemfireConstants.DEFAULT_GEMFIRE_CACHE_NAME);
 	}

-	/*
-	 * (non-Javadoc)
-	 * @see org.springframework.data.repository.config.RepositoryConfigurationExtensionSupport#postProcess(org.springframework.beans.factory.support.BeanDefinitionBuilder, org.springframework.data.repository.config.AnnotationRepositoryConfigurationSource)
-	 */
 	@Override
 	public void postProcess(BeanDefinitionBuilder builder, AnnotationRepositoryConfigurationSource configurationSource) {
 		addMappingContextPropertyReference(builder, configurationSource);
 	}

-	/*
-	 * (non-Javadoc)
-	 * @see org.springframework.data.repository.config.RepositoryConfigurationExtensionSupport#postProcess(org.springframework.beans.factory.support.BeanDefinitionBuilder, org.springframework.data.repository.config.XmlRepositoryConfigurationSource)
-	 */
 	@Override
 	public void postProcess(BeanDefinitionBuilder builder, XmlRepositoryConfigurationSource configurationSource) {
 		addMappingContextPropertyReference(builder, configurationSource);
 	}

 	/**
-	 * Adds a property reference to the store-specific {@link MappingContext}
-	 * in the given {@link BeanDefinitionBuilder bean definition}.
+	 * Adds a property reference to the data store-specific {@link MappingContext} in
+	 * the given {@link BeanDefinitionBuilder bean definition}.
 	 *
 	 * @param builder {@link BeanDefinitionBuilder} used to build the target bean definition.
 	 * @param configurationSource {@link RepositoryConfigurationSource} containing {@link Repository}
-	 * configuration meta-data.
+	 * configuration metadata.
 	 * @see org.springframework.beans.factory.support.BeanDefinitionBuilder
 	 * @see org.springframework.data.repository.config.RepositoryConfigurationSource
 	 */
-	private void addMappingContextPropertyReference(BeanDefinitionBuilder builder,
-			RepositoryConfigurationSource configurationSource) {
+	private void addMappingContextPropertyReference(@NonNull BeanDefinitionBuilder builder,
+			@NonNull RepositoryConfigurationSource configurationSource) {

 		builder.addPropertyReference(MAPPING_CONTEXT_PROPERTY_NAME,
 			configurationSource.getAttribute(MAPPING_CONTEXT_REF_ATTRIBUTE_NAME)
 				.orElse(DEFAULT_MAPPING_CONTEXT_BEAN_NAME));
 	}

-	/*
-	 * (non-Javadoc)
-	 * @see org.springframework.data.repository.config.RepositoryConfigurationExtensionSupport#registerBeansForRoot(org.springframework.beans.factory.support.BeanDefinitionRegistry, org.springframework.data.repository.config.RepositoryConfigurationSource)
-	 */
 	@Override
 	public void registerBeansForRoot(BeanDefinitionRegistry registry, RepositoryConfigurationSource configurationSource) {

@@ -153,12 +122,11 @@ public class GemfireRepositoryConfigurationExtension extends RepositoryConfigura
 	}

 	/**
-	 * Determines whether a {@link GemfireMappingContext mapping context} has already been configured.
+	 * Determines whether a {@link GemfireMappingContext} has already been configured.
 	 *
-	 * @param configurationSource {@link RepositoryConfigurationSource} used to check for the presence
-	 * of an existing {@link MappingContext} configuration.
-	 * @return a boolean value indicating whether a {@link GemfireMappingContext mapping context}
-	 * has already been configured.
+	 * @param configurationSource {@link RepositoryConfigurationSource} used to check for the presence of
+	 * an existing {@link MappingContext} configuration.
+	 * @return a boolean value indicating whether a {@link GemfireMappingContext} has already been configured.
 	 */
 	private boolean noMappingContextIsConfigured(RepositoryConfigurationSource configurationSource) {
 		return !configurationSource.getAttribute(MAPPING_CONTEXT_REF_ATTRIBUTE_NAME).isPresent();