Auto-configuration

This topic discusses Spring Boot for VMware GemFire auto-configuration.

The following Spring Framework, Spring Data for VMware GemFire and Spring Session for VMware GemFire annotations are implicitly declared by Spring Boot for VMware GemFire’s auto-configuration.

@ClientCacheApplication
@EnableGemfireCaching (alternatively, Spring Framework’s @EnableCaching)
@EnableContinuousQueries
@EnableGemfireFunctions
@EnableGemfireFunctionExecutions
@EnableGemfireRepositories
@EnableLogging
@EnablePdx
@EnableSecurity
@EnableSsl
@EnableGemFireHttpSession

You do not need to explicitly declare any of these annotations on your @SpringBootApplication class because they are provided by Spring Boot for VMware GemFire. The only reason you would explicitly declare any of these annotations is to override the Spring Boot, and in particular, Spring Boot for VMware GemFire’s auto-configuration. Otherwise, doing so is unnecessary.

You should read the chapter in Spring Boot’s reference documentation on auto-configuration.

Customizing Auto-configuration

You might ask, “How do I customize the auto-configuration provided by Spring Boot for VMware GemFire if I do not explicitly declare the annotation?”

For example, you may want to customize the member’s name. The @ClientCacheApplication annotation provides the name attribute so that you can set the client member’s name. However, Spring Boot for VMware GemFire has already implicitly declared the @ClientCacheApplication annotation through auto-configuration on your behalf. What do you do?

In this case, Spring Boot for VMware GemFire supplies a few additional annotations.

For example, to set the (client or peer) member’s name, you can use the @UseMemberName annotation:

Example 1. Setting the member’s name using @UseMemberName

@SpringBootApplication
@UseMemberName("MyMemberName")
class SpringBootGemFireClientCacheApplication {
    //...
}

Alternatively, you could set the spring.application.name or the spring.data.gemfire.name property in Spring Boot application.properties:

Example 2. Setting the member’s name using the spring.application.name property

# Spring Boot application.properties

spring.application.name = MyMemberName

Example 3. Setting the member’s name using the spring.data.gemfire.cache.name property

# Spring Boot application.properties

spring.data.gemfire.cache.name = MyMemberName

Note: The spring.data.gemfire.cache.name property is an alias for the spring.data.gemfire.name property. Both properties set the name of the client or peer member node.

In general, there are three ways to customize configuration, even in the context of Spring Boot for VMware GemFire’s auto-configuration:

Using annotations provided by Spring Boot for VMware GemFire for common and popular concerns (such as naming client or peer members with the @UseMemberName annotation or enabling durable clients with the @EnableDurableClient annotation).
Using properties (such as spring.application.name, or spring.data.gemfire.name, or spring.data.gemfire.cache.name).
Using configurers (such as ClientCacheConfigurer).

Deactivating Auto-configuration

Spring Boot’s reference documentation explains how to deactivate Spring Boot auto-configuration.

Deactivating Auto-configuration also explains how to deactivate Spring Boot for VMware GemFire auto-configuration.

In a nutshell, if you want to deactivate any auto-configuration provided by either Spring Boot or Spring Boot for VMware GemFire, declare your intent in the @SpringBootApplication annotation:

Example 4. Deactivating Specific Auto-configuration Classes

@SpringBootApplication(
  exclude = { DataSourceAutoConfiguration.class, PdxAutoConfiguration.class }
)
class SpringBootGemFireClientCacheApplication {
    // ...
}

Caution: Make sure you understand what you are doing when you deactivate auto-configuration.

Overriding Auto-configuration

Overriding explains how to override Spring Boot for VMware GemFire auto-configuration.

In a nutshell, if you want to override the default auto-configuration provided by Spring Boot for VMware GemFire, you must annotate your @SpringBootApplication class with your intent.

For example, suppose you want to configure and bootstrap an VMware GemFire CacheServer application (a peer, not a client):

Example 5. Overriding the default ClientCache Auto-Configuration by configuring and bootstrapping a CacheServer application

@SpringBootApplication
@CacheServerApplication
class SpringBootGemFireCacheServerApplication {
    // ...
}

You can also explicitly declare the @ClientCacheApplication annotation on your @SpringBootApplication class:

Example 6. Overriding by explicitly declaring @ClientCacheApplication

@SpringBootApplication
@ClientCacheApplication
class SpringBootGemFireClientCacheApplication {
    // ...
}

You are overriding Spring Boot for VMware GemFire’s auto-configuration of the ClientCache instance. As a result, you have now also implicitly consented to being responsible for other aspects of the configuration (such as security).

Why does that happen?

It happens because, in certain cases, such as security, certain aspects of security configuration (such as SSL) must be configured before the cache instance is created. Also, Spring Boot always applies user configuration before auto-configuration partially to determine what needs to be auto-configured in the first place.

