3. Explanation of the Java classes

Owned by MS (Unlicensed)
Jan 17, 2023
6 min read

Introduction

As you should have seen in the result of creating a project from the archetype, two main classes have been created:

These classes can be renamed as you prefer but they must implement the required interfaces to work with Abiquo.

CustomBackupConnection

This is the class that receives the connection data and manages the connection to the backup system.

Implements: com.abiquo.commons.plugin.IConnection

Methods

Connect

Should start the connection to the backup system.

For example, perform a login in basic auth to the REST API and save the authorization token for the next requests.

Returns: void

Parameters: com.abiquo.commons.model.ConnectionData containing the necessary data to perform the connection

Throws: com.abiquo.commons.plugin.exception.ComputeException is the expected exception to throw if something goes wrong when making the connection

Signature
public void connect(final ConnectionData connectionData) throws ComputeException

Disconnect

Should stop or finish the connection to the backup system.

For example: perform a logout from the REST API and remove the authorization token saved by the connect method.

Returns: void

Parameters: none

Throws: com.abiquo.commons.plugin.exception.ComputeException is the expected exception to throw if something goes wrong when disconnecting

Signature
 public void disconnect() throws ComputeException


CustomBackupPlugin

This is the main class that will manage all the requests from the Abiquo components (Virtual Factory and Cloud Provider Proxy).

This is the class that represents the plugin.

It must implement the BackupScheduling interface typed with your own connection class, in this case the CustomBackupConnection.

It must contain two Java annotations at class level:

Implements: com.abiquo.backup.plugin.BackupScheduling

Methods

Validate configuration

This method is called when the plugin is loaded by an Abiquo component (API, Virtual Factory and Cloud Provider Proxy) to perform the required validations to assure the plugin is properly configured to be used.

Returns: void

Parameters: none

Throws: java.lang.IllegalStateException

Signature
 public void validateConfiguration() throws IllegalStateException

Apply schedule

There are two signatures for this method that differ in the number of parameters received and the moment when they are invoked.

Signature 1

This method is invoked when a VM that contains backup information is being deployed.

The VM is already deployed and is expected to configure the backup schedule at this point.

If this method fails, the deploy is rolled back and the VM will not exist in the hypervisor.

Returns: void

Parameters:

Throws: com.abiquo.backup.plugin.exception.BackupPluginException to tell the Abiquo component what failed

Signature
public void applySchedule(final CustomBackupConnection connection,
    final VirtualMachineBackupRestoreInfo virtualMachineIdentifier,
    final BackupSchedule backupSchedule) throws BackupPluginException

Signature 2

This method is invoked for a VM that is already deployed when its backup configuration is modified.

That means that someone adds new backup configurations, removes old backup configurations or changes backup configuration values of a VM that was deployed in the past.

So we now need to apply these changes into the backup system.

If this method fails, the reconfigure is rolled back and the VM will still be in the same state it was in before the process started.

Returns: void

Parameters:

Throws: com.abiquo.backup.plugin.exception.BackupPluginException to tell the Abiquo component what failed

Signature
public void applySchedule(final CustomBackupConnection connection,
    final VirtualMachineBackupRestoreInfo virtualMachineIdentifier,
    final BackupSchedule oldBackupSchedule, final BackupSchedule newBackupSchedule)
    throws BackupPluginException

Remove schedule

This method is called when the virtual factory is going to undeploy a VM that has some backup configuration.

So we need to remove this configuration from the backup system before continuing with the VM undeploy process.

If this method fails, the undeploy is aborted.

Returns: void

Parameters: 

Throws: com.abiquo.backup.plugin.exception.BackupPluginException to tell the Abiquo component what failed

Signature
public void removeSchedule(final CustomBackupConnection connection,
    final VirtualMachineBackupRestoreInfo virtualMachineIdentifier)
    throws BackupPluginException

Execute backup

This method is called when a user requests an immediate backup.

So we need to request the backup to the backup system and wait until this finishes successfully or not and return a com.abiquo.backup.model.BackupResult of the executed backup.

