[[samples]]
= Sample Applications

NOTE: Sample applications are now maintained in the
https://github.com/spring-projects/spring-gemfire-examples[Spring Pivotal GemFire Examples] repository.

The _Spring Data for Pivotal GemFire_ project also includes one sample application.  Named "Hello World", the sample application
demonstrates how to configure and use Pivotal GemFire inside a _Spring_ application.  At runtime, the sample offers
a *shell* to the user allowing her to run various commands against the data grid.  It provides an excellent
starting point for users unfamiliar with the essential components or with _Spring_ and Pivotal GemFire concepts.

The sample is bundled with the distribution and is Maven-based.  A developer can easily import them into any
Maven-aware IDE (such as https://spring.io/tools/sts[Spring Tool Suite]) or run them from the command-line.

[[samples:hello-world]]
== Hello World

The Hello World sample application demonstrates the core functionality of the _Spring Data for Pivotal GemFire_ project.
It bootstraps Pivotal GemFire, configures it, executes arbitrary commands against the cache and shuts it down
when the application exits.  Multiple instances of the application can be started at the same time
and they will work together, sharing data without any user intervention.

.Running under Linux
NOTE: If you experience networking problems when starting Pivotal GemFire or the samples, try adding the following
system property `java.net.preferIPv4Stack=true` to the command line (e.g. `-Djava.net.preferIPv4Stack=true`).
For an alternative (global) fix especially on Ubuntu see https://jira.spring.io/browse/SGF-28[SGF-28].

[[samples:hello-world:start-stop]]
=== Starting and stopping the sample

Hello World is designed as a stand-alone Java application. It features a `main` class which can be started
either from your IDE of choice (in Eclipse/STS through `Run As/Java Application`) or from the command-line
through Maven using `mvn exec:java`.  A developer can also use `java` directly on the resulting artifact
if the classpath is properly set.

To stop the sample, simply type `exit` at the command-line or press `Ctrl+C` to stop the JVM and shutdown
the _Spring_ container.

[[samples:hello-world:run]]
=== Using the sample

Once started, the sample will create a shared data grid and allow the user to issue commands against it.
The output will likely look as follows:

[source]
----
INFO: Created Pivotal GemFire Cache [Spring Pivotal GemFire World] v. X.Y.Z
INFO: Created new cache region [myWorld]
INFO: Member xxxxxx:50694/51611 connecting to region [myWorld]
Hello World!
Want to interact with the world ? ...
Supported commands are:

get <key> - retrieves an entry (by key) from the grid
put <key> <value> - puts a new entry into the grid
remove <key> - removes an entry (by key) from the grid
...
----

For example to add new items to the grid one can use:

[source]
----
-> Bold Section qName:emphasis level:5, chunks:[put 1 unu] attrs:[role:bold]
INFO: Added [1=unu] to the cache
null
-> Bold Section qName:emphasis level:5, chunks:[put 1 one] attrs:[role:bold]
INFO: Updated [1] from [unu] to [one]
unu
-> Bold Section qName:emphasis level:5, chunks:[size] attrs:[role:bold]
1
-> Bold Section qName:emphasis level:5, chunks:[put 2 two] attrs:[role:bold]
INFO: Added [2=two] to the cache
null
-> Bold Section qName:emphasis level:5, chunks:[size] attrs:[role:bold]
2
----

Multiple instances can be ran at the same time.  Once started, the new VMs automatically see the existing Region
and its information:

[source]
----
INFO: Connected to Distributed System ['Spring Pivotal GemFire World'=xxxx:56218/49320@yyyyy]
Hello World!
...

-> Bold Section qName:emphasis level:5, chunks:[size] attrs:[role:bold]
2
-> Bold Section qName:emphasis level:5, chunks:[map] attrs:[role:bold]
[2=two] [1=one]
-> Bold Section qName:emphasis level:5, chunks:[query length = 3] attrs:[role:bold]
[one, two]
----

Experiment with the example, start (and stop) as many instances as you want, run various commands in one instance
and see how the others react.  To preserve data, at least one instance needs to be alive all times.  If all instances
are shutdown, the grid data is completely destroyed.

[[samples:hello-world:explained]]
=== Hello World Sample Explained

Hello World uses both _Spring_ XML and annotations for its configuration.  The initial bootstrapping configuration is
`app-context.xml`, which includes the cache configuration defined in the `cache-context.xml` file
and performs classpath
http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-classpath-scanning[component scanning]
for _Spring_
http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-annotation-config[components].

The cache configuration defines the Pivotal GemFire cache, Region and for illustrative purposes, a simple `CacheListener`
that acts as a logger.

The main *beans* are `HelloWorld` and `CommandProcessor` which rely on the `GemfireTemplate` to interact with
the distributed fabric.  Both classes use annotations to define their dependency and life-cycle callbacks.
