Administration API
The Admin API provides a way to administer and monitor all of GigaSpaces services and components using a simple API. The API provides information and the ability to operate on the currently running GigaSpaces Agent, the Manager, the Container, Lookup Service, Processing Unit, and Spaces.
Dependencies
In order to use this feature, include the $GS_HOME/lib/platform/service-grid/xap-admin.jar file on your classpath or use maven dependencies:
<dependency>
<groupId>com.gigaspaces</groupId>
<artifactId>xap-admin</artifactId>
<version>16.2.1</version>
</dependency>
For more information on dependencies, refer to Maven Artifacts.
Examples
The following code examples show how the Admin API can be used to display information on the currently deployed services/components:
public void gsa() {
Admin admin = new AdminFactory().addGroup("myGroup").createAdmin();
// wait till things get discovered (you can also use specific waitFor)
for (GridServiceAgent gsa : admin.getGridServiceAgents()) {
System.out.println("GSA [" + gsa.getUid()
+ "] running on Machine ["
+ gsa.getMachine().getHostAddress());
for (AgentProcessDetails processDetails : gsa.getProcessesDetails()) {
System.out.println(" -> Process ["
+ Arrays.toString(processDetails.getCommand()) + "]");
}
}
}
public void gsm() {
Admin admin = new AdminFactory().addGroup("myGroup").createAdmin();
// wait till things get discovered (you can also use specific waitFor)
for (GridServiceManager gsm : admin.getGridServiceManagers()) {
System.out.println("GSM [" + gsm.getUid() + "] running on Machine "
+ gsm.getMachine().getHostAddress());
}
}
public void gsc() {
Admin admin = new AdminFactory().addGroup("myGroup").createAdmin();
// wait till things get discovered (you can also use specific waitFor)
for (GridServiceContainer gsc : admin.getGridServiceContainers()) {
System.out.println("GSC [" + gsc.getUid() + "] running on Machine "
+ gsc.getMachine().getHostAddress());
for (ProcessingUnitInstance puInstance : gsc
.getProcessingUnitInstances()) {
System.out.println(" -> PU [" + puInstance.getName() + "]["
+ puInstance.getInstanceId() + "]["
+ puInstance.getBackupId() + "]");
}
}
}
public void pu() {
Admin admin = new AdminFactory().addGroup("myGroup").createAdmin();
// wait till things get discovered (you can also use specific waitFor)
for (ProcessingUnit processingUnit : admin.getProcessingUnits()) {
System.out.println("Processing Unit: " + processingUnit.getName()
+ " status: " + processingUnit.getStatus());
if (processingUnit.isManaged()) {
System.out.println(" -> Managing GSM: "
+ processingUnit.getManagingGridServiceManager()
.getUid());
} else {
System.out.println(" -> Managing GSM: NA");
}
for (GridServiceManager backupGSM : processingUnit
.getBackupGridServiceManagers()) {
System.out.println(" -> Backup GSM: " + backupGSM.getUid());
}
for (ProcessingUnitInstance processingUnitInstance : processingUnit) {
System.out.println(" ["
+ processingUnitInstance.getClusterInfo()
+ "] on GSC ["
+ processingUnitInstance.getGridServiceContainer()
.getUid() + "]");
if (processingUnitInstance.isEmbeddedSpaces()) {
System.out.println(" -> Embedded Space ["
+ processingUnitInstance.getSpaceInstance()
.getUid() + "]");
}
Map<String, ServiceDetails> services = processingUnitInstance.getServiceDetailsByServiceId();
for (ServiceDetails details : services.values()) {
System.out.println(" -> Service " + details);
}
}
}
}
The number of backups — space.getNumberOfBackups() — will be zero or one.
public void space() {
Admin admin = new AdminFactory().addGroup("myGroup").createAdmin();
for (Space space : admin.getSpaces()) {
System.out.println("Space [" + space.getUid()
+ "] numberOfInstances [" + space.getNumberOfInstances()
+ "] numberOfbackups [" + space.getNumberOfBackups() + "]");
System.out.println(" Stats: Write ["
+ space.getStatistics().getWriteCount() + "/"
+ space.getStatistics().getWritePerSecond() + "]");
for (SpaceInstance spaceInstance : space) {
System.out.println(" -> INSTANCE [" + spaceInstance.getUid()
+ "] instanceId [" + spaceInstance.getInstanceId()
+ "] backupId [" + spaceInstance.getBackupId()
+ "] Mode [" + spaceInstance.getMode() + "]");
System.out.println(" -> Host: "
+ spaceInstance.getMachine().getHostAddress());
System.out.println(" -> Stats: Write ["
+ spaceInstance.getStatistics().getWriteCount() + "/"
+ spaceInstance.getStatistics().getWritePerSecond()
+ "]");
}
for (SpacePartition spacePartition : space.getPartitions()) {
System.out.println(" -> Partition ["
+ spacePartition.getPartitionId() + "]");
for (SpaceInstance spaceInstance : spacePartition) {
System.out.println(" -> INSTANCE ["
+ spaceInstance.getUid() + "]");
}
}
}
}
public void virtualMachine() {
Admin admin = new AdminFactory().addGroup("myGroup").createAdmin();
// wait till things get discovered (you can also use specific waitFor)
System.out.println("VM TOTAL STATS: Heap Committed ["
+ admin.getVirtualMachines().getStatistics()
.getMemoryHeapCommittedInGB() + "GB]");
System.out.println("VM TOTAL STATS: GC PERC ["
+ admin.getVirtualMachines().getStatistics()
.getGcCollectionPerc()
+ "], Heap Used ["
+ admin.getVirtualMachines().getStatistics()
.getMemoryHeapUsedPerc() + "%]");
for (VirtualMachine virtualMachine : admin.getVirtualMachines()) {
System.out.println("VM [" + virtualMachine.getUid() + "] "
+ "Host [" + virtualMachine.getMachine().getHostAddress()
+ "] " + "GC Perc ["
+ virtualMachine.getStatistics().getGcCollectionPerc()
+ "], " + "Heap Usage ["
+ virtualMachine.getStatistics().getMemoryHeapUsedPerc()
+ "%]");
for (ProcessingUnitInstance processingUnitInstance : virtualMachine
.getProcessingUnitInstances()) {
System.out.println(" -> PU ["
+ processingUnitInstance.getUid() + "]");
}
for (SpaceInstance spaceInstance : virtualMachine
.getSpaceInstances()) {
System.out.println(" -> Space [" + spaceInstance.getUid()
+ "]");
}
}
}
public void machine() {
Admin admin = new AdminFactory().addGroup("myGroup").createAdmin();
// wait till things get discovered (you can also use specific waitFor)
for (Machine machine : admin.getMachines()) {
System.out.println("Machine ["
+ machine.getUid()
+ "], "
+ "TotalPhysicalMem ["
+ machine.getOperatingSystem().getDetails()
.getTotalPhysicalMemorySizeInGB()
+ "GB], "
+ "FreePhysicalMem ["
+ machine.getOperatingSystem().getStatistics()
.getFreePhysicalMemorySizeInGB() + "GB]]");
for (SpaceInstance spaceInstance : machine.getSpaceInstances()) {
System.out.println(" -> Space [" + spaceInstance.getUid()
+ "]");
}
for (ProcessingUnitInstance processingUnitInstance : machine
.getProcessingUnitInstances()) {
System.out.println(" -> PU ["
+ processingUnitInstance.getUid() + "]");
}
}
}
Obtaining information about the currently deployed services/components via the started GridServiceAgents:
public void findStartedGridServiceContainers() {
Admin admin = new AdminFactory().createAdmin();
// wait at least for one agent
admin.getGridServiceAgents().waitForAtLeastOne();
for (GridServiceAgent gsa : admin.getGridServiceAgents()) {
for (GridServiceContainer gsc : gsa.getGridServiceContainers()) {
// ....
}
}
}
public void findStartedGridServiceManagers() {
Admin admin = new AdminFactory().createAdmin();
// wait at least for one agent
admin.getGridServiceAgents().waitForAtLeastOne();
for (GridServiceAgent gsa : admin.getGridServiceAgents()) {
for (GridServiceManager gsm : gsa.getGridServiceManagers()) {
// ....
}
}
}
public void findStartedLookupServices() {
Admin admin = new AdminFactory().createAdmin();
// wait at least for one agent
admin.getGridServiceAgents().waitForAtLeastOne();
for (GridServiceAgent gsa : admin.getGridServiceAgents()) {
for (LookupService ls : gsa.getLookupServices()) {
// ....
}
}
}
A fully running example of a Scaling Agent is available in the Solutions & Patterns section.
Admin Construction
The Admin API uses the AdminFactory in order to create Admin instances. After you finish working with the Admin, its Admin#close() method should be called.
The Admin API discovers all the advertised services from the Lookup Service. Use the AdminFactory#addGroup to define which lookup groups. The lookup locators can also be used for non-multicast enabled environments using AdminFactory#addLocator. If the services started are secured, the username and password can be set on the Admin API as well.
Discovery Process
When the Admin is created, it starts to receive discovery events from all the advertised services/components within its lookup groups and lookup locators. The events occur asynchronously and the data model within the Admin API 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 you should wait until the structures are filled. Some components have a waitFor method that allows waiting for a specific number of services to be up. When navigating the data model, the Admin API provides its most up-to-date state of the system it is monitoring.
Domain Model
The Admin Domain Model has representation to all the data grid-level main actors. They include:
The Admin functionality is designed to interact with a service grid deployment. For StandaloneProcessingUnitContainer and IntegratedProcessingUnitContainer, components such as GridServiceAgent and GridServiceManager are not started by default, therefore portions of the Admin functionality aren't available.
Accessing the Domain Model
There are two ways to use the Admin API to access information:
- 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 (removing the event listener is not shown here for clarity):
admin.getGridServiceContainers().getGridServiceContainerAdded().add(new GridServiceContainerAddedEventListener() {
public void gridServiceContainerAdded(GridServiceContainer gridServiceContainer) {
// do something here
}
});
Removals are done in similar manner:
admin.getGridServiceContainers().getGridServiceContainerRemoved().add(new GridServiceContainerRemovedEventListener() {
public void gridServiceContainerRemoved(GridServiceContainer gridServiceContainer) {
// do something here
}
});
Since both removals and additions are common events that we would like to register for at the same time, we can use:
admin.getGridServiceContainers().addLifecycleListener(new GridServiceContainerLifecycleEventListener() {
public void gridServiceContainerAdded(GridServiceContainer gridServiceContainer) {
// do something here
}
public void gridServiceContainerRemoved(GridServiceContainer gridServiceContainer) {
// do something here
}
});
All other data structures use similar APIs to register for events. Some might have specific events that go beyond additions and removals, but they still use the same model. For example, you can register for Space mode change events across all currently running Space topologies and Space instances:
admin.getSpaces().getSpaceModeChanged().add(new SpaceModeChangedEventListener() {
public void spaceModeChanged(SpaceModeChangedEvent event) {
System.out.println("Space [" + event.getSpaceInstance().getSpace().getName() + "] " +
"Instance [" + event.getSpaceInstance().getInstanceId() + "/" +
event.getSpaceInstance().getBackupId() + "] " +
"changed mode from [" + event.getPreviousMode() + "] to [" + event.getNewMode() + "]");
}
});
Of course, you 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 event listeners implement this interface. You 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.
Security
If you are using the Admnistration API in a secured environment, there are several things that must be taken into consideration when accessing the service grid or deploying grid components (Spaces and Processing Units).
Constructing the Admin Instance
When using a secured Service Grid, the Admin instance needs to be constructed with a principal which is granted sufficient privileges based on the operations being performed using the administration API. For example, grant Manage Grid to start a Grid Service Manager (GSM) and grant Provision PU to deploy a processing unit.
The following creates an Admin instance with the user "user/password".
Admin admin = new AdminFactory().addGroup("gigaspaces").credentials("user", "password").createAdmin();
For security other than username/password, refer to the Authentication topic in the Security section of the Administration guide.
Space Deployment
Deploying a secured Space:
...
admin.getGridServiceManagers().deploy(new SpaceDeployment("mySpace").secured(true));
Deploying a secured Space with credentials supplied. These credentials propagate to internal services, such as Space Filters.
...
admin.getGridServiceManagers().deploy(new SpaceDeployment("mySpace").userDetails("myUser", "myPassword"));
Processing Unit Deployment
Deploying a secured Processing Unit. This will deploy a Processing Unit with a secured embedded Space.
...
admin.getGridServiceManagers().deploy(new ProcessingUnitDeployment("myPu").secured(true));
Deploying a secured Processing Unit with credentials supplied. With this approach, credentials do not need to be hardcoded in the pu.xml declaration. These credential propagate to all the beans that require a proxy to the Space.
...
admin.getGridServiceManagers().deploy(new ProcessingUnitDeployment("myPu").userDetails("myUser", "myPassword"));
