blob: b5fddd122e68f1ad7d486a7ff27bde574caf507e [file] [log] [blame]
---
title: Delta Propagation Properties
---
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
This topic describes the properties that can be used to configure delta propagation.
Delta propagation properties can be configured through the API and through the `gemfire.properties` and `cache.xml` files.
## <a id="delta_propagation_properties__section_561D6DA876E24469B7536E98AB12F676" class="no-quick-link"></a>delta-propagation
A `gemfire.properties` boolean that enables or disables delta propagation. When false, full entry values are sent for every update. The default setting is true, which enables delta propagation.
Disable delta propagation as follows:
- `gemfire.properties`:
``` pre
delta-propagation=false
```
- API:
``` pre
Properties props = new Properties();
props.setProperty("delta-propagation", false);
this.cache = new ClientCacheFactory(props).create();
```
## <a id="delta_propagation_properties__section_7D4590512D1548FD94F81C8726A2CA44" class="no-quick-link"></a>cloning-enabled
A region attributes boolean that affects how `fromDelta` applies deltas to the local cache. When true, the updates are applied to a clone of the value and then the clone is saved to the cache. When false, the value is modified in place in the cache. The default value is false.
Exceptions to this behavior:
- If the `Cache` attribute `copy-on-read` is true, cloning is enabled, regardless of what this attribute is set to.
- If the `Region` attribute `off-heap` is true, cloning is enabled, regardless of what this attribute is set to.
Cloning can be expensive, but it ensures that the new object is fully initialized with the delta before any application code sees it.
When cloning is enabled, by default <%=vars.product_name%> does a deep copy of the object, using serialization. You may be able to improve performance by implementing `java.lang.Cloneable` and then implementing the `clone` method, making a deep copy of anything to which a delta may be applied. The goal is to reduce significantly the overhead of copying the object while still retaining the isolation needed for your deltas.
Without cloning:
- It is possible for application code to read the entry value as it is being modified, possibly seeing the value in an intermediate, inconsistent state, with just part of the delta applied. You may choose to resolve this issue by having your application code synchronize on reads and writes.
- <%=vars.product_name%> loses any reference to the old value because the old value is transformed in place into the new value. Because of this, your `CacheListener` sees the same new value returned for `EntryEvent.getOldValue` and `EntryEvent.getNewValue` .
- Exceptions thrown from `fromDelta` may leave your cache in an inconsistent state. Without cloning, any interruption of the delta application could leave you with some of the fields in your cached object changed and others unchanged. If you do not use cloning, keep this in mind when you program your error handling in your `fromDelta` implementation.
With cloning:
- The `fromDelta` method generates more garbage in memory.
- Performance is reduced.
Enable cloning as follows:
- `cache.xml`:
``` pre
<region name="region_with_cloning">
<region-attributes refid="REPLICATE" cloning-enabled="true">
</region-attributes>
</region>
```
- API:
``` pre
RegionFactory rf = cache.createRegionFactory(REPLICATE);
rf.setCloningEnabled(true);
custRegion = rf.create("customer");
```
- gfsh:
``` pre
gfsh>create region --name="region_with_cloning" --type=REPLICATE
--enable-cloning=true
```