anchor.diff:  
   == Usage
   
  -This section briefly discusses how application code can use these APIs.
  -
  -
  -=== "persistAndFlush(..)", "removeAndFlush(...)"
  -
  -In some cases, such as when using Managed Properties and Collections for implementing 1-1, 1-n, or m-n relationships, the user needs to invoke "flush()" to send the changes to the persistence mechanism (such as JDO/DataNucleus).
  -Then is when the persistence mechanism updates the managed properties and collections.
  - 
  -
  -[source,java]
  -----
  -public abstract class Warehouse extends SalesVIPEntity<Marketplace> {
  -
  -    // {{ ExcludedProducts (Collection)
  -    @Persistent(mappedBy = "marketplace", dependentElement = "true")
  -    private SortedSet<MarketplaceExcludedProduct> excludedProducts = new TreeSet<MarketplaceExcludedProduct>();
  -
  -    @MemberOrder(sequence = "1")
  -    public SortedSet<MarketplaceExcludedProduct> getExcludedProducts() {
  -	return this.excludedProducts;
  -    }
  -
  -    public void setExcludedProducts(
  -	    final SortedSet<MarketplaceExcludedProduct> excludedProducts) {
  -	this.excludedProducts = excludedProducts;
  -    }
  -
  -    // }}
  -
  -    // {{ addExcludedProduct (action)
  -    @Action(semantics = SemanticsOf.IDEMPOTENT)
  -    @MemberOrder(sequence = "1")
  -    public MarketplaceExcludedProduct addExcludedProduct(final Product product) {
  -	MarketplaceExcludedProduct marketplaceExcludedProduct = this
  -		.findExcludedProduct(product);
  -	if (marketplaceExcludedProduct == null) {
  -	    marketplaceExcludedProduct = this.factoryService
  -		    .instantiate(MarketplaceExcludedProduct.class);
  -	}
  -
  -	this.wrap(marketplaceExcludedProduct).setMarketplace(this);
  -	this.wrap(marketplaceExcludedProduct).setProduct(product);
  -
  -	this.repositoryService.persistAndFlush(marketplaceExcludedProduct);  // <— Needed for updating the managed properties and collections.
  -
  -	return marketplaceExcludedProduct;
  -    }
  -
  -    // }}
  -
  -    // {{ deleteFromExcludedProducts (action)
  -    @Action(semantics = SemanticsOf.IDEMPOTENT)
  -    @MemberOrder(sequence = "1")
  -    public void deleteFromExcludedProducts(final Product product) {
  -	final MarketplaceExcludedProduct marketplaceExcludedProduct = this
  -		.findExcludedProduct(product);
  -	if (marketplaceExcludedProduct != null) {
  -	    this.repositoryService.remove(marketplaceExcludedProduct);
  -	    this.flushTransaction();
  -	}
  -    }
  -
  -    // }}
  -----
  -
  -On the “addExcludedProduct()” action, if the user don’t flush, this test would fail, as the managed collection would not containing the given product:
  -
  -[source,java]
  -----
  -    @Test
  -  	public void addExcludedProduct() {
  -
  -  	    // given
  -  	    final AmazonMarketplace amazonMarketplace = this.wrapSkipRules(
  -  		    this.marketplaceRepository).findOrCreateAmazonMarketplace(
  -  			    AmazonMarketplaceLocation.FRANCE);
  -  	    
  -	    final Product product = this.wrap(this.productRepository)
  -		    .createProduct(UUID.randomUUID().toString(),
  -			    UUID.randomUUID().toString());
  -  	    
  -  	    // when
  -  	    this.wrap(amazonMarketplace).addExcludedProduct(product);
  -
  -  	    // then
  -  	    Assertions.assertThat(this.wrapSkipRules(amazonMarketplace).findAllProductsExcluded()).contains(product); // <-- this would fail.
  -
  -  	}
  -  	
  -----
  -
  -=== Query
  +This section briefly discusses how application code can use (some of) these APIs.
  +
  +
  +=== Persist
   
   [source,java]
   ----
  
positive.code: By default the framework itself will cause `#flush()` to be called whenever a query is executed by way of `#allMatches(Query)`, as documented xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[above].  However, this behaviour can be disabled using the  xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
  
  
  === Query
  
  There are various implementations of the `Query` API, but these either duplicate functionality of the other overloads of `allMatches(...)` or they are not supported by the JDO/DataNucleus object store.   The only significant implementation of `Query` to be aware of is `QueryDefault`, which identifies a named query and a set of parameter/argument tuples.
  
  
negative.code: [source,java]
  ----
  public interface RepositoryService {
      <T> T instantiate(final Class<T> ofType);                                               // <1>
  
      boolean isPersistent(Object domainObject);                                              // <2>
      void persist(Object domainObject);                                                      // <3>
      void persistAndFlush(Object domainObject);                                              // <4>
  
      void remove(Object persistentDomainObject);                                             // <5>
      void removeAndFlush(Object persistentDomainObject);                                     // <6>
  
  