http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/.gitignore ---------------------------------------------------------------------- diff --git a/.gitignore b/.gitignore deleted file mode 100644 index eaf0351..0000000 --- a/.gitignore +++ /dev/null @@ -1,6 +0,0 @@ -geode-book/Gemfile.lock -geode-book/final_app -geode-book/output -out -temp -*.bak
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/CONTRIBUTE.md ---------------------------------------------------------------------- diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md deleted file mode 100644 index dd97f47..0000000 --- a/CONTRIBUTE.md +++ /dev/null @@ -1,63 +0,0 @@ -# Contributing to the Project Geode Documentation - -Project Geode welcomes your contributions to the community's documentation efforts. You can participate by writing new content, reviewing and editing existing content, or fixing bugs. This document covers the following topics: - -- [How to Contribute](#contribute) -- [Document Source Files and Tools](#source_tools) -- [Writing Guidelines](#guidelines) - -[]() - -## How to Contribute - -We use the fork-and-pull collaboration method on GitHub: - -1. In your GitHub account, fork the gemfire/docs-geode-md repository. -2. Create a local clone of your fork. -3. Make changes and commit them in your fork. -4. In the gemfire/docs-geode-md repository, create a pull request. - -See [Using Pull Requests](https://help.github.com/articles/using-pull-requests/) on GitHub for more about the fork-and-pull collaboration method. - -[]() - -## Document Source Files and Tools - -Project Geode documentation source files are written in markdown. Image files include .gif and .png graphics and editable image files in the open source SVG format. - -- [Working with Markdown Files](#markdown) -- [Working with Images and Graphics](#images) - -[]() - -### Working with Markdown Files - -You can edit markdown files in any text editor. For more, read [Daring Fireball's Markdown Syntax page](https://daringfireball.net/projects/markdown/syntax). - -[]() - -### Working with Images and Graphics - -Image files in .gif or .png format are in the `images` directory in the Project Geode docs repo. Images in .svg format are in the `images_svg` directory. - -Most of the Project Geode image files have been converted to the open source SVG format. You can insert SVG images directly into an XML topic and modify images using a SVG editor. - -The Wikipedia page [Comparison of Vector Graphics Editors](http://en.wikipedia.org/wiki/Comparison_of_vector_graphics_editors) provides a list and comparison of commercial and free vector graphics editors. Note, however, that not all of these programs support the SVG format. - -[]() - -## Writing Guidelines - -The most important advice we can provide for working with the Project Geode docs is to spend some time becoming familiar with the existing source files and the structure of the project directory. In particular, note the following conventions and tips: - -- Top-level subdirectories organize topics into "books": basic_config, configuring, developing, etc. - -- Use lowercase characters for all file and directory names. Separate words in filenames with an underscore (`_`) character. - -- Use the `.md` file extension for topic files. - -- Add new topics to the existing directories by subject type. Only create a new directory if you are starting a new subject or a new book. - -- To start a new topic, you can make a copy of an existing file with similar content and edit it. - -- Use the appropriate document type for the content you are writing. Create multiple topics if you are writing overview, procedural, and reference content. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md deleted file mode 100644 index a018ca1..0000000 --- a/README.md +++ /dev/null @@ -1,93 +0,0 @@ -# Project Geode End-User Documentation - -The latest check-ins to `project-geode/docs` are automatically built and published to <http://geode-docs.cfapps.io>. - -Project Geode provides the full source for end-user documentation in markdown format. The markdown can be built into HTML using [Bookbinder](https://github.com/pivotal-cf/bookbinder). - -Bookbinder is a gem that binds together a unified documentation web application from markdown, html, and/or DITA source material. The source material for bookbinder must be stored either in local directories or in GitHub repositories. Bookbinder runs [middleman](http://middlemanapp.com/) to produce a Rackup app that can be deployed locally or as a Web application. - -This document contains instructions for building the local Geode documentation and publishing it to Cloud Foundry or Pivotal Web Services. It contains the sections: - -- [Bookbinder Usage](#usage) -- [Prerequisites](#prereq) -- [Building the Documentation](#building) -- [Publishing the Documentation](#publishing) -- [Getting More Information](#moreinfo) - -[]() - -## Bookbinder Usage - -Bookbinder is meant to be used from within a project called a **book**. The book includes a configuration file that describes which documentation repositories to use as source materials. Bookbinder provides a set of scripts to aggregate those repositories and publish them to various locations. - -For Geode, a preconfigured **book** is provided in the directory `/geode-book`. You can use this configuration to build HTML for project Geode on your local system. - -[]() - -## Prerequisites - -- Bookbinder requires Ruby version 2.0.0-p195 or higher. - -## Building the Documentation - -1. Begin by moving or copying the `/geode-book directory` to a directory that is parallel to `project-geode/docs`. For example: - - ``` - $ cd /repos/project-geode/docs - $ cp -r geode-book .. - $ cd ../geode-book - ``` - -2. The GemFile in the book directory already defines the `gem "bookbindery"` dependency. Make sure you are in the relocated book directory and enter: - - ``` - $ bundle install - ``` - -3. The installed `config.yml` file configures the Project Geode book for building locally. The installed file configures the local directory for the markdown source files. It uses the configuration: - - ``` - book_repo: project-geode/geode-book - public_host: localhost - - sections: - - repository: - name: gemfire/docs-geode-md - directory: docs-geode - subnav_template: geode-nav - - template_variables: - product_url: http://geode.incubator.apache.org - book_title: Project Geode Documentation - ``` - -4. Build the files locally using the installed `config.yml` file. Execute the command: - - ``` - $ bundle exec bookbinder bind local - ``` - - Bookbinder converts the markdown source into HTML, putting the final output in the `final_app` directory. - -5. To view the local documentation: - - ``` - $ cd final_app - $ rackup - ``` - - You can now view the local documentation at <http://localhost:9292> - -[]() - -## Publishing the Documentation - -Because the `final_app` directory contains the full output of the HTML conversion process, you can easily publish this directory as a hosted Web application. - -[]() - -## Getting More Information - -Bookbinder provides additional functionality to construct books from multiple Github repos, to perform variable substitution, and also to automatically build documentation in a continuous integration pipeline. For more information, see <https://github.com/pivotal-cf/bookbinder>. - -The latest check-ins to `gemfire/docs-geode-md` are automatically built and published to <http://geode-docs.cfapps.io>. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/about_geode.html.md.erb ---------------------------------------------------------------------- diff --git a/about_geode.html.md.erb b/about_geode.html.md.erb deleted file mode 100644 index 3117eb4..0000000 --- a/about_geode.html.md.erb +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Apache Geode 1.0.0-incubating Documentation ---- - -This documentation describes product concepts and provides complete setup instructions for Apache Geode 1.0.0-incubating. Source files and instructions on how to build this documentation are available at [https://github.com/project-geode/docs](https://github.com/project-geode/docs) and [https://github.com/project-geode/docs/blob/master/README.md](https://github.com/project-geode/docs/blob/master/README.md). - -You can also find additional documentation about Geode on the **Apache Geode Wiki**: [https://cwiki.apache.org/confluence/display/GEODE/Index](https://cwiki.apache.org/confluence/display/GEODE/Index). - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/book_intro.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/book_intro.html.md.erb b/basic_config/book_intro.html.md.erb deleted file mode 100644 index 1b6114e..0000000 --- a/basic_config/book_intro.html.md.erb +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Basic Configuration and Programming ---- - -*Basic Configuration and Programming* describes how to configure distributed system and cache properties for your Apache Geode installation. For your applications, it provides guidance for writing code to manage your cache and distributed system connection, data regions, and data entries, including custom classes. - -- **[Distributed System and Cache Configuration](../basic_config/config_concepts/chapter_overview.html)** - - To work with your Apache Geode applications, you use a combination of configuration files and application code. - -- **[Cache Management](../basic_config/the_cache/chapter_overview.html)** - - The Geode cache is the entry point to Geode caching management. Geode provides different APIs and XML configuration models to support the behaviors of different members. - -- **[Data Regions](../basic_config/data_regions/chapter_overview.html)** - - The region is the core building block of the Apache 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. - -- **[Data Entries](../basic_config/data_entries_custom_classes/chapter_overview.html)** - - The data entry is the key/value pair where you store your data. You can manage your entries individually and in batches. To use domain objects for your entry values and keys, you need to follow Apache Geode requirements for data storage and distribution. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/config_concepts/chapter_overview.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/config_concepts/chapter_overview.html.md.erb b/basic_config/config_concepts/chapter_overview.html.md.erb deleted file mode 100644 index 8f3fa6d..0000000 --- a/basic_config/config_concepts/chapter_overview.html.md.erb +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Distributed System and Cache Configuration ---- - -To work with your Apache Geode applications, you use a combination of configuration files and application code. - -- **[Distributed System Members](../../basic_config/config_concepts/distributed_system_member_configuration.html)** - - Distributed system members are programs that connect to a Geode distributed system. You configure members to belong to a single distributed system, and you can optionally configure them to be clients or servers to members in other distributed systems, and to communicate with other distributed systems. - -- **[Setting Properties](../../basic_config/gemfire_properties/setting_distributed_properties.html)** - - Geode provides a default distributed system configuration for out-of-the-box systems. To use non-default configurations and to fine-tune your member communication, you can use a mix of various options to customize your distributed system configuration. - -- **[Options for Configuring the Cache and Data Regions](../../basic_config/the_cache/setting_cache_properties.html)** - - To populate your Apache Geode cache and fine-tune its storage and distribution behavior, you need to define cached data regions and provide custom configuration for the cache and regions. - -- **[Local and Remote Membership and Caching](../../basic_config/config_concepts/local_vs_remote.html)** - - For many Apache Geode discussions, you need to understand the difference between local and remote membership and caching. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/config_concepts/distributed_system_member_configuration.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/config_concepts/distributed_system_member_configuration.html.md.erb b/basic_config/config_concepts/distributed_system_member_configuration.html.md.erb deleted file mode 100644 index 5da27bc..0000000 --- a/basic_config/config_concepts/distributed_system_member_configuration.html.md.erb +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Distributed System Members ---- - -Distributed system members are programs that connect to a Geode distributed system. You configure members to belong to a single distributed system, and you can optionally configure them to be clients or servers to members in other distributed systems, and to communicate with other distributed systems. - -## <a id="distributed_system_member_configuration__section_326B2609B67E4FBE9BF2074C3B211E50" class="no-quick-link"></a>Member Overview - -Distributed system members (or simply "members") connect to the Geode system when they create the Geode data cache. The members' distributed system is configured through Geode properties. See [gemfire.properties and gfsecurity.properties (Geode Properties)](../../reference/topics/gemfire_properties.html). Geode properties specify all necessary information for system member startup, initialization, and communication. - -**Note:** -You cannot change a member's properties while the member is connected to the distributed system. - -Use the properties to define: - -- How to find and communicate with other system members -- How to perform logging and statistics activities -- Which persistent configuration or `cache.xml` file to use for cache and data region initialization -- Other options, including event conflation, how to handle network loss, and security settings - -## <a id="distributed_system_member_configuration__section_E755E9E4A31149C980561D617A99A002" class="no-quick-link"></a>Distributed System Membership and System Topologies - -Every Geode process is a member of a distributed system, even if the distributed system is defined as standalone, with just one member. You can run an individual distributed system in isolation or you can combine systems for vertical and horizontal scaling. See [Topology and Communication General Concepts](../../topologies_and_comm/topology_concepts/chapter_overview.html). - -- **Peer-to-Peer Distributed Systems**. Members that define the same member discovery properties belong to the same distributed system and are peers to one another. -- **Client/Server Installations**. The client/server topology uses relationships that you configure between members of multiple distributed systems. You configure some or all of the peers in one distributed system to act as cache servers to clients connecting from outside the system. Each server can host many client processes, managing cache access for all in an efficient, vertically hierarchical cache configuration. You configure the client applications to connect to the servers, using a client cache configuration. Clients run as members of standalone Geode distributed systems, with no peers, so all data updates and requests go to the servers. - -## **Multi-site Installations** - -The multi-site topology uses relationships that you configure between members of multiple distributed systems. Through this configuration, you loosely couple two or more distributed systems for automated data distribution. This is usually done for sites at geographically separate locations. You configure a subset of peers in each distributed system site with gateway senders and/or gateway receivers to manage events that are distributed between the sites. - -In the context of a single distributed system, unless otherwise specified, remote members refers to other members of the same distributed system. In client/server and multi-site installations, remote generally refers to members in other distributed systems. For example, all servers are remote to the clients that connect to them. Each client runs standalone, with connections only to the server tier, so all servers and their other clients are remote to the individual client. All gateway receivers are remote to the gateway senders that connect to them from other distributed systems,and to those gateway sendersâ peers. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/config_concepts/local_vs_remote.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/config_concepts/local_vs_remote.html.md.erb b/basic_config/config_concepts/local_vs_remote.html.md.erb deleted file mode 100644 index f48b459..0000000 --- a/basic_config/config_concepts/local_vs_remote.html.md.erb +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Local and Remote Membership and Caching ---- - -For many Apache Geode discussions, you need to understand the difference between local and remote membership and caching. - -<a id="local_vs_remote_member_and_cache__section_5535DC4C94494B6A9B106DA39F63A439"></a> -Discussions of Geode membership and caching activities often differentiate between local and remote. Local caching always refers to the central member under discussion, if there is one such obvious member, and remote refers to other members. If there is no clear, single local member, the discussion assigns names to the members to differentiate. Operations, data, configuration, and so forth that are "local to member Q" are running or resident inside the member Q process. Operations, data, configuration, and so on, that are "remote to member Q" are running or resident inside some other member. - -The local cache is the cache belonging to the local member. All other caches are remote, whether in other members of the same distributed system or in different distributed systems. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/data_entries_custom_classes/chapter_overview.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/data_entries_custom_classes/chapter_overview.html.md.erb b/basic_config/data_entries_custom_classes/chapter_overview.html.md.erb deleted file mode 100644 index 565cd87..0000000 --- a/basic_config/data_entries_custom_classes/chapter_overview.html.md.erb +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Data Entries ---- - -The data entry is the key/value pair where you store your data. You can manage your entries individually and in batches. To use domain objects for your entry values and keys, you need to follow Apache Geode requirements for data storage and distribution. - -- **[Managing Data Entries](../../basic_config/data_entries_custom_classes/managing_data_entries.html)** - - Program your applications to create, modify, and manage your cached data entries. - -- **[Requirements for Using Custom Classes in Data Caching](../../basic_config/data_entries_custom_classes/using_custom_classes.html)** - - Follow these guidelines to use custom domain classes for your cached entry keys and values. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/data_entries_custom_classes/managing_data_entries.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/data_entries_custom_classes/managing_data_entries.html.md.erb b/basic_config/data_entries_custom_classes/managing_data_entries.html.md.erb deleted file mode 100644 index d809635..0000000 --- a/basic_config/data_entries_custom_classes/managing_data_entries.html.md.erb +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Managing Data Entries ---- - -Program your applications to create, modify, and manage your cached data entries. - -<a id="managing_data_entries__section_AACC36127F17411F86D1E409B86C6E5C"></a> -**Note:** -If you do not have the cache's `copy-on-read` attribute set to true, do not change the objects returned from the Java entry access methods. Instead, create a copy of the object, then modify the copy and pass it to the Java `put` method. Modifying a value in place bypasses the entire distribution framework provided by Geode, including cache listeners and expiration activities, and can produce undesired results. - -## <a id="managing_data_entries__section_B095A4073EFB4A3C91AF7C03632EEBFB" class="no-quick-link"></a>Basic Create and Update - -To create or update an entry in the cache, use `Region.put`. For example: - -``` pre -String name = ... -String value = ... -this.currRegion.put(name,value); -``` - -**Note:** -You can also use the `gfsh put` command to add entries to a region, and the `get` command to retrieve entries from a region. See [get](../../tools_modules/gfsh/command-pages/get.html) and [put](../../tools_modules/gfsh/command-pages/put.html) for more information. - -If you want only to create the entry (with a null value and with method failure if the entry already exists), use `Region.create` instead. - -## <a id="managing_data_entries__section_7578349EA26A4621B732FE851D71A84F" class="no-quick-link"></a>Batch Operations (getAll, putAll, removeAll) - -Geode provides three APIs to perform batch operations on multiple region entries: - -- `Region.getAll` -- `Region.putAll` -- `Region.removeAll` - -The `getAll` method takes a collection of keys and returns a `Map` of values for the provided keys. If a given key does not exist in the region, then that key's value in the returned map will be null. - -The `putAll` method takes a `Map` of key-value pairs and puts them into the cache and distributes them in a single operation. - -**Example:** - -``` pre -void putAll(String command) throws CacheException -{ -// Get Entry keys and values into Strings key1, ... keyN and value1, ... valueN - Map map = new LinkedHashMap(); - map.put(key1, value1)); - ... - map.put(keyN, valueN)); - this.currRegion.putAll(map); -} -``` - -The updates to the cache are done individually in the order in which they were placed in the `Map`. For partitioned regions, multiple events are sent as a single message to the primary buckets and then distributed to the secondary buckets. - -**Note:** -The processing of maps with very many entries and/or very large data may affect system performance and cause cache update timeouts, especially if the region uses overflow or persistence to disk. - -The `removeAll` method takes a collection of keys and removes all of the entries for the specified keys from this region. This call performs the equivalent of calling`destroy(Object)` on this region once for each key in the specified collection. If an entry does not exist, then that key is skipped. An `EntryNotFoundException` is not thrown. This operation will be distributed to other caches if the region's scope is not set to `Scope.LOCAL`. - -## <a id="managing_data_entries__section_A0E0F889AC344EFA8DF304FD64418809" class="no-quick-link"></a>Safe Entry Modification - -When you get an entry value from the cache, by default, the retrieval methods return a direct reference to the cached object. This provides the value as quickly as possible, but also opens the cache to direct, in-place changes. - -**Note:** -Do not directly modify cached values. Modifying a value in place bypasses the Geode distribution framework, including cache writers and listeners, expiration activities, and transaction management, and can produce undesired results. - -Always change your entries using copies of the retrieved objectsânever directly modify the returned objects. You can do this in one of two ways: - -1. Change the entry retrieval behavior for your cache by setting the cache attribute, `copy-on-read`, to true (the default is false). - - ``` pre - <cache copy-on-read="true"> - ... - </cache> - ``` - - When `copy-on-read` is true, the entry access methods return copies of the entries. This protects you from inadvertently modifying in-place, but negatively impacts performance and memory consumption when copying is not needed. - - These entry access methods return an entry reference if `copy-on-read` is false and a copy of the entry if `copy-on-read` is true: - - `Region.get` - result of `Region.put` - `EntryEvent.getNewValue` - `Region.values` - `Region.Entry.getValue` - `EntryEvent.getOldValue` - `Query.select` - -2. Create a copy of the returned object and work with that. For objects that are cloneable or serializable, you can copy the entry value to a new object using `org.apache.geode.CopyHelper.copy`. Example: - - ``` pre - Object o = (StringBuffer)region.get("stringBuf"); - StringBuffer s = (StringBuffer) CopyHelper.copy(o); - s.append("Changes to value, added using put."); - region.put("stringBuf", s); - ``` - -## <a id="managing_data_entries__section_78F6731642944DE594316B86ECB4E70F" class="no-quick-link"></a>Retrieving Region Entries from Proxy Members - -The `Region.values` method call applies to the local region instance only. If you call the `values` method from a client region using the PROXY shortcut, the method call will not be redirected to the server region. To obtain a collection of all values in the Region from a client, you should use interest registration on ALL\_KEYS, or use a query. - -If you use the `Region.get` method from a proxy member, the method call will redirect to the region on the server if it cannot find the key locally. - -## Using gfsh to get and put - -You can use the gfsh `get` and `put` commands to manage data. See [get](../../tools_modules/gfsh/command-pages/get.html) and [put](../../tools_modules/gfsh/command-pages/put.html). - -For example: - -``` pre -get --key=('id':'133abg124') --region=region1 - -// Retrieving when key type is a wrapper(primitive)/String -get --key=('133abg124') --region=/region1/region12 --value-class=data.ProfileDetails - -get --key=('100L') --region=/region1/region12 --value-class=data.ProfileDetails ---key-class=java.lang.Long -``` - -``` pre -put --key=('id':'133abg125') --value=('firstname':'James','lastname':'Gosling') ---region=/region1 --key-class=data.ProfileKey --value-class=data.ProfileDetails - -put --key=('133abg124') --value=('Hello World!!') --region=/region2 - -put --key=('100F') --value=('2146547689879658564') --region=/region1/region12 ---key-class=java.lang.Float --value-class=java.lang.Long -``` - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/data_entries_custom_classes/using_custom_classes.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/data_entries_custom_classes/using_custom_classes.html.md.erb b/basic_config/data_entries_custom_classes/using_custom_classes.html.md.erb deleted file mode 100644 index 0fe6171..0000000 --- a/basic_config/data_entries_custom_classes/using_custom_classes.html.md.erb +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Requirements for Using Custom Classes in Data Caching ---- - -Follow these guidelines to use custom domain classes for your cached entry keys and values. - -## <a id="using_custom_classes__section_F098CAC546164094BE6872BF0C443A71" class="no-quick-link"></a>CLASSPATH - -Each memberâs `CLASSPATH` must include classes for all objects the member accesses. - -- For Java applications, use the standard Java `CLASSPATH`. -- For the cache server process, use the `CLASSPATH` environment variable or the `gfsh start server`'s `--classpath` parameter. See [Running Geode Server Processes](../../configuring/running/running_the_cacheserver.html). - -Data is sent between clients and servers in serialized form and the server stores client data in serialized form. The server does not need to deserialize data to send it to another client or to access it through a `PDXInstance`, but it does need to deserialize it to access it in other ways. The server `CLASSPATH` must include the classes for: - -- All entry keys -- Entry values in regions that the server persists to disk -- Entry values the server accesses for any reason other than access using a `PdxInstance` or transfer of the full entry value to a client - -For information on `PdxInstance`s, see [Data Serialization](../../developing/data_serialization/chapter_overview.html#data_serialization). - -## <a id="using_custom_classes__section_57EB5D02C06947B4BDE75A49286D581D" class="no-quick-link"></a>Data Serialization - -Geode serializes data entry keys and values for distribution, so all data that Geode moves out of the local cache for any reason must be serializable. Additionally, partitioned regions store data in serialized form. Almost every configuration requires serialization. - -For information on the requirements and options for data serialization, see [Data Serialization](../../developing/data_serialization/chapter_overview.html#data_serialization). - -## <a id="using_custom_classes__section_CE776B94EDCB4D269A71C3C9CFEDD5FD" class="no-quick-link"></a>Classes Used as Keys - -The region uses hashing on keys. If you define a custom class to use as a key, for the class, override: - -- `equals` -- `hashCode`. The default `hashCode` inherited from `Object` uses identity, which is different in every system member. In partitioned regions, hashing based on identity puts data in the wrong place. For details, see the Java API documentation for `java.lang.Object`. - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/data_regions/chapter_overview.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/data_regions/chapter_overview.html.md.erb b/basic_config/data_regions/chapter_overview.html.md.erb deleted file mode 100644 index 3786906..0000000 --- a/basic_config/data_regions/chapter_overview.html.md.erb +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Data Regions ---- - -The region is the core building block of the Apache 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. - -- **[Data Region Management](../../basic_config/data_regions/managing_data_regions.html)** - - Apache Geode provides different APIs and XML configuration models to support configuration and management of your data regions. - -- **[Creating a Region with gfsh](../../basic_config/data_regions/create_a_region_with_gfsh.html)** - - A simple and fast way to create a data region in the Apache Geode cache is to use the `gfsh` command-line tool. - -- **[Creating a Region Through the cache.xml File](../../basic_config/data_regions/create_a_region_with_cacheXML.html)** - - A common way to create a data region in the Apache Geode cache is through `cache.xml` declarations. - -- **[Creating a Region Through the API](../../basic_config/data_regions/create_a_region_with_API.html)** - - You can use the Geode caching API to create regions in your cache after startup. For run-time region creation, you need to use the API. - -- **[Region Naming](../../basic_config/data_regions/region_naming.html)** - - To be able to perform all available operations on your data regions, -follow these region naming guidelines. - -- **[Region Shortcuts and Custom Named Region Attributes](../../basic_config/data_regions/region_shortcuts.html)** - - Geode provides region shortcut settings, with preset region configurations for the most common region types. For the easiest configuration, start with a shortcut setting and customize as needed. You can also store your own custom configurations in the cache for use by multiple regions. - -- **[Storing and Retrieving Region Shortcuts and Custom Named Region Attributes](../../basic_config/data_regions/store_retrieve_region_shortcuts.html)** - - Use these examples to get started with Geode region shortcuts. - -- **[Managing Region Attributes](../../basic_config/data_regions/managing_region_attributes.html)** - - Use region attributes to fine-tune the region configuration provided by the region shortcut settings. - -- **[Creating Custom Attributes for Regions and Entries](../../basic_config/data_regions/creating_custom_attributes.html)** - - Use custom attributes to store information related to your region or its entries in your cache. These attributes are only visible to the local application and are not distributed. - -- **[Building a New Region with Existing Content](../../basic_config/data_regions/new_region_existing_data.html)** - - A new region or distributed system may need to be loaded with the data of an existing system. There are two approaches to accomplish this task. The approach used depends upon the organization of both the new and the existing distributed system. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/data_regions/create_a_region_with_API.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/data_regions/create_a_region_with_API.html.md.erb b/basic_config/data_regions/create_a_region_with_API.html.md.erb deleted file mode 100644 index ba8e384..0000000 --- a/basic_config/data_regions/create_a_region_with_API.html.md.erb +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Creating a Region Through the API ---- - -You can use the Geode caching API to create regions in your cache after startup. For run-time region creation, you need to use the API. - -Before you start, configure your `Cache` or `ClientCache` and determine the region shortcut and other attributes settings your region needs. - -Region creation is subject to attribute consistency checks, both internal to the cache and, if the region is not local, between all caches where the region is defined. The requirements for consistency between region attributes are detailed in the online Java API documentation. - -1. - - Use a region shortcut to create your region factory. - - - - In peers and servers, use `org.apache.geode.cache.RegionFactory`. - - - - In clients, use `org.apache.geode.cache.client.ClientRegionFactory`. - -2. - - (Optional) Use the region factory to further configure your region. -3. - - Create your region from the configured region factory. - -When you run your member with the region creation code, the region will be created in the cache. - -## Examples - -Creating a partitioned region using RegionFactory: - -``` pre -RegionFactory rf = - cache.createRegionFactory(RegionShortcut.PARTITION); -rf.addCacheListener(new LoggingCacheListener()); -custRegion = rf.create("customer"); -``` - -Creating a modified partitioned region using RegionFactory: - -``` pre -PartitionAttributesFactory paf = new PartitionAttributesFactory<CustomerId, String>(); -paf.setPartitionResolver(new CustomerOrderResolver()); - -RegionFactory rf = - cache.createRegionFactory(RegionShortcut.PARTITION); -rf.setPartitionAttributes(paf.create()); -rf.addCacheListener(new LoggingCacheListener()); -custRegion = rf.create("customer"); -``` - -Creating a client region with a pool specification using ClientRegionFactory: - -``` pre -ClientRegionFactory<String,String> cRegionFactory = - cache.createClientRegionFactory(PROXY); -Region<String, String> region = - cRegionFactory.setPoolName("Pool3").create("DATA"); -``` - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/data_regions/create_a_region_with_cacheXML.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/data_regions/create_a_region_with_cacheXML.html.md.erb b/basic_config/data_regions/create_a_region_with_cacheXML.html.md.erb deleted file mode 100644 index 2737c88..0000000 --- a/basic_config/data_regions/create_a_region_with_cacheXML.html.md.erb +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Creating a Region Through the cache.xml File ---- - -A common way to create a data region in the Apache Geode cache is through `cache.xml` declarations. - -Before you start, configure your `<cache>` or `<client-cache>` in your `cache.xml` file and determine the region shortcut and other attributes settings your region needs. The `cache.xml` file must conform to the schema definition provided in the product's `cache-1.0.xsd`. - -Region creation is subject to attribute consistency checks, both internal to the cache and, if the region is not local, between all caches where the region is defined. The requirements for consistency between region attributes are detailed in the online Java API documentation. - -1. - - In your `cache.xml` file, create a `<region>` element for your new region as a subelement to the `<cache>` element or the `<client-cache>` element. -2. - - Define your regionâs name and a region attributes shortcut setting, if one applies. Find the shortcut setting that most closely fits your region configuration. -3. - - Add other attributes as needed to customize the regionâs behavior. - -When you start your member with the `cache.xml` file, the region will be created. - -## Examples - -Partitioned Region Declaration - -``` pre -<region name="myRegion" refid="PARTITION"/> -``` - -Partitioned Region Declaration with Backup to Disk - -``` pre -<region name="myRegion" refid="PARTITION_PERSISTENT"/> -``` - -Partitioned Region Declaration with HA and Modified Storage Capacity in Host Member - -``` pre -<region name="myRegion" refid="PARTITION_REDUNDANT"> - <region-attributes> - <partition-attributes local-max-memory="512" /> - </region-attributes> -</region> -``` - -Replicated Region Declaration - -``` pre -<region name="myRegion" refid="REPLICATE"/> -``` - -Replicated Region Declaration with Event Listener and Expiration - -``` pre -<region name="myRegion" refid="REPLICATE"> - <region-attributes statistics-enabled="true"> - <entry-time-to-live> - <expiration-attributes timeout="60" action="destroy"/> - </entry-time-to-live> - <cache-listener> - <class-name>myPackage.MyCacheListener</class-name> - </cache-listener> - </region-attributes> -</region> -``` - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/data_regions/create_a_region_with_gfsh.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/data_regions/create_a_region_with_gfsh.html.md.erb b/basic_config/data_regions/create_a_region_with_gfsh.html.md.erb deleted file mode 100644 index c15c5fc..0000000 --- a/basic_config/data_regions/create_a_region_with_gfsh.html.md.erb +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Creating a Region with gfsh ---- - -A simple and fast way to create a data region in the Apache Geode cache is to use the `gfsh` command-line tool. - -Before you start, configure your `Cache` or `ClientCache` and determine the region shortcut and other attributes settings your region needs. - -Region creation is subject to attribute consistency checks, both internal to the cache and, if the region is not local, between all caches where the region is defined. The requirements for consistency between region attributes are detailed in the online Java API documentation. - -1. - - Start a `gfsh` prompt. -2. - - Connect to a server that is currently acting as a JMX Manager node. -3. - - Enter the `create region` command providing any desired region attributes as arguments. - For example: - ``` pre - gfsh>create region --name=region1 --type=REPLICATE - ``` - -4. - - Add data into the region by using the [import data](../../tools_modules/gfsh/command-pages/import.html#topic_jw2_2ld_2l) command or [put](../../tools_modules/gfsh/command-pages/put.html) gfsh command. -5. - - After you modify data in the region you can use the [export data](../../tools_modules/gfsh/command-pages/export.html#topic_263B70069BFC4A7185F86B3272011734) command to generate a snapshot of the current region's data for later use. -6. - - Export the configuration files of your server so that you can save your region's configuration and recreate the region with the same attributes the next time you start up your cache server. See [export config](../../tools_modules/gfsh/command-pages/export.html#topic_C7C69306F93743459E65D46537F4A1EE) for details. - - **Note:** - The cluster configuration service, which is enabled by default, automatically saves the configuration on the locators in the distributed system. After you use the gfsh create region command, any new servers that you start that attach to the same locator receive the same configuration. You can also create alternate configurations within a distributed system by specifying a group when creating the region and starting servers. See [Overview of the Cluster Configuration Service](../../configuring/cluster_config/gfsh_persist.html). - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/data_regions/creating_custom_attributes.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/data_regions/creating_custom_attributes.html.md.erb b/basic_config/data_regions/creating_custom_attributes.html.md.erb deleted file mode 100644 index c234016..0000000 --- a/basic_config/data_regions/creating_custom_attributes.html.md.erb +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Creating Custom Attributes for Regions and Entries ---- - -Use custom attributes to store information related to your region or its entries in your cache. These attributes are only visible to the local application and are not distributed. - -<a id="creating_custom_attributes__section_A8752F55C157480FAF435738D6244503"></a> -You can define custom user attributes so you can associate data with the region or entry and retrieve it later. Unlike the other configuration settings, these attributes are used only by your application. - -**Note:** -User attributes are not distributed. - -1. Create a Java `Object` with your attribute definitions. -2. Attach the object to the region or to an entry: - - `Region.setUserAttribute(userAttributeObject)` - - `Region.getEntry(key).setUserAttribute(userAttributeObject)` - -3. Get the attribute value: - - `Region.getUserAttribute()` - - `Region.getEntry(key).getUserAttribute()` - -This example stores attributes for later retrieval by a cache writer. - -``` pre -// Attach a user attribute to a Region with database info for table portfolio -Object myAttribute = "portfolio"; -final Region portfolios = - new RegionFactory().setCacheWriter(new PortfolioDBWriter()).create("Portfolios"); -Portfolios.setUserAttribute(myAttribute); -``` - -``` pre -//Implement a cache writer that reads the user attribute setting -public class PortfolioDBWriter extends CacheWriterAdapter { - public void beforeCreate(RegionEvent event) { - table = (String)event.getRegion().getUserAttribute(); - // update database table using name from attribute - . . . - } -} -``` - -## <a id="creating_custom_attributes__section_A5CB456E4E96410584F8856EAFB5BB83" class="no-quick-link"></a>Limitations and Alternatives - -User attributes are not distributed to other processes, so if you need to define each attribute in every process that uses the region or entry. You need to update every instance of the region separately. User attributes are not stored to disk for region persistence or overflow, so they cannot be recovered to reinitialize the region. - -If your application requires features not supported by user attributes, an alternative is to create a separate region to hold this data instead. For instance, a region, AttributesRegion, defined by you, could use region names as keys and the user attributes as values. Changes to AttributesRegion would be distributed to other processes, and you could configure the region for persistence or overflow if needed. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/data_regions/managing_data_regions.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/data_regions/managing_data_regions.html.md.erb b/basic_config/data_regions/managing_data_regions.html.md.erb deleted file mode 100644 index cd9427b..0000000 --- a/basic_config/data_regions/managing_data_regions.html.md.erb +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: Data Region Management ---- - -Apache Geode provides different APIs and XML configuration models to support configuration and management of your data regions. - -<a id="data_regions__section_18A9481217204613958897FE64105097"></a> -You store your data in region entry key/value pairs, with keys and values being any object types your application needs. - -The `org.apache.geode.cache.Region` interface implements `java.util.Map`. - -Each region's attributes define how the data in the region is stored, distributed, and managed. Data regions can be distributed, partitioned among system members, or local to the member. - -You can create regions in the `cache.xml` file, by using the API, or with the gfsh command-line interface. You can use *region shortcuts* to configure commonly-used types of regions. For more information about region shortcuts, see [Region Shortcuts Reference](../../reference/topics/region_shortcuts_reference.html#reference_lt4_54c_lk). - -**Note:** -If you change attributes that define a region, you must restart the member for the changes to take effect. - -## <a id="data_regions__section_028F2602395646818680C906F205526B" class="no-quick-link"></a>The Region APIs - -Geode's regions APIs provide specialized behavior for different system member types. - -- **Peer/Server Region APIs**. Use these methods, interfaces, and classes for peer/server region creation. These are in the `org.apache.geode.cache` package. They correspond to declarations in the `<cache>` element for creating and configuring regions. - - **`org.apache.geode.cache.Cache.createRegionFactory`** . This method takes a `RegionShortcut` `enum` to initiate region configuration, and returns a `RegionFactory`. Use `createRegionFactory()`, not "`new RegionFactory`," to create a RegionFactory. - - **`org.apache.geode.cache.RegionFactory`**. Provides methods to set individual region attributes and to create the region. The `create` call returns `Region`. - - **`org.apache.geode.cache.RegionShortcut`**. Common region configurations can be retrieved through `Cache` `createRegionShortcut` and with the region attribute, `refid`. -- **Client Region APIs**. Use these methods, interfaces, and classes for client region creation. These are in the `org.apache.geode.cache.client` package. They correspond to declarations in the `<client-cache>` element for creating and configuring regions. - - These are client versions of the Peer/Server Region APIs. These client APIs provide similar functionality, but are tailored to the needs and behaviors of client regions. - - - **`org.apache.geode.cache.clientCache.createRegionFactory`** . This method takes a `ClientRegionShortcut` `enum` to initiate region configuration, and returns a `ClientRegionFactory`. - - **`org.apache.geode.cache.client.ClientRegionFactory`**. Provides methods to set individual region attributes and to create the region. The `create` call returns `Region`. - - **`org.apache.geode.cache.client.ClientRegionShortcut`** . Common region configurations can be retrieved through `ClientCache` `createClientRegionFactory` and with the region attribute, `refid`. -- **Region APIs Used For All Member Types**. These interfaces and classes are used universally for region management. These are in the `org.apache.geode.cache` package. They correspond to declarations under the `<cache>` and `<client-cache>` elements for creating and configuring regions. - - **`org.apache.geode.cache.Region`** . Interface for managing your regions and their entries. - - **`org.apache.geode.cache.RegionAttributes`** . Object holding region configuration settings. - - **`org.apache.geode.cache.createRegionFactory`**. Can be used to create `RegionAttributes` to pass to `RegionFactory` and `ClientRegionFactory`. - -## <a id="data_regions__section_9F898C23D2164ED5BB3789FD8B1F68C3" class="no-quick-link"></a>Create and Access Data Regions - -Before you start, have your cache configuration defined, along with any cache-wide configuration your region requires, like disk store configuration and client server pool configuration. - -1. Determine the region attributes requirements and identify the region shortcut setting that most closely matches your needs. See [Region Shortcuts and Custom Named Region Attributes](region_shortcuts.html) and [Region Shortcuts](../../reference/topics/chapter_overview_regionshortcuts.html) for more information. -2. Define any region attributes that are not provided in the shortcut you chose. -3. Create a region using any of the following methods: - - `gfsh`. After starting up servers, a JMX manager and connecting to the cluster, execute the following command: - - gfsh>create region --name=Portfolios --type=REPLICATE - - Declaration in the `cache.xml`: - - <?xml version="1.0" encoding="UTF-8"?> - <cache - xmlns="http://geode.incubator.apache.org/schema/cache"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://geode.incubator.apache.org/schema/cache http://geode.incubator.apache.org/schema/cache/cache-1.0.xsd"; - version="1.0" - lock-lease="120" - lock-timeout="60" - search-timeout="300"> - <!-- Create a region named Portfolios --> - <region name="Portfolios" id="REPLICATE"/> - </cache> - - When the `cache.xml` is loaded at cache creation, the system automatically creates any declared regions. - - `RegionFactory` API calls: - - Cache cache = CacheFactory.create(); - RegionFactory rf = cache.createRegionFactory(REPLICATE); - Region pfloRegion = rf.create("Portfolios"); - -Once you have created your regions, you can access them through the `Cache` and `Region` APIs as full region lists or individually. - -## <a id="data_regions__section_jn1_sry_5m" class="no-quick-link"></a>Create and Access Data Subregions - -An individual region can contain multiple subregions. -Subregions are an older feature that will not be useful in new designs -and applications. -They are used to create a hierarchical namespace within a cache, -providing naming that feels like paths in a file system. -Here are limitations on the use of subregions: - -- A region with LOCAL scope can only have subregions with LOCAL scope. -- Partitioned region types may not be used with subregions. A subregion may not have a parent that is a partitioned region, and a subregion may not be of type PARTITION. -- A subregion must have the same scope (GLOBAL, DISTRIBUTED\_ACK, DISTRIBUTED\_NO\_ACK) as its parent region. -- Subregion names must be unique within the cache. - -You can create subregions using one of the following methods: - -- Declaration in the `cache.xml`: - - <?xml version="1.0"?> - <cache - xmlns="http://geode.incubator.apache.org/schema/cache"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://geode.incubator.apache.org/schema/cache http://geode.incubator.apache.org/schema/cache/cache-1.0.xsd"; - version="1.0" - lock-lease="120" - lock-timeout="60" - search-timeout="300"> - <!-- Create a region named Portfolios --> - <region name="Portfolios" id="REPLICATE"> - <region name="Private" id="REPLICATE"> - ... - </region> - </region> - </cache> - - When the `cache.xml` is loaded at cache creation, the system automatically creates any declared regions and subregions. - -- `RegionFactory` API calls: - - Cache cache = CacheFactory.create(); - RegionFactory rf = cache.createRegionFactory(REPLICATE); - Region pfloRegion = rf.create("Portfolios"); - Region pvtSubregion = rf.createSubregion(pfloRegion, "Private"); - -`Region` method calls with a `recursive` parameter operate on the given -region(s) and then recursively on all contained subregions. - -## <a id="data_regions__section_7AD53DCC71064883BFA9C53E6040D85A" class="no-quick-link"></a>Update Data Regions - -Update your region properties and contents through `alter region` command, the API or from `cache.xml` file declarations. - -- Execute the [alter region](../../tools_modules/gfsh/command-pages/alter.html#topic_E74ED23CB60342538B2175C326E7D758) command. -- In the API, use `Cache` and `Region` methods to change configuration parameters and modify region structure and data. -- Load new XML declarations using the `Cache.loadCacheXml` method. Where possible, declarations in the new `cache.xml` file supersede existing definitions. For example, if a region declared in the `cache.xml` file already exists in the cache, its mutable attributes are modified according to the file declarations. Immutable attributes are not affected. If a region does not already exist, it is created. Entries and indexes are created or updated according to the state of the cache and the file declarations. - -## <a id="data_regions__section_953E19F03F4541BAA3AE58118E7EA7E4" class="no-quick-link"></a>Invalidate a Region - -An invalidate region operation removes all entry values for a region, while leaving the entry keys intact. This operation can be invoked only through the API on a `Region` instance. Event notification occurs. - -``` pre -// Invalidate the entire distributed region -Region.invalidateRegion(); -``` - -The API also offers a method to invalidate only the entries within the local cache. This method may not be used on a replicated region, as doing so would invalidate the replication contract. - -``` pre -// Invalidate the region within this member -Region.localInvalidateRegion(); -``` - -## Clear a Region - -A clear region operation removes all entries from a region. This operation is not available for partitioned regions. This operation can be invoked through the API on a `Region` instance: - -``` pre -// Remove all entries for the region -Region.clear(); -``` - -It can be invoked with the `gfsh` command: - -``` pre -gfsh>remove --region=Region1 --all -``` - -Event notification occurs for a clear region operation. - -## Destroy a Region - -A destroy region operation removes the entire region. This operation can be invoked through the API on a `Region` instance: - -``` pre -// Remove the entire region -Region.destroyRegion(); -``` - -A destroy region operation can be invoked with the `gfsh` command: - -``` pre -gfsh>destroy region --name=Region1 -``` - -Event notification occurs for a destroy region operation. - -A region can be destroyed by removing the region's specification from the `cache.xml` file. - -Destroying the region by an API invocation or by using the `gfsh destroy` command while all members are online is the best way to remove a region, as Geode handles all aspects of the removal, including removing the region's persistent disk stores across the online members hosting the region. Destroying the region by removing its specification from the `cache.xml` file does not remove the region's existing persistent disk stores. - -The destroy operation can be propagated only to online members. The system will encounter restart issues if a region is destroyed while some members are online and others are offline. As those members that were offline restart, they will block indefinitely, waiting for persistent region data that no longer exists. To fix this issue, shut down all members that are blocked waiting for the removed region. Once those members are in the offline state, use the `gfsh alter disk-store` command with the `--remove` option on each offline member to remove the region. Then, restart each member. - -An edge case results in issues when destroying a persistent region (R-removed) by removing its specification from the `cache.xml` file, and region R-removed was colocated with another persistent region (R-remains). The issue occurs because the persistent information contained within R-remains is inconsistent with the (lack of) specification of R-removed. Upon restart of R-remains, its persisted metadata refers to R-removed as a colocated region, and the startup of R-remains is dependent on that removed region. Thus, the startup of R-remains blocks, unable to complete. The issue may manifest with operations on the R-remains region such as a query, put, or get, that never finishes. To fix this issue, shut down all members with the persisted metadata that refers to the removed region. Once those members are in the offline state, use the `gfsh alter disk-store` command with the `--remove` option on each offline member to remove the region. Then, restart each member. - -## <a id="data_regions__section_3C0A7E088FDB413297ED8C0CD606968D" class="no-quick-link"></a>Close a Region - -Use this to stop local caching of persistent and partitioned regions without closing the entire cache: - -``` pre -Region.close(); -``` - -The `Region.close` operation works like the `Region.localDestroyRegion` operation with these significant differences: - -- The `close` method is called for every callback installed on the region. -- No events are invoked. Of particular note, the entry events, `beforeDestroy` and `afterDestroy`, and the region events, `beforeRegionDestroy` and `afterRegionDestroy`, are not invoked. See [Events and Event Handling](../../developing/events/chapter_overview.html#implementing_event_handlers). -- If persistent, the region is removed from memory but its disk files are retained. -- If partitioned, the region is removed from the local cache. If the partitioned region is redundant, local data caching fails over to another cache. Otherwise, local data is lost. - -## Using gfsh to Manage Regions - -You can also use gfsh commands to manage regions. There are commands to create, alter, describe, destroy, rebalance, and list the regions in your distributed system. By default, the cluster configuration service saves the cluster configuration as you execute gfsh commands. When you add new servers to the cluster, the servers receive this cluster-wide configuration and create the specified regions. You can also define *groups* that apply only to some of the servers in the cluster. Servers you start that specify a group also receive the group configuration from the cluster configuration service. See [Overview of the Cluster Configuration Service](../../configuring/cluster_config/gfsh_persist.html). - -See [Creating a Region with gfsh](create_a_region_with_gfsh.html#task_75639BFA7847461D9E006E91B728BB44) and the [create](../../tools_modules/gfsh/command-pages/create.html) command reference page. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/data_regions/managing_region_attributes.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/data_regions/managing_region_attributes.html.md.erb b/basic_config/data_regions/managing_region_attributes.html.md.erb deleted file mode 100644 index 541c8dd..0000000 --- a/basic_config/data_regions/managing_region_attributes.html.md.erb +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Managing Region Attributes ---- - -Use region attributes to fine-tune the region configuration provided by the region shortcut settings. - -<a id="managing_region_attributes__section_B6363B281A994141B9B9BDD952173330"></a> -All region attributes have default settings, so you only need to use region attributes to set the ones you want to override. See [<region-attributes>](../../reference/topics/cache_xml.html#region-attributes). - -## <a id="managing_region_attributes__section_DDBF2810ABB54A55B1479AD786ED48DF" class="no-quick-link"></a>Define Region Attributes - -Create region attributes using any of these methods: - -- Declarations inside the `cache.xml` `<region>` element: - - ``` pre - <cache> - <region name="exampleRegion" refid="REPLICATE"> - <region-attributes statistics-enabled="true"> - <entry-idle-time> - <expiration-attributes timeout="10" action="destroy"/> - </entry-idle-time> - <cache-listener> - <class-name>quickstart.SimpleCacheListener</class-name> - </cache-listener> - </region-attributes> - </region> - </cache> - ``` - - When the `cache.xml` is loaded at startup, declared region attributes are automatically created and applied to the region. - -- `RegionFactory` API `set`\* method calls: - - ``` pre - // Creating a partitioned region using the RegionFactory - RegionFactory rf = cache.createRegionFactory(RegionShortcut.PARTITION); - rf.addCacheListener(new LoggingCacheListener()); - custRegion = rf.create("customer"); - ``` - - ``` pre - // Creating a partitioned region using the RegionFactory, with attribute modifications - RegionFactory rf = - cache.createRegionFactory(RegionShortcut.PARTITION); - rf.setPartitionResolver(new CustomerOrderResolver()); - rf.addCacheListener(new LoggingCacheListener()); - custRegion = rf.create("customer"); - ``` - - ``` pre - // Creating a client with a Pool Specification Using ClientRegionFactory - ClientRegionFactory<String,String> cRegionFactory = - cache.createClientRegionFactory(PROXY); - Region<String, String> region = - cRegionFactory.setPoolName("Pool3").create("DATA"); - ``` - -- By issuing the gfsh `create region` command. - -## <a id="managing_region_attributes__section_F69A7664F72D47BBA463D81B72C03B4D" class="no-quick-link"></a>Modify Region Attributes - -You can modify a regionâs event handlers and expiration and eviction attributes after the region is created. - -**Note:** -Do not modify attributes for existing regions unless absolutely necessary. Creating the attributes you need at region creation is more efficient. - -Modify attributes in one of these ways: - -- By loading a `cache.xml` with modified region attribute specifications: - - ``` pre - <!-- Change the listener for exampleRegion - ... - <region name="exampleRegion"> - <region-attributes statistics-enabled="true"> - <cache-listener> - <class-name>quickstart.ComplicatedCacheListener</class-name> - </cache-listener> - </region-attributes> - </region> - ... - ``` - -- Using the `AttributesMutator` API: - 1. Retrieve the `AttributesMutator` from the region - 2. Call the mutator set methods to modify attributes: - - ``` pre - currRegion = cache.getRegion("root"); - AttributesMutator mutator = this.currRegion.getAttributesMutator(); - mutator.addCacheListener(new LoggingCacheListener()); - ``` - -- By issuing the gfsh `alter region` command. See [alter region](../../tools_modules/gfsh/command-pages/alter.html#topic_E74ED23CB60342538B2175C326E7D758). - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/data_regions/new_region_existing_data.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/data_regions/new_region_existing_data.html.md.erb b/basic_config/data_regions/new_region_existing_data.html.md.erb deleted file mode 100644 index ad17ebd..0000000 --- a/basic_config/data_regions/new_region_existing_data.html.md.erb +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Building a New Region with Existing Content ---- - -A new region or distributed system may need to be loaded with the data of an existing system. There are two approaches to accomplish this task. The approach used depends upon the organization of both the new and the existing distributed system. - -If both the number and the type of members is the same in both the new and the existing distributed system, then the simplest option is to use backup and restore on the persistent disk store contents. Make a full online backup of the persistent data in the disk store of the existing distributed system. Copy the files that comprise the backup to the new distributed system location. A restore instills the data into the new distributed system. See [Creating Backups for System Recovery and Operational Management](../../managing/disk_storage/backup_restore_disk_store.html) for details on how to make a backup and use the backup to restore a disk store. - -Take a different approach when the number or the type of members is *not* the same in both the new and the existing distributed system. This approach uses export and import of region data. Export the region data of the existing distributed system to create a snapshot. Copy the snapshot to the new distributed system location. Import the snapshot into the new distributed system. See appropriate sections within [Cache and Region Snapshots](../../managing/cache_snapshots/chapter_overview.html) for details on making and using a snapshot. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/data_regions/region_naming.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/data_regions/region_naming.html.md.erb b/basic_config/data_regions/region_naming.html.md.erb deleted file mode 100644 index 021079d..0000000 --- a/basic_config/data_regions/region_naming.html.md.erb +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Region Naming ---- - -To be able to perform all available operations on your data regions, -follow these region naming guidelines. - -- Permitted characters within region names are alphanumeric characters -(`ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789`), -the underscore character (`_`), and the hyphen character (`-`). -- Do not use the slash character (`/`). -- Do not begin region names with two underscore characters (`__`), -as this is reserved for internal use. - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/data_regions/region_shortcuts.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/data_regions/region_shortcuts.html.md.erb b/basic_config/data_regions/region_shortcuts.html.md.erb deleted file mode 100644 index 270987b..0000000 --- a/basic_config/data_regions/region_shortcuts.html.md.erb +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Region Shortcuts and Custom Named Region Attributes ---- - -Geode provides region shortcut settings, with preset region configurations for the most common region types. For the easiest configuration, start with a shortcut setting and customize as needed. You can also store your own custom configurations in the cache for use by multiple regions. - -<a id="region_shortcuts__section_D9E58754D2B0435FA2986DBBF3063D4C"></a> -You configure automated management of data regions and their entries through region shortcuts and region attributes. These region configuration settings determine such things as where the data resides, how the region is managed in memory, reliability behavior, and the automatic loading, distribution, and expiration of data entries. - -**Note:** -Whenever possible, use region shortcuts to configure your region, and further customize behavior using region attributes. The shortcut settings are preset with the most common region configurations. - -Geode provides a number of predefined, shortcut region attributes settings for your use. You can also define your own custom region attributes and store them with an identifier for later retrieval. Both types of stored attributes are referred to as named region attributes. You can create and store your attribute settings in the `cache.xml` file and through the API. - -Retrieve region shortcuts and custom named attributes by providing the ID to the region creation, in the `refid` attribute setting. This example uses the shortcut REPLICATE attributes to create a region: - -``` pre -<region name="testREP" refid="REPLICATE"/> -``` - -You can create your own named attributes as needed, by providing an `id` in your region attributes declaration. The following region declaration: - -1. Retrieves all of the attribute settings provided by the persistent partitioned region shortcut -2. Modifies the shortcut attribute settings by specifying a disk store name to use for persistence -3. Assigns the new attribute settings to the new region named `testPR` -4. Stores the attribute settings in a new custom attributes named `testPRPersist`: - - ``` pre - <disk-store name="testDiskStore" > - <disk-dirs> - <disk-dir>PRPersist1</disk-dir> - <disk-dir>PRPersist2</disk-dir> - </disk-dirs> - </disk-store> - <region name="testPR" > - <region-attributes id="testPRPersist" - refid="PARTITION_PERSISTENT" disk-store-name="testDiskStore"/> - </region> - ``` - -## <a id="region_shortcuts__section_20548383511141B19EBC053E36877B1A" class="no-quick-link"></a>Shortcut Attribute Options - -You can select the most common region attributes settings from Geodeâs predefined named region attributes in these classes: - -- **`org.apache.geode.cache.RegionShortcut`**. For peers and servers. -- **`org.apache.geode.cache.client.ClientRegionShortcut`**. For clients. - -Shortcut attributes are a convenience only. They are just named attributes that Geode has already stored for you. You can override their settings by storing new attributes with the same id as the predefined attributes. - -For a full list of all available region shortcuts, see [Region Shortcuts Quick Reference](../../reference/topics/region_shortcuts_table.html#reference_ufj_5kz_4k). - -The `org.apache.geode.cache.RegionShortcut` Javadocs give complete listings of the options. - -## <a id="region_shortcuts__section_D0975C76572E41F79C1A6EE7CF371251" class="no-quick-link"></a>RegionShortcuts for Peers and Servers - -These are the primary options available in the region shortcut settings. The names listed appear in the shortcut identifier alone or in combination, like "`PARTITION`" in `PARTITION`, `PARTITION_PROXY`, and `PARTITION_REDUNDANT`. - -**Cache Data Storage Mode** - -- **`PARTITION`** . Creates a partitioned region. This is a data store for the region. You can also specify these options with `PARTITION`: - - **`PROXY`**. Data is not stored in the local cache and the member is a data accessor to the region. This requires other members to create non-proxy copies of the region, so the data is stored somewhere. - - **`REDUNDANT`**. The region stores a secondary copy of all data, for high availability. -- **`REPLICATE`**. Creates a replicated region. This is a data store for the region. You can also specify these options with `REPLICATE`: - - **`PROXY`**. Data is not stored in the local cache and the member is a data accessor to the region. This requires other members to create non-proxy copies of the region, so the data is stored somewhere. -- **`LOCAL`**. Creates a region private to the defining member. - -**Data Eviction** - -- **`HEAP_LRU`**. Causes least recently used data to be evicted from memory when the Geode resource manager determines that the cache has reached configured storage limits. - -**Disk Storage** - -You can specify these alone or in combination: - -- **`PERSISTENT`**. Backs up all data to disk, in addition to storing it in memory. -- **`OVERFLOW`**. Moves data out of memory and on to disk, when memory use becomes too high. - -## <a id="region_shortcuts__section_BD136ACEB8274B17ACFB9A5954D116E4" class="no-quick-link"></a>ClientRegionShortcuts for Clients - -These are the primary options available in the client region shortcut settings. The names listed appear in the shortcut identifier alone or in combination, like "`PROXY`" in `PROXY` and `CACHING_PROXY`. - -**Communication with Servers and Data Storage** - -- **`PROXY`**. Does not store data in the client cache, but connects the region to the servers for data requests and updates, interest registrations, and so on. The client is a data accessor to the region. -- **`CACHING_PROXY`**. Stores data in the client cache and connects the region to the servers for data requests and updates, interest registrations, and so on. -- **`LOCAL`**. Stores data in the client cache and does not connect the region to the servers. This is a client-side-only region. Note that this is not the same as setting the region's `scope` attribute to `LOCAL`. - -**Data Eviction** - -- **`HEAP_LRU`**. Causes least recently used data to be evicted from memory when the Geode resource manager determines that the cache has reached configured storage limits. - -**Disk Storage** - -With the LOCAL and CACHING data storage shortcut options, you can also specify these disk storage options, alone or in combination: - -- **`PERSISTENT`**. Backs up all data to disk, in addition to storing it in memory. -- **`OVERFLOW`**. Moves data out of memory and on to disk, when memory use becomes too high. - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/data_regions/store_retrieve_region_shortcuts.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/data_regions/store_retrieve_region_shortcuts.html.md.erb b/basic_config/data_regions/store_retrieve_region_shortcuts.html.md.erb deleted file mode 100644 index 9d39bd5..0000000 --- a/basic_config/data_regions/store_retrieve_region_shortcuts.html.md.erb +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Storing and Retrieving Region Shortcuts and Custom Named Region Attributes ---- - -Use these examples to get started with Geode region shortcuts. - -<a id="region_shortcuts__section_D9E58754D2B0435FA2986DBBF3063D4C"></a> -Geode region shortcuts, in `org.apache.geode.cache.RegionShortcut` for peers and servers and `org.apache.geode.cache.client.ClientRegionShortcut` for clients, are available wherever you create a region in the `cache.xml` or through the API. Custom named attributes, stored by you, are available from the moment you store them on. - -The region shortcuts are special Geode named region attributes, with identifying names. Create custom named region attributes by setting the attributes and storing them with a unique identifier in the region attribute `id`. Retrieve named attributes by providing the shortcut enum value or the name you assigned in the `id` to the region creation: - -- In the API, use the identifier in the region factory creation -- In the `cache.xml`, use the identifier in the `<region>` or `<region-attribute>` `refid` setting. The `refid` is available in both elements for convenience - -## <a id="region_shortcuts__section_8FCBCC4BDCDE4A85A27E5B9B70603F63" class="no-quick-link"></a>Examples - -**Example \#1** - -This example shows partitioned region creation in the `cache.xml`: - -- The first `region-attributes` declaration starts with the predefined `PARTITION_REDUNDANT` attributes, modifies the `local-max-memory` setting, and stores the resulting attributes in the custom-named `myPartition` attributes. -- The region declarations use the new stored attributes, but each has its own interest policy, which is specified in the individual region creation. - - ``` pre - <!-- Retrieving and storing attributes --> - <region-attributes id="myPartition" refid="PARTITION_REDUNDANT"> - <partition-attributes local-max-memory="512"/> - </region-attributes> - - <!-- Two partitioned regions, one colocated with the other --> - - <!-- Attributes are retrieved and applied in the first region --> - <region name="PartitionedRegion1" refid="myPartition"/> - - <!-- Same stored attributes, modification for this region--> - <region name="PartitionedRegion2" refid="myPartition"> - <region-attributes> - <partition-attributes colocated-with="PartitionedRegion1" /> - </region-attributes> - </region> - ``` - -**Example \#2** - -This example uses the `RegionFactory` API to create a region based on the predefined `PARTITION` region shortcut: - -``` pre -final Region diskPortfolios = - new RegionFactory("PARTITION").create("Portfolios"); -``` - -This example retrieves an attributes template and passes it to the region creation with a modified pool specification: - -``` pre -ClientRegionFactory<String,String> regionFactory = - cache.createClientRegionFactory(PROXY); -Region<String, String> region = regionFactory - .setPoolName("publisher") - .create("DATA"); -``` http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/gemfire_properties/setting_distributed_properties.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/gemfire_properties/setting_distributed_properties.html.md.erb b/basic_config/gemfire_properties/setting_distributed_properties.html.md.erb deleted file mode 100644 index db03d15..0000000 --- a/basic_config/gemfire_properties/setting_distributed_properties.html.md.erb +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Setting Properties ---- - -Geode provides a default distributed system configuration for out-of-the-box systems. To use non-default configurations and to fine-tune your member communication, you can use a mix of various options to customize your distributed system configuration. - -<a id="setting_distributed_properties__section_67EBCC53EB174B108DA7271E2CD2B76C"></a> -Geode properties are used to join a distributed system and configure system member behavior. Configure your Geode properties through the `gemfire.properties` file, the Java API, or command-line input. Generally, you store all your properties in the `gemfire.properties` file, but you may need to provide properties through other means, for example, to pass in security properties for username and password that you have received from keyboard input. - -**Note:** -Check with your Geode system administrator before changing properties through the API, including the `gemfire.properties` and `gfsecurity.properties` settings. The system administrator may need to set properties at the command line or in configuration files. Any change made through the API overrides those other settings. - -**Note:** -The product `defaultConfigs` directory has a sample `gemfire.properties` file with all default settings. - -Set distributed system properties by any combination of the following. The system looks for the settings in the order listed: - -1. `java.lang.System` property setting. Usually set at the command line. For applications, set these in your code or at the command line. - - Naming: Specify these properties in the format `gemfire.property-name`, where `property-name` matches the name in the `gemfire.properties` file. To set the gemfire property file name, use `gemfirePropertyFile` by itself - - In the API, set the `System` properties before the cache creation call. Example: - - ``` pre - System.setProperty("DgemfirePropertyFile", "gfTest"); - System.setProperty("Dgemfire.mcast-port", "10999"); - - Cache cache = new CacheFactory().create(); - ``` - - At the `java` command line, pass in `System` properties using the `-D` switch. Example: - - ``` pre - java -DgemfirePropertyFile=gfTest -Dgemfire.mcast-port=10999 test.Program - ``` -2. Entry in a `Properties` object. - - Naming: Specify these properties using the names in the `gemfire.properties` file. To set the gemfire property file name, use `gemfirePropertyFile`. - - In the API, create a `Properties` object and pass it to the cache create method. Example: - - ``` pre - Properties properties= new Properties(); - properties.setProperty("log-level", "warning"); - properties.setProperty("name", "testMember2"); - ClientCache userCache = - new ClientCacheFactory(properties).create(); - ``` - - For the cache server, pass the properties files on the `gfsh` command line as command-line options. Example: - - ``` pre - gfsh>start server --name=server_name --mcast-port=10338 --properties-file=serverConfig/gemfire.properties --security-properties-file=gfsecurity.properties - ``` - - See [Running Geode Server Processes](../../configuring/running/running_the_cacheserver.html) for more information on running cache servers. - -3. Entry in a `gemfire.properties` file. See [Deploying Configuration Files without the Cluster Configuration Service](../../configuring/running/deploying_config_files.html). Example: - - ``` pre - cache-xml-file=cache.xml - conserve-sockets=true - disable-tcp=false - ``` - -4. Default value. The default property values are listed in the online Java documentation for `org.apache.geode.distributed.DistributedSystem`. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ccc2fbda/basic_config/the_cache/chapter_overview.html.md.erb ---------------------------------------------------------------------- diff --git a/basic_config/the_cache/chapter_overview.html.md.erb b/basic_config/the_cache/chapter_overview.html.md.erb deleted file mode 100644 index c003e8b..0000000 --- a/basic_config/the_cache/chapter_overview.html.md.erb +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Cache Management ---- - -The Geode cache is the entry point to Geode caching management. Geode provides different APIs and XML configuration models to support the behaviors of different members. - -- **[Introduction to Cache Management](../../basic_config/the_cache/intro_cache_management.html)** - - The cache provides in-memory storage and management for your data. - -- **[Managing a Peer or Server Cache](../../basic_config/the_cache/managing_a_peer_server_cache.html)** - - You start your peer or server cache using a combination of XML declarations and API calls. Close the cache when you are done. - -- **[Managing a Client Cache](../../basic_config/the_cache/managing_a_client_cache.html)** - - You have several options for client cache configuration. Start your client cache using a combination of XML declarations and API calls. Close the client cache when you are done. - -- **[Managing a Cache in a Secure System](../../basic_config/the_cache/managing_a_secure_cache.html)** - - When you create your cache in a secure system, you provide credentials to the connection process for authentication by already-running, secure members. Clients connect to secure servers. Peers are authenticated by secure locators or peer members. - -- **[Managing RegionServices for Multiple Secure Users](../../basic_config/the_cache/managing_a_multiuser_cache.html)** - - In a secure system, you can create clients with multiple, secure connections to the servers from each client. The most common use case is a Geode client embedded in an application server that supports data requests from many users. Each user may be authorized to access a subset of data on the servers. For example, customer users may be allowed to see and update only their own orders and shipments. - -- **[Launching an Application after Initializing the Cache](../../basic_config/the_cache/setting_cache_initializer.html)** - - You can specify a callback application that is launched after the cache initialization. - -
