http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/basic_config/data_regions/managing_data_regions.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/managing_data_regions.html.md.erb b/geode-docs/basic_config/data_regions/managing_data_regions.html.md.erb deleted file mode 100644 index cd9427b..0000000 --- a/geode-docs/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/ff80a931/geode-docs/basic_config/data_regions/managing_region_attributes.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/managing_region_attributes.html.md.erb b/geode-docs/basic_config/data_regions/managing_region_attributes.html.md.erb deleted file mode 100644 index 541c8dd..0000000 --- a/geode-docs/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/ff80a931/geode-docs/basic_config/data_regions/new_region_existing_data.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/new_region_existing_data.html.md.erb b/geode-docs/basic_config/data_regions/new_region_existing_data.html.md.erb deleted file mode 100644 index ad17ebd..0000000 --- a/geode-docs/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/ff80a931/geode-docs/basic_config/data_regions/region_naming.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/region_naming.html.md.erb b/geode-docs/basic_config/data_regions/region_naming.html.md.erb deleted file mode 100644 index 021079d..0000000 --- a/geode-docs/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/ff80a931/geode-docs/basic_config/data_regions/region_shortcuts.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/region_shortcuts.html.md.erb b/geode-docs/basic_config/data_regions/region_shortcuts.html.md.erb deleted file mode 100644 index 270987b..0000000 --- a/geode-docs/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/ff80a931/geode-docs/basic_config/data_regions/store_retrieve_region_shortcuts.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/data_regions/store_retrieve_region_shortcuts.html.md.erb b/geode-docs/basic_config/data_regions/store_retrieve_region_shortcuts.html.md.erb deleted file mode 100644 index 9d39bd5..0000000 --- a/geode-docs/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/ff80a931/geode-docs/basic_config/gemfire_properties/setting_distributed_properties.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/gemfire_properties/setting_distributed_properties.html.md.erb b/geode-docs/basic_config/gemfire_properties/setting_distributed_properties.html.md.erb deleted file mode 100644 index db03d15..0000000 --- a/geode-docs/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/ff80a931/geode-docs/basic_config/the_cache/chapter_overview.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/the_cache/chapter_overview.html.md.erb b/geode-docs/basic_config/the_cache/chapter_overview.html.md.erb deleted file mode 100644 index c003e8b..0000000 --- a/geode-docs/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. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/basic_config/the_cache/intro_cache_management.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/the_cache/intro_cache_management.html.md.erb b/geode-docs/basic_config/the_cache/intro_cache_management.html.md.erb deleted file mode 100644 index 2d21a60..0000000 --- a/geode-docs/basic_config/the_cache/intro_cache_management.html.md.erb +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Introduction to Cache Management ---- - -The cache provides in-memory storage and management for your data. - -<a id="concept_F8BA7F2D3B5A40D78461E78BC5FB31FA__section_B364B076EB5843DAAC28EE2805686453"></a> -You organize your data in the cache into *data regions*, each with its own configurable behavior. You store your data into your regions in key/value pairs called *data entries*. The cache also provides features like transactions, data querying, disk storage management, and logging. See the Javadocs for `org.apache.geode.cache.Cache`. - -You generally configure caches using the `gfsh` command-line utility or a combination of XML declarations and API calls. Geode loads and processes your XML declarations when you first create the cache. - -Geode has one cache type for managing server and peer caches and one for managing client caches. The cache server process automatically creates its server cache at startup. In your application process, the cache creation returns an instance of the server/peer or client cache. From that point on, you manage the cache through API calls in your application. - -## <a id="concept_F8BA7F2D3B5A40D78461E78BC5FB31FA__section_20973C59F1C94E35A02CE6582503205A" class="no-quick-link"></a>The Caching APIs - -Geode's caching APIs provide specialized behavior for different system member types and security settings. - -- **`org.apache.geode.cache.RegionService`**. Generally, you use the `RegionService` functionality through instances of `Cache` and `ClientCache`. You only specifically use instances of `RegionService` for limited-access users in secure client applications that service many users. The `RegionService` API provides access to existing cache data regions and to the standard query service for the cache. For client caches, queries are sent to the server tier. For server and peer caches, queries are run in the current cache and any available peers. `RegionService` is implemented by `GemFireCache`. -- **`org.apache.geode.cache.GemFireCache`**. You do not specifically use instances of `GemFireCache`, but you use `GemFireCache` functionality in your instances of `Cache` and `ClientCache`. `GemFireCache` extends `RegionService` and adds general caching features like region attributes, disk stores for region persistence and overflow, and access to the underlying distributed system. `GemFireCache` is implemented by `Cache` and `ClientCache`. -- **`org.apache.geode.cache.Cache`**. Use the `Cache` interface to manage server and peer caches. You have one `Cache` per server or peer process. The `Cache` extends `GemFireCache` and adds server/peer caching features like communication within the distributed system, region creation, transactions and querying, and cache server functionality. -- **`org.apache.geodeâsetting_cache_initializer.cache.ClientCache`**. Use the `ClientCache` interface to manage the cache in your clients. You have one `ClientCache` per client process. The `ClientCache` extends `GemFireCache` and adds client-specific caching features like client region creation, subscription keep-alive management for durable clients, querying on server and client tiers, and RegionService creation for secure access by multiple users within the client. - -## <a id="concept_F8BA7F2D3B5A40D78461E78BC5FB31FA__section_6486BDAF06EC4B91A548872066F3EC8C" class="no-quick-link"></a>The Cache XML - -Your `cache.xml` must be formatted according to the product XML schema definition `cache-1.0.xsd`. The schema definition file is available in the product distribution at `$GEMFIRE/schemas/geode.apache.org/schema/cache/cache-1.0.xsd`. - -You use one format for peer and server caches and another for client caches. - -`cache.xml` for Peer/Server: - -``` pre -<?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â> -... -</cache> -``` - -`cache.xml` for Client: - -``` pre -<?xml version="1.0" encoding="UTF-8"?> -<client-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â> -... -</client-cache> -``` - -For more information on the `cache.xml` file, see [cache.xml](../../reference/topics/chapter_overview_cache_xml.html#cache_xml). - -## <a id="concept_F8BA7F2D3B5A40D78461E78BC5FB31FA__section_B113BC6921DA434C947D4326DDB4526E" class="no-quick-link"></a>Create and Close a Cache - -Your system configuration and cache configuration are initialized when you start your member processes and create each memberâs Geode cache. If you are using the cluster configuration service, member processes can pick up its cache configuration from the cluster or group's current configuration. See [Overview of the Cluster Configuration Service](../../configuring/cluster_config/gfsh_persist.html). - -The steps in this section use `gemfire.properties` and `cache.xml` file examples, except where API is required. You can configure your distributed system properties and cache through the API as well, and you can use a combination of file configuration and API configuration. - -The XML examples may not include the full `cache.xml` file listing. All of your declarative cache configuration must conform to the cache XSD in the product installation `$GEMFIRE/schemas/geode.apache.org/schema/cache/cache-1.0.xsd`. - -For all of your Geode applications: - -1. Create your `Cache`, for peer/server applications, or `ClientCache`, for client applications. This connects to the Geode system you have configured and initializes any configured data regions. Use your cache instance to access your regions and perform your application work. -2. Close your cache when you are done. This frees up resources and disconnects your application from the distributed system in an orderly manner. - -Follow the instructions in the subtopics under [Cache Management](chapter_overview.html#the_cache) to customize your cache creation and closure for your application needs. You may need to combine more than one of the sets of instructions. For example, to create a client cache in a system with security, you would follow the instructions for creating and closing a client cache and for creating and closing a cache in a secure system. - -## <a id="concept_F8BA7F2D3B5A40D78461E78BC5FB31FA__section_E8781B263D434F6A9104194AE7BE1647" class="no-quick-link"></a>Export and Import a Cache Snapshot - -To aid in the administration of cache data and speed the setup of new environments, you can export a snapshot of the entire cache (all regions) and then import the snapshot into a new cache. For example, you could take a snapshot of the production environment cache in order to import the cache's data into a testing environment. - -For more details on exporting and importing snapshots of a cache, see [Cache and Region Snapshots](../../managing/cache_snapshots/chapter_overview.html#concept_E6AC3E25404D4D7788F2D52D83EE3071). - -## Cache Management with gfsh and the Cluster Configuration Service - -You can use gfsh commands to mange a server cache. There are gfsh commands to create regions, start servers, and to create queues and other objects. As you issue these commands, the Cluster Configuration Service saves cache.xml and gemfire.properties files on the locators and distributes those configurations to any new members that join the cluster. See [Overview of the Cluster Configuration Service](../../configuring/cluster_config/gfsh_persist.html). http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/basic_config/the_cache/managing_a_client_cache.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/the_cache/managing_a_client_cache.html.md.erb b/geode-docs/basic_config/the_cache/managing_a_client_cache.html.md.erb deleted file mode 100644 index 94099aa..0000000 --- a/geode-docs/basic_config/the_cache/managing_a_client_cache.html.md.erb +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Managing a Client Cache ---- - -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. - -<a id="managing_a_client_cache__section_566044C44C434926A7A9FBAB2BF463BF"></a> -Geode clients are processes that send most or all of their data requests and updates to a Geode server system. Clients run as standalone processes, without peers of their own. - -**Note:** -Geode automatically configures the distributed system for your `ClientCache` as standalone, which means the client has no peers. Do not try to set the `gemfire.properties` `mcast-port` or `locators` for a client application or the system will throw an exception. - -1. Create your client cache: - 1. In your `cache.xml`, use the `client-cache` DOCTYPE and configure your cache inside a `<client-cache>` element. Configure your server connection pool and your regions as needed. Example: - - ``` pre - <?xml version="1.0" encoding="UTF-8"?> - <client-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"> - <pool name="serverPool"> - <locator host="host1" port="44444"/> - </pool> - <region name="exampleRegion" refid="PROXY"/> - </client-cache> - ``` - - **Note:** - Applications that use a `client-cache` may want to set `concurrency-checks-enabled` to false for a region in order to see all events for that region. Geode server members can continue using concurrency checks, but they will pass all events to the client cache. This configuration ensures that the client sees all region events, but it does not prevent the client cache region from becoming out-of-sync with the server cache. See [Consistency for Region Updates](../../developing/distributed_regions/region_entry_versions.html#topic_CF2798D3E12647F182C2CEC4A46E2045). - - 2. If you use multiple server pools, configure the pool name explicitly for each client region. Example: - - ``` pre - <pool name="svrPool1"> - <locator host="host1" port="40404"/> - </pool> - <pool name="svrPool2"> - <locator host="host2" port="40404"/> - </pool> - <region name="clientR1" refid="PROXY" pool-name="svrPool1"/> - <region name="clientR2" refid="PROXY" pool-name="svrPool2"/> - <region name="clientsPrivateR" refid="LOCAL"/> - ``` - - 3. In your Java client application, create the cache using the `ClientCacheFactory` `create` method. Example: - - ``` pre - ClientCache clientCache = new ClientCacheFactory().create(); - ``` - - This creates the server connections and initializes the clientâs cache according to your `gemfire.properties` and `cache.xml` specifications. - -2. Close your cache when you are done using the `close` method of your `Cache` instance: - - ``` pre - cache.close(); - ``` - - If your client is durable and you want to maintain your durable queues while the client cache is closed, use: - - ``` pre - clientCache.close(true); - ``` - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/basic_config/the_cache/managing_a_multiuser_cache.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/the_cache/managing_a_multiuser_cache.html.md.erb b/geode-docs/basic_config/the_cache/managing_a_multiuser_cache.html.md.erb deleted file mode 100644 index 76dc590..0000000 --- a/geode-docs/basic_config/the_cache/managing_a_multiuser_cache.html.md.erb +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Managing RegionServices for Multiple Secure Users ---- - -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. - -<a id="managing_a_multiuser_cache__section_A2A0F835DF35450E8E4B5304F4BC07E2"></a> - -In a single client, multiple authenticated users can all access the same `ClientCache` through instances of the `RegionService` interface. Because there are multiple users with varying authorization levels, access to cached data is done entirely through the servers, where each userâs authorization can be managed. -Follow these steps in addition to the steps in [Managing a Cache in a Secure System](managing_a_secure_cache.html#managing_a_secure_cache). - -1. Create your cache and `RegionService` instances: - 1. Configure your clientâs server pool for multiple secure user authentication. Example: - - ``` pre - <pool name="serverPool" multiuser-authentication="true"> - <locator host="host1" port="44444"/> - </pool> - ``` - - This enables access through the pool for the `RegionService` instances and disables it for the `ClientCache` instance. - - 2. After you create your `ClientCache`, from your `ClientCache` instance, for each user call the `createAuthenticatedView` method, providing the userâs particular credentials. These are create method calls for two users: - - ``` pre - Properties properties = new Properties(); - properties.setProperty("security-username", cust1Name); - properties.setProperty("security-password", cust1Pwd); - RegionService regionService1 = - clientCache.createAuthenticatedView(properties); - - properties = new Properties(); - properties.setProperty("security-username", cust2Name); - properties.setProperty("security-password", cust2Pwd); - RegionService regionService2 = - clientCache.createAuthenticatedView(properties); - ``` - - For each user, do all of your caching and region work through the assigned `RegionService` instance. Access to the server cache will be governed by the serverâs configured authorization rules for each individual user. -2. Close your cache by closing the `ClientCache` instance only. Do not close the `RegionService` instances first. This is especially important for durable clients. - -## <a id="managing_a_multiuser_cache__section_692D9961E8224739903E483BF8AB4F84" class="no-quick-link"></a>Requirements and Caveats for RegionService - -Once each region is created, you can perform operations on it through the `ClientCache` instance or the `RegionService` instances, but not both. - -**Note:** -You can use the `ClientCache` to create a region that uses a pool configured for multi-user authentication, then access and do work on the region using your `RegionService` instances. - -To use `RegionService`, regions must be configured as `EMPTY`. Depending on your data access requirements, this configuration might affect performance, because the client goes to the server for every get. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/basic_config/the_cache/managing_a_peer_server_cache.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/the_cache/managing_a_peer_server_cache.html.md.erb b/geode-docs/basic_config/the_cache/managing_a_peer_server_cache.html.md.erb deleted file mode 100644 index 89ad024..0000000 --- a/geode-docs/basic_config/the_cache/managing_a_peer_server_cache.html.md.erb +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Managing a Peer or Server Cache ---- - -You start your peer or server cache using a combination of XML declarations and API calls. Close the cache when you are done. - -<a id="creating_and_closing_a_peer_cache__section_1633A80F0DB04794BB6C3A7F05EED97E"></a> -Geode peers are members of a Geode distributed system that do not act as clients to another Geode distributed system. Geode servers are peers that also listen for and process client requests. - -1. Create your cache: - 1. Start up a cluster and the cluster configuration service: - 1. Start a locator with `--enable-cluster-configuration` set to true. (It is set true by default.) - - ``` pre - gfsh>start locator --name=locator1 - ``` - - 2. Start up member processes that use the cluster configuration service (enabled by default): - - ``` pre - gfsh>start server --name=server1 --server-port=40404 - ``` - - 3. Create regions: - - ``` pre - gfsh>create region --name=customerRegion --type=REPLICATE - - gfsh>create region --name=ordersRegion --type=PARTITION - ``` - - 2. Or if you are not using the cluster configuration service, directly configure cache.xml in each member of your cluster. In your `cache.xml`, use the `cache` DOCTYPE and configure your cache inside a `<cache>` element. Example: - - ``` pre - <?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â> - // NOTE: Use this <cache-server> element only for server processes - <cache-server port="40404"/> - <region name="customerRegion" refid="REPLICATE" /> - <region name="ordersRegion" refid="PARTITION" /> - </cache> - ``` - - 3. To programmatically create the `Cache` instance: - - In your Java application, use the `CacheFactory` create method: - - ``` pre - Cache cache = new CacheFactory().create(); - ``` - - If you are running a server using the Geode `cacheserver` process, it automatically creates the cache and connection at startup and closes both when it exits. - - The system creates the distributed system connection and initializes the cache according to your `gemfire.properties` and `cache.xml` specifications. - -2. Close your cache when you are done using the inherited `close` method of the `Cache` instance: - - ``` pre - cache.close(); - ``` - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/basic_config/the_cache/managing_a_secure_cache.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/the_cache/managing_a_secure_cache.html.md.erb b/geode-docs/basic_config/the_cache/managing_a_secure_cache.html.md.erb deleted file mode 100644 index 6bd109c..0000000 --- a/geode-docs/basic_config/the_cache/managing_a_secure_cache.html.md.erb +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Managing a Cache in a Secure System ---- - -To create a cache in a secured system, -authentication at connection time will require credentials. -Authorization permits operations as configured. - -<a id="managing_a_secure_cache__section_11BF0F3F64504B74B39CD4C1CF58E6FC"></a> -These steps demonstrate a programmatic cache creation. - -1. To create the cache: - 1. Add necessary security properties to the `gemfire.properties` or `gfsecurity.properties` file, to configure for your particular security implementation. Examples: - - ``` pre - security-client-auth-init=mySecurity.UserPasswordAuthInit.create - ``` - - ``` pre - security-peer-auth-init=myAuthPkg.myAuthInitImpl.create - ``` - - 2. When you create your cache, pass any properties required by your security implementation to the cache factory create call by using one of these methods: - - `ClientCacheFactory` or `CacheFactory` `set` methods. Example: - - ``` pre - ClientCache clientCache = new ClientCacheFactory() - .set("security-username", username) - .set("security-password", password) - .create(); - ``` - - Properties object passed to the `ClientCacheFactory` or `CacheFactory` `create` method. These are usually properties of a sensitive nature that you do not want to put inside the `gfsecurity.properties` file. Example: - - ``` pre - Properties properties = new Properties(); - properties.setProperty("security-username", username); - properties.setProperty("security-password", password); - Cache cache = new CacheFactory(properties).create(); - ``` - - **Note:** - Properties passed to a cache creation method override any settings in either the `gemfire.properties` file or `gfsecuirty.properties`. - -2. Close your cache when you are done, using the `close` method of the `ClientCache` instance or the inherited `close` method of the `Cache` instance. Example: - - ``` pre - cache.close(); - ``` - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/basic_config/the_cache/setting_cache_initializer.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/the_cache/setting_cache_initializer.html.md.erb b/geode-docs/basic_config/the_cache/setting_cache_initializer.html.md.erb deleted file mode 100644 index 20cc2c6..0000000 --- a/geode-docs/basic_config/the_cache/setting_cache_initializer.html.md.erb +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Launching an Application after Initializing the Cache ---- - -You can specify a callback application that is launched after the cache initialization. - -By specifying an `<initializer>` element in your cache.xml file, you can trigger a callback application, which is run after the cache has been initialized. Applications that use the cacheserver script to start up a server can also use this feature to hook into a callback application. To use this feature, you need to specify the callback class within the `<initializer>` element. This element should be added to the end of your `cache.xml` file. - -You can specify the `<initializer>` element for either server caches or client caches. - -The callback class must implement the `Declarable` interface. When the callback class is loaded, its `init` method is called, and any parameters defined in the `<initializer>` element are passed as properties. - -The following is an example specification. - -In cache.xml: - -``` pre -<initializer> - <class-name>MyInitializer</class-name> - <parameter name="members"> - <string>2</string> - </parameter> -</initializer> -``` - -Here's the corresponding class definition: - -``` pre - -import org.apache.geode.cache.Declarable; - -public class MyInitializer implements Declarable { - public void init(Properties properties) { - System.out.println(properties.getProperty("members")); - } -} -``` - -The following are some additional real-world usage scenarios: - -1. Start a SystemMembershipListener - - ``` pre - <initializer> - <class-name>TestSystemMembershipListener</class-name> - </initializer> - ``` - -2. Write a custom tool that monitors cache resources - - ``` pre - <initializer> - <class-name>ResourceMonitorCacheXmlLoader</class-name> - </initializer> - ``` - -Any singleton or timer task or thread can be instantiated and started using the initializer element. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/basic_config/the_cache/setting_cache_properties.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/basic_config/the_cache/setting_cache_properties.html.md.erb b/geode-docs/basic_config/the_cache/setting_cache_properties.html.md.erb deleted file mode 100644 index 76d5066..0000000 --- a/geode-docs/basic_config/the_cache/setting_cache_properties.html.md.erb +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Options for Configuring the Cache and Data Regions ---- - -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. - -<a id="setting_cache_properties__section_FB536C90C219432D93E872CBD49D66B1"></a> -Cache configuration properties define: - -- Cache-wide settings such as disk stores, communication timeouts, and settings designating the member as a server -- Cache data regions - -Configure the cache and its data regions through one or more of these methods: - -- Through a persistent configuration that you define when issuing commands that use the gfsh command line utility. `gfsh` supports the administration, debugging, and deployment of Apache Geode processes and applications. You can use gfsh to configure regions, locators, servers, disk stores, event queues, and other objects. - - As you issue commands, gfsh saves a set of configurations that apply to the entire cluster and also saves configurations that only apply to defined groups of members within the cluster. You can re-use these configurations to create a distributed system. See [Overview of the Cluster Configuration Service](../../configuring/cluster_config/gfsh_persist.html). - -- Through declarations in the XML file named in the `cache-xml-file` `gemfire.properties` setting. This file is generally referred to as the `cache.xml` file, but it can have any name. See [cache.xml](../../reference/topics/chapter_overview_cache_xml.html#cache_xml). -- Through application calls to the `org.apache.geode.cache.CacheFactory`, `org.apache.geode.cache.Cache` and `org.apache.geode.cache.Region` APIs. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/configuring/chapter_overview.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/configuring/chapter_overview.html.md.erb b/geode-docs/configuring/chapter_overview.html.md.erb deleted file mode 100644 index 8026e72..0000000 --- a/geode-docs/configuring/chapter_overview.html.md.erb +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Configuring and Running a Cluster ---- - -You use the `gfsh` command-line utility to configure your Apache Geode cluster (also called a "distributed system"). The cluster configuration service persists the cluster configurations and distributes the configurations to members of the cluster. There are also several additional ways to configure a cluster. - -You use `gfsh` to configure regions, disk stores, members, and other Geode objects. You also use `gfsh` to start and stop locators, servers, and Geode monitoring tools. As you execute these commands, the cluster configuration service persists the configuration. When new members join the cluster, the service distributes the configuration to the new members. - -`gfsh` is the recommended means of configuring and managing your Apache Geode cluster, however you can still configure many aspects of a cluster using the older methods of the cache.xml and gemfire.properties files. See [cache.xml](../reference/topics/chapter_overview_cache_xml.html#cache_xml) and the [Reference](../reference/book_intro.html#reference) for configuration parameters. You can also configure some aspects of a cluster using a Java API. See [Managing Apache Geode](../managing/book_intro.html#managing_gemfire_intro). - -- **[Overview of the Cluster Configuration Service](../configuring/cluster_config/gfsh_persist.html)** - - The Apache Geode cluster configuration service persists cluster configurations created by `gfsh` commands to the locators in a cluster and distributes the configurations to members of the cluster. - -- **[TutorialâCreating and Using a Cluster Configuration](../configuring/cluster_config/persisting_configurations.html)** - - A short walk-through that uses a single computer to demonstrate how to use `gfsh` to create a cluster configuration for a Geode cluster. - -- **[Deploying Application JARs to Apache Geode Members](../configuring/cluster_config/deploying_application_jars.html)** - - You can dynamically deploy your application JAR files to specific members or to all members in your distributed system. Geode automatically keeps track of JAR file versions; autoloads the deployed JAR files to the CLASSPATH; and auto-registers any functions that the JAR contains. - -- **[Using Member Groups](../configuring/cluster_config/using_member_groups.html)** - - Apache Geode allows you to organize your distributed system members into logical member groups. - -- **[Exporting and Importing Cluster Configurations](../configuring/cluster_config/export-import.html)** - - The cluster configuration service exports and imports configurations created using `gfsh` for an entire Apache Geode cluster. - -- **[Cluster Configuration Files and Troubleshooting](../configuring/cluster_config/gfsh_config_troubleshooting.html)** - - When you use the cluster configuration service in Geode, you can examine the generated configuration files in the `cluster_config` directory on the locator. `gfsh` saves configuration files at the cluster-level and at the individual group-level. - -- **[Loading Existing Configuration Files into Cluster Configuration](../configuring/cluster_config/gfsh_load_from_shared_dir.html)** - - To load an existing cache.xml or gemfire.properties configuration file into a new cluster, use the `--load-cluster-configuration-from-dir` parameter when starting up the locator. - -- **[Using gfsh to Manage a Remote Cluster Over HTTP or HTTPS](../configuring/cluster_config/gfsh_remote.html)** - - You can connect `gfsh` via HTTP or HTTPS to a remote cluster and manage the cluster using `gfsh` commands. - -- **[Deploying Configuration Files without the Cluster Configuration Service](../configuring/running/deploying_config_files.html)** - - You can deploy your Apache Geode configuration files in your system directory structure or in jar files. You determine how you want to deploy your configuration files and set them up accordingly. - -- **[Starting Up and Shutting Down Your System](../configuring/running/starting_up_shutting_down.html)** - - Determine the proper startup and shutdown procedures, and write your startup and shutdown scripts. - -- **[Running Geode Locator Processes](../configuring/running/running_the_locator.html)** - - The locator is a Geode process that tells new, connecting members where running members are located and provides load balancing for server use. - -- **[Running Geode Server Processes](../configuring/running/running_the_cacheserver.html)** - - A Geode server is a process that runs as a long-lived, configurable member of a client/server system. - -- **[Managing System Output Files](../configuring/running/managing_output_files.html)** - - Geode output files are optional and can become quite large. Work with your system administrator to determine where to place them to avoid interfering with other system activities. - -- **[Firewall Considerations](../configuring/running/firewall_ports_config.html)** - - You can configure and limit port usage for situations that involve firewalls, for example, between client-server or server-server connections. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/configuring/cluster_config/deploying_application_jars.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/configuring/cluster_config/deploying_application_jars.html.md.erb b/geode-docs/configuring/cluster_config/deploying_application_jars.html.md.erb deleted file mode 100644 index 08eb1d5..0000000 --- a/geode-docs/configuring/cluster_config/deploying_application_jars.html.md.erb +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Deploying Application JARs to Apache Geode Members ---- - -You can dynamically deploy your application JAR files to specific members or to all members in your distributed system. Geode automatically keeps track of JAR file versions; autoloads the deployed JAR files to the CLASSPATH; and auto-registers any functions that the JAR contains. - -To deploy and undeploy application JAR files in Apache Geode, use the `gfsh` `deploy` or `undeploy` command. You can deploy a single JAR or multiple JARs (by either specifying the JAR filenames or by specifying a directory that contains the JAR files), and you can also target the deployment to a member group or multiple member group. For example, after connecting to the distributed system where you want to deploy the JARs, you could type at the `gfsh` prompt: - -``` pre -gfsh> deploy --jar=group1_functions.jar -``` - -This command deploys the `group1_functions.jar` file to all members in the distributed system. - -To deploy the JAR file to a subset of members, use the `--group` argument. For example: - -``` pre -gfsh> deploy --jar=group1_functions.jar --group=MemberGroup1 -``` - -In the example it is assumed that you have already defined the member group that you want to use when starting up your members. See [Configuring and Running a Cluster](../chapter_overview.html#concept_lrh_gyq_s4) for more information on how to define member groups and add a member to a group. - -To deploy all the JAR files that are located in a specific directory to all members: - -``` pre -gfsh> deploy --dir=libs/group1-libs -``` - -You can either provide a JAR file name or a directory of JARs for deployment, but you cannot specify both at once. - -To undeploy all previously deployed JAR files throughout the distributed system: - -``` pre -gfsh> undeploy -``` - -To undeploy a specific JAR file: - -``` pre -gfsh> undeploy --jar=group1_functions.jar -``` - -To target a specific member group when undeploying all JAR files: - -``` pre -gfsh> undeploy --group=MemberGroup1 -``` - -Only JAR files that have been previously deployed on members in the MemberGroup1 group will be undeployed. - -To see a list of all deployed JARs in your distributed system: - -``` pre -gfsh> list deployed -``` - -To see a list of all deployed JARs in a specific member group: - -``` pre -gfsh> list deployed --group=MemberGroup1 -``` - -Sample output: - -``` pre - - Member | Deployed JAR | JAR Location ---------- | -------------------- | --------------------------------------------------- -datanode1 | group1_functions.jar | /usr/local/gemfire/deploy/vf.gf#group1_functions.jar#1 -datanode2 | group1_functions.jar | /usr/local/gemfire/deploy/vf.gf#group1_functions.jar#1 -``` - -For more information on `gfsh` usage, see [gfsh (Geode SHell)](../../tools_modules/gfsh/chapter_overview.html). - -## <a id="concept_4436C021FB934EC4A330D27BD026602C__section_D36E345C6E254D27B0F4B0C8711F5E6A" class="no-quick-link"></a>Deployment Location for JAR Files - -The system location where JAR files are written on each member is determined by the `deploy-working-dir` Geode property configured for that member. For example, you could have the following configured in the `gemfire.properties` file for your member: - -``` pre -#gemfire.properties -deploy-working-dir=/usr/local/gemfire/deploy -``` - -This deployment location can be local or a shared network resource (such as a mount location) used by multiple members in order to reduce disk space usage. If you use a shared directory, you still need to deploy the JAR file on every member that you want to have access to the application, because deployment updates the CLASSPATH and auto-registers functions. - -## About Deploying JAR Files and the Cluster Configuration Service - -By default, the cluster configuration service distributes deployed JAR files to all locators in the distributed system. When you start a new server using `gfsh`, the locator supplies configuration files and deployed jar files to the member and writes them to the server's directory. - -See [Overview of the Cluster Configuration Service](gfsh_persist.html). - -## <a id="concept_4436C021FB934EC4A330D27BD026602C__section_D9219C5EEED64672930200677C2118C9" class="no-quick-link"></a>Versioning of JAR Files - -When you deploy JAR files to a distributed system or member group, the JAR file is modified to indicate version information in its name. Each JAR filename is prefixed with `vf.gf#` and contains a version number at the end of the filename. For example, if you deploy `MyClasses.jar` five times, the filename is displayed as `vf.gf#MyClasses.jar#5` when you list all deployed jars. - -When you deploy a new JAR file, the member receiving the deployment checks whether the JAR file is a duplicate, either because the JAR file has already been deployed on that member or because the JAR file has already been deployed to a shared deployment working directory that other members are also using. If another member has already deployed this JAR file to the shared directory (determined by doing a byte-for-byte compare to the latest version in its directory), the member receiving the latest deployment does not write the file to disk. Instead, the member updates the ClassPathLoader to use the already deployed JAR file. If a newer version of the JAR file is detected on disk and is already in use, the deployment is canceled. - -When a member begins using a JAR file, the member obtains a shared lock on the file. If the member receives a newer version by deployment, the member releases the shared lock and tries to delete the existing JAR file in favor of the newer version. If no other member has a shared lock on the existing JAR, the existing, older version JAR is deleted. - -## <a id="concept_4436C021FB934EC4A330D27BD026602C__section_F8AC59EEC8C5434FBC6F38A12A7371CE" class="no-quick-link"></a>Automatic Class Path Loading - -When a cache is started, the new cache requests that the latest versions of each JAR file in the current working directory be added to the ClassPathLoader. If a JAR file has already been deployed to the ClassPathLoader, the ClassPathLoader updates its loaded version if a newer version is found; otherwise, there is no change. If detected, older versions of the JAR files are deleted if no other member has a shared lock on them. - -Undeploying a JAR file does not automatically unload the classes that were loaded during deployment. You need to restart your members to unload those classes. - -When a cache is closed it requests that all currently deployed JAR files be removed from the ClassPathLoader. - -If you are using a shared deployment working directory, all members sharing the directory should belong to the same member group. Upon restart, all members that share the same deployment working directory will deploy and autoload their CLASSPATH with any JARs found in the current working directory. This means that some members may load the JARs even though they are not part of the member group that received the original deployment. - -## <a id="concept_4436C021FB934EC4A330D27BD026602C__section_C1ECA5A66C27403A9A18D0E04EFCC66D" class="no-quick-link"></a>Automatic Function Registration - -When you deploy a JAR file that contains a function (in other words, contains a class that implements the Function interface), the function is automatically registered through the `FunctionService.registerFunction` method. If another JAR file is deployed (either with the same JAR filename or another filename) with the same function, the new implementation of the function is registered, overwriting the old one. If a JAR file is undeployed, any functions that were auto-registered at the time of deployment are unregistered. Because deploying a JAR file that has the same name multiple times results in the JAR being un-deployed and re-deployed, functions in the JAR are unregistered and re-registered each time this occurs. If a function with the same ID is registered from multiple differently named JAR files, the function is unregistered if any of those JAR files are re-deployed or un-deployed. - -During `cache.xml` load, the parameters for any declarables are saved. If functions found in a JAR file are also declarable, and have the same class name as the declarables whose parameters were saved after loading cache.xml, then function instances are created using those Parameters and are also registered. Therefore, if the same function is declared multiple times in the `cache.xml` with different sets of parameters, when the JAR is deployed a function is instantiated for each set of parameters. If any functions are registered using parameters from a `cache.xml` load, the default, no-argument function is not registered. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/ff80a931/geode-docs/configuring/cluster_config/export-import.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/configuring/cluster_config/export-import.html.md.erb b/geode-docs/configuring/cluster_config/export-import.html.md.erb deleted file mode 100644 index e730c5b..0000000 --- a/geode-docs/configuring/cluster_config/export-import.html.md.erb +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Exporting and Importing Cluster Configurations ---- - -The cluster configuration service exports and imports configurations created using `gfsh` for an entire Apache Geode cluster. - -The cluster configuration service saves the cluster configuration as you create a regions, disk-stores and other objects using `gfsh` commands. You can export this configuration as well as any jar files that contain application files to a zip file and then import this configuration to create a new cluster. - -## Exporting a Cluster Configuration - -You issue the `gfsh` `export cluster-configuration` command to save the configuration data for you cluster in a zip file. This zip file contains subdirectories for cluster-level configurations and a directory for each group specified in the cluster. The contents of these directories are described in [Cluster Configuration Files and Troubleshooting](gfsh_config_troubleshooting.html#concept_ylt_2cb_y4). - -To export a cluster configuration, run the `gfsh` `export cluster-configuration` command while connected to a Geode cluster. For example: - -``` pre -export cluster-configuration --zip-file-name=myClusterConfig.zip --dir=/home/username/configs -``` - -See [export cluster-configuration](../../tools_modules/gfsh/command-pages/export.html#topic_mdv_jgz_ck). - -**Note:** -`gfsh` only saves cluster configuration values for configurations specified using `gfsh`. Configurations created by the management API are not saved with the cluster configurations. - -## Importing a Cluster Configuration - -You can import a cluster configuration to a running locator. After importing the configuration, any servers you start receive this cluster configuration. - -To import a cluster configuration, start one or more locators and then run the `gfsh` `import cluster-configuration` command. For example: - -``` pre -import cluster-configuration --zip-file-name=/home/username/configs/myClusterConfig.zip -``` - -See [import cluster-configuration](../../tools_modules/gfsh/command-pages/import.html#topic_vnv_grz_ck). - -**Note:** -You cannot import a cluster configuration to a cluster where cache servers are already running. - -
