anchor.diff:  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
  +
  +=== `persistAndFlush(...)`, `removeAndFlush(...)`
  +
  +In some cases, such as when using managed properties and collections for implementing 1-1, 1-n, or m-n relationships,
  +the developer needs to invoke `flush()` to send the changes to the DataNucleus persistence mechanism.  These
  +managed properties and collections and then updated.
  +
  +The `persistAndFlush(...)` and `removeAndFlush(...)` methods (introduced in `1.13.0-SNAPSHOT`) save the developer from
  +having to call the `flush(...)` method.
  +
  +For example, the following code requires a flush to occur, so uses these methods:
  +
  +[source,java]
  +----
  +public abstract class Warehouse extends SalesVIPEntity<Marketplace> {
  +
  +    @Persistent(mappedBy = "marketplace", dependentElement = "true")
  +    @Getter @Setter                                                             // <1>
  +    private SortedSet<MarketplaceExcludedProduct> excludedProducts =
  +                            new TreeSet<MarketplaceExcludedProduct>();
  +
  +    @Action(semantics = SemanticsOf.IDEMPOTENT)
  +    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);     // <2>
  +        return marketplaceExcludedProduct;
  +    }
  +
  +    @Action(semantics = SemanticsOf.IDEMPOTENT)
  +    public void deleteFromExcludedProducts(final Product product) {
  +        final MarketplaceExcludedProduct marketplaceExcludedProduct = findExcludedProduct(product);
  +        if (marketplaceExcludedProduct != null) {
  +            this.repositoryService.removeAndFlush(marketplaceExcludedProduct);
  +        }
  +    }
  +    ...                                                                         // <3>
  +}
  +----
  +<1> using lombok for brevity
  +<2> Needed for updating the managed properties and collections.
  +<3> injected services and other methods ommited
  +
  +On the “addExcludedProduct()” action, if the user didn’t flush, the following test would fail because 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);                                                    // <1>
  +}
  +----
  +<1> this would fail.
  +
  +
  +
  +=== Query and `xxxMatches(...)`
   
   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.
   
  
positive.code: 
      <T> T firstMatch(Query<T> query);                                                       // <12>
      <T> T firstMatch(final Class<T> ofType, final Predicate<T> predicate);                  // <13>
  
  }
  ----
  <1> create a new non-persisted domain entity.  This is identical to
  
negative.code: ``RepositoryService``'s API too because instantiating and persisting objects are often done together.
  <2> test whether a particular domain object is persistent or not
  <3> persist (ie save) an object to the persistent object store (or do nothing if it is already persistent).
  <4> (`1.13.0-SNAPSHOT`) persist (ie save) and flush; same as `persist()`, but also flushes changes to database and updates managed properties and collections (i.e., 1-1, 1-n, m-n relationships automatically maintained by the DataNucleus persistence mechanism).
  <5> remove (ie delete) an object from the persistent object store (or do nothing if it has already been deleted).
  <6> (`1.13.0-SNAPSHOT`) remove (delete) and flush;  same as `remove()`, but also flushes changes to database and updates managed properties and collections (i.e., 1-1, 1-n, m-n relationships automatically maintained by the DataNucleus persistence mechanism).
  <7> return all persisted instances of specified type.  Mostly for prototyping, though can be useful to obtain all instances of domain entities if the number is known to be small.  The optional varargs parameters are for paging control; more on this below.
  <8> all persistence instances matching the specified `Query`.  Query itself is an Isis abstraction on top of JDO/DataNucleus' Query API.  *This is the primary API used for querying*
  <9> As the previous, but with client-side filtering using a `Predicate`.  Only really intended for prototyping.
  