EntityPersister.java

interface EntityPersister ... {
  
	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Design a "Queryable"-like contract for asking the persister to augment
	// a org.hibernate.sql.exec.spi.JdbcOperation.
	//
	// One caveat to this is that currently JdbcOperation exposes the SQL String
	// whereas it would be more effective to have this contract have access to the
	// SQL AST for augmentation.  Either have JdbcOperation expose SQL AST, or
	// have this contract take an "in-flight" view of the JdbcOperation.
	//
	// Another consideration is that in the PoC, these methods simply accepted the
	// SQM node types.  That's awkward if we want this to operate at the level
	// of SQL-AST/JdbcOperation as produced by persisters because we'd have to
	// create and pass "intermediary objects" - or build SQM objects anyway, which
  	// kind of defeats the purpose (perf) of persisters operating on 
  	// SQL-AST/JdbcOperation level.  Another option that I shudder to mention would
  	// be to have overloaded forms - but that is fugly, and again/ defeats another 
  	// purpose of this design (centralization)
	//
	// todo (6.0) - (CRITICAL) determine the best approach for this ^^

	// todo  (6.0) - need to apply "load query influencers"?  Or is that handled by callers?
	//		if we want that handled here, probably better pass in "in flight" access
	//		to the SQL AST here to allow augmentation to other parts of the query - e.g.
	//		applying join restrictions to the WHERE clause in cases where the Dialect
	//		does not support "ANSI joins".


	/**
	 * Build the EntityTableGroup for this entity.  This method is called
	 * when the entity is the root.
	 *
	 * @param fromElementSourceInfo Information about the TableGroup to be built
	 * @param tableSpace The SQL-AST TableSpace that is to be the container for the TableGroup we build
	 * @param sqlAliasBaseManager Access to the SQL alias manager
	 *
	 * @return The generated EntityTableGroup
	 */
	EntityTableGroup applyTableGroup(
			TableGroupSourceInfo fromElementSourceInfo,
			TableSpace tableSpace,
			SqlAliasBaseManager sqlAliasBaseManager);

	interface TableGroupSourceInfo {
		String getUniqueIdentifier();
		String getIdentificationVariable();
		EntityPersister getIntrinsicSubclassEntityPersister();
	}

	/**
	 * Build the EntityTableGroup for this entity.  This method is called
	 * when the entity is the root.
	 *
	 * @param navigableBindingInfo Information about the TableGroupJoin to be built, including infor about its LHS
	 * @param tableSpace The SQL-AST TableSpace that is to be the container for the TableGroupJoin we build
	 * @param sqlAliasBaseManager Access to the SQL alias manager
	 *
	 * @return The generated TableGroupJoin
	 */
	TableGroupJoin applyTableGroupJoin(
			NavigableBindingInfo navigableBindingInfo,
			SqmJoinType joinType,
			TableSpace tableSpace,
			TableGroupResolutionContext tableGroupResolutionContext,
			SqlAliasBaseManager sqlAliasBaseManager);

	interface NavigableBindingInfo extends TableGroupSourceInfo {
		NavigableSourceBindingInfo getSourceBindingInfo();
		Navigable getBoundNavigable();
	}

	interface NavigableSourceBindingInfo extends NavigableBindingInfo {
		@Override
		NavigableSource getBoundNavigable();
	}

	interface TableGroupResolutionContext {
		// todo : args... "unique identifier"?
		TableGroup resolveTableGroup();
	}
}