Until this method finishes the VM is locked in Abiquo, which means no users can access or modify it.

So its a good idea to wait until the backup finishes to end this method.

Returns: com.abiquo.backup.model.BackupResult with all the results data from the backup executed, and whether it finished successfully or not.

Parameters:

Throws: com.abiquo.backup.plugin.exception.BackupPluginException to tell the Abiquo component what failed

Signature
public BackupResult executeBackup(final CustomBackupConnection connection,
    final VirtualMachineBackupRestoreInfo virtualMachineIdentifier,
    final OnDemandBackupOptions options) throws BackupPluginException

Execute restore

This method is called when a user requests a restore of a backup from a virtual machine.

So we need to request to restore the saved backup and wait until it finishes successfully or not and return a com.abiquo.backup.model.BackupResult.RestoreResult of the executed restore.

Until this method finishes the VM remains locked in Abiquo, which means that no user can access or modify it.

A restore can be requested for a deployed VM or an undeployed one. 

Returns: com.abiquo.backup.model.BackupResult.RestoreResult with all the data from the executed restore, finished successfully or not.

Parameters:

Throws: com.abiquo.backup.plugin.exception.BackupPluginException to tell the Abiquo component what failed

Signature
public RestoreResult executeRestore(final CustomBackupConnection connection,
    final VirtualMachineBackupRestoreInfo virtualMachineIdentifier, final String backupId)
    throws BackupPluginException

List results

This method is called every time the API wants to check for the existing backup results in the backup system.

This is done when a Backup Manager of the type of the plugin exists, at intervals defined by the property abiquo.backup.check.delay defined in the abiquo.properties file of the API server.

This method retrieves all results and sends them to the API.

As some backups may not expire or exist for a long time, the API saves the date when this call is made (lastCheckDate parameter) and sends it in the next iteration.

Sending this date enables the plugin to filter the results requested of the backup system and skip to request results already saved in Abiquo database and with no changes made.

This could cause the skip of the results that were in an in progress state because they are older than the given lastCheckDate. To solve that, another parameter is received with a set of all the provider IDs of the results that actually are saved in Abiquo database as in progress in order to check them and add them to the results list.

Returns: java.util.List<com.abiquo.backup.model.BackupResult> with all the returned backup results, done, failed or in progress.

Parameters:

  • 3. Explanation of the Java classes#CustomBackupConnection with the connection already established.

  • java.time.ZonedDateTime (lastCheckDate) of the last execution of this method.

  • java.util.Set<java.lang.String> with all the provider IDs of backup results saved as in progress in the Abiquo database.

Throws: com.abiquo.backup.plugin.exception.BackupPluginException to tell the Abiquo component what failed

Signature
public List<BackupResult> listResults(final CustomBackupConnection connection,
    final ZonedDateTime lastCheckDate, final Set<String> inProgressResultProviderIds)
    throws BackupPluginException

Get expired results

This method is called after invoking the 3. Explanation of the Java classes#List Results method.

This method receives a list of provider IDs of the backup results that the Abiquo API considers to be expired and it's expected to return only those ones that are really expired.

So get the provider ids, check each result, and return only the expired ones.

Returns: java.util.List<Srting> with the provider IDs of the backup results really expired.

Parameters:

Throws: com.abiquo.backup.plugin.exception.BackupPluginException to tell the Abiquo component what failed

Signature
public List<String> getExpiredResults(final CustomBackupConnection connection,
    final List<String> providerIds) throws BackupPluginException

Get constraint

Abiquo integrates different backup technologies and not all of them support the same features, so we created a list of constraints that defines which features are not supported.

This method returns the value of the constraint requested by Abiquo components.

The key parameter is a java.lang.String that can be converted into the enumeration com.abiquo.commons.model.enumerator.ConstraintKey that for backup always expects a java.lang.Boolean value converted to java.lang.String.

Returns: java.lang.String with the value for a constraint

Parameters: java.lang.String the key of the constraint

Throws: No checked exception

Signature
public String getConstraint(final String key)



Copyright © 2006-2024, Abiquo Holdings SL. All rights reserved