Caution: Make sure you understand what you are doing when you override auto-configuration.

Replacing Auto-configuration

See the Spring Boot reference documentation on replacing auto-configuration.

Understanding Auto-configuration

This section covers the Spring Boot for VMware GemFire provided auto-configuration classes that correspond to the Spring Data for VMware GemFire annotations in more detail.

To review the complete list of Spring Boot for VMware GemFire auto-configuration classes, see Complete Set of Auto-configuration Classes.

`@ClientCacheApplication`

The Spring Boot for VMware GemFire ClientCacheAutoConfiguration class corresponds to the Spring Data for VMware GemFire @ClientCacheApplication annotation.

Spring Boot for VMware GemFire starts with the opinion that application developers primarily build GemFire client applications when using Spring Boot. This means building Spring Boot applications with an VMware GemFire ClientCache instance connected to a dedicated cluster of VMware GemFire servers that manage the data as part of a client/server topology.

Users do not need to explicitly declare and annotate their @SpringBootApplication class with Spring Data for VMware GemFire’s @ClientCacheApplication annotation. Spring Boot for VMware GemFire’s provided auto-configuration class is already meta-annotated with Spring Data for VMware GemFire’s @ClientCacheApplication annotation. Therefore, you only need to do the following:

@SpringBootApplication
class SpringBootGemFireClientCacheApplication {
    // ...
}

`@EnableGemfireCaching`

The Spring Boot for VMware GemFire CachingProviderAutoConfigurationclass corresponds to the Spring Data for VMware GemFire @EnableGemfireCaching annotation.

If you used the core Spring Framework to configure VMware GemFire as a caching provider in Spring’s Cache Abstraction, you need to:

Example 7. Configuring caching using the Spring Framework

@SpringBootApplication
@EnableCaching
class CachingUsingApacheGemFireConfiguration {

    @Bean
    GemfireCacheManager cacheManager(GemFireCache cache) {

        GemfireCacheManager cacheManager = new GemfireCacheManager();

        cacheManager.setCache(cache);

        return cacheManager;
    }
}

If you use Spring Data for VMware GemFire’s @EnableGemfireCaching annotation, you can simplify the preceding configuration:

Example 8. Configuring caching using Spring Data for VMware GemFire

@SpringBootApplication
@EnableGemfireCaching
class CachingUsingApacheGemFireConfiguration {

}

Also, if you use Spring Boot for VMware GemFire, you need only do:

Example 9. Configuring caching using Spring Boot for VMware GemFire

@SpringBootApplication
class CachingUsingApacheGemFireConfiguration {

}

This lets you focus on the areas in your application that would benefit from caching without having to enable the plumbing. You can then demarcate the service methods in your application that are good candidates for caching:

Example 10. Using caching in your application

@Service
class CustomerService {

    @Caching(cacheable = @Cacheable("CustomersByName"))
    Customer findBy(String name) {
        // ...
    }
}

See Caching with VMware GemFire for more details.

`@EnableContinuousQueries`

The Spring Boot for VMware GemFire ContinuousQueryAutoConfiguration class corresponds to the Spring Data for VMware GemFire @EnableContinuousQueries annotation.

Without having to enable anything, you can annotate your application (POJO) component method(s) with the Spring Data for VMware GemFire @ContinuousQuery annotation to register a CQ and start receiving events. The method acts as a CqEvent handler or, in VMware GemFire’s terminology, the method is an implementation of the CqListener interface (see VMware GemFire Java API Reference).

Example 11. Declare application CQs

@Component
class MyCustomerApplicationContinuousQueries {

    @ContinuousQuery(query = "SELECT customer.* "
        + " FROM /Customers customers"
        + " WHERE customer.getSentiment().name().equalsIgnoreCase('UNHAPPY')")
    public void handleUnhappyCustomers(CqEvent event) {
        // ...
    }
}

As the preceding example shows, you can define the events you are interested in receiving by using an OQL query with a finely tuned query predicate that describes the events of interest and implements the handler method to process the events (such as applying a credit to the customer’s account and following up in email).

See Continuous Query for more details.

`@EnableGemfireFunctionExecutions` and `@EnableGemfireFunctions`

The Spring Boot for VMware GemFire FunctionExecutionAutoConfiguration class corresponds to both the Spring Data for VMware GemFire @EnableGemfireFunctionExecutions and Spring Data for VMware GemFire @EnableGemfireFunctionsannotations.

Whether you need to execute or implement a Function, Spring Boot for VMware GemFire detects the Function definition and auto-configures it appropriately for use in your Spring Boot application. You need only define the Function execution or implementation in a package below the main @SpringBootApplication class:

Example 12. Declare a Function Execution

package example.app.functions;

@OnRegion(region = "Accounts")
interface MyCustomerApplicationFunctions {

    void applyCredit(Customer customer);

}

