[[bootstrap]]
= Bootstrapping Pivotal GemFire with the Spring container

_Spring Data for Pivotal GemFire_ provides full configuration and initialization of the Pivotal GemFire In-Memory Data Grid (IMDG)
using the _Spring_ IoC container.  The framework includes several classes to help simplify the configuration of
Pivotal GemFire components including: Caches, Regions, Indexes, DiskStores, Functions, WAN Gateways, persistence backup
along with several other Distributed System components in order to support a variety of use cases with minimal effort.

NOTE: This section assumes basic familiarity with Pivotal GemFire. For more information,
see the Pivotal GemFire http://geode.apache.org/docs/[product documentation].

[[bootstrap:namespace:xml]]
== Advantages of using Spring over Pivotal GemFire `cache.xml`

_Spring Data for Pivotal GemFire's_ XML namespace supports full configuration of the Pivotal GemFire In-Memory Data Grid (IMDG).
The XML namespace is the preferred way to configure Pivotal GemFire in a _Spring_ context in order to properly
manage Pivotal GemFire's lifecycle inside the _Spring_ container.  While support for Pivotal GemFire's native `cache.xml` persists
for legacy reasons, Pivotal GemFire application developers are encouraged to do everything in _Spring_ XML to take advantage of
the many wonderful things _Spring_ has to offer such as modular XML configuration, property placeholders and overrides,
SpEL, and environment profiles.  Behind the XML namespace, _Spring Data for Pivotal GemFire_ makes extensive use of _Spring's_
`FactoryBean` pattern to simplify the creation, configuration and initialization of Pivotal GemFire components.

Pivotal GemFire provides several callback interfaces, such as `CacheListener`, `CacheLoader` and `CacheWriter`,
that allow developers to add custom event handlers. Using _Spring's_ IoC container, these callbacks may be configured
as normal _Spring_ beans and injected into Pivotal GemFire components. This is a significant improvement over native `cache.xml`,
which provides relatively limited configuration options and requires callbacks to implement Pivotal GemFire's `Declarable`
interface (see <<apis:declarable>> to see how you can still use `Declarables` within _Spring's_ IoC/DI container).

In addition, IDEs, such as the _Spring Tool Suite_ (STS), provide excellent support for _Spring_ XML namespaces
including code completion, pop-up annotations, and real time validation, making them easy to use.

[[bootstrap:namespace]]
== Using the Core Namespace

To simplify configuration, _Spring Data for Pivotal GemFire_ provides a dedicated XML namespace for configuring core Pivotal GemFire
components. It is possible to configure beans directly using _Spring's_ standard `<bean>` definition. However,
all bean properties are exposed via the XML namespace so there is little benefit to using raw bean definitions.
For more information about XML Schema-based configuration in _Spring_, see the
http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#xsd-config[appendix]
in the _Spring Framework_ reference documentation.

NOTE: _Spring Data Repository_ support uses a separate XML namespace. See <<gemfire-repositories>> for more information
on how to configure _Spring Data for Pivotal GemFire_ Repositories.

To use the _Spring Data for Pivotal GemFire_ XML namespace, simply declare it in your _Spring_ XML configuration meta-data:

[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:gfe="http://www.springframework.org/schema/geode"<!--1--><!--2-->
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="
    http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
    http://www.springframework.org/schema/geode http://www.springframework.org/schema/gemfire/spring-geode.xsd"> <!--3-->

  <bean id ... >

  <gfe:cache ...> <!--4-->

</beans>
----
<1> _Spring Data for Pivotal GemFire_ XML namespace prefix. Any name will do but through out this reference documentation,
`gfe` will be used.
<2> The XML namespace prefix is mapped to the URI.
<3> The XML namespace URI location. Note that even though the location points to an external address (which does exist
and is valid), _Spring_ will resolve the schema locally as it is included in the _Spring Data for Pivotal GemFire_ library.
<4> Example declaration using the XML namespace with the `gfe` prefix.

[NOTE]
====
It is possible to change the default namespace from `beans` to `gfe`. This is useful for XML configuration
composed mainly of Pivotal GemFire components as it avoids declaring the prefix. To achieve this, simply swap the namespace
prefix declaration above:

[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/geode" <!--1-->
  xmlns:beans="http://www.springframework.org/schema/beans" <!--2-->
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="
    http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
    http://www.springframework.org/schema/geode http://www.springframework.org/schema/gemfire/spring-geode.xsd">

  <beans:bean id ... > <!--3-->

  <cache ...> <!--4-->

</beans>
----
<1> The default namespace declaration for this XML document points to the _Spring Data for Pivotal GemFire_ XML namespace.
<2> The `beans` namespace prefix declaration for _Spring's_ raw bean definitions.
<3> Bean declaration using the `beans` namespace. Notice the prefix.
<4> Bean declaration using the `gfe` namespace. Notice the lack of prefix since `gfe` is the default namespace.
====

:leveloffset: +1

include::{basedocdir}/reference/data-access.adoc[]
include::{basedocdir}/reference/cache.adoc[]
include::{basedocdir}/reference/region.adoc[]
include::{basedocdir}/reference/indexing.adoc[]
include::{basedocdir}/reference/diskstore.adoc[]
include::{basedocdir}/reference/snapshot.adoc[]
include::{basedocdir}/reference/function.adoc[]
include::{basedocdir}/reference/gateway.adoc[]

:leveloffset: -1
