io.ebean.FetchGroup Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ebean-api Show documentation
ebean api
There is a newer version: 15.8.0
package io.ebean;

import org.jspecify.annotations.NullMarked;
import io.ebean.service.SpiFetchGroupQuery;

/**
 * Defines what part of the object graph to load (select and fetch clauses).
 * 
 * Using a FetchGroup effectively sets the select() and fetch() clauses for a query. It is alternative
 * to specifying the select() and fetch() clauses on the query allowing for more re-use of "what to load"
 * that can be defined separately from the query and combined with other FetchGroups.
 * 
 *
 * Select example
 * {@code
 *
 * FetchGroup fetchGroup = FetchGroup.of(Customer.class, "name, status");
 *
 * Customer.query()
 *   .select(fetchGroup)
 *   .findList();
 *
 * }
 *
 * Select and fetch example
 * {@code
 *
 * FetchGroup fetchGroup = FetchGroup.of(Customer.class)
 *   .select("name, status")
 *   .fetch("contacts", "firstName, lastName, email")
 *   .build();
 *
 * Customer.query()
 *   .select(fetchGroup)
 *   .findList();
 *
 * }
 *
 * Combining FetchGroups
 * 
 *   FetchGroups can be combined together to form another FetchGroup.
 * 
 * {@code
 *
 *  FetchGroup FG_ADDRESS = FetchGroup.of(Address.class)
 *    .select("line1, line2, city")
 *    .fetch("country", "name")
 *    .build();
 *
 *  FetchGroup FG_CUSTOMER = FetchGroup.of(Customer.class)
 *    .select("name, version")
 *    .fetch("billingAddress", FG_ADDRESS)
 *    .build();
 *
 *
 *  Customer.query()
 *    .select(FG_CUSTOMER)
 *    .findList();
 *
 * }
 *
 * @param  The bean type the Fetch group can be applied to
 */
@NullMarked
public interface FetchGroup {

  /**
   * Return the FetchGroup with the given select clause.
   * 
   *   We use this for simple FetchGroup that only select() properties and do not have additional fetch() clause.
   * 
   * {@code
   *
   * FetchGroup fetchGroup = FetchGroup.of(Customer.class, "name, status");
   *
   * Customer.query()
   *   .select(fetchGroup)
   *   .findList();
   *
   * }
   *
   * @param select The select clause of the FetchGroup
   *
   * @return The FetchGroup with the given select clause
   */
  static  FetchGroup of(Class cls, String select) {
    return XBootstrapService.fetchGroupOf(cls, select);
  }

  /**
   * Return the FetchGroupBuilder with the given select clause that we can add fetch clauses to.
   * 
   * We chain select() with one or more fetch() clauses to define the object graph to load.
   * 
   * {@code
   *
   * FetchGroup fetchGroup = FetchGroup.of(Customer.class)
   *   .select("name, status")
   *   .fetch("contacts", "firstName, lastName, email")
   *   .build();
   *
   * Customer.query()
   *   .select(fetchGroup)
   *   .findList();
   *
   * }
   *
   * @return The FetchGroupBuilder with the given select clause which we will add fetch clauses to
   */
  static  FetchGroupBuilder of(Class cls) {
    return XBootstrapService.fetchGroupOf(cls);
  }

  /**
   * Return a query to be used by query beans for constructing FetchGroup.
   */
  static  SpiFetchGroupQuery queryFor(Class beanType) {
    return XBootstrapService.fetchGroupQueryFor(beanType);
  }

}