From 0cd2a6c1c4678e8e197f6f6532b403bef36d1818 Mon Sep 17 00:00:00 2001 From: Jay Bryant Date: Thu, 25 Jun 2020 14:42:25 -0500 Subject: [PATCH] Wording changes Removed the language of oppression and violence and replaced it with more neutral language. Note that problematic words in the code have to remain in the docs until the code changes. --- .../asciidoc/introduction/new-features.adoc | 2 +- .../reference/bootstrap-annotations.adoc | 27 +++------ src/main/asciidoc/reference/data-access.adoc | 3 +- src/main/asciidoc/reference/data.adoc | 6 +- .../reference/function-annotations.adoc | 60 +++++++++---------- src/main/asciidoc/reference/function.adoc | 6 +- src/main/asciidoc/reference/indexing.adoc | 2 +- src/main/asciidoc/reference/lucene.adoc | 2 +- src/main/asciidoc/reference/repositories.adoc | 10 ++-- src/main/asciidoc/reference/samples.adoc | 2 +- 10 files changed, 55 insertions(+), 65 deletions(-) diff --git a/src/main/asciidoc/introduction/new-features.adoc b/src/main/asciidoc/introduction/new-features.adoc index 3e6fdec90..103640ff3 100644 --- a/src/main/asciidoc/introduction/new-features.adoc +++ b/src/main/asciidoc/introduction/new-features.adoc @@ -86,7 +86,7 @@ and <> * Removed all default values specified in {sdg-name} XML namespace Region-type elements to rely on {data-store-name} defaults instead. * Added convenience to automatically create `DiskStore` directory locations. -* SDG annotated Function implementations can now be executed from `Gfsh`. +* SDG annotated Function implementations can now be run from `Gfsh`. * Enabled {data-store-name} `GatewayReceivers` to be started manually. * Added support for Auto Region Lookups. See <> * Added support for Region Templates. See <> diff --git a/src/main/asciidoc/reference/bootstrap-annotations.adoc b/src/main/asciidoc/reference/bootstrap-annotations.adoc index 0479a830a..1c8f7e652 100644 --- a/src/main/asciidoc/reference/bootstrap-annotations.adoc +++ b/src/main/asciidoc/reference/bootstrap-annotations.adoc @@ -812,8 +812,10 @@ or associated properties, as follows: ---- @SpringBootApplication @ClientCacheApplication -@EnableLogging(logLevel="info", logFile="/absolute/file/system/path/to/application.log) -public class ClientApplication { .. } +@EnableLogging(logLevel="info", logFile="/absolute/file/system/path/to/application.log") +public class ClientApplication { + .. +} ---- While the `logLevel` attribute can be specified with all the cache-based application annotations @@ -1657,18 +1659,7 @@ and used instead of configuration properties to customize a `DiskStore` at runti @EnableDiskStore(name = "OrdersDiskStore", autoCompact = true, compactionThreshold = 70, maxOplogSize = 512, diskDirectories = @DiskDiretory(location = "/absolute/path/to/order/disk/files")) class ServerApplication { - - @Bean - DiskStoreConfigurer ordersDiskStoreDiretoryConfigurer( - @Value("${orders.disk.store.location}") String location) { - - return (beanName, diskStoreFactoryBean) -> { - - if ("OrdersDiskStore".equals(beanName) { - diskStoreFactoryBean.setDiskDirs(Collections.singletonList(new DiskDir(location)); - } - } - } + . . . } ---- @@ -1684,11 +1675,11 @@ More details on {data-store-name} Region persistence and overflow (using DiskSto There is not much use in storing data in Regions unless the data can be accessed. In addition to `Region.get(key)` operations, particularly when the key is known in advance, data is commonly retrieved -by executing queries on the Regions that contain the data. With {data-store-name}, queries are written by using +by running queries on the Regions that contain the data. With {data-store-name}, queries are written by using the Object Query Language (OQL), and the specific data set that a client wishes to access is expressed in the query's predicate (for example, `SELECT * FROM /Books b WHERE b.author.name = 'Jon Doe'`). -Generally, querying without indexes is inefficient. When executing queries without an index, {data-store-name} +Generally, querying without indexes is inefficient. When running queries without an index, {data-store-name} performs the equivalent of a full table scan. Indexes are created and maintained for fields on objects used in query predicates to match the data of interest, as @@ -1829,7 +1820,7 @@ Lucene queries by using the familiar Spring template design pattern. Finally, we close this section with a few extra tips to keep in mind when using indexes: -* While OQL indexes are not required to execute OQL Queries, Lucene Indexes are required to execute Lucene +* While OQL indexes are not required to run OQL Queries, Lucene Indexes are required to run Lucene text-based searches. * OQL indexes are not persisted to disk. They are only maintained in memory. So, when an {data-store-name} node is restarted, the index must be rebuilt. @@ -1899,7 +1890,7 @@ class PublisherPrintApplication { @ContinuousQuery(name = "DemandExceedsSupply", query = "SELECT book.* FROM /Books book, /Inventory inventory - WHERE book.title = 'How to crush it in the Book business like Amazon" + WHERE book.title = 'How to crush it in the Book business like Amazon' AND inventory.isbn = book.isbn AND inventory.available < ( SELECT sum(order.lineItems.quantity) diff --git a/src/main/asciidoc/reference/data-access.adoc b/src/main/asciidoc/reference/data-access.adoc index 5e9ac5e55..782dbbf5f 100644 --- a/src/main/asciidoc/reference/data-access.adoc +++ b/src/main/asciidoc/reference/data-access.adoc @@ -3,8 +3,7 @@ In addition to the core XML namespace (`gfe`), {sdg-name} provides a data access XML namespace (`gfe-data`), which is primarily intended to simplify the development of {data-store-name} client applications. This namespace -currently contains support for {data-store-name} <> and Function -<>, as well as a `` tag that offers a convenient way to connect to +currently contains support for {data-store-name} <> and <>, as well as a `` tag that offers a convenient way to connect to a {data-store-name} cluster. [[data-access:datasource]] diff --git a/src/main/asciidoc/reference/data.adoc b/src/main/asciidoc/reference/data.adoc index cd2d0759b..d639d9ccf 100644 --- a/src/main/asciidoc/reference/data.adoc +++ b/src/main/asciidoc/reference/data.adoc @@ -10,7 +10,7 @@ This chapter also covers support for dependency injection of {data-store-name} m As with many other high-level abstractions provided by Spring, {sdg-name} provides a *template* to simplify {data-store-name} data access operations. The class provides several methods containing common Region operations, -but also provides the capability to *execute* code against native {data-store-name} APIs without having to deal with +but also provides the capability to *run* code against native {data-store-name} APIs without having to deal with {data-store-name} checked exceptions by using a `GemfireCallback`. The template class requires a {data-store-name} `Region`, and once configured, is thread-safe and is reusable @@ -42,7 +42,7 @@ template.execute(new GemfireCallback>() { ---- For accessing the full power of the {data-store-name} query language, a developer can use the `find` and `findUnique` -methods, which, compared to the `query` method, can execute queries across multiple Regions, execute projections, +methods, which, compared to the `query` method, can run queries across multiple Regions, run projections, and the like. The `find` method should be used when the query selects multiple items (through `SelectResults`) and the latter, @@ -80,7 +80,7 @@ transparently across multiple APIs and can be configured either programmatically (the most popular choice). For {data-store-name}, {sdg-name} provides a dedicated, per-cache, `PlatformTransactionManager` that, once declared, -allows Region operations to be executed atomically through Spring: +allows Region operations to be run atomically through Spring: .Enable Transaction Management using XML [source,xml] diff --git a/src/main/asciidoc/reference/function-annotations.adoc b/src/main/asciidoc/reference/function-annotations.adoc index d9a703b5b..be44093a2 100644 --- a/src/main/asciidoc/reference/function-annotations.adoc +++ b/src/main/asciidoc/reference/function-annotations.adoc @@ -1,27 +1,27 @@ [[function-annotations]] -= Annotation Support for Function Execution += Annotation Support for Functions {sdg-name} includes annotation support to simplify working with {data-store-name} -{x-data-store-docs}/developing/function_exec/chapter_overview.html[Function execution]. +{x-data-store-docs}/developing/function_exec/chapter_overview.html[running Functions]. Under the hood, the {data-store-name} API provides classes to implement and register {data-store-name} {x-data-store-javadoc}/org/apache/geode/cache/execute/Function.html[Functions] that are deployed on {data-store-name} servers, which may then be invoked by other peer member applications or remotely from cache clients. -Functions can execute in parallel, distributed among multiple {data-store-name} servers in the cluster, aggregating the +Functions can run in parallel, distributed among multiple {data-store-name} servers in the cluster, aggregating the results using the map-reduce pattern and sent back to the caller. Functions can also be targeted to run on a single -server or Region. The {data-store-name} API supports remote execution of Functions targeted by using various predefined -scopes: on Region, on members (in groups), on servers, and others. The implementation and execution of remote Functions, +server or Region. The {data-store-name} API supports remotely running Functions targeted by using various predefined +scopes: on Region, on members (in groups), on servers, and others. The implementation and running of remote Functions, as with any RPC protocol, requires some boilerplate code. -{sdg-name}, true to Spring's core value proposition, aims to hide the mechanics of remote Function execution and let you +{sdg-name}, true to Spring's core value proposition, aims to hide the mechanics of remotely running Functions and to let you focus on core POJO programming and business logic. To this end, {sdg-name} introduces annotations to declaratively register the public methods of a POJO class as {data-store-name} Functions along with the ability to invoke registered Functions (including remotely) by using annotated interfaces. -== Implementation Versus Execution +== Implementation Versus Running -There are two separate concerns to address: implementation and execution. +There are two separate concerns to address: implementation and running. The first is Function implementation (server-side), which must interact with the {x-data-store-javadoc}/org/apache/geode/cache/execute/FunctionContext.html[`FunctionContext`] @@ -40,7 +40,7 @@ Region, server, servers, member, or members. If the Function produces a result, to aggregate and acquire the execution results. In certain cases, a custom `ResultCollector` implementation is required and may be registered with the `Execution`. -NOTE: 'Client' and 'Server' are used here in the context of Function execution, which may have a different meaning +NOTE: 'Client' and 'Server' are used here in the context of running Functions, which may have a different meaning than client and server in {data-store-name}'s client-server topology. While it is common for an application using a `ClientCache` instance to invoke a Function on one or more {data-store-name} servers in a cluster, it is also possible to execute Functions in a peer-to-peer (P2P) configuration, where the application is a member of the cluster @@ -52,14 +52,14 @@ of being a peer member of the cluster. Using {data-store-name} APIs, the `FunctionContext` provides a runtime invocation context that includes the client's calling arguments and a `ResultSender` implementation to send results back to the client. Additionally, if the Function -is executed on a Region, the `FunctionContext` is actually an instance of `RegionFunctionContext`, which provides +is run on a Region, the `FunctionContext` is actually an instance of `RegionFunctionContext`, which provides additional information, such as the target Region on which the Function was invoked, any filter (a set of specific keys) associated with the `Execution`, and so on. If the Region is a `PARTITION` Region, the Function should use the `PartitionRegionHelper` to extract the local data set. By using Spring, you can write a simple POJO and use the Spring container to bind one or more of your POJO's public methods to a Function. The signature for a POJO method intended to be used as a Function must generally conform -to the client's execution arguments. However, in the case of a Region execution, the Region data may also be provided +to the client's run-time arguments. However, in the case of running on a Region, the Region data may also be provided (presumably the data is held in the local partition if the Region is a `PARTITION` Region). Additionally, the Function may require the filter that was applied, if any. This suggests that the client and server @@ -145,7 +145,7 @@ as shown in the `functionWithContext` method shown previously. Presumably, the i the `ResultSender` directly to send results to the caller. Finally, the `GemfireFunction` annotation supports the `requiredPermissions` attribute, which specifies the permissions -required to execute the Function. By default, all Functions require the `DATA:WRITE` permission. The attribute +required to run the Function. By default, all Functions require the `DATA:WRITE` permission. The attribute accepts an array of Strings allowing you to modify the permissions as required by your application and/or Function UC. Each resource permission is expected to be in the following format: `::[Target]:[Key]`. @@ -189,22 +189,22 @@ The following example activates annotation processing by annotating a Java confi class ApplicationConfiguration { ... } ---- -[[function-execution]] -== Executing a Function +[[using-a-function]] +== Using a Function -A process that invokes a remote Function needs to provide the Function's ID, calling arguments, the execution target +A process that invokes a remote Function needs to provide the Function's ID, calling arguments, the target (`onRegion`, `onServers`, `onServer`, `onMember`, or `onMembers`) and (optionally) a filter set. By using {sdg-name}, all you need do is define an interface supported by annotations. Spring creates a dynamic proxy for the interface, which uses the `FunctionService` to create an `Execution`, invoke the `Execution`, and (if necessary) coerce the results to the defined return type. This technique is similar to the way {sdg-name}'s Repository extension works. Thus, some of the configuration and concepts should be familiar. -Generally, a single interface definition maps to multiple Function executions, one corresponding to each method +Generally, a single interface definition maps to multiple Functions, one corresponding to each method defined in the interface. -=== Annotations for Function Execution +=== Annotations for Running Functions -To support client-side Function execution, the following {sdg-acronym} Function annotations are provided: `@OnRegion`, +To support running client-side Functions, the following {sdg-acronym} Function annotations are provided: `@OnRegion`, `@OnServer`, `@OnServers`, `@OnMember`, and `@OnMembers`. These annotations correspond to the `Execution` implementations provided by {data-store-name}'s {x-data-store-javadoc}/org/apache/geode/cache/execute/FunctionService.html[`FunctionService`] class. @@ -214,7 +214,7 @@ whose value is the name of a Spring bean implementing the {x-data-store-javadoc}/org/apache/geode/cache/execute/ResultCollector.html[`ResultCollector`] interface to use for the execution. -CAUTION: The proxy interface binds all declared methods to the same execution configuration. Although it is expected +CAUTION: The proxy interface binds all declared methods to the same configuration. Although it is expected that single method interfaces are common, all methods in the interface are backed by the same proxy instance and therefore all share the same configuration. @@ -238,8 +238,8 @@ to bind this invocation to a different Function ID. === Enabling Annotation Processing -The client-side uses Spring's classpath component scanning capability to discover annotated interfaces. To enable -Function execution annotation processing in XML, insert the following element in your XML configuration: +The client-side uses Spring's classpath component scanning capability to discover annotated interfaces. To +use Function annotation processing in XML, insert the following element in your XML configuration: [source,xml] ---- @@ -257,10 +257,10 @@ Optionally, you can annotate your Java configuration class as follows: @EnableGemfireFunctionExecutions(basePackages = "org.example.myapp.gemfire.functions") ---- -[[function-execution-programmatic]] -== Programmatic Function Execution +[[using-functions-programmatically]] +== Using Functions Programmatically -Using the Function execution annotated interface defined in the previous section, simply auto-wire your interface +Using the Function annotated interface defined in the previous section, you can auto-wire your interface into an application bean that will invoke the Function: [source,java] @@ -277,7 +277,7 @@ public class MyApplication { } ---- -Alternately, you can use a Function execution template directly. In the following example, +Alternately, you can use a Function template directly. In the following example, the `GemfireOnRegionFunctionTemplate` creates an `onRegion` Function `Execution`: .Using the `GemfireOnRegionFunctionTemplate` @@ -296,8 +296,8 @@ containing the result and attempts to coerce that value into the requested type. that returns the `List` as is. The first parameter is the Function ID. The filter argument is optional. The remaining arguments are a variable argument `List`. -[[function-execution-pdx]] -== Function Execution with PDX +[[using-functions-with-pdx]] +== Using Functions with PDX When using {sdg-name}'s Function annotation support combined with {data-store-name}'s {x-data-store-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX Serialization], @@ -320,9 +320,9 @@ public class OrderFunctions { NOTE: The `Integer` typed `count` parameter is arbitrary, as is the separation of the `Order` class and the `OrderSource` enum, which might be logical to combine. However, the arguments were setup this way -to demonstrate the problem with Function executions in the context of PDX. +to demonstrate the problem with running Functions in the context of PDX. -Your `Order` class and `OrderSource` enum might be defined as follows: +Your `Order` class and `OrderSource` enumeration might be defined as follows: [source,java] ---- @@ -345,7 +345,7 @@ public enum OrderSource { } ---- -Of course, you can define a Function `Execution` interface to call the 'process' {data-store-name} server Function, +You can define a Function `Execution` interface to call the 'process' {data-store-name} server Function, as follows: [source,java] diff --git a/src/main/asciidoc/reference/function.adoc b/src/main/asciidoc/reference/function.adoc index e812ea87d..f18e51835 100644 --- a/src/main/asciidoc/reference/function.adoc +++ b/src/main/asciidoc/reference/function.adoc @@ -1,15 +1,15 @@ [[bootstrap:function]] = Configuring the Function Service -{sdg-name} provides <> support for implementing, registering and executing +{sdg-name} provides <> support for implementing, registering and running {data-store-name} Functions. {sdg-name} also provides XML namespace support for registering {data-store-name} {x-data-store-javadoc}/org/apache/geode/cache/execute/Function.html[Functions] -for remote function execution. +for remote function processing. See {data-store-name}'s {x-data-store-docs}/developing/function_exec/chapter_overview.html[documentation] -for more information on the Function execution framework. +for more information on the Function processing framework. {data-store-name} Functions are declared as Spring beans and must implement the `org.apache.geode.cache.execute.Function` interface or extend `org.apache.geode.cache.execute.FunctionAdapter`. diff --git a/src/main/asciidoc/reference/indexing.adoc b/src/main/asciidoc/reference/indexing.adoc index fddd4288e..615a84038 100644 --- a/src/main/asciidoc/reference/indexing.adoc +++ b/src/main/asciidoc/reference/indexing.adoc @@ -183,7 +183,7 @@ have the same definition but different names. {sdg-name} can only accomplish this by using {data-store-name}'s API, by first removing the existing `Index` and then recreating the `Index` with the new name. It is possible that either the remove or subsequent create invocation -could fail. There is no way to execute both actions atomically and rollback this joint operation if either fails. +could fail. There is no way to perform both actions atomically and roll back this joint operation if either fails. However, if it succeeds, then you have the same problem as before with the `ignoreIfExists` option. Any existing OQL query statement using query hints that refer to the old `Index` by name must be changed. diff --git a/src/main/asciidoc/reference/lucene.adoc b/src/main/asciidoc/reference/lucene.adoc index 095a5fd7b..7a9a31034 100644 --- a/src/main/asciidoc/reference/lucene.adoc +++ b/src/main/asciidoc/reference/lucene.adoc @@ -296,7 +296,7 @@ Finally, {sdg-name} provides annotation configuration support for `LuceneIndexes Eventually, the {sdg-acronym} Lucene support will finds its way into the Repository infrastructure extension for {data-store-name} so that Lucene queries can be expressed as methods on an application `Repository` interface, -in much the same way as the <> works today. +in much the same way as the <> works today. However, in the meantime, if you want to conveniently express `LuceneIndexes`, you can do so directly on your application domain objects, as the following example shows: diff --git a/src/main/asciidoc/reference/repositories.adoc b/src/main/asciidoc/reference/repositories.adoc index bdbb297e8..30a65b940 100644 --- a/src/main/asciidoc/reference/repositories.adoc +++ b/src/main/asciidoc/reference/repositories.adoc @@ -2,7 +2,7 @@ = {sdg-name} Repositories {sdg-name} provides support for using the Spring Data Repository abstraction to easily persist entities into -{data-store-name} along with executing queries. A general introduction to the Repository programming model +{data-store-name} along with running queries. A general introduction to the Repository programming model is provided https://docs.spring.io/spring-data/data-commons/docs/current/reference/html/#repositories[here]. [[gemfire-repositories.spring-configuration-xml]] @@ -73,7 +73,7 @@ for more details. The `@EnableGemfireRepositories` annotation also lets you specify the location of named OQL queries, which reside in a Java `Properties` file, by using the `namedQueriesLocation` attribute. The property name must match the name -of a Repository query method and the property value is the OQL query you want executed when the Repository query method +of a Repository query method and the property value is the OQL query you want to run when the Repository query method is called. The `repositoryImplementationPostfix` attribute can be set to an alternate value (defaults to `Impl`) if your @@ -92,10 +92,10 @@ Many other aspects of the {sdg-acronym}'s Repository infrastructure extension ma https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/repository/config/EnableGemfireRepositories.html[`@EnableGemfireRepositories`] Javadoc for more details on all configuration settings. -[[gemfire-repositories.queries.executing]] -== Executing OQL Queries +[[gemfire-repositories.queries.running]] +== Running OQL Queries -{sdg-name} Repositories enable the definition of query methods to easily execute {data-store-name} OQL queries +{sdg-name} Repositories enable the definition of query methods to easily run {data-store-name} OQL queries against the Region the managed entity maps to, as the following example shows: .Sample Repository diff --git a/src/main/asciidoc/reference/samples.adoc b/src/main/asciidoc/reference/samples.adoc index cf70fa779..55fde5643 100644 --- a/src/main/asciidoc/reference/samples.adoc +++ b/src/main/asciidoc/reference/samples.adoc @@ -16,7 +16,7 @@ Maven-aware IDE (such as the https://spring.io/tools/sts[Spring Tool Suite]) or == Hello World The "`Hello World`" sample application demonstrates the core functionality of the {sdg-name} project. -It bootstraps {data-store-name}, configures it, executes arbitrary commands against the cache, and shuts it down +It bootstraps {data-store-name}, configures it, runs arbitrary commands against the cache, and shuts it down when the application exits. Multiple instances of the application can be started at the same time and work together, sharing data without any user intervention.