See a fully running example of a Scaling Agent as part of the Solutions & Patterns section.

Admin Construction

The Admin API uses the AdminFactory in order to create Admin instances. Once working with the Admin is done, its Admin#close() method should be called.

The Admin discovers all the advertised services from the Lookup Service. In order to define which lookup groups the AdminFactory#addGroup can be used. The lookup locators can also be used for non multicast enabled environment using AdminFactory#addLocator can be used. If the services started are secured, the username and password can be set on the Admin API as well.

Discovery Process

Once the Admin is created, it will start to receive discovery events of all the advertised services / components within its lookup groups / lookup locators. Note, the events occur asynchronously and the data model within the Admin gets initialized in the background with services coming and going.

This means that just creating the Admin and calling a specific “getter” for a data structure might not return what is currently deployed, and one should wait till the structures are filled. Some components have a waitFor method that allow to wait for specific number of services to be up. When navigating the data model, the Admin API will provide its most up to date state of the system it is monitoring.

Domain Model

The Admin Domain Model has representation to all GigaSpaces level main actors. They include:

Deploy Processing Units on a random Grid Service Manager. Deploy pure Space Processing Units on a random Grid Service Manager. Get all the currently discovered Grid Service Managers. Wait for X number of Grid Service Managers to be up.

Runtime Events

Register for Grid Service Manager addition (discovery) and removals events.

A deployable processing unit running one or more Processing Unit Instances. Managed by the Grid Service Manager.

Main Operations

Undeploy the Processing Unit - Increase the number of Processing Units Instances (if allowed). - Decrease the number of Processing Unit Instances (if allowed). - Get the deployment status of the Processing Unit. - Get the managing Grid Service Manager. - Get the list of backup Grid Service Managers. - List all the currently running Processing Unit Instances. - Wait for X number of Processing Unit Instances or be up. - Get an embedded Space that the Processing Unit has. - Wait for an embedded Space to be correlated (discovered) with the Processing Unit.

An actual instance of a Processing Unit running within a Grid Service Container.

Main Operations

Destroy itself (if SLA is breached, will be instantiated again). - Decrease itself (and destroying itself in the process). Will not attempt to create it again. - Relocate itself to a different Grid Service Container. - List all its inner services (such as event containers). - Get the embedded Space Instance running within it (if there is one). - Get the JEE container details if it is a web processing unit.

Composed of one or more Space Instances to form a Space topology (cluster)

Main Operations

Get all the currently running Space Instance that are part of the Space. - Wait for X number of Space Instances to be up. - Get aggregated Space statistics. - Get a clustered GigaSpace to perform Space operations.

Runtime Events

Register for Space Instance additions and removals events. - Register for Space Instance change mode events (for all Space Instances that are part of the Space). - Register for Space Instance replication status change events (for all Space Instances that are part of the Space). - Register for aggregated Space statistics events (if monitoring).

A virtual machine (JVM) that is currently running at least one GigaSpaces component / service.

Main Operations

Get the Grid Service Agent (if exists). - Get the Grid Service Manager (if exists). - Get the Grid Service Container (if exists). - Get all the Processing Unit Instances that are running within the Virtual Machine. - Get all the Space Instances that are running within the Virtual Machine. - Get the details of the Virtual Machine (min/max memory, and so on). - Get the statistics of the Virtual Machine (heap used, and so on).

An actual Machine (identified by its host address) running one or more GigaSpaces components / services in one or more Virtual Machines. Associated with one Operating System

Main Operations

Get all the Grid Service Agents running on the Machine. - Get all the Grid Service Containers running on the Machine. - Get all the Grid Service Managers running on the Machine. - Get all the Virtual Machines running on the Machine. - Get all the Processing Unit Instances running on the Machine. - Get all the Space Instances running on the Machine. - Get the Operating System the Machine is running on.

Runtime Events

Register for Space Instances additions and removals events from the Machine. - Register for Processing Unit Instance additions and removals events from the Machine.

The Admin functionality is designed for interacting with a service grid deployment. In the case of StandaloneProcessingUnitContainer and IntegratedProcessingUnitContainer, components such as GridServiceAgent or GridServiceManager are not started by default, therefore portions of the Admin functionality will not be available.

Accessing the Domain Model

There are two ways the Admin API can be used to access information the Admin API can provide.

Call specific “getters” for the data and iterate over them (as shown in the example at the top of the page).

Register for specific events using the Admin API. Events are handled by different components of the Admin API in similar manner. We will take one of them and use it as a reference example.

