1 Introduction

This document defines the feature and API enhancements for improving usability of GemFire.

2 Related Documents

  • Usability improvements

3 Terminology

4 Architectural Description

4.1 Client API

This section defines changes to the Client API with an emphasis on how Regions are accessed or created on a server.

4.1.1 Creation of Proxy Regions

Add new createProxyRegion(String) and createProxyRegion(String, Pool) methods to Client Cache:

 

Region customersProxy = c.createProxyRegion("customers"); 
Region ordersProxy = c.createProxyRegion("orders", serverPool);

The createProxyRegion will fail if the Region does not exist on any of the default pool's servers. This operation will always succeed if the Region is defined on at least one of the servers in the distributed system. It will not matter if the Region is available on the server that the client connects to. The server will automatically proxy all requests to the appropriate server(s).

TODO: This method can be invoked multiple times to create multiple proxies with the same name from the same client - or - should allow each thread to have its own ClientCache?

Clients can currently create a client Region that does not exist on any server (yet). We will change this and require that the servers are up and their regions are available before the client starts creating its Regions. A create on a client will fail unless the Region already exists on at least one server.

Additional API support:

 

Region customersProxy = c.createProxyRegion("customers"); 
Region customersProxyAlso = regionService.getRegion("customers"); 
Region parentProxy = customersProxy.getParentRegion(); 
Set<Region> subproxies = parentProxy.subregions(true); 
Set<Region> rootProxies = regionService.rootProxyRegions();

We'll add RegionService#rootProxyRegions() to return a Set of all root level proxy Regions.

RegionService#getRegion(String) will change to return a proxy Region or regular Region if either exists.

Region#getParentRegion() and Region#subregions(boolean) will be changed to return a proxy Region if the Region of context is a proxy Region.

The following methods will be deprecated. The preferred means to get similar information will be to create a proxy Region which will delegate such method calls to the server:

  • Region#keySetOnServer
  • Region#containsKeyOnServer

4.1.2 Additional Support for Proxy Regions

Proxy regions currently perform operations locally. This will be changed to always send the operations to the server. This will change the following operations:

  • Region#getParentRegion maybe
  • Region#getAttributes maybe
  • Region#getAttributesMutator maybe
  • Region#getStatistics maybe
  • Region#localInvalidateRegion noop
  • Region#localDestroyRegion noop
  • Region#close maybe
  • Region#saveSnapshot this might already work
  • Region#loadSnapshot this might already work
  • Region#getSubregion maybe
  • Region#createSubregion maybe
  • Region#subregions maybe
  • Region#getEntry
  • Region#create (will now fail it exists on server)
  • Region#put (will now return old value)
  • Region#localInvalidate noop
  • Region#localDestroy noop
  • Region#keySet
  • Region#values
  • Region#entrySet
  • Region#getUserAttribute maybe
  • Region#setUserAttribute maybe
  • Region#isDestroyed
  • Region#containsValueForKey
  • Region#containsKey
  • Region#getRegionDistributedLock maybe
  • Region#getDistributedLock maybe
  • Region#becomeLockGrantor
  • Region#localClear noop
  • Region#containsValue
  • Region#isEmpty
  • Region#size
  • Region#putIfAbsent
  • Region#remove(key, value)
  • Region#replace

We should discuss if the "local" methods are of any use to a client since it is unclear what server they will be performed on.

Currently operations that are sent to a server must go to the correct server that owns a resource. This will be changed so that the server that a client sends an operation to will automatically forward it to its peer (who may not even have a cache server running) that owns the resource. This will be done for all region ops and queries.

4.1.3 Server Management Service

As introduced in the MBean Federation Spec, the entry point to GemFire Management is through interface ManagementService:

ManagementService service = ManagementService.getManagementService(cache);

When a ClientCache is used as the argument to ManagementService#getManagementService(Cache), it will create a version of the ManagementService which will delegate all operations to the server group the client is connected to. Usage of this ManagementService will utilize the client connection to the server to delegate to the ManagementService on a server.

4.1.2.1 Creating Regions on a Server

GFSH and the JMX APIs will support creating regions on the server. The client can create regions on a server group by using its ManagementService to execute GFSH commands on the server using ManagementService#processComand(String). Using this same API, the client can create or manage anything on the server group(s) its connected to.

DynamicRegionFactory should be deprecated in favor of using the new Management API.

4.2 Cache API

4.2.1 Subregion Creation

Currently no API exists that lets you create a subregion using ClientRegionFactory or RegionFactory. The createSubregion methods on Region all take the old RegionAttributes which is created using the deprecated AttributesFactory. Region#createSubregion will be deprecated if it's not already.

A new createSubregion(Region parent, String name) method will be added to both ClientRegionFactory and RegionFactory. If the parent Region does not exist an exception will be thrown.