org.apache.geode.cache.client (Apache Geode 1.13.2)
Date: 2021-03-08

# Package org.apache.geode.cache.client

The `org.apache.geode.cache.client` package provides APIs used for client connectivity and caching.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  ClientCache | A ClientCache instance controls the life cycle of the local singleton cache in a client.
  ClientRegionFactory<K,V> | A factory for constructing `client cache` `regions`.
  Pool | A pool for connections from a client to a set of GemFire Cache Servers.
  PoolFactory | This interface provides for the configuration and creation of instances of `Pool`.
  SocketFactory | A socket factory used to create sockets from a client to locators or servers.

- Class Summary
  Class | Description
  --- | ---
  ClientCacheFactory | Factory class used to create the singleton `client cache` and connect to one or more GemFire Cache Servers.
  PoolManager | Manages creation and access to `connection pools` for clients.

- Enum Summary
  Enum | Description
  --- | ---
  ClientRegionShortcut | Each enum represents a predefined `RegionAttributes` in a `ClientCache`.

- Exception Summary
  Exception | Description
  --- | ---
  AllConnectionsInUseException | Indicates that the connection pool is at its maximum size and all connections are in use.
  ClientNotReadyException | Deprecated as of 6.5 this exception is no longer thrown by GemFire so any code that catches it should be removed.
  NoAvailableLocatorsException | An exception indicating that there are no active locators available to connect to.
  NoAvailableServersException | An exception indicating that there are no active servers available to connect to.
  ServerConnectivityException | A generic exception indicating that a failure has happened while communicating with a gemfire server.
  ServerOperationException | An exception indicating that a failure has happened on the server while processing an operation that was sent to it by a client.
  ServerRefusedConnectionException | A `ServerRefusedConnectionException` indicates a client attempted to connect to a server, but the handshake was rejected.
  SubscriptionNotEnabledException | An exception indicating that client subscriptions are not enabled on this client, but the client is trying to perform an operation that requires a client subscription, such as `Region.registerInterest(Object)`.

## Package org.apache.geode.cache.client Description

The `org.apache.geode.cache.client` package provides APIs used for client connectivity and caching.

Most clients will only need to create a `ClientCache` using a `ClientCacheFactory`.

A client configures the servers it will connect to by creating one or more `pools`. For most use cases one pool per client is all you need and the easiest way to get a single pool is to use `ClientCacheFactory`. If you do need more than one pool use a `pool factory` obtained from the `pool manager` before you create the cache using `ClientCacheFactory`.

An alternative to these APIs is to use the `pool` XML element as described in the `cache6_5.dtd`.

If you create more than one pool then for regions that will use a pool you need to configure the pool name on the regions. This can be done by setting the pool name on the region using the `API` or using the `pool-name` attribute on the `region-attributes` as described in the `cache6_5.dtd`.

## Client Declarative Caching

A "caching XML file" declares regions, entries, and attributes. When a `ClientCache` is created its contents can be initialized according to a caching XML file. The top level element must be a client-cache element.

The Document Type Definition for a declarative cache XML file can be found in `"doc-files/cache6_5.dtd"`. For examples of declarative cache XML files see example1.