Skip to content
Permalink
Browse files
GEODE-10313: User Guide: Add javadocs template variable (#7696)
  • Loading branch information
davebarnes97 committed May 17, 2022
1 parent e186005 commit cbd8795bc30dd595b6956b957301167f2f0ac5d5
Showing 12 changed files with 18 additions and 17 deletions.
@@ -45,5 +45,6 @@ template_variables:
book_title_short: Geode Docs
local_header_title: Apache Geode
local_header_img: /images/Apache_Geode_logo_symbol.png
javadocs: /releases/latest/javadoc

broken_link_exclusions: iefix|using_custom_classes|arrowhead|cppdocs|DotNetDocs
@@ -44,7 +44,7 @@ You can customize the specific behaviors in `ReflectionBasedAutoSerializer` by o
These methods are only called the first time the `ReflectionBasedAutoSerializer` sees a new class. The results will be remembered and used the next time the same class is seen.
For details on these methods and their default behaviors, see the JavaDocs on [ReflectionBasedAutoSerializer](/releases/latest/javadoc/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html) for details.
For details on these methods and their default behaviors, see the JavaDocs on [ReflectionBasedAutoSerializer](<%=vars.javadocs%>/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html) for details.

## <a id="concept_9E020566EE794A81A48A90BA798EC279__section_7C4CC39FD82A48A9B5F8376522078192" class="no-quick-link"></a>Example of Optimizing Autoserialization of BigInteger and BigDecimal Types

@@ -47,4 +47,4 @@ In addition to speeding standard object serialization, you can use the `DataSeri
You can also use `DataSerializer` to serialize domain objects. It serializes data in the same way as `DataSerializable` but allows you to serialize classes without modifying the domain class code.
See the JavaDocs on [DataSerializable](/releases/latest/javadoc/org/apache/geode/DataSerializable.html) and [DataSerializer](/releases/latest/javadoc/org/apache/geode/DataSerializer.html) for more information.
See the JavaDocs on [DataSerializable](<%=vars.javadocs%>/org/apache/geode/DataSerializable.html) and [DataSerializer](<%=vars.javadocs%>/org/apache/geode/DataSerializer.html) for more information.
@@ -50,7 +50,7 @@ When using multiple `dispatcher-threads` (greater than 1) with a serial event qu
- **key (default)**. All updates to the same key are distributed in order. <%=vars.product_name%> preserves key ordering by placing all updates to the same key in the same dispatcher thread queue. You typically use key ordering when updates to entries have no relationship to each other, such as for an application that uses a single feeder to distribute stock updates to several other systems.
- **thread**. All region updates from a given thread are distributed in order. <%=vars.product_name%> preserves thread ordering by placing all region updates from the same thread into the same dispatcher thread queue. In general, use thread ordering when updates to one region entry affect updates to another region entry.
- **partition**. All region events that share the same partitioning key are distributed in order. Specify partition ordering when applications use a [PartitionResolver](/releases/latest/javadoc/org/apache/geode/cache/PartitionResolver.html) to implement [custom partitioning](../partitioned_regions/using_custom_partition_resolvers.html). With partition ordering, all entries that share the same "partitioning key" (RoutingObject) are placed into the same dispatcher thread queue.
- **partition**. All region events that share the same partitioning key are distributed in order. Specify partition ordering when applications use a [PartitionResolver](<%=vars.javadocs%>/org/apache/geode/cache/PartitionResolver.html) to implement [custom partitioning](../partitioned_regions/using_custom_partition_resolvers.html). With partition ordering, all entries that share the same "partitioning key" (RoutingObject) are placed into the same dispatcher thread queue.

You cannot configure the `order-policy` for a parallel event queue, because parallel queues cannot preserve event ordering for regions. Only the ordering of events for a given partition (or in a given queue of a distributed region) can be preserved.

@@ -94,7 +94,7 @@ class MyAsyncEventListener implements AsyncEventListener {
## <a id="implementing_write_behind_cache_event_handling__section_AB80262CFB6D4867B52A5D6D880A5294" class="no-quick-link"></a>Processing AsyncEvents
Use the [AsyncEventListener.processEvents](/releases/latest/javadoc/org/apache/geode/cache/asyncqueue/AsyncEventListener.html) method to process AsyncEvents. This method is called asynchronously when events are queued to be processed. The size of the list reflects the number of batch events where batch size is defined in the AsyncEventQueueFactory. The `processEvents` method returns a boolean; true if the AsyncEvents are processed correctly, and false if any events fail processing. As long as `processEvents` returns false, <%=vars.product_name%> continues to re-try processing the events.
Use the [AsyncEventListener.processEvents](<%=vars.javadocs%>/org/apache/geode/cache/asyncqueue/AsyncEventListener.html) method to process AsyncEvents. This method is called asynchronously when events are queued to be processed. The size of the list reflects the number of batch events where batch size is defined in the AsyncEventQueueFactory. The `processEvents` method returns a boolean; true if the AsyncEvents are processed correctly, and false if any events fail processing. As long as `processEvents` returns false, <%=vars.product_name%> continues to re-try processing the events.
You can use the `getDeserializedValue` method to obtain cache values for entries that have been updated or created. Since the `getDeserializedValue` method will return a null value for destroyed entries, you should use the `getKey` method to obtain references to cache objects that have been destroyed. Here's an example of processing AsyncEvents:
@@ -234,7 +234,7 @@ To configure a write-behind cache listener, you first configure an asynchronous
mutator.addAsyncEventQueueId("sampleQueue");
```
See the [<%=vars.product_name%> API documentation](/releases/latest/javadoc/org/apache/geode/cache/AttributesMutator.html) for more information.
See the [<%=vars.product_name%> API documentation](<%=vars.javadocs%>/org/apache/geode/cache/AttributesMutator.html) for more information.

4. Optionally configure persistence and conflation for the queue.
**Note:**
@@ -57,7 +57,7 @@ See [Authorization of Function Execution](../../managing/security/implementing_a
- For partitioned regions, the `PartitionRegionHelper` provides access to additional information and data for the region. For single regions, use `getLocalDataForContext`. For colocated regions, use `getLocalColocatedRegions`.
**Note:**
When you use `PartitionRegionHelper.getLocalDataForContext`, `putIfAbsent` may not return expected results if you are working on local data set instead of the region.
4. To propagate an error condition or exception back to the caller of the function, throw a FunctionException from the `execute` method. <%=vars.product_name%> transmits the exception back to the caller as if it had been thrown on the calling side. See the Java API documentation for [FunctionException](/releases/latest/javadoc/org/apache/geode/cache/execute/FunctionException.html) for more information.
4. To propagate an error condition or exception back to the caller of the function, throw a FunctionException from the `execute` method. <%=vars.product_name%> transmits the exception back to the caller as if it had been thrown on the calling side. See the Java API documentation for [FunctionException](<%=vars.javadocs%>/org/apache/geode/cache/execute/FunctionException.html) for more information.
Example function code:
@@ -27,7 +27,7 @@ The use of query bind parameters is now supported in Client-to-Server queries.
The query parameters are identified by a dollar sign, $, followed by a digit that represents the parameter's position in the parameter array passed to the execute method. Counting begins at 1, so $1 references the first bound attribute, $2 the second attribute, and so on.
The Query interface provides an overloaded execute method that accepts parameters inside an Object array. See the [Query.execute](/releases/latest/javadoc/org/apache/geode/cache/query/Query.html) JavaDocs for more details.
The Query interface provides an overloaded execute method that accepts parameters inside an Object array. See the [Query.execute](<%=vars.javadocs%>/org/apache/geode/cache/query/Query.html) JavaDocs for more details.

The 0th element of the Object array is used for the first query parameter, and so on. If the parameter count or parameter types do not match the query specification, the execute method throws an exception. Specifically, if you pass in the wrong number of parameters, the method call throws a `QueryParameterCountInvalidException`. If a parameter object type is not compatible with what is expected, the method call throws a `TypeMismatchException`.

@@ -25,7 +25,7 @@ Indexes are automatically kept current with the region data they reference. The

Asynchronous index maintenance batches up multiple updates to the same region key. The default mode is synchronous, since this provides the greatest consistency with region data.

See [RegionFactory.setIndexMaintenanceSynchronous](/releases/latest/javadoc/org/apache/geode/cache/RegionFactory.html).
See [RegionFactory.setIndexMaintenanceSynchronous](<%=vars.javadocs%>/org/apache/geode/cache/RegionFactory.html).
This declarative index creation sets the maintenance mode to asynchronous:
@@ -61,7 +61,7 @@ TYPE Position WHERE portfolio.status = 'active'

## <a id="concept_85AE7D6B1E2941ED8BD2A8310A81753E__section_1B7762EC686A4808B1D12E8851954E82" class="no-quick-link"></a>SELECT Statement Results

The result of a SELECT statement is either UNDEFINED or is a Collection that implements the [SelectResults](/releases/latest/javadoc/org/apache/geode/cache/query/SelectResults.html) interface.
The result of a SELECT statement is either UNDEFINED or is a Collection that implements the [SelectResults](<%=vars.javadocs%>/org/apache/geode/cache/query/SelectResults.html) interface.
The SelectResults returned from the SELECT statement is either:
@@ -24,9 +24,9 @@ limitations under the License.
<a id="querying_partitioned_regions__section_4C603563DEDC4303818FB8F894470457"></a>
The following list summarizes the querying functionality supported by <%=vars.product_name%> for partitioned regions:
- **Ability to target specific nodes in a query**. If you know that a specific bucket contains the data that you want to query, you can use a function to ensure that your query only runs the specific node that holds the data. This can greatly improve query efficiency. The ability to query data on a specific node is only available if you are using functions and if the function is executed on one single region. In order to do this, you need to use `Query.execute(RegionFunctionContext context)`. See the [Java API](/releases/latest/javadoc/org/apache/geode/cache/query/Query.html) and [Querying a Partitioned Region on a Single Node](../query_additional/query_on_a_single_node.html#concept_30B18A6507534993BD55C2C9E0544A97) for more details.
- **Ability to optimize partitioned region query performance using key indexes**. You can improve query performance on data that is partitioned by key or a field value by creating a key index and then executing the query using use `Query.execute(RegionFunctionContext context)` with the key or field value used as filter. See the [Java API](/releases/latest/javadoc/org/apache/geode/cache/query/Query.html) and [Optimizing Queries on Data Partitioned by a Key or Field Value](../query_additional/partitioned_region_key_or_field_value.html#concept_3010014DFBC9479783B2B45982014454) for more details.
- **Ability to perform equi-join queries between partitioned regions and between partitioned regions and replicated regions**. Join queries between partitioned region and between partitioned regions and replicated regions are supported through the function service. In order to perform equi-join operations on partitioned regions or partitioned regions and replicated regions, the partitioned regions must be colocated, and you need to use the need to use `Query.execute(RegionFunctionContext context)`. See the [Java API](/releases/latest/javadoc/org/apache/geode/cache/query/Query.html) and [Performing an Equi-Join Query on Partitioned Regions](../partitioned_regions/join_query_partitioned_regions.html#concept_B930D276F49541F282A2CFE639F107DD) for more details.
- **Ability to target specific nodes in a query**. If you know that a specific bucket contains the data that you want to query, you can use a function to ensure that your query only runs the specific node that holds the data. This can greatly improve query efficiency. The ability to query data on a specific node is only available if you are using functions and if the function is executed on one single region. In order to do this, you need to use `Query.execute(RegionFunctionContext context)`. See the [Java API](<%=vars.javadocs%>/org/apache/geode/cache/query/Query.html) and [Querying a Partitioned Region on a Single Node](../query_additional/query_on_a_single_node.html#concept_30B18A6507534993BD55C2C9E0544A97) for more details.
- **Ability to optimize partitioned region query performance using key indexes**. You can improve query performance on data that is partitioned by key or a field value by creating a key index and then executing the query using use `Query.execute(RegionFunctionContext context)` with the key or field value used as filter. See the [Java API](<%=vars.javadocs%>/org/apache/geode/cache/query/Query.html) and [Optimizing Queries on Data Partitioned by a Key or Field Value](../query_additional/partitioned_region_key_or_field_value.html#concept_3010014DFBC9479783B2B45982014454) for more details.
- **Ability to perform equi-join queries between partitioned regions and between partitioned regions and replicated regions**. Join queries between partitioned region and between partitioned regions and replicated regions are supported through the function service. In order to perform equi-join operations on partitioned regions or partitioned regions and replicated regions, the partitioned regions must be colocated, and you need to use the need to use `Query.execute(RegionFunctionContext context)`. See the [Java API](<%=vars.javadocs%>/org/apache/geode/cache/query/Query.html) and [Performing an Equi-Join Query on Partitioned Regions](../partitioned_regions/join_query_partitioned_regions.html#concept_B930D276F49541F282A2CFE639F107DD) for more details.

- **[Using ORDER BY on Partitioned Regions](../query_additional/order_by_on_partitioned_regions.html)**

@@ -78,8 +78,8 @@ To perform a client to server query, use `org.apache.geode.cache.client.Pool.get
Refer to the following JavaDocs for specific APIs:
- [Query package](/releases/latest/javadoc/org/apache/geode/cache/query/package-summary.html)
- [QueryService](/releases/latest/javadoc/org/apache/geode/cache/query/QueryService.html)
- [Query package](<%=vars.javadocs%>/org/apache/geode/cache/query/package-summary.html)
- [QueryService](<%=vars.javadocs%>/org/apache/geode/cache/query/QueryService.html)

**Note:**
You can also perform queries using the gfsh `query` command. See [query](../../tools_modules/gfsh/command-pages/query.html).
@@ -702,9 +702,9 @@ ELEMENT(SELECT DISTINCT * FROM /exampleRegion WHERE id = 'XYZ-1').status = 'acti
## <a id="reference_D5CE64F5FD6F4A808AEFB748C867189E__section_5383407F9D004D4EB4E695252EBA1EF0" class="no-quick-link"></a>Which APIs should I use to write my queries?
If you are querying a Java application’s local cache or querying other members, use [org.apache.geode.cache.Cache.getQueryService](/releases/latest/javadoc/org/apache/geode/cache/query/QueryService.html).
If you are querying a Java application’s local cache or querying other members, use [org.apache.geode.cache.Cache.getQueryService](<%=vars.javadocs%>/org/apache/geode/cache/query/QueryService.html).
If you are writing a Java client to server query, use [org.apache.geode.cache.client.Pool.getQueryService](/releases/latest/javadoc/org/apache/geode/cache/client/Pool.html).
If you are writing a Java client to server query, use [org.apache.geode.cache.client.Pool.getQueryService](<%=vars.javadocs%>/org/apache/geode/cache/client/Pool.html).
## <a id="reference_D5CE64F5FD6F4A808AEFB748C867189E__section_3E6E4B33D57846008EF4404D2B687597" class="no-quick-link"></a>How do I invoke an object's method in a query?
@@ -776,7 +776,7 @@ QueryService qs = cache.getQueryService();
qs.createKeyIndex("myKeyIndex", "id", "exampleRegion");
```
For more information on using this API, see the [JavaDocs](/releases/latest/javadoc/index.html).
For more information on using this API, see the [JavaDocs](<%=vars.javadocs%>/index.html).
**Sample XML**

0 comments on commit cbd8795

Please sign in to comment.