It will ease life for newcomers, as the “flush()” invokation is needed for DataNucleus to update “mappedBy” collections, for example, when a new element has been added.

For Queries, we’re currently invoking always flush(…) before executing it on the persistence layer, but that’s not the default behavior when setting a property, for example.

So when DN reloads entities collections would not be updated.

Let's see an example (notice the "this.persistAndFlush(...)" helper method invocation):

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.persistAndFlush(marketplaceExcludedProduct); <—————————————

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(); }

}

// }}

// {{ findExcludedProduct (action)
@Action(semantics = SemanticsOf.SAFE)
@MemberOrder(sequence = "1")
public MarketplaceExcludedProduct findExcludedProduct(final Product product)

{ return this.repositoryService.firstMatch(QueryDefault.create( MarketplaceExcludedProduct.class, "findByMarketplaceAndProduct", "marketplace", this, "product", product)); }

// }}

// {{ findAllProductsExcluded (action)
@Action(semantics = SemanticsOf.SAFE, hidden = Where.EVERYWHERE)
public Set<Product> findAllProductsExcluded()

{ return this.getExcludedProducts().stream().map(mep -> mep.getProduct()) .collect(Collectors.toSet()); }

// }}

}

On the “addExcludedProduct()” action, if the user don’t flush(), in addition to persist(), this test would fail, not containing the given product:

@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); }