API Interfaces and Classes

This section gives an overview of the primary interfaces and classes that are provided by the GemFire Administration API package com.gemstone.gemfire.admin. Complete information on the package is available in the online Java API documentation, which you can navigate to through the docs/index.html file.

com.gemstone.gemfire.admin Package

The com.gemstone.gemfire.admin package includes the administration API and the health monitoring API.

System Administration API

The administration API allows you to configure, start, and stop a distributed system and many of its components. The API is made up of distributed system administration, component administration, and cache administration. In addition to the core components listed here, the administration API provides interfaces to issue and handle system member alerts and to monitor statistics. The interfaces for the distributed system and its components have accompanying configuration interfaces, such as ManagedEntityConfig for ManagedEntity.

Distributed System Administration
  • AdminDistributedSystemFactory—Used to define and retrieve an AdminDistributedSystem instance.
  • AdminDistributedSystem—This is the administrative interface for managing a GemFire system. Use the AdminDistributedSystemFactory class to define and create an instance of AdminDistributedSystem. With the AdminDistributedSystem instance, you can perform tasks on the distributed system such as defining, starting, and stopping GemFire cache servers, merging system logs, and obtaining administrative interfaces to applications that host GemFire caches.
  • DistributedSystemConfig—Describes a distributed system to administer by specifying its configuration. The DistributedSystemConfig.ConfigListener interface handles changes to the distributed system configuration.
  • CacheVm—Describes a GemFire cache server system member, which is a long-lived caching application started with the <productDir>/bin/cacheserver script. A cache server is often used as the server process in a client/server architecture. This can be configured through the CacheVmConfig interface. See also vFabric GemFire cacheserver.
Component Administration
  • ManagedEntity—An entity that can be managed, including being started and stopped, through the admin API. Applications cannot be managed in this way, but the other system members can.
  • DistributionLocator—A single locator process, of which a distributed system may use zero or more. Extends the ManagedEntity interface. Locators are system members that can be configured, started and stopped through this interface.
  • CacheVm—Manages a cache server in a distributed system. Extends SystemMember and ManagedEntity.
  • SystemMember—Monitors a member of a GemFire system. Provides access to the member’s cache.
  • SystemMembershipListener—Application plug-in interface whose callback methods are invoked when members join or leave the GemFire distributed system. Receives SystemMembershipEvents.
  • SystemMembershipEvent—An event interface that reports when a member has joined or left the distributed system and provides the member ID of the process that joined or left.
Cache Administration
  • SystemMemberCache—Represents a SystemMember’s cache. Through this interface, like through the local application’s Cache interface, you can create regions in a remote member’s cache. You can also enable and disable server processes and modify cache attributes.
  • SystemMemberCacheServer—Represents a server for a cache, which is instantiated through the SystemMemberCache interface. Through this interface, the server can be configured, started, and stopped. For information on servers, see "Client/Server Architecture and Configuration Basics."
  • SystemMemberRegion—Represents a SystemMember’s view of one of its cache regions. You cannot access a region’s contents through this API.
  • SystemMemberCacheListener—Application plug-in interface whose callback methods can be used to track the life cycle of caches and regions in the GemFire distributed system. Receives SystemMemberCacheEvents and SystemMemberRegionEvents.
  • SystemMemberCacheEvent—An event interface that reports when a cache is created or closed. Provides the member ID and the operation. Extends SystemMembershipEvent.
  • SystemMemberRegionEvent—An event interface that reports when a region has joined or left the distributed system. Provides the member ID, the operation, and the region name. Extends SystemMemberCacheEvent.
  • AlertListener—A log listener whose callback methods are invoked when it receives notice of serious log messages.

This figure shows the relationships between the primary interfaces of the administration API.

Figure 1. GemFire Core Admin Interfaces

The other area of functionality in the administration API is the health monitoring API, discussed in the next section.

System Health Monitoring

The health monitoring API allows you to configure and monitor system health indicators for GemFire distributed systems and their components. There are three levels of health: good health that indicates that all GemFire components are behaving reasonably, okay health that indicates that one or more GemFire components are slightly unhealthy and may need some attention, and poor health that indicates that a GemFire component is unhealthy and needs immediate attention.

Because each GemFire application has its own definition of what it means to be healthy, the metrics that are used to determine health are configurable. GemFireHealthConfig provides methods for configuring the health of the distributed system and members that host Cache instances. Health can be configured on both a global and per-machine basis. GemFireHealthConfig also allows you to configure how often GemFire’s health is evaluated.

The health administration APIs allow you to configure performance thresholds for each component type in the distributed system (including the distributed system itself). These threshold settings are compared to system statistics to obtain a report on each component’s health. A component is considered to be in good health if all of the user-specified criteria for that component are satisfied. The other possible health settings, okay and poor, are assigned to a component as fewer of the health criteria are met.

The interfaces in the admin package that relate to health monitoring are:
  • GemFireHealth—Health configuration and monitoring for a distributed system. Includes set and get methods for distributed system health configuration (DistributedSystemHealthConfig) and for components residing on individual host machines in the distributed system (GemFireHealthConfig). Also provides methods for getting the overall health of the system, for retrieving diagnostic information in the case of ill health, and for resetting all health indicators in the system to optimal.
  • DistributedSystemHealthConfig—Health configuration for the distributed system. Settings include the number of unexpected departures from the distributed system by system members.
  • GemFireHealthConfig—Health configuration for components of a distributed system that reside on a given machine. This combines MemberHealthConfig, and CacheHealthConfig.
  • CacheHealthConfig—Health configuration for cache instances. Settings include:
    • Durations for netSearch and load operations
    • Cache hit ratio
    • Event delivery queue size
  • MemberHealthConfig—Health configuration for distributed system members. Settings include:
    • JVM process size
    • Incoming and outgoing message queue sizes
    • Number of timeouts waiting for replies from other members
    • Multicast retransmission rates
  • GemFireHealth.Health—An enumerated type for the health of GemFire.

Health monitoring is managed from the GemFireHealth interface. You use it to set and access configuration settings for the distributed system and for system components. You can set default configuration settings for distributed system components that you can override for any host machine. This figure shows the relationships between the interfaces.

Figure 2. Setting the GemFire Health Configuration

GemFireHealth oversees all configuration settings and provides monitoring and management tools. The host machines that do not have a GemFireHealthConfig associated with them are monitored using the default GemFire health configuration settings.

GemFire health configuration settings cover cache and member configurations. Member configuration settings apply to each member in the distributed system. Cache settings apply to every cache in the system.