Then you can inject the Function execution into any application component and use it:

Example 13. Use the Function

package example.app.service;

@Service
class CustomerService {

    @Autowired
    private MyCustomerApplicationFunctions customerFunctions;

    void analyzeCustomerSentiment(Customer customer) {

        // ...

        this.customerFunctions.applyCredit(customer);

        // ...
    }
}

The same pattern basically applies to Function implementations, except in the implementation case, Spring Boot for VMware GemFire registers the Function implementation for use (that is, to be called by a Function execution).

Doing so lets you focus on defining the logic required by your application and not worry about how Functions are registered, called, and so on. Spring Boot for VMware GemFire handles this concern for you.

Note: Function implementations are typically defined and registered on the server side.

See Function Implementations and Executions for more details.

`@EnableGemfireRepositories`

The Spring Boot for VMware GemFire GemFireRepositoriesAutoConfigurationRegistrar class corresponds to the Spring Data for VMware GemFire @EnableGemfireRepositories annotation.

As with Functions, you only need to focus on the data access operations (such as basic CRUD and simple queries) required by your application to carry out its operation, not with how to create and perform them (for example, Region.get(key) and Region.put(key, obj)) or execute them (for example, Query.execute(arguments)).

Start by defining your Spring Data Repository:

Example 14. Define an application-specific Repository

package example.app.repo;

interface CustomerRepository extends CrudRepository<Customer, Long> {

    List<Customer> findBySentimentEqualTo(Sentiment sentiment);

}

Then you can inject the Repository into an application component and use it:

Example 15. Using the application-specific Repository

package example.app.sevice;

@Service
class CustomerService {

    @Autowired
    private CustomerRepository repository;

    public void processCustomersWithSentiment(Sentiment sentiment) {

        this.repository.findBySentimentEqualTo(sentiment)
            .forEach(customer -> { /* ... */ });

        // ...
    }
}

Your application-specific Repository simply needs to be declared in a package below the main @SpringBootApplication class. Again, you are focusing only on the data access operations and queries required to carry out the operations of your application.

See Spring Data Repositories for more details.

`@EnableLogging`

The Spring Boot for VMware GemFire LoggingAutoConfiguration class corresponds to the Spring Data for VMware GemFire @EnableLogging annotation.

Logging is an essential application concern to understand what is happening in the system along with when and where the events occurred. By default, Spring Boot for VMware GemFire auto-configures logging for VMware GemFire with the default log-level, “config”.

You can change any aspect of logging, such as the log-level, in Spring Boot application.properties:

Example 16. Change the log-level for VMware GemFire

# Spring Boot application.properites.

spring.data.gemfire.cache.log-level=debug

Note: The spring.data.gemfire.logging.level property is an alias for spring.data.gemfire.cache.log-level.

You can also configure other aspects, such as the log file size and disk space limits for the filesystem location used to store the VMware GemFire log files at runtime.

Under the hood, VMware GemFire’s logging is based on Log4j. Therefore, you can configure VMware GemFire logging to use any logging provider (such as Logback) and configuration metadata appropriate for that logging provider so long as you supply the necessary adapter between Log4j and whatever logging system you use. For instance, if you include org.springframework.boot:spring-boot-starter-logging, you are using Logback and you will need the org.apache.logging.log4j:log4j-to-slf4j adapter.

`@EnablePdx`

The Spring Boot for VMware GemFire PdxSerializationAutoConfiguration class corresponds to the Spring Data for VMware GemFire @EnablePdx annotation.

Any time you need to send an object over the network or overflow or persist an object to disk, your application domain model object must be serializable. It would be painful to have to implement java.io.Serializable in every one of your application domain model objects (such as Customer) that would potentially need to be serialized.

Furthermore, using Java Serialization may not be ideal (it may not be the most portable or efficient solution) in all cases or even possible in other cases (such as when you use a third-party library over which you have no control).

In these situations, you need to be able to send your object anywhere, anytime without unduly requiring the class type to be serializable and exist on the classpath in every place it is sent. The final destination may not even be a Java application. This is where VMware GemFire PDX Serialization steps in to help.

However, you do not need to know how to configure PDX to identify the application class types that need to be serialized. Instead, you can define your class type as follows:

Example 17. Customer class

@Region("Customers")
class Customer {

    @Id
    private Long id;

    @Indexed
    private String name;

    // ...
}

Spring Boot for VMware GemFire’s auto-configuration handles the rest.

See Data Serialization with PDX for more details.

`@EnableSecurity`

The Spring Boot for VMware GemFire ClientSecurityAutoConfiguration class and PeerSecurityAutoConfiguration class correspond to the Spring Data for VMware GemFire @EnableSecurity annotation, but they apply security (specifically, authentication and authorization (auth) configuration) for both clients and servers.