If we want to register, for example, for Grid Service Container additions, we can use the following code (note, removing the event listener is not shown here for clarity):

All other data structures use similar API to register for events. Some might have specific events that goes beyond just additions and removals, but they still use the same model. For example, here is how we can register for Space Mode change events across all currently running Space topologies and Space Instances:

Of course, we can register the same listener on a specific Space topology or event on a specific SpaceInstance.

Last, the Admin interface provides a one stop method called addEventListener that accepts an AdminListener. Most events listener implement this interface. One can create a class that implements several chosen listener interfaces, call the addEventListener method, and they will automatically be added to their respective components. For example, if our listener implements GridServiceContainerAddedEventListener and GridServiceManagerAddedEventListener, the listener will automatically be added to the GridServiceManagers and GridServiceContainers.

Details and Statistics

Some components in the Admin API can provide statistics. For example, a SpaceInstance can provide statistics on how many times the read API was called on it. Statistics change over time, and in order to get them either the “getter” for the Statistics can be used, or a statistics listener can be registered for statistics change events.

Details of a specific component provide information that does not change over time, but can be used to provide more information regarding the component, or to compute statistics. For example, the VirtualMachine provides in its details the minimum and maximum heap memory size, which the VirtualMachine statistics provide the currently used heap memory size. The detailed information is used to provide the percentage used in the Virtual Machine statistics.

The Admin API also provide aggregated details and statistics. For example, the Space provides SpaceStatistics allowing to get the aggregated statistics of all the different Space Instances that belong to it.

Each component in the Admin API that can provide statistics (either direct statistics, or aggregated statistics) implements the StatisticsMonitor interface. The statistics monitor allows to start to monitor statistics and stop to monitor statistics. Monitoring for statistics is required if one wishes to register for statistics change events. The interval that statistics will be polled is controlled using the statistics interval.

The statistics interval is important event when the Admin API is not actively polling for statistics. Each call to a “getter” of statistics will only perform a remote call to the component if the last statistics fetch happened before the statistics interval. This behavior allows for users of the Admin API to not worry about “hammering” different components for statistics since the Admin will make sure that statistics calls are cached internally for the statistics interval period.

A SpaceInstance implements the StatisticsMonitor interface. Calling startMonitor and stopMonitor on it will cause monitoring of statistics to be enabled or disabled on it.

Space also implements the StatisticsMonitor interface. Calling startMonitor on it will cause it to start monitoring all its SpaceInstance s. If a SpaceInstance is discovered after the the call to startMonitor occurred, it will start monitoring itself automatically. This means that if the a SpaceInstanceStatisticsChangedEventListener was registered on the Space, it will automatically start to get Space Instance statistics change events for the newly discovered SpaceInstance.

Spaces also implements the StatisticsMonitor interface. Calling startMonitor on it will cause it to start monitoring all the Space s it has (and as a result, also SpaceInstance s, see the paragraph above). A SpaceInstanceStatisticsChangedEventListener can also be registered on the Spaces level as well.

The above Space level statistics behavior works in much the way with other components. For example, the VirutalMachine and VirtualMachines, Transport and Transports, OperatingSystem and OperatingSystems.

The Admin interface also implements the StatisticsMonitor interface. Calling startMonitor on it will cause all holders to start monitoring. These include: Spaces, VirtualMachines, Transports, and OperatingSystems.

Space Runtime Statistics

The space maintains statistics information about all the data types (e.g. space class types) it stores and the amount of space objects stored in memory for each data type. Below example how to retrieve this data. This approach avoiding the need to use the GigaSpace.Count() that is relatively expensive with spaces that store large number of objects.

If you are monitoring the space class instance count with some monitoring tool you should use the approach below rather calling the GigaSpace.Count().

Monitoring the Mirror Service

You may monitor various aspects of the mirror service using the administration and monitoring API.
The mirror statistics are available using the SpaceInstance statistics. They can be used to monitor the state of the mirror space and whether or not it is functioning properly. These statistics are relevant only for a mirror space instance, and are not available for ordinary space instances. The code below traverses all the space instances and finds the mirror space by retrieving the mirror statistics object (if it isn’t null this means it’s a mirror space). It then prints out some of the available statistics.

Monitoring the Remote Transport Activity

PU Status Changed Events

It is possible to receive notifications about the deployment status of a Processing Unit. An event listener can be attached to the Admin that delivers events describing the current and previous DeploymentStatus of a Processing Unit.
Here is an example: