RegionService (Apache Geode 1.14.2)
Date: 2021-12-14

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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and 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 Detail

    - #### 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.
      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.

    - #### 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.

    - #### 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