001/*
002 *  Copyright (c) 2022-2025, Mybatis-Flex (fuhai999@gmail.com).
003 *  <p>
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *  <p>
008 *  http://www.apache.org/licenses/LICENSE-2.0
009 *  <p>
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016
017package com.mybatisflex.core.query;
018
019import com.mybatisflex.core.paginate.Page;
020
021import java.util.List;
022import java.util.Optional;
023
024/**
025 * <p>链式查询接口。
026 *
027 * <p>该接口定义了通用的链式查询方法：
028 * <ul>
029 *     <li><b>one</b>: 查询一条数据。
030 *     <li><b>list</b>: 查询多条数据。
031 *     <li><b>page</b>: 分页查询数据。
032 * </ul>
033 *
034 * @param <T> 实体类类型
035 * @author 王帅
036 * @since 2023-08-08
037 */
038public interface ChainQuery<T> {
039
040    /**
041     * 获取一条数据。
042     *
043     * @return 一条数据
044     */
045    T one();
046
047    /**
048     * 获取一条数据，返回的数据为 asType 类型。
049     *
050     * @param asType 接收数据类型
051     * @param <R>    接收数据类型
052     * @return 一条数据
053     */
054    <R> R oneAs(Class<R> asType);
055
056    /**
057     * 获取一条数据，并封装为 {@link Optional} 返回。
058     *
059     * @return 一条数据
060     */
061    default Optional<T> oneOpt() {
062        return Optional.ofNullable(one());
063    }
064
065    /**
066     * 获取一条数据，返回的数据为 asType 类型，并封装为 {@link Optional} 返回。
067     *
068     * @param asType 接收数据类型
069     * @param <R>    接收数据类型
070     * @return 一条数据
071     */
072    default <R> Optional<R> oneAsOpt(Class<R> asType) {
073        return Optional.ofNullable(oneAs(asType));
074    }
075
076    /**
077     * 获取多条数据。
078     *
079     * @return 数据列表
080     */
081    List<T> list();
082
083    /**
084     * 获取多条数据，返回的数据为 asType 类型。
085     *
086     * @param asType 接收数据类型
087     *               @param <R>    接收数据类型
088     * @return 数据列表
089     */
090    <R> List<R> listAs(Class<R> asType);
091
092    /**
093     * 获取分页数据。
094     *
095     * @param page 分页对象
096     * @return 分页数据
097     */
098    Page<T> page(Page<T> page);
099
100    /**
101     * 获取分页数据，返回的数据为 asType 类型。
102     *
103     * @param page   分页对象
104     * @param asType 接收数据类型
105     *               @param <R>    接收数据类型
106     * @return 分页数据
107     */
108    <R> Page<R> pageAs(Page<R> page, Class<R> asType);
109
110}