Google Git
Sign in
apache / geode-site / c1e1f5ba34f0a4e0af949688890f67e7e7b3f8f7 / . / docs / geode-native / cpp / 113 / regions / regions.html
blob: 67432d681d414ce84a706f39a526ef641fded6e3 [file] [log] [blame]
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<!-- Always force latest IE rendering engine or request Chrome Frame -->
<meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible">
<link href='https://fonts.googleapis.com/css?family=Source+Sans+Pro:300,300italic,400italic,400,600' rel='stylesheet' type='text/css'>
<!-- Use title if it's in the page YAML frontmatter -->
<title>
Configuring Regions |
Geode Native C++ Docs
</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link href="/stylesheets/all.css" rel="stylesheet" media="screen, print" />
<link href="/stylesheets/print.css" rel="stylesheet" media="print" />
<link href='/images/favicon.ico' rel='shortcut icon'>
<script src="/javascripts/all.js"></script>
</head>
<body class="docs docs_geode-native docs_geode-native_cpp docs_geode-native_cpp_113 docs_geode-native_cpp_113_regions docs_geode-native_cpp_113_regions_regions has-subnav">
<div class="viewport">
<div class='wrap'>
<script type="text/javascript">
document.domain = "apache.org";
</script>
<!--
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.
-->
<header class="header header-layout">
<h1 class="logo">
<a href="/">
<img src="/images/Apache_Geode_logo_symbol_white.png" style="width:30px;">
Apache Geode Native C++ Documentation
</a>
</h1>
<div class="header-links js-bar-links">
<div class="btn-menu" data-behavior="MenuMobile"></div>
<div class="header-item"><a href="http://geode.apache.org">Back to Product Page</a></div>
<div class="header-item">
<a href="http://geode.apache.org/community" target="_blank">Community</a>
</div>
</div>
</header>
<div class="container">
<!--googleoff: index-->
<!--
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.
-->
<div id="sub-nav" class="js-sidenav nav-container" role="navigation">
<a class="sidenav-title" data-behavior="SubMenuMobile">Doc Index</a>
<div class="nav-content">
<ul>
<li>
<a href="/docs/geode-native/cpp/113/about-client-users-guide.html">Apache Geode Native Documentation</a>
</li>
<li class="has_submenu">
<a href="/docs/geode-native/cpp/113/getting-started/getting-started-nc-client.html">Getting Started with the Native Library</a>
<ul>
<li>
<a href="/docs/geode-native/cpp/113/getting-started/getting-started-nc-client.html#set_up_dev_environment">Set Up Your Development Environment</a>
</li>
<li>
<a href="/docs/geode-native/cpp/113/getting-started/getting-started-nc-client.html#establish_cluster_access">Establish Access to a Geode Cluster</a>
</li>
<li>
<a href="/docs/geode-native/cpp/113/getting-started/getting-started-nc-client.html#app_dev_walkthroughs">Application Development Walkthroughs</a>
</li>
<li>
<a href="/docs/geode-native/cpp/113/getting-started/getting-started-nc-client.html#programming_examples">Programming Examples</a>
</li>
<li>
<a href="/docs/geode-native/cpp/113/getting-started/put-get-example.html">Put/Get/Remove Examples</a>
</li>
</ul>
</li>
<li class="has_submenu">
<a href="/docs/geode-native/cpp/113/configuring/configuration.html">Configuring a Client Application</a>
<ul>
<li>
<a href="/docs/geode-native/cpp/113/configuring/system-level-configuration.html">System Level Configuration</a>
</li>
</ul>
</li>
<li>
<a href="/docs/geode-native/cpp/113/configuring/config-client-cache.html">Configuring the Client Cache</a>
</li>
<li class="has_submenu">
<a href="/docs/geode-native/cpp/113/regions/regions.html">Configuring Regions</a>
<ul>
<li>
<a href="/docs/geode-native/cpp/113/regions/registering-interest-for-entries.html">Registering Interest for Entries</a>
</li>
<li>
<a href="/docs/geode-native/cpp/113/regions/region-attributes.html">Region Attributes</a>
</li>
</ul>
</li>
<li class="has_submenu">
<a href="/docs/geode-native/cpp/113/connection-pools/configuring-pools.html">Configuring Pools</a>
<ul>
<li>
<a href="/docs/geode-native/cpp/113/connection-pools/client-pool-api.html">Native Client Pool API</a>
</li>
<li>
<a href="/docs/geode-native/cpp/113/connection-pools/configuring-pools-attributes-example.html">Pool Configuration Example and Settings</a>
</li>
<li>
<a href="/docs/geode-native/cpp/113/connection-pools/subscription-properties.html">Subscription Properties</a>
</li>
</ul>
</li>
<li>
<a href="/docs/geode-native/cpp/113/serialization/data-serialization.html">Serializing Data</a>
</li>
<li>
<a href="/docs/geode-native/cpp/113/remote-queries.html">Remote Queries</a>
</li>
<li>
<a href="/docs/geode-native/cpp/113/continuous-queries.html">Continuous Queries</a>
</li>
<li class="has_submenu">
<a href="/docs/geode-native/cpp/113/security/security.html">Security: Authentication and Encryption</a>
<ul>
<li>
<a href="/docs/geode-native/cpp/113/security/authentication.html">Authentication</a>
</li>
<li>
<a href="/docs/geode-native/cpp/113/security/sslclientserver.html">TLS/SSL Client-Server Communication Encryption</a>
</li>
</ul>
</li>
<li>
<a href="/docs/geode-native/cpp/113/function-execution.html">Function Execution</a>
</li>
<li>
<a href="/docs/geode-native/cpp/113/transactions.html">Transactions</a>
</li>
<li>
<a href="/docs/geode-native/cpp/113/configuring/sysprops.html">System Properties</a>
</li>
<li>
<a href="/docs/geode-native/cpp/113/client-cache-ref.html">Client Cache XML Reference</a>
</li>
</ul>
</div>
</div>
<!--googleon: index-->
<main class="content content-layout" id="js-content" role="main">
<a id="top"></a>
<!--
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.
-->
<span style="font-weight:200;font-size:31px;" style="float:left;">
<img src="/images/Apache_Geode_logo_symbol.png" style="height:26px;">
Apache Geode Native C++
</span>
<span class="local-header version-info" style="float:right;">
<a href="https://cwiki.apache.org/confluence/display/GEODE/Release+Notes">CHANGELOG</a>
</span>
<!--
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.
-->
<h1 class="title-container" >
Configuring Regions
</h1>
<div id="js-quick-links" >
<div class="quick-links"><ul>
<li><a href="#programmatic-region-creation">Programmatic Region Creation</a></li>
<li><a href="#declarative-region-creation">Declarative Region Creation</a></li>
<li><a href="#invalidating-regions">Invalidating and Destroying Regions</a></li>
<li><a href="#region-access">Region Access</a></li>
<li><a href="#getting-region-size">Getting the Region Size</a></li>
</ul></div>
</div>
<div class="to-top" id="js-to-top">
<a href="#top" title="back to top"></a>
</div>
<!--
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.
-->
<p>The region is the core building block of the Geode distributed system. All cached
data is organized into data regions and you do all of your data puts, gets, and querying activities
against them.</p>
<p>In order to connect to a Geode server, a client application must define a region that corresponds to
a region on the server, at least in name.
See <a href="geodeman/basic_config/data_regions/chapter_overview.html">Data Regions</a> in the <em>Geode User Guide</em>
for details regarding server regions, and <a href="/docs/geode-native/cpp/113/regions/region-attributes.html">Region Attributes</a> in this guide for
client region configuration parameters.</p>
<p>You can create regions either programmatically or through declarative statements in a <code>cache.xml</code> file.
Programmatic configuration is recommended, as it keeps the configuration close at hand and eliminates an external dependency.
Region creation is subject to attribute consistency checks.</p>
<h2 id="programmatic-region-creation"><a id="programmatic-region-creation"></a>Programmatic Region Creation</h2>
<p>To create a region:</p>
<ol>
<li>Create a cache using <code>CacheFactory</code> to set its characteristics.</li>
<li>The cache includes an instance of <code>PoolManager</code>&mdash;use it to create a connection pool.</li>
<li>Use the cache to instantiate a <code>RegionFactory</code> and use it to create a region, specifying any desired attributes
and an association with the connection pool.</li>
</ol>
<h3 id="c++-region-creation-example">C++ Region Creation Example</h3>
<p>The following example illustrates how to create two regions with different characteristics using C++.</p>
<pre class="highlight cpp"><code><span class="k">auto</span> <span class="n">cache</span> <span class="o">=</span> <span class="n">CacheFactory</span><span class="p">()</span>
<span class="p">.</span><span class="n">set</span><span class="p">(</span><span class="s">"log-level"</span><span class="p">,</span> <span class="s">"none"</span><span class="p">)</span>
<span class="p">.</span><span class="n">create</span><span class="p">();</span>
<span class="n">cache</span><span class="p">.</span><span class="n">getPoolManager</span><span class="p">()</span>
<span class="p">.</span><span class="n">createFactory</span><span class="p">()</span>
<span class="p">.</span><span class="n">addLocator</span><span class="p">(</span><span class="s">"localhost"</span><span class="p">,</span> <span class="mi">10334</span><span class="p">)</span>
<span class="p">.</span><span class="n">create</span><span class="p">(</span><span class="s">"pool"</span><span class="p">);</span>
<span class="k">auto</span> <span class="n">regionFactory</span> <span class="o">=</span> <span class="n">cache</span><span class="p">.</span><span class="n">createRegionFactory</span><span class="p">(</span><span class="n">RegionShortcut</span><span class="o">::</span><span class="n">PROXY</span><span class="p">);</span>
<span class="k">auto</span> <span class="n">regionFactory2</span> <span class="o">=</span> <span class="n">cache</span><span class="p">.</span><span class="n">createRegionFactory</span><span class="p">(</span><span class="n">RegionShortcut</span><span class="o">::</span><span class="n">CACHING_PROXY</span><span class="p">);</span>
<span class="k">auto</span> <span class="n">region</span> <span class="o">=</span> <span class="n">regionFactory</span>
<span class="p">.</span><span class="n">setPoolName</span><span class="p">(</span><span class="s">"pool"</span><span class="p">)</span>
<span class="p">.</span><span class="n">create</span><span class="p">(</span><span class="s">"example_userinfo"</span><span class="p">);</span>
<span class="k">auto</span> <span class="n">region2</span> <span class="o">=</span> <span class="n">regionFactory2</span>
<span class="p">.</span><span class="n">setPoolName</span><span class="p">(</span><span class="s">"pool"</span><span class="p">)</span>
<span class="p">.</span><span class="n">setEntryTimeToLive</span><span class="p">(</span><span class="n">ExpirationAction</span><span class="o">::</span><span class="n">INVALIDATE</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">chrono</span><span class="o">::</span><span class="n">seconds</span><span class="p">(</span><span class="mi">120</span><span class="p">))</span>
<span class="p">.</span><span class="n">create</span><span class="p">(</span><span class="s">"example_userinfo2"</span><span class="p">);</span>
</code></pre>
<h2 id="declarative-region-creation"><a id="declarative-region-creation"></a>Declarative Region Creation</h2>
<p>Declarative region creation involves placing the region&rsquo;s XML declaration, with the appropriate
attribute settings, in a <code>cache.xml</code> file that is loaded at cache creation.</p>
<p>Like the programmatic examples above, the following example creates two regions with attributes and a connection pool:</p>
<pre class="highlight xml"><code><span class="cp">&lt;?xml version="1.0" encoding="UTF-8"?&gt;</span>
<span class="nt">&lt;client-cache</span>
<span class="na">xmlns=</span><span class="s">"http://geode.apache.org/schema/cpp-cache"</span>
<span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span>
<span class="na">xsi:schemaLocation=</span><span class="s">"http://geode.apache.org/schema/cpp-cache</span>
<span class="err">http://geode.apache.org/schema/cpp-cache/cpp-cache-1.0.xsd"</span>
<span class="na">version=</span><span class="s">"1.0"</span><span class="nt">&gt;</span>
<span class="nt">&lt;pool</span> <span class="na">name=</span><span class="s">"examplePool"</span> <span class="na">subscription-enabled=</span><span class="s">"true"</span><span class="nt">&gt;</span>
<span class="nt">&lt;server</span> <span class="na">host=</span><span class="s">"localhost"</span> <span class="na">port=</span><span class="s">"40404"</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/pool&gt;</span>
<span class="nt">&lt;region</span> <span class="na">name=</span><span class="s">"clientRegion1"</span> <span class="na">refid=</span><span class="s">"PROXY"</span><span class="nt">&gt;</span>
<span class="nt">&lt;region-attributes</span> <span class="na">pool-name=</span><span class="s">"examplePool"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;/region&gt;</span>
<span class="nt">&lt;region</span> <span class="na">name=</span><span class="s">"clientRegion2"</span> <span class="na">refid=</span><span class="s">"CACHING_PROXY"</span><span class="nt">&gt;</span>
<span class="nt">&lt;region-attributes</span> <span class="na">pool-name=</span><span class="s">"examplePool"</span><span class="nt">&gt;</span>
<span class="nt">&lt;region-time-to-live&gt;</span>
<span class="nt">&lt;expiration-attributes</span> <span class="na">timeout=</span><span class="s">"120s"</span> <span class="na">action=</span><span class="s">"invalidate"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;/region-time-to-live&gt;</span>
<span class="nt">&lt;/region-attributes&gt;</span>
<span class="nt">&lt;/region&gt;</span>
<span class="nt">&lt;/client-cache&gt;</span>
</code></pre>
<p>The <code>cache.xml</code> file contents must conform to the XML described in the <code>cpp-cache-1.0.xsd</code> file provided in your distribution&rsquo;s <code>xsds</code> subdirectory
and available online at <a href="https://geode.apache.org/schema/cpp-cache/cpp-cache-1.0.xsd">https://geode.apache.org/schema/cpp-cache/cpp-cache-1.0.xsd</a>.</p>
<h2 id="invalidating-and-destroying-regions"><a id="invalidating-regions"></a>Invalidating and Destroying Regions</h2>
<p>Invalidation marks all entries contained in the region as invalid (with null values). Destruction
removes the region and all of its contents from the cache.</p>
<p><a id="invalidating-region__section_6F7E304D1D5743F1B53FCBD4F82651D0"></a>
You can execute these operations explicitly in the local cache in the following ways:</p>
<ul>
<li> Through direct API calls from the client using <code>apache::geode::client::Region:invalidateRegion()</code></li>
<li> Through expiration activities based on the region&rsquo;s statistics and attribute settings.</li>
</ul>
<p>In either case, you can perform invalidation and destruction as a local or a distributed operation.</p>
<ul>
<li> A local operation affects the region only in the local cache.</li>
<li> A distributed operation works first on the region in the local cache and then distributes the operation to all other caches where the region is defined. This is the proper choice when the region is no longer needed, or valid, for any application in the distributed system.</li>
<li> If the region on the server is configured as a partitioned region, it cannot be cleared using API calls from the client.</li>
</ul>
<p>A user-defined cache writer can abort a region destroy operation. Cache writers are synchronous
listeners with the ability to abort operations. If a cache writer is defined for the region anywhere
in the distributed system, it is invoked before the region is explicitly destroyed.</p>
<p>Whether carried out explicitly or through expiration activities, invalidation and destruction cause event notification.</p>
<h2 id="region-access"><a id="region-access"></a>Region Access</h2>
<p>You can use <code>Cache::getRegion</code> to retrieve a reference to a specified region.</p>
<p><code>Cache::getRegion</code> returns <code>nullptr</code> if the region is not already present in the application&rsquo;s cache. A server region must already exist.</p>
<p>A region name <em>cannot</em> contain these characters:</p>
<table><thead>
<tr>
<th>Ineligible Character description</th>
<th>Ineligible Character</th>
</tr>
</thead><tbody>
<tr>
<td>whitespace</td>
<td><em>space</em> or <em>tab</em></td>
</tr>
<tr>
<td>angle brackets</td>
<td>&lt; &nbsp; &gt;</td>
</tr>
<tr>
<td>colon</td>
<td>:</td>
</tr>
<tr>
<td>quote</td>
<td><code>&quot;</code></td>
</tr>
<tr>
<td>forward slash and back slash</td>
<td>/ &nbsp; \</td>
</tr>
<tr>
<td>pipe (vertical bar)</td>
<td>&#124;</td>
</tr>
<tr>
<td>question mark</td>
<td>?</td>
</tr>
<tr>
<td>asterisk</td>
<td>*</td>
</tr>
</tbody></table>
<h2 id="getting-the-region-size"><a id="getting-region-size"></a>Getting the Region Size</h2>
<p>The <code>Region</code> API provides a <code>size</code> method that gets the size of a region.
For client regions, this gives the number of entries in the local cache, not on the servers.
See the <code>Region</code> API documentation for details.</p>
</main>
</div>
</div>
</div>
<div id="scrim"></div>
<div class="container">
<footer class="site-footer-links">
<!--
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.
-->
<div class="copyright">
<a href='/'>Apache Geode Documentation</a>
&copy; 2020 <a href='http://www.apache.org/'>The Apache Software Foundation</a>.
</div>
<div class="support">
Need help? <a href="http://geode.apache.org/community" target="_blank">Visit the Community</a>
</div>
</footer>
</div><!--end of container-->
</body>
</html>