V2NIMSearchTeamMemberParams.java

浏览该文件的文档.

package com.netease.nimlib.sdk.v2.team.params;

import com.netease.nimlib.sdk.v2.message.enums.V2NIMSearchKeywordMathType;
import com.netease.nimlib.sdk.v2.team.model.V2NIMTeamRefer;
import java.util.ArrayList;
import java.util.List;

/**
 * 搜索群成员参数类
 * <p>
 * 该类用于配置搜索群成员的各种参数，包括关键字列表、匹配类型、目标群组等。
 * 支持在指定群组中搜索成员，也支持全局搜索所有群成员。
 * </p>
 *
 */
public class V2NIMSearchTeamMemberParams {

    /**
     * 关键字列表
     * <p>
     * 用于搜索的关键字列表，最多支持5个关键字。
     * null和size==0都表示为空，将返回参数错误。
     * </p>
     */
    private List<String> keywordList;

    /**
     * 关键字匹配类型
     * <p>
     * 指定关键字列表的匹配类型：
     * <ul>
     *   <li>V2NIM_SEARCH_KEYWORD_MATH_TYPE_OR: "或"关系搜索</li>
     *   <li>V2NIM_SEARCH_KEYWORD_MATH_TYPE_AND: "与"关系搜索</li>
     * </ul>
     * 默认为"或"关系搜索。当关键字列表为空或数量为1时，该字段无效。
     * </p>
     */
    private V2NIMSearchKeywordMathType keywordMatchType;

    /**
     * 群组引用列表
     * <p>
     * 需要检索的群ID列表，设置后将检索对应群组包含的群成员。
     * 该参数为空时，检索全部群成员。
     * 最大50个，超过50返回参数错误。
     * </p>
     */
    private List<V2NIMTeamRefer> teamRefers;

    /**
     * 是否搜索用户账号
     * <p>
     * 默认不启动搜索。由于大部分场景账号ID都是无实际业务意义标识串，
     * 因此默认不会对该字段构建索引，减少空间消耗。
     * 如果需要同时检索该字段，需要在应用首次使用时配置
     * 初始化字段：searchAccountIdEnabled为true。
     * </p>
     */
    private boolean searchAccountId;

    /**
     * 是否同时搜索群昵称
     * <p>
     * 默认为true。searchAccountId和searchTeamNick不能同时为false，
     * 否则返回参数错误。
     * </p>
     */
    private boolean searchTeamNick;

    /**
     * 单次检索返回的数量
     * <p>
     * 默认20，本地可以设置INT.MAXVALUE返回所有检索结果。
     * 必须为正数，云端检索不建议超过100。
     * 小于等于0返回参数错误。
     * 该参数仅服务器有效。
     * </p>
     */
    private int limit;

    /**
     * 起始位置标记
     * <p>
     * 首次传空字符串""，后续传上次返回的nextToken。
     * 该参数仅服务器有效。
     * </p>
     */
    private String nextToken;

    /**
     * 默认构造方法
     * <p>
     * 初始化默认值：
     * <ul>
     *   <li>keywordMatchType: V2NIM_SEARCH_KEYWORD_MATH_TYPE_OR</li>
     *   <li>searchAccountId: false</li>
     *   <li>searchTeamNick: true</li>
     *   <li>limit: 20</li>
     *   <li>nextToken: ""</li>
     * </ul>
     * </p>
     */
    public V2NIMSearchTeamMemberParams() {
        this.keywordMatchType = V2NIMSearchKeywordMathType.V2NIM_SEARCH_KEYWORD_MATH_TYPE_OR;
        this.searchAccountId = false;
        this.searchTeamNick = true;
        this.limit = 20;
        this.nextToken = "";
    }

    /**
     * 获取关键字列表
     * 
     * @return 关键字列表，可能为null
     */
    public List<String> getKeywordList() {
        return keywordList;
    }

