From 4cbef9529d606b6baa6579b18fbfaafaf7052ba9 Mon Sep 17 00:00:00 2001 From: John Blum Date: Mon, 30 Jul 2018 18:05:41 -0700 Subject: [PATCH] SGF-775 - Add quick start reference to the 'Bootstrapping Apache Geode Using Annotations' chapter. Resolves DATAGEODE-114. --- src/main/asciidoc/index.adoc | 1 + .../bootstrap-annotations-quickstart.adoc | 603 ++++++++++++++++++ .../reference/bootstrap-annotations.adoc | 182 +++--- .../AbstractAnnotationConfigSupport.java | 3 +- 4 files changed, 699 insertions(+), 90 deletions(-) create mode 100644 src/main/asciidoc/reference/bootstrap-annotations-quickstart.adoc diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index 85adf205..dc842e61 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -27,6 +27,7 @@ Costin Leau; David Turanski; John Blum; Oliver Gierke; Jay Bryant :sdg-acronym: SDG :sdg-javadoc: https://docs.spring.io/spring-data/{data-store-name-symbolic}/docs/current/api :sdg-name: Spring Data for {data-store-name} +:sdg-website: https://projects.spring.io/spring-data-gemfire :spring-data-access-schema-location: http://www.springframework.org/schema/data/gemfire/spring-data-gemfire.xsd :spring-data-access-schema-namespace: http://www.springframework.org/schema/data/gemfire :spring-data-commons-docs: https://docs.spring.io/spring-data/commons/docs/current/reference diff --git a/src/main/asciidoc/reference/bootstrap-annotations-quickstart.adoc b/src/main/asciidoc/reference/bootstrap-annotations-quickstart.adoc new file mode 100644 index 00000000..365dad3b --- /dev/null +++ b/src/main/asciidoc/reference/bootstrap-annotations-quickstart.adoc @@ -0,0 +1,603 @@ +[[bootstap-annotations-quickstart]] += Annotation-based Configuration Quick Start + +The following sections provide an overview to the {sdg-acronym} annotations in order to get started quickly. + +NOTE: All annotations provide additional configuration attributes along with associated <> +to conveniently customize the configuration and behavior of {data-store-name} at runtime. However, in general, +none of the attributes or associated properties are required to use a particular {data-store-name} feature. +Simply declare the annotation to enable the feature and you are done. Refer to the individual Javadoc of +each annotation for more details. + +[[bootstap-annotations-quickstart-clientcache]] +== Configure a `ClientCache` Application + +To configure and bootstrap a {data-store-name} `ClientCache` application, use the following: + +[source,java] +---- +@SpringBootApplication +@ClientCacheApplication +public class ClientApplication { + + public static void main(String[] args) { + SpringApplication.run(ClientApplication.class, args); + } +} +---- + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html[`@ClientCacheApplication` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-peercache]] +== Configure a Peer `Cache` Application + +To configure and bootstrap a {data-store-name} Peer `Cache` application, use the following: + +[source,java] +---- +@SpringBootApplication +@PeerCacheApplication +public class ServerApplication { + + public static void main(String[] args) { + SpringApplication.run(ServerApplication.class, args); + } +} +---- + +NOTE: If you would like to enable a `CacheServer` that allows `ClientCache` applications to connect to this server, +then simply replace the `@PeerCacheApplication` annotation with the `@CacheServerApplication` annotation. This will +start a `CacheServer` running on "`localhost`", listening on the default `CacheServer` port of `40404`. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/CacheServerApplication.html[`@CacheServerApplication` Javadoc]. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/PeerCacheApplication.html[`@PeerCacheApplication` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-locator]] +== Configure an Embedded Locator + +Annotate your Spring `@PeerCacheApplication` or `@CacheServerApplication` class with `@EnableLocator` to start +an embedded Locator bound to all NICs listening on the default Locator port, `10334`, as follows: + +[source,java] +---- +@SpringBootApplication +@CacheServerApplication +@EnableLocator +public class ServerApplication { + + public static void main(String[] args) { + SpringApplication.run(ServerApplication.class, args); + } +} +---- + +NOTE: `@EnableLocator` can only be used with {data-store-name} server applications. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnableLocator.html[`@EnableLocator` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-manager]] +== Configure an Embedded Manager + +Annotate your Spring `@PeerCacheApplication` or `@CacheServerApplication` class with `@EnableManager` to start +an embedded Manager bound to all NICs listening on the default Manager port, `1099`, as follows: + +[source,java] +---- +@SpringBootApplication +@CacheServerApplication +@EnableManager +public class ServerApplication { + + public static void main(String[] args) { + SpringApplication.run(ServerApplication.class, args); + } +} +---- + +NOTE: `@EnableManager` can only be used with {data-store-name} server applications. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnableManager.html[`@EnableManager` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-httpserver]] +== Configure the Embedded HTTP Server + +Annotate your Spring `@PeerCacheApplication` or `@CacheServerApplication` class with `@EnableHttpService` to start +the embedded HTTP server (Jetty) listening on port `7070`, as follows: + +[source,java] +---- +@SpringBootApplication +@CacheServerApplication +@EnableHttpService +public class ServerApplication { + + public static void main(String[] args) { + SpringApplication.run(ServerApplication.class, args); + } +} +---- + +NOTE: `@EnableHttpService` can only be used with {data-store-name} server applications. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnableHttpService.html[`@EnableHttpService` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-memcachedserver]] +== Configure the Embedded Memcached Server + +Annotate your Spring `@PeerCacheApplication` or `@CacheServerApplication` class with `@EnableMemcachedServer` to start +the embedded Memcached server (Gemcached) listening on port `11211`, as follows: + +[source,java] +---- +@SpringBootApplication +@CacheServerApplication +@EnableMemcachedServer +public class ServerApplication { + + public static void main(String[] args) { + SpringApplication.run(ServerApplication.class, args); + } +} +---- + +NOTE: `@EnableMemcachedServer` can only be used with {data-store-name} server applications. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnableMemcachedServer.html[`@EnableMemcachedServer` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-redisserver]] +== Configure the Embedded Redis Server + +Annotate your Spring `@PeerCacheApplication` or `@CacheServerApplication` class with `@EnableRedisServer` to start +the embedded Redis server listening on port `6379`, as follows: + +[source,java] +---- +@SpringBootApplication +@CacheServerApplication +@EnableRedisServer +public class ServerApplication { + + public static void main(String[] args) { + SpringApplication.run(ServerApplication.class, args); + } +} +---- + +NOTE: `@EnableRedisServer` can only be used with {data-store-name} server applications. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnableRedisServer.html[`@EnableRedisServer` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-logging]] +== Configure Logging + +To configure or adjust {data-store-name} logging, annotate your Spring, {data-store-name} client or server +application class with `@EnableLogging`, as follows: + +[source,java] +---- +@SpringBootApplication +@ClientCacheApplication +@EnableLogging(logLevel="trace") +public class ClientApplication { + + public static void main(String[] args) { + SpringApplication.run(ClientApplication.class, args); + } +} +---- + +NOTE: Default `log-level` is "`config`". Also, this annotation will not adjust log levels in your application, +only for {data-store-name}. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnableLogging.html[`@EnableLogging` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-statistics]] +== Configure Statistics + +To gather {data-store-name} statistics at runtime, annotate your Spring, {data-store-name} client or server +application class with `@EnableStatistics`, as follows: + +[source,java] +---- +@SpringBootApplication +@ClientCacheApplication +@EnableStatistics +public class ClientApplication { + + public static void main(String[] args) { + SpringApplication.run(ClientApplication.class, args); + } +} +---- + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnableStatistics.html[`@EnableStatistics` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-pdx]] +== Configure PDX + +To enable {data-store-name} PDX serialization, annotate your Spring, {data-store-name} client or server +application class with `@EnablePdx`, as follows: + +[source,java] +---- +@SpringBootApplication +@ClientCacheApplication +@EnablePdx +public class ClientApplication { + + public static void main(String[] args) { + SpringApplication.run(ClientApplication.class, args); + } +} +---- + +NOTE: {data-store-name} PDX Serialization is an alternative to Java Serialization with many added benefits. For one, +it makes short work of making all of your application domain model types serializable without having to implement +`java.io.Serializable`. + +NOTE: By default, {sdg-acronym} configures the `MappingPdxSerializer` to serialize your application domain model types, +which does not require any special configuration out-of-the-box in order to properly identify application domain objects +that need to be serialized and htne perform the serialization since, the logic in `MappingPdxSerializer` is based on +Spring Data's mapping infrastructure. See <> for more details. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnablePdx.html[`@EnablePdx` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-ssl]] +== Configure SSL + +To enable {data-store-name} SSL, annotate your Spring, {data-store-name} client or server application class +with `@EnableSsl`, as follows: + +[source,java] +---- +@SpringBootApplication +@ClientCacheApplication +@EnableSsl(components = SERVER) +public class ClientApplication { + + public static void main(String[] args) { + SpringApplication.run(ClientApplication.class, args); + } +} +---- + +NOTE: Minimally, {data-store-name} requires you to specify a keystore & truststore using the appropriate configuration +attributes or properties. Both keystore & truststore configuration attributes or properties may refer to the same +`KeyStore` file. Additionally, you will need to specify a username and password to access the `KeyStore` file +if the file has been secured. + +NOTE: {data-store-name} SSL allows you to configure the specific components of the system that require TLS, such as +client/server, Locators, Gateways, etc. Optionally, you can specify that all components of {data-store-name} +use SSL with "`ALL`". + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html[`@EnableSsl` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-security]] +== Configure Security + +To enable {data-store-name} security, annotate your Spring, {data-store-name} client or server application class +with `@EnableSecurity`, as follows: + +[source,java] +---- +@SpringBootApplication +@ClientCacheApplication +@EnableSecurity +public class ClientApplication { + + public static void main(String[] args) { + SpringApplication.run(ClientApplication.class, args); + } +} +---- + +NOTE: On the server, you must configure access to the auth credentials. You may either implement the {data-store-name} +{x-data-store-javadoc}/org/apache/geode/security/SecurityManager.html[`SecurityManager`] interface or declare +1 or more Apache Shiro `Realms`. See <> for more details. + +NOTE: On the client, you must configure a username and password. See <> +for more details. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSecurity.html[`@EnableSecurity` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-properties]] +== Configure {data-store-name} Properties + +To configure other, low-level {data-store-name} properties not covered by the feature-oriented, {sdg-acronym} +configuration annotations, annotate your Spring, {data-store-name} client or server application class +with `@GemFireProperties`, as follows: + +[source,java] +---- +@SpringBootApplication +@PeerCacheApplication +@EnableGemFireProperties( + cacheXmlFile = "/path/to/cache.xml", + conserveSockets = true, + groups = "GroupOne", + remoteLocators = "lunchbox[11235],mailbox[10101],skullbox[12480]" +) +public class ServerApplication { + + public static void main(String[] args) { + SpringApplication.run(ServerApplication.class, args); + } +} +---- + +NOTE: Some {data-store-name} properties are client-side only while others are server-side only. Please review the +{data-store-name} {x-data-store-docs}/reference/topics/gemfire_properties.html[docs] for the appropriate use +of each property. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnableGemFireProperties.html[`@EnableGemFireProperties` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-caching]] +== Configure Caching + +To use {data-store-name} as a _caching provider_ in Spring's {spring-framework-docs}/integration.html#cache[_Cache Abstraction_], +and have {sdg-acronym} automatically create {data-store-name} Regions for the caches required by your application +service components, then annotate your Spring, {data-store-name} client or server application class +with `@EnableGemfireCaching` and `@EnableCachingDefinedRegions`, as follows: + +[source,java] +---- +@SpringBootApplication +@ClientCacheApplication +@EnableCachingDefinedRegions +@EnableGemfireCaching +public class ClientApplication { + + public static void main(String[] args) { + SpringApplication.run(ClientApplication.class, args); + } +} +---- + +Then, simply go on to define the application services that require caching, as follows: + +[source,java] +---- +@Service +public class BookService { + + @Cacheable("Books") + public Book findBy(ISBN isbn) { + ... + } +} +---- + +NOTE: `@EnableCachingDefinedRegions` is optional. That is, you may manually define your Regions if you desire. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnableCachingDefinedRegions.html[`@EnableCachingDefinedRegions` Javadoc]. + +See {sdg-javadoc}/org/springframework/data/gemfire/cache/config/EnableGemfireCaching.html[`@EnableGemfireCaching` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-repositories]] +== Configure Regions, Indexes, Repositories and Entities for Persistent Applications + +To make short work of creating Spring, {data-store-name} persistent client or server applications, annotate your +application class with `@EnableEntityDefinedRegions`, `@EnableGemfireRepositories` and `@EnableIndexing`, as follows: + +[source,java] +---- +@SpringBootApplication +@ClientCacheApplication +@EnableEntityDefinedRegions(basePackageClasses = Book.class) +@EnableGemfireRepositories(basePackageClasses = BookRepository.class) +@EnableIndexing +public class ClientApplication { + + public static void main(String[] args) { + SpringApplication.run(ClientApplication.class, args); + } +} +---- + +NOTE: The `@EnableEntityDefinedRegions` annotation is required when using the `@EnableIndexing` annotation. +See <> for more details. + +Next, define your entity class and use the `@Region` mapping annotation to specify the Region in which your entity +will be stored. Use the `@Indexed` annotation to define Indexes on entity fields used in your application queries, +as follows: + +[source,java] +---- +package example.app.model; + +import ...; + +@Region("Books") +public class Book { + + @Id + private ISBN isbn; + + @Indexed; + private Author author; + + @Indexed + private LocalDate published; + + @LuceneIndexed + private String title; + +} +---- + +NOTE: The `@Region("Books")` entity class annotation is used by the `@EnableEntityDefinedRegions` to determine +the Regions required by the application. See <> and <> +for more details. + +Finally, define your CRUD Repository with simple queries to persist and access `Books`, as follows: + +[source,java] +---- +package example.app.repo; + +import ...; + +public interface BookRepository extends CrudRepository { + + List findByAuthorOrderByPublishedDesc(Author author); + +} +---- + +TIP: See <> for more details. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnableEntityDefinedRegions.html[`@EnableEntityDefinedRegions` Javadoc]. + +See {sdg-javadoc}/org/springframework/data/gemfire/repository/config/EnableGemfireRepositories.html[`@EnableGemfireRepositories` Javadoc]. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnableIndexing.html[`@EnableIndexing` Javadoc]. + +See {sdg-javadoc}/org/springframework/data/gemfire/mapping/annotation/Region.html[`@Region` Javadoc]. + +See {sdg-javadoc}/org/springframework/data/gemfire/mapping/annotation/Indexed.html[`@Indexed` Javadoc]. + +See {sdg-javadoc}/org/springframework/data/gemfire/mapping/annotation/LuceneIndexed.html[`@LuceneIndexed` Javadoc]. + +See <> for more details. + +See <> for more details. + +[[bootstap-annotations-quickstart-functions]] +== Configure Functions + +{data-store-name} Functions are useful in distributed compute scenarios where a potentially expensive computation +requiring data can be performed in parallel across the nodes in the cluster. In this case, it is more efficient +to bring the logic to where the data is located (stored) rather than requesting and fetching the data to be processed +by the computation. + +Use the `@EnableGemfireFunctions` along with the `@GemfireFunction` annotation to enable {data-store-name} Functions +definitions implemented as methods on POJOs, as follows: + +[source, java] +---- +@PeerCacheApplication +@EnableGemfireFunctions +class ServerApplication { + + public static void main(String[] args) { + SpringApplication.run(ServerApplication.class, args); + } + + @GemfireFunction + Integer computeLoyaltyPoints(Customer customer) { + ... + } +} +---- + +Use the `@EnableGemfireFunctionExecutions` along with 1 of the Function calling annotations: `@OnMember`, `@OnMembers`, +`@OnRegion`, `@OnServer` and `@OnServers`. + +[source, java] +---- +@ClientCacheApplication +@EnableGemfireFunctionExecutions(basePackageClasses = CustomerRewardsFunction.class) +class ClientApplication { + + public static void main(String[] args) { + SpringApplication.run(ClientApplication.class, args); + } +} + +@OnRegion("Customers") +interface CustomerRewardsFunctions { + + Integer computeLoyaltyPoints(Customer customer); + +} +---- + +See {sdg-javadoc}/org/springframework/data/gemfire/function/config/EnableGemfireFunctions.html[`@EnableGemfireFunctions` Javadoc]. + +See {sdg-javadoc}/org/springframework/data/gemfire/function/annotation/GemfireFunction.html[`@GemfireFunction` Javadoc]. + +See {sdg-javadoc}/org/springframework/data/gemfire/function/config/EnableGemfireFunctionExecutions.html[`@EnableGemfireFunctionExecutions` Javadoc]. + +See {sdg-javadoc}/org/springframework/data/gemfire/function/annotation/OnMember.html[`@OnMember` Javadoc], +{sdg-javadoc}/org/springframework/data/gemfire/function/annotation/OnMembers.html[`@OnMembers` Javadoc], +{sdg-javadoc}/org/springframework/data/gemfire/function/annotation/OnRegion.html[`@OnRegion` Javadoc], +{sdg-javadoc}/org/springframework/data/gemfire/function/annotation/OnServer.html[`@OnServer` Javadoc], +and {sdg-javadoc}/org/springframework/data/gemfire/function/annotation/OnServers.html[`@OnServers` Javadoc]. + +See <> for more details. + +[[bootstap-annotations-quickstart-continuousquery]] +== Configure Continuous Query + +Real-time, event stream processing is becoming an increasingly important task for data-intensive applications, +primarily in order to respond to user requests in a timely manner. {data-store-name} Continuous Query (CQ) +will help you achieve this rather complex task quite easily. + +Enable CQ by annotating your application class with `@EnableContinuousQueries` and define your CQs along with +the associated event handlers, as follows: + +[source,java] +---- +@ClientCacheApplication +@EnableContinuousQueries +class ClientApplication { + + public static void main(String[] args) { + SpringApplication.run(ClientApplication.class, args); + } +} +---- + +Then, define your CQs by annotating the associated handler method with `@ContinousQuery`, as follows: + +[source,java] +---- +@Service +class CustomerService { + + @ContinuousQuery(name = "CustomerQuery", query = "SELECT * FROM /Customers c WHERE ...") + public void process(CqEvent event) { + ... + } +} +---- + +Anytime an event occurs changing the `Customer` data to match the predicate in your CQ query, the `process` method +will be called. + +NOTE: {data-store-name} CQ is a client-side feature only. + +See {sdg-javadoc}/org/springframework/data/gemfire/config/annotation/EnableContinuousQueries.html[`@EnableContinuousQueries` Javadoc]. + +See {sdg-javadoc}/org/springframework/data/gemfire/listener/annotation/ContinuousQuery.html[`@ContinuousQuery` Javadoc]. + +See <> and <> for more details. diff --git a/src/main/asciidoc/reference/bootstrap-annotations.adoc b/src/main/asciidoc/reference/bootstrap-annotations.adoc index 4a61c8ac..e5f0e0f2 100644 --- a/src/main/asciidoc/reference/bootstrap-annotations.adoc +++ b/src/main/asciidoc/reference/bootstrap-annotations.adoc @@ -1,13 +1,18 @@ [[bootstrap-annotation-config]] = Bootstrapping {data-store-name} using Spring Annotations -{sdg-name} (SDG) 2.0 introduces a new annotation-based configuration model +{sdg-name} ({sdg-acronym}) 2.0 introduces a new annotation-based configuration model to configure and bootstrap {data-store-name} using the Spring container. The primary motivation for introducing an annotation-based approach to the configuration of {data-store-name} -in a Spring context is to enable application developers to _get up and running_ as _quickly_ +in a Spring context is to enable Spring application developers to _get up and running_ as _quickly_ and as _easily_ as possible. +Let's get started! + +TIP: If you would like to get started even faster, refer to +the <> section. + [[bootstrap-annotation-config-introduction]] == Introduction @@ -32,10 +37,10 @@ Further complexity arises from the different supported topologies: The annotation-based configuration model aims to simplify all this and more. The annotation-based configuration model is an alternative to XML-based configuration using {sdg-name}'s XML namespace. -With XML, you could use the `gfe` XML schema for configuration and the `gfe-data` XML schema for data access -related concerns. See "<>" for more details. +With XML, you could use the `gfe` XML schema for configuration and the `gfe-data` XML schema for data access. +See "<>" for more details. -NOTE: As of SDG 2.0, the annotation-based configuration model does not yet support the configuration of +NOTE: As of {sdg-acronym} 2.0, the annotation-based configuration model does not yet support the configuration of {data-store-name}'s WAN components and topology. Like Spring Boot, {sdg-name}'s annotation-based configuration model was designed as an opinionated, @@ -46,9 +51,9 @@ By following convention, all annotations provide reasonable and sensible default The default value for a given annotation attribute directly corresponds to the default value provided in {data-store-name} for the same configuration property. -The intention is to let you enable a {data-store-name} feature or an embedded service by declaring the annotation -on your Spring `@Configuration` or `@SpringBootApplication` class without needing to unnecessarily configure -a large number of properties just to use the feature. +The intention is to let you enable {data-store-name} features or an embedded services by declaring the appropriate +annotation on your Spring `@Configuration` or `@SpringBootApplication` class without needing to unnecessarily configure +a large number of properties just to use the feature or service. Again, _getting started_, _quickly_ and as _easily_, is the primary objective. @@ -57,7 +62,8 @@ and {sdg-name}'s annotation-based configuration quietly backs away. You need onl you wish to adjust. Also, as we will see later in this document, there are several ways to configure a {data-store-name} feature or embedded service by using the annotations. -You can find all the new SDG Java `Annotations` in the `org.springframework.data.gemfire.config.annotation` package. +You can find all the new {sdg-acronym} Java `Annotations` in the `org.springframework.data.gemfire.config.annotation` +package. [[bootstrap-annotation-config-geode-applications]] == Bootstrapping {data-store-name} Applications with Spring @@ -1399,6 +1405,81 @@ and configure the values of these `@EnableOffHeap` annotation attributes. See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableOffHeap.html[`@EnableOffHeap` annotation Javadoc] for more details. +[[bootstrap-annotation-config-region-disk-stores]] +=== Configuring Disk Stores + +Alternatively, you can configure Regions to persist data to disk. You can also configure Regions to overflow +data to disk when Region entries are evicted. In both cases, a `DiskStore` is required to persist and/or overflow +the data. When an explicit `DiskStore` has not been configured for a Region with persistence or overflow, +{data-store-name} uses the `DEFAULT` `DiskStore`. + +We recommend defining Region-specific `DiskStores` when persisting and/or overflowing data to disk. + +{sdg-name} provides annotation support for defining and creating application Region `DiskStores` +by annotating the application class with the `@EnableDiskStore` and `@EnableDiskStores` annotations. + +TIP: `@EnableDiskStores` is a composite annotation for aggregating one or more `@EnableDiskStore` annotations. + +For example, while `Book` information might mostly consist of reference data from some external data source +(such as Amazon), `Order` data is most likely going to be transactional in nature and something the application +is going to need to retain (and maybe even overflow to disk if the transaction volume is high enough) -- +or so any book publisher and author hopes, anyway. + +Using the `@EnableDiskStore` annotation, you can define and create a `DiskStore` as follows: + +.Spring application defining a `DiskStore` +[source, java] +---- +@SpringBootApplication +@PeerCacheApplication +@EnableDiskStore(name = "OrdersDiskStore", autoCompact = true, compactionThreshold = 70, + maxOplogSize = 512, diskDirectories = @DiskDiretory(location = "/absolute/path/to/order/disk/files")) +class ServerApplication { .. } +---- + +Again, more than one `DiskStore` can be defined by using the composite, `@EnableDiskStores` annotation. + +As with other annotations in {sdg-name}'s annotation-based configuration model, both `@EnableDiskStore` +and `@EnableDiskStores` have many attributes along with associated configuration properties to customize +the `DiskStores` created at runtime. + +Additionally, the `@EnableDiskStores` annotation defines certain common `DiskStore` attributes that apply to all +`DiskStores` created from `@EnableDiskStore` annotations composed with the `@EnableDiskStores` annotation itself. +Individual `DiskStore` configuration override a particular global setting, but the `@EnableDiskStores` annotation +conveniently defines common configuration attributes that apply across all `DiskStores` aggregated by the annotation. + +{sdg-name} also provides the `DiskStoreConfigurer` callback interface, which can be declared in Java configuration +and used instead of configuration properties to customize a `DiskStore` at runtime, as the following example shows: + +.Spring application with custom DiskStore configuration +[source, java] +---- +@SpringBootApplication +@PeerCacheApplication +@EnableDiskStore(name = "OrdersDiskStore", autoCompact = true, compactionThreshold = 70, + maxOplogSize = 512, diskDirectories = @DiskDiretory(location = "/absolute/path/to/order/disk/files")) +class ServerApplication { + + @Bean + DiskStoreConfigurer ordersDiskStoreDiretoryConfigurer( + @Value("${orders.disk.store.location}") String location) { + + return (beanName, diskStoreFactoryBean) -> { + + if ("OrdersDiskStore".equals(beanName) { + diskStoreFactoryBean.setDiskDirs(Collections.singletonList(new DiskDir(location)); + } + } + } +} +---- + +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableDiskStore.html[`@EnableDiskStore`] and https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableDiskStores.html[`@EnableDiskStores`] annotation +Javadoc for more details on the available attributes as well as associated configuration properties. + +More details on {data-store-name} Region persistence and overflow (using DiskStores) can be found +{x-data-store-docs}/developing/storing_data_on_disk/chapter_overview.html[here]. + [[bootstrap-annotation-config-region-indexes]] === Configuring Indexes @@ -1544,7 +1625,7 @@ Essentially, indexes are defined from fields or properties on the entity class t to inspect the entity's fields and properties for the presence of index annotations. Without this scan, index annotations cannot be found. We also strongly recommend that you limit the scope of the scan. -While Lucene queries are not (yet) supported on {sdg-name} repositories, SDG does provide comprehensive +While Lucene queries are not (yet) supported on {sdg-name} repositories, {sdg-acronym} does provide comprehensive https://docs.spring.io/spring-data-gemfire/docs/current/reference/html/#bootstrap:lucene[support] for {data-store-name} Lucene queries by using the familiar Spring template design pattern. @@ -1585,81 +1666,6 @@ More details on {data-store-name} indexes can be found More details on {data-store-name} Lucene queries can be found {x-data-store-docs}/tools_modules/lucene_integration.html[here]. -[[bootstrap-annotation-config-region-continuous-queries]] -=== Configuring Disk Stores - -You can configure Regions to persist data to disk. You can also configure Regions to overflow data to disk when -Region entries are evicted. In both cases, a `DiskStore` is required to persist and/or overflow the data. -When an explicit `DiskStore` has not been configured for a Region with persistence or overflow, {data-store-name} -uses the `DEFAULT` `DiskStore`. - -We recommend defining Region-specific `DiskStores` when persisting and/or overflowing data to disk. - -{sdg-name} provides annotation support for defining and creating application Region `DiskStores` -by annotating the application class with the `@EnableDiskStore` and `@EnableDiskStores` annotations. - -TIP: `@EnableDiskStores` is a composite annotation for aggregating one or more `@EnableDiskStore` annotations. - -For example, while `Book` information might mostly consist of reference data from some external data source -(such as Amazon), `Order` data is most likely going to be transactional in nature and something the application -is going to need to retain (and maybe even overflow to disk if the transaction volume is high enough) -- -or so any book publisher and author hopes, anyway. - -Using the `@EnableDiskStore` annotation, you can define and create a `DiskStore` as follows: - -.Spring application defining a `DiskStore` -[source, java] ----- -@SpringBootApplication -@PeerCacheApplication -@EnableDiskStore(name = "OrdersDiskStore", autoCompact = true, compactionThreshold = 70, - maxOplogSize = 512, diskDirectories = @DiskDiretory(location = "/absolute/path/to/order/disk/files")) -class ServerApplication { .. } ----- - -Again, more than one `DiskStore` can be defined by using the composite, `@EnableDiskStores` annotation. - -As with other annotations in {sdg-name}'s annotation-based configuration model, both `@EnableDiskStore` -and `@EnableDiskStores` have many attributes along with associated configuration properties to customize -the `DiskStores` created at runtime. - -Additionally, the `@EnableDiskStores` annotation defines certain common `DiskStore` attributes that apply to all -`DiskStores` created from `@EnableDiskStore` annotations composed with the `@EnableDiskStores` annotation itself. -Individual `DiskStore` configuration override a particular global setting, but the `@EnableDiskStores` annotation -conveniently defines common configuration attributes that apply across all `DiskStores` aggregated by the annotation. - -{sdg-name} also provides the `DiskStoreConfigurer` callback interface, which can be declared in Java configuration -and used instead of configuration properties to customize a `DiskStore` at runtime, as the following example shows: - -.Spring application with custom DiskStore configuration -[source, java] ----- -@SpringBootApplication -@PeerCacheApplication -@EnableDiskStore(name = "OrdersDiskStore", autoCompact = true, compactionThreshold = 70, - maxOplogSize = 512, diskDirectories = @DiskDiretory(location = "/absolute/path/to/order/disk/files")) -class ServerApplication { - - @Bean - DiskStoreConfigurer ordersDiskStoreDiretoryConfigurer( - @Value("${orders.disk.store.location}") String location) { - - return (beanName, diskStoreFactoryBean) -> { - - if ("OrdersDiskStore".equals(beanName) { - diskStoreFactoryBean.setDiskDirs(Collections.singletonList(new DiskDir(location)); - } - } - } -} ----- - -See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableDiskStore.html[`@EnableDiskStore`] and https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableDiskStores.html[`@EnableDiskStores`] annotation -Javadoc for more details on the available attributes as well as associated configuration properties. - -More details on {data-store-name} Region persistence and overflow (using DiskStores) can be found -{x-data-store-docs}/developing/storing_data_on_disk/chapter_overview.html[here]. - [[bootstrap-annotation-config-continuous-queries]] == Configuring Continuous Queries @@ -2164,9 +2170,9 @@ the next person who has to maintain the code (which might be you at some point i [[bootstrap-annotation-config-tips-undocumented-annotations]] === Additional Configuration-based Annotations -The following SDG Annotations were not discussed in this reference documentation, either because the annotation supports -a deprecated feature of {data-store-name} or because there are better, alternative ways to accomplishing -the function that the annotation provides: +The following {sdg-acronym} Annotations were not discussed in this reference documentation, either because +the annotation supports a deprecated feature of {data-store-name} or because there are better, alternative ways +to accomplishing the function that the annotation provides: * `@EnableAuth`: Enables {data-store-name}'s old authentication and authorization security model. (Deprecated. {data-store-name}'s new integrated security framework can be enabled on both clients and servers by using {sdg-acronym}'s diff --git a/src/main/java/org/springframework/data/gemfire/config/annotation/support/AbstractAnnotationConfigSupport.java b/src/main/java/org/springframework/data/gemfire/config/annotation/support/AbstractAnnotationConfigSupport.java index 74232e75..9fe0c09b 100644 --- a/src/main/java/org/springframework/data/gemfire/config/annotation/support/AbstractAnnotationConfigSupport.java +++ b/src/main/java/org/springframework/data/gemfire/config/annotation/support/AbstractAnnotationConfigSupport.java @@ -119,7 +119,7 @@ public abstract class AbstractAnnotationConfigSupport * @return a boolean value indicating whether the given {@link Object} has value. */ protected static boolean hasValue(Object value) { - return Optional.ofNullable(value).isPresent(); + return value != null; } /** @@ -177,7 +177,6 @@ public abstract class AbstractAnnotationConfigSupport return evaluationContext; } - /* (non-Javadoc) */ private void configureTypeConverter(EvaluationContext evaluationContext, BeanFactory beanFactory) { Optional.ofNullable(evaluationContext)