Configuring your Spring Boot, VMware GemFire ClientCache application to properly authenticate with a cluster of secure VMware GemFire servers is as simple as setting a username and a password in Spring Boot application.properties:

Example 18. Supplying Authentication Credentials

# Spring Boot application.properties

spring.data.gemfire.security.username=Batman
spring.data.gemfire.security.password=r0b!n

Note: Configuring authentication in a managed environment like Tanzu Platform for Cloud Foundry with GemFire requires no additional setup.

Authorization is configured on the server-side and is made simple with Spring Boot for GemFire and the help of Apache Shiro. Of course, this assumes you use Spring Boot for GemFire to configure and bootstrap your GemFire cluster in the first place, which is even easier with Spring Boot for GemFire. See Running a VMware GemFire cluster with Spring Boot from your IDE.

See Security for more details.

`@EnableSsl`

The Spring Boot for GemFire SslAutoConfiguration class corresponds to the Spring Data for GemFire @EnableSsl annotation.

Configuring SSL for secure transport (TLS) between your Spring Boot, VMware GemFire ClientCache application and an VMware GemFire cluster can be a real problem, especially to get right from the start. So, it is something that Spring Boot for VMware GemFire makes as simple as possible.

You can supply a trusted.keystore file containing the certificates in a well-known location (such as the root of your application classpath), and Spring Boot for VMware GemFire’s auto-configuration steps in to handle the rest.

This is useful during development, but we highly recommend using a more secure procedure (such as integrating with a secure credential store like LDAP, CredHub, or Vault) when deploying your Spring Boot application to production.

`@EnableGemFireHttpSession`

The Spring Boot for VMware GemFire SpringSessionAutoConfiguration class corresponds to the Spring Session for VMware GemFire @EnableGemFireHttpSession annotation.

Configuring VMware GemFire to serve as the (HTTP) session state caching provider by using Spring Session requires that you only include the correct module, that is spring-boot-session-3.0-gemfire-10.0:1.0.0:

Example 19. Using Spring Session

<dependency>
    <groupId>com.vmware.gemfire</groupId>
    <artifactId>spring-boot-session-3.0-gemfire-10.0</artifactId>
    <version>1.0.0</version>
</dependency>

With Spring Session and specifically Spring Boot for VMware GemFire on the classpath of your Spring Boot, VMware GemFire ClientCache Web application, you can manage your (HTTP) session state with VMware GemFire. No further configuration is needed. Spring Boot for VMware GemFire auto-configuration detects Spring Session on the application classpath and does the rest.

See Spring Session for more details.

RegionTemplateAutoConfiguration

The Spring Boot for VMware GemFire RegionTemplateAutoConfiguration class has no corresponding Spring Data for VMware GemFire annotation. However, the auto-configuration of a GemfireTemplate for every VMware GemFire Region defined and declared in your Spring Boot application is still supplied by Spring Boot for VMware GemFire.

For example, you can define a Region by using:

Example 20. Region definition using JavaConfig

@Configuration
class GemFireConfiguration {

    @Bean("Customers")
    ClientRegionFactoryBean<Long, Customer> customersRegion(GemFireCache cache) {

        ClientRegionFactoryBean<Long, Customer> customersRegion =
            new ClientRegionFactoryBean<>();

        customersRegion.setCache(cache);
        customersRegion.setShortcut(ClientRegionShortcut.PROXY);

        return customersRegion;
    }
}

Alternatively, you can define the Customers Region by using @EnableEntityDefinedRegions:

Example 21. Region definition using @EnableEntityDefinedRegions

@Configuration
@EnableEntityDefinedRegions(basePackageClasses = Customer.class)
class GemFireConfiguration {

}

Then Spring Boot for VMware GemFire supplies a GemfireTemplate instance that you can use to perform low-level data-access operations (indirectly) on the Customers Region:

Example 22. Use the GemfireTemplate to access the “Customers” Region

@Repository
class CustomersDao {

    @Autowired
    @Qualifier("customersTemplate")
    private GemfireTemplate customersTemplate;

    Customer findById(Long id) {
        return this.customerTemplate.get(id);
    }
}

You need not explicitly configure GemfireTemplates for each Region to which you need low-level data access (such as when you are not using the Spring Data Repository abstraction).

Be careful to qualify the GemfireTemplate for the Region to which you need data access, especially given that you probably have more than one Region defined in your Spring Boot application.

See Data Access with GemfireTemplate for more details.

Customizing Auto-configuration

Deactivating Auto-configuration

Overriding Auto-configuration

Replacing Auto-configuration

Understanding Auto-configuration

@ClientCacheApplication

@EnableGemfireCaching

@EnableContinuousQueries

@EnableGemfireFunctionExecutions and @EnableGemfireFunctions

@EnableGemfireRepositories

@EnableLogging

@EnablePdx

@EnableSecurity

@EnableSsl

@EnableGemFireHttpSession