package com.xmomen.module.resource.api;

import java.io.File;
import java.util.List;
import java.util.Map;

/**
 * DfsService 接口定义了与分布式文件系统（DFS）进行交互的一系列操作。
 * 这些操作涵盖了文件的上传、下载、删除、列表获取以及路径获取等功能。
 */
public interface DfsService {

    /**
     * 将本地文件上传到分布式文件系统。
     *
     * @param filePath 文件在本地的路径，用于定位要上传的文件。
     * @param key  文件的唯一标识，可用于区分不同的文件。
     * @param metadata  文件的元数据，以键值对的形式存储额外信息。
     * @return 若上传成功，返回包含文件在 DFS 中路径信息的 DfsPath 对象；若失败则返回 null。
     */
    public DfsPath putObject(String filePath, String key, Map<String, String> metadata);

    /**
     * 将 File 对象表示的文件上传到分布式文件系统。
     *
     * @param file  要上传的文件对象。
     * @param key  文件的唯一标识，用于区分不同的文件。
     * @param metadata  文件的元数据，以键值对的形式存储额外信息。
     * @return 若上传成功，返回包含文件在 DFS 中路径信息的 DfsPath 对象；若失败则返回 null。
     */
    public DfsPath putObject(File file, String key, Map<String, String> metadata);

    /**
     * 将字节数组形式的文件内容上传到分布式文件系统。
     *
     * @param bytes  文件的字节数据，代表文件的实际内容。
     * @param key  文件的唯一标识，用于区分不同的文件。
     * @param metadata  文件的元数据，以键值对的形式存储额外信息。
     * @param extName  文件的扩展名，用于标识文件类型。
     * @return 若上传成功，返回包含文件在 DFS 中路径信息的 DfsPath 对象；若失败则返回 null。
     */
    public DfsPath putObject(byte[] bytes, String key, Map<String, String> metadata, String extName);

    /**
     * 从分布式文件系统中根据远程路径和键获取文件。
     *
     * @param remotePath  文件在分布式文件系统中的远程路径，用于定位文件。
     * @param key  文件的唯一标识，用于验证文件的身份。
     * @return 若获取成功，返回包含文件数据和元信息的 DfsFile 对象；若失败则返回 null。
     */
    public DfsFile getObject(String remotePath, String key);

    /**
     * 从分布式文件系统中删除指定远程路径和键对应的文件。
     *
     * @param remotePath  文件在分布式文件系统中的远程路径，用于定位要删除的文件。
     * @param key  文件的唯一标识，用于验证要删除的文件。
     * @return 若删除成功，返回 true；若失败则返回 false。
     */
    public boolean deleteObject(String remotePath, String key);

    /**
     * 获取分布式文件系统中的文件列表。
     *
     * @return 返回一个包含 DfsFile 对象的列表，每个对象代表文件系统中的一个文件；若列表为空则返回空列表。
     */
    public List<DfsFile> listObjects();

    /**
     * 根据文件在分布式文件系统中的远程路径获取其完整的 HTTP 访问路径。
     *
     * @param remotePath  文件在分布式文件系统中的远程路径。
     * @return 返回文件的完整 HTTP 访问路径，可用于在网络上访问该文件。
     */
    public String getHttpPath(String remotePath);

    /**
     * 根据 DMS 文件路径获取其对应的完整 HTTP 访问路径。
     * DMS 可能是某种特定的文件管理系统。
     *
     * @param dmsFilePath  DMS 系统中的文件路径。
     * @return 返回该文件对应的完整 HTTP 访问路径。
     */
    public String getDmsHttpPath(String dmsFilePath);

    /**
     * 根据指定的类型获取默认路径。
     * 这里的类型可能是文件的分类、用途等，具体含义取决于实现。
     *
     * @param type  文件的类型标识。
     * @return 返回对应类型的默认路径。
     */
    public String getDefaultPath(String type);
}