gemfire-rest 1.0.2

Python client for GemFire's REST service

# py-gemfire-rest
=================

This library enables your python applications to use GemFire as a datastore. (GemFire is a distributed key-value store. A short tutorial can be found at http://goo.gl/rF93fn). This library exposes Spring's CrudRepository like methods in an effort to simplify GemFire's APIs while still giving access to advanced GemFire features (details below).

## Installation
---------------

Using pip installation is simple

$ sudo pip install gemfire-rest

or from source:

$ sudo python setup.py install

## Quick Start
--------------

1. Start the GemFire REST service by [following the instructions](http://gemfire.docs.pivotal.io/latest/userguide/index.html#gemfire_rest/setup_config.html)
2. Create a Region on the server (Region is a distributed ConcurrentMap in which GemFire stores the data).

gfsh>create region --name=orders --type=PARTITION

3.
```python
>>> from GemfireClient import *
>>> client = GemfireClient(hostname="localhost", port=8080)
>>> myRepo = client.create_repository("orders")
>>> myRepo.save(order)
```

where the order object has an "id" instance variable. The library handles converting the object to/from json.

## API Reference
----------------

This library exercises [GemFire's REST APIs](http://gemfire.docs.pivotal.io/latest/userguide/index.html#gemfire_rest/book_intro.html) for enabling your python application to use GemFire as its datastore. To get started, we create a client by providing a hostname and port for an already running endpoint.
```python
client = GemfireClient(hostname="localhost", port=8080)
```

For each type of Object that we want to store in GemFire, we create a repository (Please not that you will have to create a Region on the server with the same name as the repository).
```python
orders = client.create_repository("orders")
```
The client provides a method to look up all the Regions that have been created on the server already:
```python
client.list_all_regions()
```

GemfireClient also has methods for querying and function execution which we will see later.

### Repository
--------------

Just like Spring's CrudRepository interface, the following methods are available on the Repository
```python
save(entities) #saves one or more entities in GemFire
find(ids) #finds entities with the given ids
find_all() #returns all data in region
exists(id) #checks to see if an entity with the given id exists
delete(entities) #deletes the given entities from GemFire
delete_all() #deletes all data in the GemFire region
```

As the naming suggests, intention of these methods is pretty clear. One thing that needs to be highlighted here is that all entities need an identity; this library uses "id" instance variable as identity. So all entities that are stored in GemFire need to have an instance variable named "id".

### Region
----------

For advanced operations, we also provide access to Region, which defines the following methods:
```python
create(key, value) #will insert only if key does not exists
update(key, value) #will update only if the key exists
keys() # returns all keys in the region
compare_and_set(key, oldvalue, newvalue) #sets the key to newvalue only if current value is equal ot oldvalue
```

### Querying
------------
GemfireClient provides API for running ad-hoc [OQL queries](http://gemfire.docs.pivotal.io/latest/userguide/index.html#developing/querying_basics/chapter_overview.html) on the server.
```python
adhoc_query(query_string) #OQL query string
```

For faster performance, you will want to run prepared OQL queries. GemfireClient provides the following APIs for this:
```python
new_query(query_id, query_string) #registers and prepares the OQL query on the server
run_query(query_id, query_args) #runs the query with specified parameters
```