001package io.ebean;
002
003import javax.annotation.Nonnull;
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 */
026public interface FetchGroupBuilder<T> {
027
028  /**
029   * Specify specific properties to select (top level properties).
030   */
031  @Nonnull
032  FetchGroupBuilder<T> select(String select);
033
034  /**
035   * Fetch all the properties at the given path.
036   */
037  @Nonnull
038  FetchGroupBuilder<T> fetch(String path);
039
040  /**
041   * Fetch the path with the nested fetch group.
042   */
043  @Nonnull
044  FetchGroupBuilder<T> fetch(String path, FetchGroup<?> nestedGroup);
045
046  /**
047   * Fetch the path using a query join with the nested fetch group.
048   */
049  @Nonnull
050  FetchGroupBuilder<T> fetchQuery(String path, FetchGroup<?> nestedGroup);
051
052  /**
053   * Fetch the path lazily with the nested fetch group.
054   */
055  @Nonnull
056  FetchGroupBuilder<T> fetchLazy(String path, FetchGroup<?> nestedGroup);
057
058  /**
059   * Fetch the path including specified properties.
060   */
061  @Nonnull
062  FetchGroupBuilder<T> fetch(String path, String properties);
063
064  /**
065   * Fetch the path including all its properties using a query join.
066   */
067  @Nonnull
068  FetchGroupBuilder<T> fetchQuery(String path);
069
070  /**
071   * Fetch the path including all its properties using L2 cache.
072   * Cache misses fallback to fetchQuery().
073   */
074  @Nonnull
075  FetchGroupBuilder<T> fetchCache(String path);
076
077  /**
078   * Fetch the path including specified properties using a query join.
079   */
080  @Nonnull
081  FetchGroupBuilder<T> fetchQuery(String path, String properties);
082
083  /**
084   * Fetch the path including specified properties using L2 cache.
085   * Cache misses fallback to fetchQuery().
086   */
087  @Nonnull
088  FetchGroupBuilder<T> fetchCache(String path, String properties);
089
090  /**
091   * Fetch the path including all its properties lazily.
092   */
093  @Nonnull
094  FetchGroupBuilder<T> fetchLazy(String path);
095
096  /**
097   * Fetch the path including specified properties lazily.
098   */
099  @Nonnull
100  FetchGroupBuilder<T> fetchLazy(String path, String properties);
101
102  /**
103   * Build and return the FetchGroup.
104   */
105  @Nonnull
106  FetchGroup<T> build();
107}