    /**
     * 设置关键字列表
     * 
     * @param keywordList 关键字列表，最多5个，不能为null或空
     */
    public void setKeywordList(List<String> keywordList) {
        this.keywordList = keywordList;
    }

    /**
     * 获取关键字匹配类型
     * 
     * @return 关键字匹配类型
     */
    public V2NIMSearchKeywordMathType getKeywordMatchType() {
        return keywordMatchType;
    }

    /**
     * 设置关键字匹配类型
     * 
     * @param keywordMatchType 关键字匹配类型
     */
    public void setKeywordMatchType(V2NIMSearchKeywordMathType keywordMatchType) {
        this.keywordMatchType = keywordMatchType;
    }

    /**
     * 获取群组引用列表
     * 
     * @return 群组引用列表，可能为null
     */
    public List<V2NIMTeamRefer> getTeamRefers() {
        return teamRefers;
    }

    /**
     * 设置群组引用列表
     * 
     * @param teamRefers 群组引用列表，最多50个
     */
    public void setTeamRefers(List<V2NIMTeamRefer> teamRefers) {
        this.teamRefers = teamRefers;
    }

    /**
     * 是否搜索用户账号
     * 
     * @return true表示搜索用户账号，false表示不搜索
     */
    public boolean isSearchAccountId() {
        return searchAccountId;
    }

    /**
     * 设置是否搜索用户账号
     * 
     * @param searchAccountId true表示搜索用户账号，false表示不搜索
     */
    public void setSearchAccountId(boolean searchAccountId) {
        this.searchAccountId = searchAccountId;
    }

    /**
     * 是否搜索群昵称
     * 
     * @return true表示搜索群昵称，false表示不搜索
     */
    public boolean isSearchTeamNick() {
        return searchTeamNick;
    }

    /**
     * 设置是否搜索群昵称
     * 
     * @param searchTeamNick true表示搜索群昵称，false表示不搜索
     */
    public void setSearchTeamNick(boolean searchTeamNick) {
        this.searchTeamNick = searchTeamNick;
    }

    /**
     * 获取单次检索返回的数量限制
     * 
     * @return 数量限制
     */
    public int getLimit() {
        return limit;
    }

    /**
     * 设置单次检索返回的数量限制
     * 仅服务器有效
     * 
     * @param limit 数量限制，必须为正数
     */
    public void setLimit(int limit) {
        this.limit = limit;
    }

    /**
     * 获取起始位置标记
     * 
     * @return 起始位置标记
     */
    public String getNextToken() {
        return nextToken;
    }

    /**
     * 设置起始位置标记
     * 仅服务器有效
     * 
     * @param nextToken 起始位置标记
     */
    public void setNextToken(String nextToken) {
        this.nextToken = nextToken;
    }

    /**
     * 验证参数有效性
     * 
     * @return true表示参数有效，false表示参数无效
     */
    @SuppressWarnings("java:S1126")
    public boolean isValid() {
        // 关键字列表不能为空
        if (keywordList == null || keywordList.isEmpty()) {
            return false;
        }
        
        // 关键字列表最多5个
        if (keywordList.size() > 5) {
            return false;
        }
        
        // searchAccountId和searchTeamNick不能同时为false
        if (!searchAccountId && !searchTeamNick) {
            return false;
        }
        
        // teamRefers最多50个
        if (teamRefers != null && teamRefers.size() > 50) {
            return false;
        }
        
        return true;
    }

    /**
     * 验证参数有效性
     *
     * @return true表示参数有效，false表示参数无效
     */
    public String isValidWithErrorMsg() {
        // 关键字列表不能为空
        if (keywordList == null || keywordList.isEmpty()) {
            return "keywordList is null or empty";
        }

        // 关键字列表最多5个
        if (keywordList.size() > 5) {
            return "keywordList size > 5";
        }

        // searchAccountId和searchTeamNick不能同时为false
        if (!searchAccountId && !searchTeamNick) {
            return "searchAccountId and searchTeamNick are both false";
        }

        // teamRefers最多50个
        if (teamRefers != null && teamRefers.size() > 50) {
            return "teamRefers size > 50";
        }

        return null;
    }

