[Quota] Add API to list preset variables (#8372)

* Add API for listing Quota preset variables

* Add new line at EOF

* Address review

* Remove usage types

* Remove usage types from quotatypes

* Remove unused imports

* Add space for preset variable definition description

Co-authored-by: Bernardo De Marco Gonçalves <bernardomg2004@gmail.com>

---------

Co-authored-by: Bernardo De Marco Gonçalves <bernardomg2004@gmail.com>

Author: BryanMLima

framework/quota/src/main/java/org/apache/cloudstack/quota/activationrule/presetvariables/Account.java

@@ -17,7 +17,9 @@
 
 package org.apache.cloudstack.quota.activationrule.presetvariables;
 
-public class Account extends GenericPresetVariable{
+public class Account extends GenericPresetVariable {
+    @PresetVariableDefinition(description = "Role of the account. This field will not exist if the account is a project.")
+
     private Role role;
 
     public Role getRole() {

framework/quota/src/main/java/org/apache/cloudstack/quota/activationrule/presetvariables/BackupOffering.java

@@ -20,6 +20,7 @@
 package org.apache.cloudstack.quota.activationrule.presetvariables;
 
 public class BackupOffering extends GenericPresetVariable {
+    @PresetVariableDefinition(description = "External ID of the backup offering that generated the backup.")
     private String externalId;
 
     public String getExternalId() {

framework/quota/src/main/java/org/apache/cloudstack/quota/activationrule/presetvariables/ComputeOffering.java

@@ -18,6 +18,7 @@
 package org.apache.cloudstack.quota.activationrule.presetvariables;
 
 public class ComputeOffering extends GenericPresetVariable {
+    @PresetVariableDefinition(description = "A boolean informing if the compute offering is customized or not.")
     private boolean customized;
 
     public boolean isCustomized() {

framework/quota/src/main/java/org/apache/cloudstack/quota/activationrule/presetvariables/ComputingResources.java

@@ -21,8 +21,13 @@
 import org.apache.commons.lang3.builder.ToStringStyle;
 
 public class ComputingResources {
+    @PresetVariableDefinition(description = "Current VM's memory (in MiB).")
     private Integer memory;
+
+    @PresetVariableDefinition(description = "Current VM's vCPUs.")
     private Integer cpuNumber;
+
+    @PresetVariableDefinition(description = "Current VM's CPU speed (in MHz).")
     private Integer cpuSpeed;
 
     public Integer getMemory() {

framework/quota/src/main/java/org/apache/cloudstack/quota/activationrule/presetvariables/Domain.java

@@ -18,6 +18,7 @@
 package org.apache.cloudstack.quota.activationrule.presetvariables;
 
 public class Domain extends GenericPresetVariable {
+    @PresetVariableDefinition(description = "Path of the domain owner of the resource.")
     private String path;
 
     public String getPath() {

framework/quota/src/main/java/org/apache/cloudstack/quota/activationrule/presetvariables/GenericPresetVariable.java

@@ -23,8 +23,12 @@
 import org.apache.cloudstack.utils.reflectiontostringbuilderutils.ReflectionToStringBuilderUtils;
 
 public class GenericPresetVariable {
+    @PresetVariableDefinition(description = "ID of the resource.")
     private String id;
+
+    @PresetVariableDefinition(description = "Name of the resource.")
     private String name;
+
     protected transient Set<String> fieldNamesToIncludeInToString = new HashSet<>();
 
     public String getId() {

framework/quota/src/main/java/org/apache/cloudstack/quota/activationrule/presetvariables/Host.java

@@ -20,8 +20,10 @@
 import java.util.List;
 
 public class Host extends GenericPresetVariable {
+    @PresetVariableDefinition(description = "List of tags of the host where the VM is running (i.e.: [\"a\", \"b\"]).")
     private List<String> tags;
 
+    @PresetVariableDefinition(description = "Whether the tag is a rule interpreted in JavaScript.")
     private Boolean isTagARule;
 
     public List<String> getTags() {

framework/quota/src/main/java/org/apache/cloudstack/quota/activationrule/presetvariables/PresetVariableDefinition.java

@@ -0,0 +1,42 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// the License.  You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+package org.apache.cloudstack.quota.activationrule.presetvariables;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Describes the preset variable and indicates to which Quota usage types it is loaded.
+ */
+@Target(FIELD)
+@Retention(RUNTIME)
+public @interface PresetVariableDefinition {
+    /**
+     * An array indicating for which Quota usage types the preset variable is loaded.
+     * @return an array with the usage types for which the preset variable is loaded.
+     */
+    int[] supportedTypes() default 0;
+
+    /**
+     * A {@link String} describing the preset variable.
+     * @return the description of the preset variable.
+     */
+    String description() default "";
+}

framework/quota/src/main/java/org/apache/cloudstack/quota/activationrule/presetvariables/PresetVariables.java

@@ -19,11 +19,22 @@
 
 public class PresetVariables {
 
+    @PresetVariableDefinition(description = "Account owner of the resource.")
     private Account account;
+
+    @PresetVariableDefinition(description = "Domain owner of the resource.")
     private Domain domain;
+
+    @PresetVariableDefinition(description = "Project owner of the resource. This field will not exist if the resource belongs to an account.")
     private GenericPresetVariable project;
+
+    @PresetVariableDefinition(description = "Type of the record used. Examples for this are: VirtualMachine, DomainRouter, SourceNat, KVM.")
     private String resourceType;
+
+    @PresetVariableDefinition(description = "Data related to the resource being processed.")
     private Value value;
+
+    @PresetVariableDefinition(description = "Zone where the resource is.")
     private GenericPresetVariable zone;
 
     public Account getAccount() {

framework/quota/src/main/java/org/apache/cloudstack/quota/activationrule/presetvariables/Role.java

@@ -20,6 +20,7 @@
 import org.apache.cloudstack.acl.RoleType;
 
 public class Role extends GenericPresetVariable {
+    @PresetVariableDefinition(description = "Role type of the resource's owner.")
     private RoleType type;
 
     public RoleType getType() {

framework/quota/src/main/java/org/apache/cloudstack/quota/activationrule/presetvariables/Storage.java

@@ -22,9 +22,13 @@
 import com.cloud.storage.ScopeType;
 
 public class Storage extends GenericPresetVariable {
+    @PresetVariableDefinition(description = "List of string representing the tags of the storage where the volume is (i.e.: [\"a\", \"b\"]).")
     private List<String> tags;
 
+    @PresetVariableDefinition(description = "Whether the tag is a rule interpreted in JavaScript. Applicable only for primary storages.")
     private Boolean isTagARule;
+
+    @PresetVariableDefinition(description = "Scope of the storage where the volume is. Values can be: ZONE, CLUSTER or HOST. Applicable only for primary storages.")
     private ScopeType scope;
 
     public List<String> getTags() {

framework/quota/src/main/java/org/apache/cloudstack/quota/activationrule/presetvariables/Value.java

@@ -23,25 +23,75 @@
 import com.cloud.storage.Snapshot;
 import com.cloud.storage.Storage.ProvisioningType;
 import com.cloud.vm.snapshot.VMSnapshot;
+import org.apache.cloudstack.quota.constant.QuotaTypes;
 
 public class Value extends GenericPresetVariable {
+
+    @PresetVariableDefinition(description = "ID of the resource.", supportedTypes = {QuotaTypes.ALLOCATED_VM, QuotaTypes.RUNNING_VM, QuotaTypes.VOLUME, QuotaTypes.TEMPLATE,
+            QuotaTypes.ISO, QuotaTypes.SNAPSHOT, QuotaTypes.NETWORK_OFFERING, QuotaTypes.VM_SNAPSHOT})
+    private String id;
+
+    @PresetVariableDefinition(description = "Name of the resource.", supportedTypes = {QuotaTypes.ALLOCATED_VM, QuotaTypes.RUNNING_VM, QuotaTypes.VOLUME, QuotaTypes.TEMPLATE,
+            QuotaTypes.ISO, QuotaTypes.SNAPSHOT, QuotaTypes.NETWORK_OFFERING, QuotaTypes.VM_SNAPSHOT})
+    private String name;
+
+    @PresetVariableDefinition(description = "Host where the VM is running.", supportedTypes = {QuotaTypes.RUNNING_VM})
     private Host host;
+
+    @PresetVariableDefinition(description = "OS of the VM/template.", supportedTypes = {QuotaTypes.RUNNING_VM, QuotaTypes.ALLOCATED_VM, QuotaTypes.TEMPLATE, QuotaTypes.ISO})
     private String osName;
+
+    @PresetVariableDefinition(description = "A list of resources of the account between the start and end date of the usage record being calculated " +
+            "(i.e.: [{zoneId: ..., domainId:...}]).")
     private List<Resource> accountResources;
+
+    @PresetVariableDefinition(supportedTypes = {QuotaTypes.ALLOCATED_VM, QuotaTypes.RUNNING_VM, QuotaTypes.VOLUME, QuotaTypes.TEMPLATE, QuotaTypes.ISO, QuotaTypes.SNAPSHOT,
+            QuotaTypes.VM_SNAPSHOT}, description = "List of tags of the resource in the format key:value (i.e.: {\"a\":\"b\", \"c\":\"d\"}).")
     private Map<String, String> tags;
+
+    @PresetVariableDefinition(description = "Tag of the network offering.", supportedTypes = {QuotaTypes.NETWORK_OFFERING})
     private String tag;
+
+    @PresetVariableDefinition(description = "Size of the resource (in MiB).", supportedTypes = {QuotaTypes.TEMPLATE, QuotaTypes.ISO, QuotaTypes.VOLUME, QuotaTypes.SNAPSHOT,
+            QuotaTypes.BACKUP})
     private Long size;
+
+    @PresetVariableDefinition(description = "Virtual size of the backup.", supportedTypes = {QuotaTypes.BACKUP})
     private Long virtualSize;
+
+    @PresetVariableDefinition(description = "Provisioning type of the resource. Values can be: thin, sparse or fat.", supportedTypes = {QuotaTypes.VOLUME})
     private ProvisioningType provisioningType;
+
+    @PresetVariableDefinition(description = "Type of the snapshot. Values can be: MANUAL, RECURRING, HOURLY, DAILY, WEEKLY and MONTHLY.", supportedTypes = {QuotaTypes.SNAPSHOT})
     private Snapshot.Type snapshotType;
+
+    @PresetVariableDefinition(description = "Type of the VM snapshot. Values can be: Disk or DiskAndMemory.", supportedTypes = {QuotaTypes.VM_SNAPSHOT})
     private VMSnapshot.Type vmSnapshotType;
+
+    @PresetVariableDefinition(description = "Computing offering of the VM.", supportedTypes = {QuotaTypes.RUNNING_VM, QuotaTypes.ALLOCATED_VM})
     private ComputeOffering computeOffering;
+
+    @PresetVariableDefinition(description = "Template/ISO with which the VM was created.", supportedTypes = {QuotaTypes.RUNNING_VM, QuotaTypes.ALLOCATED_VM})
     private GenericPresetVariable template;
+
+    @PresetVariableDefinition(description = "Disk offering of the volume.", supportedTypes = {QuotaTypes.VOLUME})
     private GenericPresetVariable diskOffering;
+
+    @PresetVariableDefinition(description = "Storage where the volume or snapshot is. While handling with snapshots, this value can be from the primary storage if the global " +
+            "setting 'snapshot.backup.to.secondary' is false, otherwise it will be from secondary storage.", supportedTypes = {QuotaTypes.VOLUME, QuotaTypes.SNAPSHOT})
     private Storage storage;
+
+    @PresetVariableDefinition(description = "Computing resources consumed by the VM.", supportedTypes = {QuotaTypes.RUNNING_VM})
     private ComputingResources computingResources;
+
+    @PresetVariableDefinition(description = "Backup offering of the backup.", supportedTypes = {QuotaTypes.BACKUP})
     private BackupOffering backupOffering;
+
+    @PresetVariableDefinition(description = "The hypervisor where the resource was deployed. Values can be: XenServer, KVM, VMware, Hyperv, BareMetal, Ovm, Ovm3 and LXC.",
+            supportedTypes = {QuotaTypes.RUNNING_VM, QuotaTypes.ALLOCATED_VM, QuotaTypes.VM_SNAPSHOT, QuotaTypes.SNAPSHOT})
     private String hypervisorType;
+
+    @PresetVariableDefinition(description = "The volume format. Values can be: RAW, VHD, VHDX, OVA and QCOW2.", supportedTypes = {QuotaTypes.VOLUME, QuotaTypes.VOLUME_SECONDARY})
     private String volumeFormat;
     private String state;
 

framework/quota/src/main/java/org/apache/cloudstack/quota/constant/QuotaTypes.java

@@ -22,6 +22,7 @@
 
 import org.apache.cloudstack.usage.UsageTypes;
 import org.apache.cloudstack.usage.UsageUnitTypes;
+import org.apache.cloudstack.utils.reflectiontostringbuilderutils.ReflectionToStringBuilderUtils;
 
 public class QuotaTypes extends UsageTypes {
     private final Integer quotaType;
@@ -100,4 +101,13 @@ static public String getDescription(int quotaType) {
         }
         return null;
     }
+
+    static public QuotaTypes getQuotaType(int quotaType) {
+        return quotaTypeMap.get(quotaType);
+    }
+
+    @Override
+    public String toString() {
+        return ReflectionToStringBuilderUtils.reflectOnlySelectedFields(this, "quotaType", "quotaName");
+    }
 }

framework/quota/src/test/java/org/apache/cloudstack/quota/activationrule/presetvariables/ValueTest.java

@@ -25,6 +25,20 @@
 @RunWith(MockitoJUnitRunner.class)
 public class ValueTest {
 
+    @Test
+    public void setIdTestAddFieldIdToCollection() {
+        Value variable = new Value();
+        variable.setId(null);
+        Assert.assertTrue(variable.fieldNamesToIncludeInToString.contains("id"));
+    }
+
+    @Test
+    public void setNameTestAddFieldNameToCollection() {
+        Value variable = new Value();
+        variable.setName(null);
+        Assert.assertTrue(variable.fieldNamesToIncludeInToString.contains("name"));
+    }
+
     @Test
     public void setHostTestAddFieldHostToCollection() {
         Value variable = new Value();

plugins/database/quota/src/main/java/org/apache/cloudstack/api/command/QuotaPresetVariablesListCmd.java

@@ -0,0 +1,66 @@
+//Licensed to the Apache Software Foundation (ASF) under one
+//or more contributor license agreements.  See the NOTICE file
+//distributed with this work for additional information
+//regarding copyright ownership.  The ASF licenses this file
+//to you under the Apache License, Version 2.0 (the
+//"License"); you may not use this file except in compliance
+//with the License.  You may obtain a copy of the License at
+//
+//http://www.apache.org/licenses/LICENSE-2.0
+//
+//Unless required by applicable law or agreed to in writing,
+//software distributed under the License is distributed on an
+//"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+//KIND, either express or implied.  See the License for the
+//specific language governing permissions and limitations
+//under the License.
+package org.apache.cloudstack.api.command;
+
+import com.cloud.exception.InvalidParameterValueException;
+import com.cloud.user.Account;
+import org.apache.cloudstack.api.APICommand;
+import org.apache.cloudstack.api.ApiConstants;
+import org.apache.cloudstack.api.BaseCmd;
+import org.apache.cloudstack.api.Parameter;
+import org.apache.cloudstack.api.response.ListResponse;
+import org.apache.cloudstack.api.response.QuotaPresetVariablesItemResponse;
+import org.apache.cloudstack.api.response.QuotaResponseBuilder;
+import org.apache.cloudstack.quota.constant.QuotaTypes;
+
+import javax.inject.Inject;
+import java.util.List;
+
+@APICommand(name = "quotaPresetVariablesList", responseObject = QuotaPresetVariablesItemResponse.class, description = "List the preset variables available for using in the " +
+        "Quota tariff activation rules given the usage type.", since = "4.20", requestHasSensitiveInfo = false, responseHasSensitiveInfo = false)
+public class QuotaPresetVariablesListCmd extends BaseCmd {
+
+    @Inject
+    QuotaResponseBuilder quotaResponseBuilder;
+
+    @Parameter(name = ApiConstants.USAGE_TYPE, type = CommandType.INTEGER, required = true, description = "The usage type for which the preset variables will be retrieved.")
+    private Integer quotaType;
+
+    @Override
+    public void execute() {
+        List<QuotaPresetVariablesItemResponse> responses = quotaResponseBuilder.listQuotaPresetVariables(this);
+        ListResponse<QuotaPresetVariablesItemResponse> listResponse = new ListResponse<>();
+        listResponse.setResponses(responses);
+        listResponse.setResponseName(getCommandName());
+        setResponseObject(listResponse);
+    }
+
+    public QuotaTypes getQuotaType() {
+        QuotaTypes quotaTypes = QuotaTypes.getQuotaType(quotaType);
+
+        if (quotaTypes == null) {
+            throw new InvalidParameterValueException(String.format("Usage type not found for value [%s].", quotaType));
+        }
+
+        return quotaTypes;
+    }
+
+    @Override
+    public long getEntityOwnerId() {
+        return Account.ACCOUNT_ID_SYSTEM;
+    }
+}

plugins/database/quota/src/main/java/org/apache/cloudstack/api/response/QuotaPresetVariablesItemResponse.java

@@ -0,0 +1,47 @@
+//Licensed to the Apache Software Foundation (ASF) under one
+//or more contributor license agreements.  See the NOTICE file
+//distributed with this work for additional information
+//regarding copyright ownership.  The ASF licenses this file
+//to you under the Apache License, Version 2.0 (the
+//"License"); you may not use this file except in compliance
+//with the License.  You may obtain a copy of the License at
+//
+//http://www.apache.org/licenses/LICENSE-2.0
+//
+//Unless required by applicable law or agreed to in writing,
+//software distributed under the License is distributed on an
+//"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+//KIND, either express or implied.  See the License for the
+//specific language governing permissions and limitations
+//under the License.
+package org.apache.cloudstack.api.response;
+
+import com.cloud.serializer.Param;
+import com.google.gson.annotations.SerializedName;
+import org.apache.cloudstack.api.BaseResponse;
+
+public class QuotaPresetVariablesItemResponse extends BaseResponse {
+    @SerializedName("variable")
+    @Param(description = "variable")
+    private String variable;
+
+    @SerializedName("description")
+    @Param(description = "description")
+    private String description;
+
+    public QuotaPresetVariablesItemResponse() {
+        super("variables");
+    }
+
+    public void setVariable(String variable) {
+        this.variable = variable;
+    }
+
+    public String getDescription() {
+        return description;
+    }
+
+    public void setDescription(String description) {
+        this.description = description;
+    }
+}