com.katalon.platform.api.controller.FolderController Maven / Gradle / Ivy
package com.katalon.platform.api.controller;
import java.util.List;
import com.katalon.platform.api.exception.ResourceException;
import com.katalon.platform.api.model.FolderEntity;
import com.katalon.platform.api.model.ProjectEntity;
import com.katalon.platform.api.model.TestCaseEntity;
import com.katalon.platform.api.service.ProjectManager;
/**
* FolderController is a unique KS Controller to help KS plugins can manipulate {@link FolderEntity} in the file
* system.
*
* @see #getFolder(ProjectEntity, String)
* @see #newFolder(ProjectEntity, FolderEntity, String)
* @see #getAvailableFolderName(ProjectEntity, FolderEntity, String)
* @see #getChildTestCases(ProjectEntity, FolderEntity)
*
* @since 1.0.4
*/
public interface FolderController extends Controller {
/**
* Returns an instance of FolderEntity of the given project by the give folderId
*
* @param project an instance of working project. The current working project can retrieve by using
* {@link ProjectManager#getCurrentProject()}.
* @param folderId id of FolderEntity
* @return an instance of FolderEntity
* @throws ResourceException thrown if KS could not access information of the FolderEntity in the file system
* @since 1.0.4
*/
FolderEntity getFolder(ProjectEntity project, String folderId) throws ResourceException;
/**
* Creates new folder under the given parentFolder with a specified name
*
* @param project project an instance of working project. The current working project can retrieve by using
* {@link ProjectManager#getCurrentProject()}.
* @param parentFolder parent folder of new folder
* @param name name of new folder. Name should not be blank or content non-English characters. Please use
* {@link #getAvailableFolderName(ProjectEntity, FolderEntity, String)} before using.
* @return new created FolderEntity
* @throws ResourceException thrown if name is duplicated or invalid format, or KS could not create new folder in
* the file system.
*
* @since 1.0.4
*/
FolderEntity newFolder(ProjectEntity project, FolderEntity parentFolder, String name) throws ResourceException;
/**
* Returns an available name for the given name
*
* Sample of using: We want to create a folder with name New Folder under root folder Test Cases
*
* Case 1: There is no New Folder folder under Test Cases then the result is New
* Folder
*
* Case 2: New Folder folder exists, but New Folder (1) doesn't then the result is New Folder
* (1)
*
* Case 3: New Folder and New Folder (1) folder exist, but New Folder (2) doesn't then the
* result is New Folder (2)
*
* @param project project an instance of working project. The current working project can retrieve by using
* {@link ProjectManager#getCurrentProject()}.
* @param parentFolder parent folder that needs to check name
* @param name name of new folder. Name should not be blank or content non-English characters.
* @return a new available name
* @throws ResourceException thrown if name is invalid format, or KS could not read or access parent folder.
*
* @since 1.0.4
*/
String getAvailableFolderName(ProjectEntity project, FolderEntity parentFolder, String name)
throws ResourceException;
/**
* List the children test cases under a folder.
*
* @param project project an instance of working project. The current working project can retrieve by using
* {@link ProjectManager#getCurrentProject()}.
* @param parentFolder parent folder that needs to check.
* @return list of TestCaseEntity. The list can be empty but not null.
* @throws ResourceException thrown if KS could not read or access test cases under parent folder.
*
* @since 1.0.4
*/
List getChildTestCases(ProjectEntity project, FolderEntity parentFolder) throws ResourceException;
/**
* List the children folders under a folder.
*
* @param project project an instance of working project. The current working project can retrieve by using
* {@link ProjectManager#getCurrentProject()}.
* @param parentFolder parent folder that needs to check.
* @return list of FolderEntity. The list can be empty but not null.
* @throws ResourceException thrown if KS could not read or access test cases under parent folder.
*
* @since 1.0.7
*/
List getChildFolders(ProjectEntity project, FolderEntity parentFolder) throws ResourceException;
}