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 specified properties using a query join.
072   */
073  @Nonnull
074  FetchGroupBuilder<T> fetchQuery(String path, String properties);
075
076  /**
077   * Fetch the path including all its properties lazily.
078   */
079  @Nonnull
080  FetchGroupBuilder<T> fetchLazy(String path);
081
082  /**
083   * Fetch the path including specified properties lazily.
084   */
085  @Nonnull
086  FetchGroupBuilder<T> fetchLazy(String path, String properties);
087
088  /**
089   * Build and return the FetchGroup.
090   */
091  @Nonnull
092  FetchGroup<T> build();
093}