    /**
     * V2NIMSearchTeamMemberParams的Builder类
     * <p>
     * 用于构建V2NIMSearchTeamMemberParams对象，提供流式API。
     * </p>
     */
    public static class Builder {
        private V2NIMSearchTeamMemberParams params;

        /**
         * 构造Builder
         */
        public Builder() {
            this.params = new V2NIMSearchTeamMemberParams();
        }

        /**
         * 设置关键字列表
         * 
         * @param keywordList 关键字列表
         * @return Builder对象
         */
        public Builder keywordList(List<String> keywordList) {
            params.setKeywordList(keywordList);
            return this;
        }

        /**
         * 添加单个关键字
         * 
         * @param keyword 关键字
         * @return Builder对象
         */
        public Builder addKeyword(String keyword) {
            if (params.getKeywordList() == null) {
                params.setKeywordList(new ArrayList<>());
            }
            params.getKeywordList().add(keyword);
            return this;
        }

        /**
         * 设置关键字匹配类型
         * 
         * @param keywordMatchType 关键字匹配类型
         * @return Builder对象
         */
        public Builder keywordMatchType(V2NIMSearchKeywordMathType keywordMatchType) {
            params.setKeywordMatchType(keywordMatchType);
            return this;
        }

        /**
         * 设置群组引用列表
         * 
         * @param teamRefers 群组引用列表
         * @return Builder对象
         */
        public Builder teamRefers(List<V2NIMTeamRefer> teamRefers) {
            params.setTeamRefers(teamRefers);
            return this;
        }

        /**
         * 添加单个群组引用
         * 
         * @param teamRefer 群组引用
         * @return Builder对象
         */
        public Builder addTeamRefer(V2NIMTeamRefer teamRefer) {
            if (params.getTeamRefers() == null) {
                params.setTeamRefers(new ArrayList<>());
            }
            params.getTeamRefers().add(teamRefer);
            return this;
        }

        /**
         * 设置是否搜索用户账号
         * 
         * @param searchAccountId 是否搜索用户账号
         * @return Builder对象
         */
        public Builder searchAccountId(boolean searchAccountId) {
            params.setSearchAccountId(searchAccountId);
            return this;
        }

        /**
         * 设置是否搜索群昵称
         * 
         * @param searchTeamNick 是否搜索群昵称
         * @return Builder对象
         */
        public Builder searchTeamNick(boolean searchTeamNick) {
            params.setSearchTeamNick(searchTeamNick);
            return this;
        }

        /**
         * 设置单次检索返回的数量限制
         * 
         * @param limit 数量限制
         * @return Builder对象
         */
        public Builder limit(int limit) {
            params.setLimit(limit);
            return this;
        }

        /**
         * 设置起始位置标记
         * 
         * @param nextToken 起始位置标记
         * @return Builder对象
         */
        public Builder nextToken(String nextToken) {
            params.setNextToken(nextToken);
            return this;
        }

        /**
         * 构建V2NIMSearchTeamMemberParams对象
         * 
         * @return V2NIMSearchTeamMemberParams对象
         * @throws IllegalArgumentException 当参数无效时
         */
        public V2NIMSearchTeamMemberParams build() {
            return params;
        }
    }

    @Override
    public String toString() {
        return "V2NIMSearchTeamMemberParams{" +
                "keywordList=" + keywordList +
                ", keywordMatchType=" + keywordMatchType +
                ", teamRefers=" + teamRefers +
                ", searchAccountId=" + searchAccountId +
                ", searchTeamNick=" + searchTeamNick +
                ", limit=" + limit +
                ", nextToken='" + nextToken + '\'' +
                '}';
    }
}