Create API to list Quota credits

api/src/main/java/org/apache/cloudstack/api/ApiConstants.java

@@ -1191,6 +1191,14 @@ public class ApiConstants {
             "numeric value will be applied; if the result is neither a boolean nor a numeric value, the tariff will not be applied. If the rule is not informed, the tariff " +
             "value will be applied.";
 
+    public static final String PARAMETER_DESCRIPTION_START_DATE_POSSIBLE_FORMATS = "The recommended format is \"yyyy-MM-dd'T'HH:mm:ssZ\" (e.g.: \"2023-01-01T12:00:00+0100\"); " +
+            "however, the following formats are also accepted: \"yyyy-MM-dd HH:mm:ss\" (e.g.: \"2023-01-01 12:00:00\") and \"yyyy-MM-dd\" (e.g.: \"2023-01-01\" - if the time is not " +
+            "added, it will be interpreted as \"00:00:00\"). If the recommended format is not used, the date will be considered in the server timezone.";
+
+    public static final String PARAMETER_DESCRIPTION_END_DATE_POSSIBLE_FORMATS = "The recommended format is \"yyyy-MM-dd'T'HH:mm:ssZ\" (e.g.: \"2023-01-01T12:00:00+0100\"); " +
+            "however, the following formats are also accepted: \"yyyy-MM-dd HH:mm:ss\" (e.g.: \"2023-01-01 12:00:00\") and \"yyyy-MM-dd\" (e.g.: \"2023-01-01\" - if the time is not " +
+            "added, it will be interpreted as \"23:59:59\"). If the recommended format is not used, the date will be considered in the server timezone.";
+
     /**
      * This enum specifies IO Drivers, each option controls specific policies on I/O.
      * Qemu guests support "threads" and "native" options Since 0.8.8 ; "io_uring" is supported Since 6.3.0 (QEMU 5.0).
@@ -1213,14 +1221,6 @@ public String toString() {
         }
     }
 
-    public static final String PARAMETER_DESCRIPTION_START_DATE_POSSIBLE_FORMATS = "The recommended format is \"yyyy-MM-dd'T'HH:mm:ssZ\" (e.g.: \"2023-01-01T12:00:00+0100\"); " +
-            "however, the following formats are also accepted: \"yyyy-MM-dd HH:mm:ss\" (e.g.: \"2023-01-01 12:00:00\") and \"yyyy-MM-dd\" (e.g.: \"2023-01-01\" - if the time is not " +
-            "added, it will be interpreted as \"00:00:00\"). If the recommended format is not used, the date will be considered in the server timezone.";
-
-    public static final String PARAMETER_DESCRIPTION_END_DATE_POSSIBLE_FORMATS = "The recommended format is \"yyyy-MM-dd'T'HH:mm:ssZ\" (e.g.: \"2023-01-01T12:00:00+0100\"); " +
-            "however, the following formats are also accepted: \"yyyy-MM-dd HH:mm:ss\" (e.g.: \"2023-01-01 12:00:00\") and \"yyyy-MM-dd\" (e.g.: \"2023-01-01\" - if the time is not " +
-            "added, it will be interpreted as \"23:59:59\"). If the recommended format is not used, the date will be considered in the server timezone.";
-
     public enum BootType {
         UEFI, BIOS;
 

engine/schema/src/main/java/com/cloud/domain/dao/DomainDao.java

@@ -42,5 +42,7 @@ public interface DomainDao extends GenericDao<DomainVO, Long> {
 
     List<Long> getDomainChildrenIds(String path);
 
+    List<Long> getDomainAndChildrenIds(long domainId);
+
     boolean domainIdListContainsAccessibleDomain(String domainIdList, Account caller, Long domainId);
 }

engine/schema/src/main/java/com/cloud/domain/dao/DomainDaoImpl.java

@@ -19,6 +19,7 @@
 import java.sql.PreparedStatement;
 import java.sql.ResultSet;
 import java.sql.SQLException;
+import java.util.ArrayList;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
@@ -238,6 +239,15 @@
         return customSearch(sc, null);
     }
 
+    @Override
+    public List<Long> getDomainAndChildrenIds(long domainId) {
+        DomainVO domain = findById(domainId);
+        if (domain != null) {
+            return getDomainChildrenIds(domain.getPath());
+        }
+        return new ArrayList<>();
+    }
+
     @Override
     public boolean isChildDomain(Long parentId, Long childId) {
         if ((parentId == null) || (childId == null)) {

engine/schema/src/main/resources/META-INF/db/schema-42010to42100.sql

@@ -24,3 +24,10 @@ CALL `cloud`.`IDEMPOTENT_ADD_COLUMN`('cloud.console_session', 'console_endpoint_
 
 -- Add client_address column to cloud.console_session table
 CALL `cloud`.`IDEMPOTENT_ADD_COLUMN`('cloud.console_session', 'client_address', 'VARCHAR(45)');
+
+-- Allow default roles to use quotaCreditsList
+INSERT INTO cloud.role_permissions (uuid, role_id, rule, permission, sort_order)
+SELECT uuid(), role_id, 'quotaCreditsList', permission, sort_order
+FROM cloud.role_permissions rp
+WHERE rule = 'quotaStatement'
+AND NOT EXISTS(SELECT 1 FROM cloud.role_permissions rp_ WHERE rp.role_id = rp_.role_id AND rp_.rule = 'quotaCreditsList');

framework/quota/src/main/java/org/apache/cloudstack/quota/dao/QuotaCreditsDao.java

@@ -25,7 +25,7 @@
 
 public interface QuotaCreditsDao extends GenericDao<QuotaCreditsVO, Long> {
 
-    List<QuotaCreditsVO> findCredits(long accountId, long domainId, Date startDate, Date endDate);
+    List<QuotaCreditsVO> findCredits(Long accountId, Long domainId, Date startDate, Date endDate, boolean recursive);
 
     QuotaCreditsVO saveCredits(QuotaCreditsVO credits);
 

framework/quota/src/main/java/org/apache/cloudstack/quota/dao/QuotaCreditsDaoImpl.java

@@ -16,19 +16,20 @@
 //under the License.
 package org.apache.cloudstack.quota.dao;
 
-import java.util.Collections;
 import java.util.Date;
 import java.util.List;
 
 import javax.inject.Inject;
 
+import com.cloud.domain.dao.DomainDao;
+import com.cloud.utils.db.Filter;
+import com.cloud.utils.db.SearchBuilder;
 import org.apache.cloudstack.quota.vo.QuotaBalanceVO;
 import org.apache.cloudstack.quota.vo.QuotaCreditsVO;
+import org.apache.commons.lang3.ObjectUtils;
 import org.springframework.stereotype.Component;
 
-import com.cloud.utils.db.Filter;
 import com.cloud.utils.db.GenericDaoBase;
-import com.cloud.utils.db.QueryBuilder;
 import com.cloud.utils.db.SearchCriteria;
 import com.cloud.utils.db.Transaction;
 import com.cloud.utils.db.TransactionCallback;
@@ -39,25 +40,36 @@
 public class QuotaCreditsDaoImpl extends GenericDaoBase<QuotaCreditsVO, Long> implements QuotaCreditsDao {
 
     @Inject
-    QuotaBalanceDao _quotaBalanceDao;
+    DomainDao domainDao;
+    @Inject
+    QuotaBalanceDao quotaBalanceDao;
+
+    private SearchBuilder<QuotaCreditsVO> quotaCreditsVoSearch;
+
+    public QuotaCreditsDaoImpl() {
+        quotaCreditsVoSearch = createSearchBuilder();
+        quotaCreditsVoSearch.and("updatedOn", quotaCreditsVoSearch.entity().getUpdatedOn(), SearchCriteria.Op.BETWEEN);
+        quotaCreditsVoSearch.and("accountId", quotaCreditsVoSearch.entity().getAccountId(), SearchCriteria.Op.EQ);
+        quotaCreditsVoSearch.and("domainId", quotaCreditsVoSearch.entity().getDomainId(), SearchCriteria.Op.IN);
+        quotaCreditsVoSearch.done();
+    }
 
     @Override
-    public List<QuotaCreditsVO> findCredits(final long accountId, final long domainId, final Date startDate, final Date endDate) {
-        return Transaction.execute(TransactionLegacy.USAGE_DB, new TransactionCallback<List<QuotaCreditsVO>>() {
-            @Override
-            public List<QuotaCreditsVO> doInTransaction(final TransactionStatus status) {
-                if ((startDate != null) && (endDate != null) && startDate.before(endDate)) {
-                    Filter filter = new Filter(QuotaCreditsVO.class, "updatedOn", true, 0L, Long.MAX_VALUE);
-                    QueryBuilder<QuotaCreditsVO> qb = QueryBuilder.create(QuotaCreditsVO.class);
-                    qb.and(qb.entity().getAccountId(), SearchCriteria.Op.EQ, accountId);
-                    qb.and(qb.entity().getDomainId(), SearchCriteria.Op.EQ, domainId);
-                    qb.and(qb.entity().getUpdatedOn(), SearchCriteria.Op.BETWEEN, startDate, endDate);
-                    return search(qb.create(), filter);
-                } else {
-                    return Collections.<QuotaCreditsVO> emptyList();
-                }
-            }
-        });
+    public List<QuotaCreditsVO> findCredits(Long accountId, Long domainId, Date startDate, Date endDate, boolean recursive) {
+        SearchCriteria<QuotaCreditsVO> sc = quotaCreditsVoSearch.create();
+        Filter filter = new Filter(QuotaCreditsVO.class, "updatedOn", true, 0L, Long.MAX_VALUE);
+
+        sc.setParametersIfNotNull("accountId", accountId);
+        if (domainId != null) {
+            List<Long> domainIds = recursive ? domainDao.getDomainAndChildrenIds(domainId) : List.of(domainId);
+            sc.setParameters("domainId", domainIds.toArray());
+        }
+
+        if (ObjectUtils.allNotNull(startDate, endDate)) {
+            sc.setParameters("updatedOn", startDate, endDate);
+        }
+
+        return Transaction.execute(TransactionLegacy.USAGE_DB, (TransactionCallback<List<QuotaCreditsVO>>) status -> search(sc, filter));
     }
 
     @Override
@@ -68,7 +80,7 @@
                 persist(credits);
                 // make an entry in the balance table
                 QuotaBalanceVO bal = new QuotaBalanceVO(credits);
-                _quotaBalanceDao.persist(bal);
+                quotaBalanceDao.persist(bal);
                 return credits;
             }
         });

framework/quota/src/main/java/org/apache/cloudstack/quota/vo/QuotaCreditsVO.java

@@ -17,6 +17,7 @@
 package org.apache.cloudstack.quota.vo;
 
 import org.apache.cloudstack.api.InternalIdentity;
+import org.apache.cloudstack.utils.reflectiontostringbuilderutils.ReflectionToStringBuilderUtils;
 
 import javax.persistence.Column;
 import javax.persistence.Entity;
@@ -113,4 +114,9 @@
     public long getId() {
         return this.id;
     }
+
+    @Override
+    public String toString() {
+        return ReflectionToStringBuilderUtils.reflectOnlySelectedFields(this, "id", "accountId", "domainId", "credit");
+    }
 }

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

@@ -0,0 +1,122 @@
+//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.utils.Pair;
+
+import org.apache.cloudstack.api.ACL;
+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.AccountResponse;
+import org.apache.cloudstack.api.response.DomainResponse;
+import org.apache.cloudstack.api.response.ListResponse;
+import org.apache.cloudstack.api.response.QuotaCreditsResponse;
+import org.apache.cloudstack.api.response.QuotaResponseBuilder;
+import org.apache.commons.lang3.ObjectUtils;
+import org.apache.commons.lang3.time.DateUtils;
+
+import java.util.Calendar;
+import java.util.Date;
+import java.util.List;
+
+import javax.inject.Inject;
+
+@APICommand(name = "quotaCreditsList", responseObject = QuotaCreditsResponse.class, description = "Lists quota credits of an account.", since = "4.20.0",
+        requestHasSensitiveInfo = false, responseHasSensitiveInfo = false)
+public class QuotaCreditsListCmd extends BaseCmd {
+
+    @Inject
+    QuotaResponseBuilder quotaResponseBuilder;
+
+    @ACL
+    @Parameter(name = ApiConstants.ACCOUNT_ID, type = CommandType.UUID, entityType = AccountResponse.class, description = "ID of the account for which the credit statement will be generated.")
+    private Long accountId;
+
+    @ACL
+    @Parameter(name = ApiConstants.DOMAIN_ID, type = CommandType.UUID, entityType = DomainResponse.class, description = "ID of the domain for which credit statement will be generated. " +
+            "Available only for administrators.")
+    private Long domainId;
+
+    @Parameter(name = ApiConstants.END_DATE, type = CommandType.DATE, description = "End date of the credit statement. If not provided, the current date will be " +
+            "considered as the end date. " + ApiConstants.PARAMETER_DESCRIPTION_END_DATE_POSSIBLE_FORMATS)
+    private Date endDate;
+
+    @Parameter(name = ApiConstants.START_DATE, type = CommandType.DATE, description = "Start date of the credit statement. If not provided, the first day of the current month " +
+            "will be considered as the start date. " + ApiConstants.PARAMETER_DESCRIPTION_START_DATE_POSSIBLE_FORMATS)
+    private Date startDate;
+
+    @Parameter(name = ApiConstants.IS_RECURSIVE, type = CommandType.BOOLEAN, description = "Whether to generate the credit statement for the provided domain and its children. " +
+            "Defaults to false.")
+    private Boolean recursive = false;
+
+    public Long getAccountId() {
+        return accountId;
+    }
+
+    public void setAccountId(Long accountId) {
+        this.accountId = accountId;
+    }
+
+    public Long getDomainId() {
+        return domainId;
+    }
+
+    public void setDomainId(Long domainId) {
+        this.domainId = domainId;
+    }
+
+    public Date getEndDate() {
+        return ObjectUtils.defaultIfNull(endDate, new Date());
+    }
+
+    public void setEndDate(Date endDate) {
+        this.endDate = endDate;
+    }
+
+    public Date getStartDate() {
+        return ObjectUtils.defaultIfNull(startDate, DateUtils.truncate(new Date(), Calendar.MONTH));
+    }
+
+    public void setStartDate(Date startDate) {
+        this.startDate = startDate;
+    }
+
+    public Boolean getRecursive() {
+        return recursive;
+    }
+
+    public void setRecursive(Boolean recursive) {
+        this.recursive = recursive;
+    }
+
+    @Override
+    public void execute() {
+        Pair<List<QuotaCreditsResponse>, Integer> responses = quotaResponseBuilder.createQuotaCreditsListResponse(this);
+        ListResponse<QuotaCreditsResponse> response = new ListResponse<>();
+        response.setResponses(responses.first(), responses.second());
+        response.setResponseName(getCommandName());
+        setResponseObject(response);
+    }
+
+    @Override
+    public long getEntityOwnerId() {
+        return -1;
+    }
+
+}

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

@@ -122,8 +122,8 @@
 
     public void addCredits(QuotaBalanceVO credit) {
         QuotaCreditsResponse cr = new QuotaCreditsResponse();
-        cr.setCredits(credit.getCreditBalance());
-        cr.setUpdatedOn(credit.getUpdatedOn() == null ? null : new Date(credit.getUpdatedOn().getTime()));
+        cr.setCredit(credit.getCreditBalance());
+        cr.setCreditedOn(credit.getUpdatedOn());
         credits.add(0, cr);
     }