RegionService (Apache Geode 2.0.2)
Description: declaration: package: org.apache.geode.cache, interface: RegionService

Package org.apache.geode.cache

# Interface RegionService

All Superinterfaces:
  `AutoCloseable`

All Known Subinterfaces:
  `Cache`, `ClientCache`, `GemFireCache`

public interface RegionService extends AutoCloseable
A RegionService provides access to existing `regions` that exist in a `GemFire cache`. Regions can be obtained using `getRegion(java.lang.String)` and queried using `getQueryService()`. The service should be `closed` to free up resources once it is no longer needed. Once it `is closed` any attempt to use it or any `regions` obtained from it will cause a `CacheClosedException` to be thrown.

Instances of the interface are created using one of the following methods:

- `CacheFactory.create()` creates a server instance of `Cache`.
- `ClientCacheFactory.create()` creates a client instance of `ClientCache`.
- `ClientCache.createAuthenticatedView(Properties)` creates a client multiuser authenticated cache view.

Since:
  GemFire 6.5

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Terminates this region service and releases all its resources.
  `PdxInstance`
  `createPdxEnum(String className, String enumName, int enumOrdinal)`
  Creates and returns a PdxInstance that represents an enum value.
  `PdxInstanceFactory`
  `createPdxInstanceFactory(String className)`
  Returns a factory that can create a `PdxInstance`.
  `CancelCriterion`
  `getCancelCriterion()`
  the cancellation criterion for this service
  `JSONFormatter`
  `getJsonFormatter()`
  Returns the JSONFormatter.
  `QueryService`
  `getQueryService()`
  Return the QueryService for this region service.
  `<K, V> Region<K,V>`
  `getRegion(String path)`
  Return the existing region (or subregion) with the specified path.
  `boolean`
  `isClosed()`
  Indicates if this region service has been closed.
  `Set<Region<?,?>>`
  `rootRegions()`
  Returns unmodifiable set of the root regions that are in the region service.

- ## Method Details

  - ### getCancelCriterion

    CancelCriterion getCancelCriterion()
    the cancellation criterion for this service
    Returns:
      the service's cancellation object

  - ### getRegion

    <K, V> Region<K,V> getRegion(String path)
    Return the existing region (or subregion) with the specified path. Whether or not the path starts with a forward slash it is interpreted as a full path starting at a root.
    Type Parameters:
      `K` - the type of keys in the region
      `V` - the type of values in the region
    Parameters:
      `path` - the path to the region
    Returns:
      the Region or null if not found
    Throws:
      `IllegalArgumentException` - if path is null, the empty string, or "/"

  - ### rootRegions

    Set<Region<?,?>> rootRegions()
    Returns unmodifiable set of the root regions that are in the region service. This set is a snapshot; it is not backed by the region service.
    Returns:
      a Set of regions

  - ### createPdxInstanceFactory

    PdxInstanceFactory createPdxInstanceFactory(String className)
    Returns a factory that can create a `PdxInstance`.
    Parameters:
      `className` - the fully qualified class name that the PdxInstance will become when it is fully deserialized unless `PdxInstanceFactory.neverDeserialize()` is called. If className is the empty string then no class versioning will be done for that PdxInstance and `PdxInstanceFactory.neverDeserialize()` will be automatically called on the returned factory.
    Returns:
      the factory
    Throws:
      `IllegalArgumentException` - if className is `null`.
    Since:
      GemFire 6.6.2

  - ### createPdxEnum

    PdxInstance createPdxEnum(String className, String enumName, int enumOrdinal)
    Creates and returns a PdxInstance that represents an enum value.
    Parameters:
      `className` - the name of the enum class
      `enumName` - the name of the enum constant
      `enumOrdinal` - the ordinal value of the enum constant
    Returns:
      a PdxInstance that represents the enum value
    Throws:
      `IllegalArgumentException` - if className or enumName are `null`.
    Since:
      GemFire 6.6.2

  - ### getQueryService

    QueryService getQueryService()
    Return the QueryService for this region service. For a region service in a client the returned QueryService will execute queries on the server. For a region service not in a client the returned QueryService will execute queries on the local and peer regions.
    Returns:
      the QueryService for this region service

  - ### getJsonFormatter

    JSONFormatter getJsonFormatter()
    Returns the JSONFormatter. In the multi-user case, this will return a JSONFormatter that has the knowledge of the user associated with this region service.
    Returns:
      the JSONFormatter

  - ### close

    void close()
    Terminates this region service and releases all its resources. Calls `Region.close()` on each region in the service. After this service is closed, any further method calls on this service or any region object obtained from the service will throw `CacheClosedException`, unless otherwise noted.
    Specified by:
      `close` in interface `AutoCloseable`
    Throws:
      `CacheClosedException` - if the service is already closed.

  - ### isClosed

    boolean isClosed()
    Indicates if this region service has been closed. After a new service is created, this method returns false; After close is called on this service, this method returns true. This method does not throw `CacheClosedException` if the service is closed.
    Returns:
      true, if this service has just been created or has started to close; false, otherwise