001package io.ebean;
002
003import io.avaje.lang.NonNullApi;
004
005/**
006 * Builds a FetchGroup by adding fetch clauses.
007 * <p>
008 * We add select() and fetch() clauses to define the object graph we want to load.
009 * </p>
010 *
011 * <pre>{@code
012 *
013 * FetchGroup fetchGroup = FetchGroup
014 *   .select("name, status")
015 *   .fetch("contacts", "firstName, lastName, email")
016 *   .build();
017 *
018 * Customer.query()
019 *   .select(fetchGroup)
020 *   .where()
021 *   ...
022 *   .findList();
023 *
024 * }</pre>
025 */
026@NonNullApi
027public interface FetchGroupBuilder<T> {
028
029  /**
030   * Specify specific properties to select (top level properties).
031   */
032  FetchGroupBuilder<T> select(String select);
033
034  /**
035   * Fetch all the properties at the given path.
036   */
037  FetchGroupBuilder<T> fetch(String path);
038
039  /**
040   * Fetch the path with the nested fetch group.
041   */
042  FetchGroupBuilder<T> fetch(String path, FetchGroup<?> nestedGroup);
043
044  /**
045   * Fetch the path using a query join with the nested fetch group.
046   */
047  FetchGroupBuilder<T> fetchQuery(String path, FetchGroup<?> nestedGroup);
048
049  /**
050   * Fetch the path lazily with the nested fetch group.
051   */
052  FetchGroupBuilder<T> fetchLazy(String path, FetchGroup<?> nestedGroup);
053
054  /**
055   * Fetch the path including specified properties.
056   */
057  FetchGroupBuilder<T> fetch(String path, String properties);
058
059  /**
060   * Fetch the path including all its properties using a query join.
061   */
062  FetchGroupBuilder<T> fetchQuery(String path);
063
064  /**
065   * Fetch the path including all its properties using L2 cache.
066   * Cache misses fallback to fetchQuery().
067   */
068  FetchGroupBuilder<T> fetchCache(String path);
069
070  /**
071   * Fetch the path including specified properties using a query join.
072   */
073  FetchGroupBuilder<T> fetchQuery(String path, String properties);
074
075  /**
076   * Fetch the path including specified properties using L2 cache.
077   * Cache misses fallback to fetchQuery().
078   */
079  FetchGroupBuilder<T> fetchCache(String path, String properties);
080
081  /**
082   * Fetch the path including all its properties lazily.
083   */
084  FetchGroupBuilder<T> fetchLazy(String path);
085
086  /**
087   * Fetch the path including specified properties lazily.
088   */
089  FetchGroupBuilder<T> fetchLazy(String path, String properties);
090
091  /**
092   * Build and return the FetchGroup.
093   */
094  FetchGroup<T> build();
095}