http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/continuous-querying/3-native-client-cq-api.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/continuous-querying/3-native-client-cq-api.html.md.erb b/geode-docs/docs/geode-native-docs/continuous-querying/3-native-client-cq-api.html.md.erb new file mode 100644 index 0000000..f04aead --- /dev/null +++ b/geode-docs/docs/geode-native-docs/continuous-querying/3-native-client-cq-api.html.md.erb @@ -0,0 +1,38 @@ +--- +title: CQ API and Main Features +--- + +This chapter documents the primary native client API for CQ management. + +The Apache Geode native client API allows your clients to create and manage CQs. (The server side does not have an API.) Continuous querying provides native client query syntax, events-based management, integration with client/server architecture, active query execution, and interest criteria based on data values. For complete information on the classes and interfaces described here, see the API documentation at [http://gemfire-apis.docs.pivotal.io](http://gemfire-apis.docs.pivotal.io). + +**Gemstone::GemFire::Cache** + +Only C\# versions of CQ API interfaces, classes, and methods are shown here (example: `CqQuery.execute`). The code examples demonstrate both C++ and C\# versions. + +- `QueryService` interface. Provides methods that enable you to: + - Create a new CQ and specify whether it is durable (available for durable clients) + - Execute a CQ with or without an initial result + - List all the CQs registered by the client + - Close and stop CQs + - Get a handle on `CqStatistics` for the client + + You run `QueryService` CQ methods against the server cache. The QueryService can be obtained from the cache or from a pool. +- `CqQuery`interface. Provides methods for managing a continuous query after it is created through the `QueryService`. This interface is used typically to begin and end CQ execution and to retrieve other CQ-related objects such as CQ attributes, CQ statistics, and CQ state. +- `CqListener` application plug-in interface. Handles continuous query events after they occur. You program this interface. +- `CqEvent`interface. Provides all information sent from the server about the CQ event, which is passed to the CQ's `CqListener` methods. +- `CqState` interface. Provides information on the state of a `CqQuery`, through the getState method of the `CqQuery` instance. +- `CqAttributes, CqAttributesFactory, CqAttributesMutator` interfaces. Allow you to manage CQ attributes. The attributes consist of `CqListener `plug-in specifications. +- `CqStatistics, CqServiceStatistics` interfaces. Allow you to access statistics information for a single CQ and for the query service's management of CQs as a whole. For details on statistics, see [Statistics API](../cpp-caching-api/gfe-cpp-api.html#concept_AB12290E89CA4724AC9F51EFF7B8B8EA__section_42764C6327944514AE4A26684D7EBCB0). + +## <a id="security__section_74A3A0ECC2B645CEAEFDF68350E55EB4" class="no-quick-link"></a>Main Features of Continuous Querying + +Continuous querying in the native client has the following features: + +- **Standard Geode native client query syntax and semantics**. CQ queries are expressed in the same language used for other native client queries. See [Remote Querying](../remote-querying/remote-querying.html). +- **Standard Geode events-based management of CQ events**. The event handling used to process CQ events is based on the standard Geode event handling framework. The CQListener interface is similar to [Application Plug-Ins](../client-cache/application-plugins.html) and [Application Callbacks](../dotnet-caching-api/application-callbacks.html). +- **Complete integration with the client/server architecture**. CQ functionality uses existing server-to-client messaging mechanisms to send events. All tuning of your server-to-client messaging also tunes the messaging of your CQ events. If your system is configured for high availability then your CQs are highly available, with seamless failover provided in case of server failure (see [High Availability for Client-to-Server Communication](../preserving-data/high-availability-client-server.html)). If your clients are durable, you can also define any of your CQs as durable (see [Durable Client Messaging](../preserving-data/durable-client-messaging.html)). +- **Interest criteria based on data values**. CQ queries are run against the region's entry values. Compare this to register interest by reviewing [Registering Interest for Entries](../client-cache/registering-interest-for-entries.html). +- **Active query execution**. Once initialized, the queries only operate on new events instead of on the entire region data set. Events that change the query result are sent to the client immediately. + +
http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/continuous-querying/5-implementing-cq.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/continuous-querying/5-implementing-cq.html.md.erb b/geode-docs/docs/geode-native-docs/continuous-querying/5-implementing-cq.html.md.erb new file mode 100644 index 0000000..1113acd --- /dev/null +++ b/geode-docs/docs/geode-native-docs/continuous-querying/5-implementing-cq.html.md.erb @@ -0,0 +1,18 @@ +--- +title: Implementing a Continuous Query +--- + +You can specify CQs for any client region. + +Here are the high-level steps for implementing a continuous query, with links to more detailed information in this chapter. + +1. Make sure your system is configured properly to run CQs. See [Configuring for Continuous Querying](2-config-for-continuous-querying.html#security). +2. Decide what data to track on the server and write your queries. Use your criteria for tracking data changes to write your CQ queries. See [Writing the Continuous Query](5a-writing-cq.html#security). +3. Determine how to handle the CQ events on the client and write your listeners. + + Each CQ can have any number of listeners. In addition to your core CQ listeners, you might have listeners that you use for all CQs to track statistics or other general information. See [Writing the CQ Listener](5b-writing-cq-listener.html#security). + +4. Write the client code to put the queries and their listeners into named CQ queries and execute the queries. Make sure you close the queries if your client no longer needs them and when the client exits. See [Running the Continuous Query Code](5e-running-cq-code.html#security). +5. Write any code you need for monitoring and managing your CQ query. See [Managing Continous Queries](6-managing-cqs.html#security). +6. Run your code, monitor and tune as needed. + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/continuous-querying/5a-writing-cq.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/continuous-querying/5a-writing-cq.html.md.erb b/geode-docs/docs/geode-native-docs/continuous-querying/5a-writing-cq.html.md.erb new file mode 100644 index 0000000..67ba592 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/continuous-querying/5a-writing-cq.html.md.erb @@ -0,0 +1,26 @@ +--- +title: Writing the Continuous Query +--- + +Each CQ uses a query and any number of listeners. The query filters the events on the server and the listener handles the events that make it through the query filter. With the query and the listener in hand, you can create and execute your query through the API. + +This is the basic syntax for the CQ query: + +``` pre +SELECT * FROM /fullRegionPath [iterator] [WHERE clause] +``` + +The CQ query must satisfy the standard Geode native client querying specifications described in [Remote Querying](../remote-querying/remote-querying.html). It also must satisfy these restrictions: + +- The `FROM` clause must contain only a single region specification, with optional iterator variable. +- The query must be a `SELECT` expression only, preceded by zero or more `IMPORT` statements. This means the query cannot be a statement like `/tradeOrder.name` or `(SELECT * from /tradeOrder).size`. +- The CQ query cannot use: + - Cross region joins + - Drill-downs into nested collections + - `DISTINCT` + - Projections + - Bind parameters + +Queries not meeting these constraints generate an `UnsupportedOperationException` from the `QueryServicenewCq` method. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/continuous-querying/5b-writing-cq-listener.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/continuous-querying/5b-writing-cq-listener.html.md.erb b/geode-docs/docs/geode-native-docs/continuous-querying/5b-writing-cq-listener.html.md.erb new file mode 100644 index 0000000..2e3c06e --- /dev/null +++ b/geode-docs/docs/geode-native-docs/continuous-querying/5b-writing-cq-listener.html.md.erb @@ -0,0 +1,280 @@ +--- +title: Writing the CQ Listener or CQ Status Listener +--- + +The following C++ and C\# .NET examples show how you might program a simple `CqListener` or `CqStatusListener` to update a display screen based on the CQ events it receives. + +The listener retrieves the `queryOperation` and entry key and value from the `CqEvent` , then updates the screen according to the operation type provided in `queryOperation`. + +CQ events do not change your client cache. They are provided as an event service only. This allows you to have any collection of CQs without storing large amounts of data in your regions. If you need to persist information from CQ events, program your listener to store the information where it makes the most sense for your application. + +Be very careful if you choose to update your cache from your `CqListener`. If your listener updates the region that is queried in its own CQ, the update may be forwarded to the server. If the update on the server satisfies the same CQ, it may be returned to the same listener that did the update, which could put your application into an infinite loop. This same scenario could be played out with multiple regions and multiple CQs if the listeners are programmed to update each other's regions. + +## CqListener Implementation (C++) + +``` pre +// CqListener class +class TradeEventListener : public CqListener { + public: + void onEvent(const CqEvent& cqEvent) { + // Operation associated with the query op + CqOperation::CqOperationType queryOperation = cqEvent.getQueryOperation(); + // key and new value from the event + CacheableKeyPtr key = cqEvent.getKey(); + TradeOrderPtr tradeOrder = dynCast<TradeOrderPtr>(cqEvent.getNewValue()); + if (queryOperation==CqOperation::OP_TYPE_UPDATE) { + // update data on the screen for the trade order + . . . + } + else if (queryOperation==CqOperation::OP_TYPE_CREATE) { + // add the trade order to the screen + . . . + } + else if (queryOperation==CqOperation::OP_TYPE_DESTROY) { + // remove the trade order from the screen + . . . + } + } + void onError(const CqEvent& cqEvent) { + // handle the error + } + void close() { + // close the output screen for the trades + . . . + } +} +``` + +## CqListener Implementation (C\# .NET) + +``` pre +// CqListener class +public class TradeEventListener : ICqListener { + public void onEvent(CqEvent cqEvent) { + // Operation associated with the query op + CqOperationType queryOperation = cqEvent.getQueryOperation(); + // key and new value from the event + ICacheableKey key = cqEvent.getKey(); + CacheableString keyStr = key as CacheableString; + IGFSerializable val = cqEvent.getNewValue(); + TradeOrder tradeOrder = val as TradeOrder; + if (queryOperation==CqOperationType.OP_TYPE_UPDATE) { + // update data on the screen for the trade order + // . . . + } + else if (queryOperation== CqOperationType.OP_TYPE_CREATE) { + // add the trade order to the screen + // . . . + } + else if (queryOperation== CqOperationType.OP_TYPE_DESTROY) { + // remove the trade order from the screen + // . . . + } + } + public void onError(CqEvent cqEvent) { + // handle the error + } + // From CacheCallback + public void close() { + // close the output screen for the trades + // . . . + } +} +``` + +## <a id="security__section_B80352FB8FC94C929C934598FE958692" class="no-quick-link"></a>Writing a CqStatusListener + +If you need your CQs to detect whether they are connected to any of the servers that host its subscription queues, implement a `CqStatusListener` instead of a `CqListener`. + +`CqStatusListener` extends the current `CqListener`, allowing a client to detect when a CQ is connected and/or disconnected from the server(s). The `onCqConnected()` method will be invoked when the CQ is connected, and when the CQ has been reconnected after being disconnected. The `onCqDisconnected()` method will be invoked when the CQ is no longer connected to any servers. + +Taking the examples from above, we can instead implement a `CqStatusListener`. + +When you install the `CqStatusListener`, your listener will be able to detect its connection status to the servers that it is querying. + +## CqStatusListener Implementation (C++) + +``` pre +class MyCqStatusListener : public CqStatusListener { + uint8_t m_id; + uint32_t m_numInserts; + uint32_t m_numUpdates; + uint32_t m_numDeletes; + uint32_t m_numEvents; + uint32_t m_cqsConnectedCount; + uint32_t m_cqsDisconnectedCount; + + public: + uint8_t getId() + { + return m_id; + } + uint32_t getNumInserts() + { + return m_numInserts; + } + uint32_t getNumUpdates() + { + return m_numUpdates; + } + uint32_t getNumDeletes() + { + return m_numDeletes; + } + uint32_t getNumEvents() + { + return m_numEvents; + } + uint32_t getCqsConnectedCount() + { + return m_cqsConnectedCount; + } + uint32_t getCqsDisConnectedCount() + { + return m_cqsDisconnectedCount; + } + MyCqStatusListener(uint8_t id): + m_id(id), + m_numInserts(0), + m_numUpdates(0), + m_numDeletes(0), + m_numEvents(0), + m_cqsDisconnectedCount(0), + m_cqsConnectedCount(0) + { + } + inline void updateCount(const CqEvent& cqEvent) + { + m_numEvents++; + switch (cqEvent.getQueryOperation()) + { + case CqOperation::OP_TYPE_CREATE: { + m_numInserts++; + break; + } + case CqOperation::OP_TYPE_UPDATE: { + m_numUpdates++; + break; + } + case CqOperation::OP_TYPE_DESTROY: { + m_numDeletes++; + break; + } + default: + break; + } + } + void onEvent(const CqEvent& cqe){ + updateCount(cqe); + } + void onError(const CqEvent& cqe){ + updateCount(cqe); + } + void close(){ + } + void onCqDisconnected() { + //This is called when the cq loses connection with all servers. + m_cqsDisconnectedCount++; + } + void onCqConnected() { + //This is called when the cq establishes a connection with a server. + m_cqsConnectedCount++; + } + void clear() { + m_numInserts = 0; + m_numUpdates = 0; + m_numDeletes = 0; + m_numEvents = 0; + m_cqsDisconnectedCount = 0; + m_cqsConnectedCount = 0; + } +}; +``` + +## CQStatusListener Implementation (C\# .NET) + +``` pre + public class MyCqStatusListener<TKey, TResult> : ICqStatusListener<TKey, TResult> + { + #region Private members + private bool m_failedOver = false; + private UInt32 m_eventCountBefore = 0; + private UInt32 m_errorCountBefore = 0; + private UInt32 m_eventCountAfter = 0; + private UInt32 m_errorCountAfter = 0; + private UInt32 m_CqConnectedCount = 0; + private UInt32 m_CqDisConnectedCount = 0; + #endregion + + #region Public accessors + public MyCqStatusListener(int id) + { + } + public void failedOver() + { + m_failedOver = true; + } + public UInt32 getEventCountBefore() + { + return m_eventCountBefore; + } + public UInt32 getErrorCountBefore() + { + return m_errorCountBefore; + } + public UInt32 getEventCountAfter() + { + return m_eventCountAfter; + } + public UInt32 getErrorCountAfter() + { + return m_errorCountAfter; + } + public UInt32 getCqConnectedCount() + { + return m_CqConnectedCount; + } + public UInt32 getCqDisConnectedCount() + { + return m_CqDisConnectedCount; + } + #endregion + + public virtual void OnEvent(CqEvent<TKey, TResult> ev) + { + if (m_failedOver == true) + m_eventCountAfter++; + else + m_eventCountBefore++; + } + public virtual void OnError(CqEvent<TKey, TResult> ev) + { + if (m_failedOver == true) + m_errorCountAfter++; + else + m_errorCountBefore++; + } + public virtual void Close() + { + } + public virtual void OnCqConnected() + { + m_CqConnectedCount++; + } + public virtual void OnCqDisconnected() + { + m_CqDisConnectedCount++; + } + public virtual void Clear() + { + m_eventCountBefore = 0; + m_errorCountBefore = 0; + m_eventCountAfter = 0; + m_errorCountAfter = 0; + m_CqConnectedCount = 0; + m_CqDisConnectedCount = 0; + } + } +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/continuous-querying/5c-cq-event-object.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/continuous-querying/5c-cq-event-object.html.md.erb b/geode-docs/docs/geode-native-docs/continuous-querying/5c-cq-event-object.html.md.erb new file mode 100644 index 0000000..1917675 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/continuous-querying/5c-cq-event-object.html.md.erb @@ -0,0 +1,60 @@ +--- +title: CqEvent Object +--- + +The `CqEvent` object contains information about the CQ event. + +- Entry key and new value. +- Base operation that triggered the CQ event in the server. +- `CqQuery` object associated with this CQ event. +- Query operation associated with this CQ event. This operation describes the change affected to the query results by the cache event. Possible values are: + - `CREATE`, which corresponds to the standard database `INSERT` operation. + - ` UPDATE` + - `DESTROY`, which corresponds to the standard database `DELETE` operation. + +<a id="security__section_A619799378B14214AF922D819907FF38"></a> +This table describes the query operation based on whether the old and new entry values in the region entry event satisfy the query criteria. + +<a id="security__table_92A6A66523764199A19BCD66BA189921"></a> + +<table> +<caption><span class="tablecap">Table 1. Query Operation Based on Old and New Entry Values</span></caption> +<colgroup> +<col width="33%" /> +<col width="33%" /> +<col width="33%" /> +</colgroup> +<tbody> +<tr class="odd"> +<td><strong>Old Entry Value</strong></td> +<td><strong>New Entry Value</strong></td> +<td><strong>Query Operation</strong></td> +</tr> +<tr class="even"> +<td>No value or value does not satisfy the query criteria.</td> +<td>No value (operation is <code class="ph codeph">invalidate</code> or <code class="ph codeph">destroy</code>) or value does not satisfy the query. +<p></p> +<p>Value satisfies the query.</p></td> +<td>N/A - no event +<p></p> +<p></p> +<p><code class="ph codeph">create</code></p></td> +</tr> +<tr class="odd"> +<td>Value satisfies the query</td> +<td>No value (operation is <code class="ph codeph">invalidate</code> or <code class="ph codeph">destroy</code>) or value does not satisfy the query. +<p></p> +<p>Value satisfies the query.</p></td> +<td><code class="ph codeph">destroy</code> +<p></p> +<p></p> +<p><code class="ph codeph">update</code></p></td> +</tr> +</tbody> +</table> + +<span class="tablecap">**Table 1.** Query Operation Based on Old and New Entry Values</span> + +You can use the query operation to decide what to do with the `CqEvent` in your listeners. For example, a `CqListener` that displays query results on screen might stop displaying the entry, start displaying the entry, or update the entry display depending on the query operation. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/continuous-querying/5d-when-error-occurs.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/continuous-querying/5d-when-error-occurs.html.md.erb b/geode-docs/docs/geode-native-docs/continuous-querying/5d-when-error-occurs.html.md.erb new file mode 100644 index 0000000..25cd1fd --- /dev/null +++ b/geode-docs/docs/geode-native-docs/continuous-querying/5d-when-error-occurs.html.md.erb @@ -0,0 +1,17 @@ +--- +title: When an Error Occurs in a Running CQ +--- + +When an error occurs in CQ execution on the server, specific information on the error itself is stored in the server's log file. An exception is passed to the client, and the client throws an exception. + +The server log will contain an error message indicating an error while processing CQ , like this: + +``` pre +[error 2007/12/18 12:03:18.903 PST <RMI TCP Connection(2)- +192.0.2.0> tid=0x18] Error while processing CQ on the event, key : +key-1, CqName :testCQEvents_0, ClientId : +identity(carlos(3249):52623/35391,connection=1,durableAttributes=null) +Error :No public attribute named 'ID' was found in class java.lang.Object +``` + +Errors in CQ execution are usually caused by data errors, such as invalid object types that are stored in the server region. In this case, the query is trying to read into an object of type Portfolio for an entry where an empty object has been stored. You can avoid these types of errors by placing constraints on the region entries, or by otherwise controlling the types of objects stored in your server regions. http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/continuous-querying/5e-running-cq-code.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/continuous-querying/5e-running-cq-code.html.md.erb b/geode-docs/docs/geode-native-docs/continuous-querying/5e-running-cq-code.html.md.erb new file mode 100644 index 0000000..b5626d8 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/continuous-querying/5e-running-cq-code.html.md.erb @@ -0,0 +1,67 @@ +--- +title: Running the Continuous Query Code +--- + +Create your CQ from an instance of the QueryService. Once created, the CQ is maintained primarily through the CqQuery interface. The following two C++ and C\# examples show the basic calls in the CQ life cycle. + +## CQ Creation, Execution, and Close (C++) + +``` pre +// Get cache and qrySvcPtr - refs to local cache and QueryService +// Create client /tradeOrder region configured to talk to the server +// Create CqAttribute using CqAttributeFactory +CqAttributesFactory cqf; +// Create a listener and add it to the CQ attributes +// callback defined below +CqListenerPtr tradeEventListener (new TradeEventListener()); +QueryServicePtr qrySvcPtr = cachePtr->getQueryService();" cqf.addCqListener(tradeEventListener); +CqAttributesPtr cqa = cqf.create(); +// Name of the CQ and its query +char* cqName = "priceTracker"; +char* queryStr = "SELECT * FROM /tradeOrder t where t.price > 100.00"; +// Create the CqQuery +CqQueryPtr priceTracker = qrySvcPtr->newCq(cqName, queryStr, cqa); try { + // Execute CQ + priceTracker->execute(); +} catch (Exception& ex){ + ex.printStackTrace(); +} + // Now the CQ is running on the server, sending CqEvents to the listener + . . . +} +// End of life for the CQ - clear up resources by closing +priceTracker->close() +``` + +## CQ Creation, Execution, and Close (C\# .NET) + +``` pre +// Get cache and queryService - refs to local cache and QueryService +// Create client /tradeOrder region configured to talk to the server +// Create CqAttribute using CqAttributeFactory +CqAttributesFactory cqf = new CqAttributesFactory(); +// Create a listener and add it to the CQ attributes +//callback defined below +ICqListener tradeEventListener = new TradeEventListener(); +cqf.addCqListener(tradeEventListener); +CqAttributes cqa = cqf.create(); +// Name of the CQ and its query +String cqName = "priceTracker "; +String queryStr = "SELECT * FROM /tradeOrder t where t.price >100.00 "; +QueryService queryService = cache.GetQueryService(); +// Create the CqQuery +CqQuery priceTracker = queryService.newCq(cqName, queryStr, cqa, true); +try { + // Execute CQ + priceTracker.execute(); + }catch (Exception ex){ + //handle exception + } +// Now the CQ is running on the server, sending CqEvents to the listener +// . . . +} +// End of life for the CQ - clear up resources by closing +priceTracker.close(); +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/continuous-querying/5f-cq-execution-options.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/continuous-querying/5f-cq-execution-options.html.md.erb b/geode-docs/docs/geode-native-docs/continuous-querying/5f-cq-execution-options.html.md.erb new file mode 100644 index 0000000..4a6c5fc --- /dev/null +++ b/geode-docs/docs/geode-native-docs/continuous-querying/5f-cq-execution-options.html.md.erb @@ -0,0 +1,13 @@ +--- +title: CQ Execution Options +--- + +CQ execution can be done with or without an initial result set by calling `CqQuery.Execute` or `CqQuery.ExecuteWithInitialResults`. The initial `SelectResults` returned from `ExecuteWithInitialResults` is the same as the one you would get if you ran the query ad hoc by calling `QueryService.NewQuery.Execute` on the server cache, but with the key added. + +Individual CQs are executed using` CqQueryexecute*` methods. You can also execute all CQs for the client or for a region through the client `QueryService`. CQs that are running can be stopped or closed. + +If you are managing a data set from the CQ results, you can initialize the set by iterating over the result set and then updating it from your listeners as events arrive. For example, you might populate a new screen with initial results and then update the screen from a listener. + +Just as with the standalone query, the initial results represents a possibly moving snapshot of the cache. If there are updates to the server region while the result set is being created, the result set and the subsequent event-by-event CQ query execution might miss some events. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/continuous-querying/6-managing-cqs.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/continuous-querying/6-managing-cqs.html.md.erb b/geode-docs/docs/geode-native-docs/continuous-querying/6-managing-cqs.html.md.erb new file mode 100644 index 0000000..51c3874 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/continuous-querying/6-managing-cqs.html.md.erb @@ -0,0 +1,35 @@ +--- +title: Managing Continuous Queries +--- + +This section discusses how to access and manage your CQs from your client. The calls discussed here are all executed specifically for the calling client. A client cannot access or modify the CQs belonging to another client. + +This section discusses how to access and manage your CQs from your client. The calls discussed here are all executed specifically for the calling client. A client cannot access or modify the CQs belonging to another client. + +For detailed method usage, see the API documentation at [http://gemfire-apis.docs.pivotal.io](http://gemfire-apis.docs.pivotal.io). + +## <a id="security__section_939E26544C6E4C419336B7B04D1DE77F" class="no-quick-link"></a>Accessing CQs and CQ Statistics + +You can use the `QueryServicegetCq*` methods to access a single named CQ, an array of all CQs registered, and an array of all CQs registered in the client. You canuse the `CqEvent.getCq` method to access the CQ used to produce a `CqEvent`. + +CQ runtime statistics are available for the client through the `CqServiceStatistics` and `CqStatistics` interfaces described under [CQ API and Main Features](3-native-client-cq-api.html#security). You can get information on the events generated by a specific CQ from the `CqStatistics` object returned by `CqQuery.GetStatistics`. You can get higher-level information about the CQs the client has registered, running, and so on, from the `CqServiceStatistics` object returned by `QueryService.GetCqStatistics` . + +Client statistics are for the single client only. The server's pertain to all clients with CQs on this server. + +## <a id="security__section_0803146FEC9F4E088C01C521ED83723D" class="no-quick-link"></a>Modifying CQ Attributes + +You can modify the attributes for an existing CQ using the methods provided by `CqQuery.GetCqAttributesMutator`. The attributes consist of a list of listeners. + +## <a id="security__section_132104D528A7457A90EAE120B9080565" class="no-quick-link"></a>Stopping and Closing CQs + +You stop individual CQs with the `CqQuerystop` method. You can stop all CQs for the client through the `QueryService`. Stopped CQs are in the same state as new CQs that have not yet been executed. You can close or execute a stopped CQ. + +You close individual CQs with the `CqQueryclose` method. You can also close all CQs for the client through the `QueryService`. Closed CQs cannot be executed. CQs are also closed in the following cases: + +- The client closes its cache after closing all of its CQs--Closing the client cache closes the `QueryService` and all associated CQs on the client and server. +- The client disconnects from its server--This might be because of a network outage or some other failure. When a client disconnects, all CQs created by the client are removed from the server and put into a `CLOSED` state on the client. +- The server region is destroyed--When a server region is destroyed, all associated CQs are also cleaned up on the server and the region destroy event is sent to the client. On the client, the `CqListener.Close` method is called for all CQs on the region. + +## <a id="security__section_C11FA08192934D578C4FC1EFB610F50B" class="no-quick-link"></a>Getting All Durable CQs Registered with the Server + +To obtain a list of all durable CQs registered on the server, use the `QueryService.getAllDurableCqsFromServer` API. http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/continuous-querying/continuous-querying.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/continuous-querying/continuous-querying.html.md.erb b/geode-docs/docs/geode-native-docs/continuous-querying/continuous-querying.html.md.erb new file mode 100644 index 0000000..9e64b4a --- /dev/null +++ b/geode-docs/docs/geode-native-docs/continuous-querying/continuous-querying.html.md.erb @@ -0,0 +1,23 @@ +--- +title: Continuous Querying +--- + +*Continuous Querying* describes how to implement continuous querying in the Apache Geode native client so that C++ and .NET clients can run queries against events in the Geode cache server region. It also describes main features and the native client CQ API. + +- **[How Continuous Querying Works](1-how-cont-query-works.html)** + + C++ and .NET clients register interest in events using simple query expressions. Events are sent to client listeners that you can program to do whatever your application requires. + +- **[Implementing a Continuous Query](5-implementing-cq.html)** + + You can specify CQs for any client region. + +- **[Managing Continuous Queries](6-managing-cqs.html)** + + This section discusses how to access and manage your CQs from your client. The calls discussed here are all executed specifically for the calling client. A client cannot access or modify the CQs belonging to another client. + +- **[CQ API and Main Features](3-native-client-cq-api.html)** + + This chapter documents the primary native client API for CQ management. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/accessing-entry.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/accessing-entry.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/accessing-entry.html.md.erb new file mode 100644 index 0000000..4a97d6f --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/accessing-entry.html.md.erb @@ -0,0 +1,28 @@ +--- +title: Accessing an Entry +--- + +The standard `Region::get API` method returns the value associated with the specified key, and passes the callback argument to any cache loaders or cache writers that are invoked in the operation. + +If the value is not present locally, it is requested from the cache server. If the cache server request is unsuccessful, a local cache loader is invoked. + +The entry value is either retrieved from the local cache or fetched by the regionâs locally defined cache loader. + +In the following example, the program uses the API to do a get for each entry that was put into the cache: + +``` pre +for ( int32_t i=0; i< 100; i++) { + CacheableInt32Ptr res = dynCast<CacheableInt32Ptr>(regionPtr->get(i)); +} +``` + +## <a id="concept_2B85EC4AB9FA446998147A1539D818CC__section_80F9A9E8F8514A9FBA19106C2473B370" class="no-quick-link"></a>Bulk Get Operations Using getAll + +You can use the `Region::getAll` API (`Region.GetAll` for .NET) to get values for an array of keys from the local cache or server. If the value for a key is not present locally, then it is requested from the server. + +**Note:** +The value returned is not copied, so multi-threaded applications should not modify the value directly, but should instead use the update methods. + +The getAll API also supports providing a callback argument to any cache loaders or cache writers that are invoked in the operation. See the Region API documentation for more information about using `getAll`. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/add-entry-to-cache.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/add-entry-to-cache.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/add-entry-to-cache.html.md.erb new file mode 100644 index 0000000..e54306a --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/add-entry-to-cache.html.md.erb @@ -0,0 +1,43 @@ +--- +title: Adding an Entry to the Cache +--- + +You can populate a native client region with cache entries using the `Region::put` or the `Region::create` API functions. Code examples demonstrate these actions. + +The `put` function places a new value into a region entry with the specified key, while the `create` function creates a new entry in the region. Both functions provide a user-defined parameter object to any cache writer invoked in the process, and new values for both functions are propagated to a connected cache server. + +## Adding Entries Using create + +When the put function adds an entry, the previous value is overwritten if there is already an entry associated with the specified key in the region. In the next example, the program uses the API to put 100 entries into the cache by iteratively creating keys and values, both of which are integers. + +``` pre +for ( int32_t i=0; i < 100; i++ ) { + regionPtr->put( i, CacheableInt32::create(i) ); +} +``` + +## <a id="concept_26D4E6C6BC6F4AB8884E33119999656D__section_748916759F0246619CD27E7456DCA365" class="no-quick-link"></a>Bulk Put Operations Using putAll + +You can batch up multiple key/value pairs into a hashmap and put them into the cache with a single operation using the `Region::putAll` API function (`Region.PutAll` for .NET) . Each entry is processed for interest registration on the server, so each entry requires its own unique event ID. Updates and creates can be mixed in a `putAll` operation, so those events need to be addressed on the cache server for appropriate cache listener invocation on distributed system members. Map entries retain their original order when they are processed at the server. + +The following table lists the client and cache server statistics for `putAll`. + +<a id="concept_26D4E6C6BC6F4AB8884E33119999656D__table_4693B08B5B4D44118DC399C8826C9750"></a> + +| Statistic Type | Chart Name | Description | +|--------------------|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| +| `CachePerfStats` | `Putalls` | Total number of times a map is added or replaced in the cache as a result of a local operation. Also reports the number of `putAll` operations. | +| `CachePerfStats` | `putallTime` | Total time to replace a map in the cache as a result of a local operation. | +| `CacheServerStats` | `putAllRequests` | Number of `putAll` requests. | +| `CacheServerStats` | `putAllResponses` | Number of `putAll` responses written to the cache client. | +| `CacheServerStats` | `processPutAllTime` | Total time to process a cache client `putAll` request, including the time to put all objects into the cache. | +| `CacheServerStats` | `readPutAllRequestTime` | Total time to read `putAll` requests. | +| `CacheServerStats` | `writePutAllResponseTime` | Total time to write `putAll` responses. | +| `CacheClientStats` | `putAll` | Number of `putAll` requests sent to the cache server. | +| `CacheClientStats` | `sendPutAllTime` | Total time for `sendPutAll` . | + +<span class="tablecap">**Table 1.** putAll Statistics for Cache Server and Client</span> + +The putAll API also supports providing a callback argument to any cache loaders or cache writers that are invoked in the operation. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/cpp-caching-api.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/cpp-caching-api.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/cpp-caching-api.html.md.erb new file mode 100644 index 0000000..06bc876 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/cpp-caching-api.html.md.erb @@ -0,0 +1,51 @@ +--- +title: Pivotal GemFire Native Client C++ API +--- + +This section describes the primary classes and usage conventions for the native client C++ API. It demonstrates how to use the API to create caches and perform data serialization. + +The C++ API documentation is available at [http://gemfire-apis.docs.pivotal.io](http://gemfire-apis.docs.pivotal.io). It provides extensive implementation details for the C++ structures and functions. + +Several example API programs are included in the `SampleCode` directory. See [QuickStart Examples and Guide](../introduction/examples-quickstart.html#examples-quickstart). + +- **[About the Native Client C++ API](gfe-cpp-api.html)** + + The native client C++ API allows C++ and .NET developers to programmatically create, populate, and manage a Geode distributed system. The C++ library is thread-safe, except where specified otherwise in the API documentation at [http://gemfire-apis.docs.pivotal.io](http://gemfire-apis.docs.pivotal.io). + +- **[Creating a Cache](creating-cache.html)** + + The code snippets in this section show cache creation. + +- **[Creating a Proxy Client-Side Region](creating-region.html)** + + This section provides code examples for creating and customizing proxy client-side regions. + +- **[Adding an Entry to the Cache](add-entry-to-cache.html)** + + You can populate a native client region with cache entries using the `Region::put` or the `Region::create` API functions. Code examples demonstrate these actions. + +- **[Accessing an Entry](accessing-entry.html)** + + The standard `Region::get API` method returns the value associated with the specified key, and passes the callback argument to any cache loaders or cache writers that are invoked in the operation. + +- **[Removing an Entry](removing-entry.html)** + + The standard `Region::remove` API removes the entry with the specified key and provides a user-defined parameter object to any `CacheWriter` or `CacheListener` invoked in the process. + +- **[Serializing Data](serialization_overview.html)** + + All data that Geode moves out of the local cache must be serializable. + +- **[Implementing User-Defined Objects in Java Clients](user-defined-objects.html)** + + You can use one of two methods to implement a user-defined object in a Java client that works with C++ clients: `Instantiator.register` and `DataSerializable`. + +- **[Using a Custom Class](using-custom-class.html)** + + This example shows how to use the defined `BankAccount` custom key type and the `AccountHistory` value type. + +- **[Creating New Statistics](creating-new-statistics.html)** + + This example provides a programmatic code sample for creating and registering new statistics. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/creating-cache.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/creating-cache.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/creating-cache.html.md.erb new file mode 100644 index 0000000..59b8979 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/creating-cache.html.md.erb @@ -0,0 +1,22 @@ +--- +title: Creating a Cache +--- + +The code snippets in this section show cache creation. + +When you create your cache, the system automatically connects your process to the server tier. For systems with security enabled, the credentials for a connecting client are authenticated when it creates the cache. See [Security](../security/overviewsecurity.html#security) for more information about authenticated connections. + +## Creating the System Connection and the Cache + +In this example, the application creates the cache by calling the `CacheFactory::create` function, specifying the servers to connect to: + +``` pre +CacheFactoryPtr cacheFactory = CacheFactory::createCacheFactory(); + CachePtr cachePtr = cacheFactory + ->addServer("localhost", 40404) + ->addServer("localhost", 40405) + ->setSubscriptionEnabled(true) + ->create(); +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/creating-new-statistics.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/creating-new-statistics.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/creating-new-statistics.html.md.erb new file mode 100644 index 0000000..9a30dca --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/creating-new-statistics.html.md.erb @@ -0,0 +1,53 @@ +--- +title: Creating New Statistics +--- + +This example provides a programmatic code sample for creating and registering new statistics. + +For information about the `gemfire_statistics` API, see [Statistics API](gfe-cpp-api.html#concept_AB12290E89CA4724AC9F51EFF7B8B8EA__section_42764C6327944514AE4A26684D7EBCB0). + +## Creating New Statistics Programmatically + +``` pre +//Get StatisticsFactory +StatisticsFactory* factory = StatisticsFactory::getExistingInstance(); +Â +Â +//Define each StatisticDescriptor and put each in an array +StatisticDescriptor** statDescriptorArr = new StatisticDescriptor*[6]; +statDescriptorArr[0] = statFactory->createIntCounter("IntCounter", + "Test Statistic Descriptor Int Counter.","TestUnit"); +Â +statDescriptorArr[1] = statFactory->createIntGauge("IntGauge", + "Test Statistic Descriptor Int Gauge.","TestUnit"); +Â +statDescriptorArr[2] = statFactory->createLongCounter("LongCounter", + "Test Statistic Descriptor Long Counter.","TestUnit"); +Â +statDescriptorArr[3] = statFactory->createLongGauge("LongGauge", + "Test Statistic Descriptor Long Gauge.","TestUnit"); +Â +statDescriptorArr[4] = statFactory->createDoubleCounter("DoubleCounter", + "Test Statistic Descriptor Double Counter.","TestUnit"); +Â +statDescriptorArr[5] = statFactory->createDoubleGauge("DoubleGauge", + "Test Statistic Descriptor Double Gauge.","TestUnit"); +Â +Â +//Create a StatisticsType +StatisticsType* statsType = statFactory->createType("TestStatsType", + "Statistics for Unit Test.",statDescriptorArr, 6); +Â +//Create Statistics of a given type +Statistics* testStat = + factory->createStatistics(statsType,"TestStatistics"); +Â +Â +//Statistics are created and registered. Set and increment individual values +Int statIdIntCounter = statsType->nameToId("IntCounter"); +testStat->setInt(statIdIntCounter, 10 ); +testStat->incInt(statIdIntCounter, 1 ); +int currentValue = testStat->getInt(statIdIntCounter); +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/creating-region.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/creating-region.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/creating-region.html.md.erb new file mode 100644 index 0000000..c6f8eb1 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/creating-region.html.md.erb @@ -0,0 +1,34 @@ +--- +title: Creating a Proxy Client-Side Region +--- + +This section provides code examples for creating and customizing proxy client-side regions. + +**Note:** +Creating a region through the native client API creates only a proxy client-side region. A corresponding region with the same name and path should also exist on the servers that have been configured for client connections and upon which the client will perform its operations. + +To create a region, you create a `RegionFactory` using the `RegionShortcut` that most closely fits your region configuration. From that, create your region, customizing the settings as region attributes as needed. + +## Creating a CACHING\_PROXY Region + +This example creates a region using a CACHING\_PROXY `RegionShortcut` with no further modifications: + +``` pre +RegionFactoryPtr regionFactory = + cachePtr->createRegionFactory(CACHING_PROXY); +regionPtr = regionFactory ->create("exampleRegion"); +``` + +## Creating a CACHING\_PROXY Region with LRU + +This example creates a region based on the CACHING\_PROXY RegionShortcut with two additional region attributes settings. For information on the settings, see [Region Attributes Descriptions](../client-cache/region-attributes-desc.html#region-attributes-desc). + +``` pre +RegionFactoryPtr regionFactory = + cachePtr->createRegionFactory(CACHING_PROXY); +regionPtr = regionFactory->setLruEntriesLimit( 20000 ) + ->setInitialCapacity( 20000 ) + ->create("exampleRegion"); +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/data-as-blob.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/data-as-blob.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/data-as-blob.html.md.erb new file mode 100644 index 0000000..85d3209 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/data-as-blob.html.md.erb @@ -0,0 +1,11 @@ +--- +title: Serializing and Accessing Data as a Blob +--- + +If you have data that is best handled as a blob, such as structs that do not contain pointers, use the serializable type `CacheableBytes` . `CacheableBytes` is a blob class that implements the serialization for you. + +`CacheableBytes` also provides direct access to the blob data. Because it is not derived from the `CacheableKey` interface, `CacheableBytes` enables you to modify data in place and then put it into the region again to distribute the change. + +For more information, see the API documentation for `CacheableBytes.` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/gfe-cpp-api.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/gfe-cpp-api.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/gfe-cpp-api.html.md.erb new file mode 100644 index 0000000..4b1cde1 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/gfe-cpp-api.html.md.erb @@ -0,0 +1,61 @@ +--- +title: About the Native Client C++ API +--- + +The native client C++ API allows C++ and .NET developers to programmatically create, populate, and manage a Geode distributed system. The C++ library is thread-safe, except where specified otherwise. + +This chapter gives a general overview of the classes in the `gemfire`, `gemfire_statistics`, and `gemfire_admin` namespaces. For complete and current information on the classes listed here, see the C++ API documentation at [http://gemfire-apis.docs.pivotal.io](http://gemfire-apis.docs.pivotal.io). + +## <a id="concept_AB12290E89CA4724AC9F51EFF7B8B8EA__section_14B45E09CA014951AD38D0E051DF8727" class="no-quick-link"></a>Cache Classes + +The native client C++ API has the following cache classes: + +- **CacheFactory**. Use this class to create and configure a `Cache` instance. If `cache.xml` is specified, the cache is created based on the declarations loaded from that file. +- **Cache**. Entry point to the client caching API. The cache is created by calling the `create` function of the factory class, `CacheFactory`. Regions are configured and obtained using the `Cache::createRegionFactory()` API. + +## <a id="concept_AB12290E89CA4724AC9F51EFF7B8B8EA__section_9F27929D85CC4EBFB29925974776C985" class="no-quick-link"></a>Region Classes + +The native client C++ API has the following region classes: + +- **Region**. Provides functions for managing regions and cached data. Use these functions to perform the following actions: + - Retrieve information about the region, such as its parent region and region attribute objects. + - Invalidate or destroy the region. + - Create, update, invalidate and destroy region entries. + - Retrieve region entry keys, entry values, and RegionEntry objects, either individually or as entire sets. + - Retrieve the statistics object associated with the region. + - Set and get user-defined attributes. +- **RegionEntry**. Contains the key and value for the entry, and provides all non-distributed entry operations. This object's operations are not distributed and do not affect statistics. + +## <a id="concept_AB12290E89CA4724AC9F51EFF7B8B8EA__section_CEC4E57E76E84D099D0F55F49F3B64DA" class="no-quick-link"></a>Region Attribute Classes + +The native client C++ API has the following region attribute classes: + +- **RegionAttributes**. Holds all attribute values for a region and provides functions for retrieving all attribute settings. This class can be modified by the `AttributesMutator` class after region creation. +- **AttributesMutator** . Allows modification of an existing regionâs attributes for application plug-ins and expiration actions. Each region has an `AttributesMutator` instance. + +## <a id="concept_AB12290E89CA4724AC9F51EFF7B8B8EA__section_658D04298E13459382D48544AF36A2FA" class="no-quick-link"></a>Application Plug-In Classes + +The native client C++ API has the following application plug-in classes: + +- **CacheLoader**. Loads data into a region on a cache miss. +- **CacheWriter**. Synchronously handles region and entry events before the events occur. Entry events are `create`, `update`, `invalidate`, and `destroy`. Region events are invalidate and destroy. This class has the ability to abort events. +- **CacheListener**. Handles region and entry events after they occur. Entry events are `create`, `update`, `invalidate`, and `destroy`. Region events are `invalidate` and `destroy`. + +## <a id="concept_AB12290E89CA4724AC9F51EFF7B8B8EA__section_B3479F5739B048C0BD3EDA89BE0266E0" class="no-quick-link"></a>Event Handling Classes + +The native client C++ API has the following event handling classes: + +- **RegionEvent**. Provides information about the event, such as in what region the event originated, whether the event originated in a cache remote to the event handler, and whether the event resulted from a distributed operation. +- **EntryEvent**. Provides all available information for the `RegionEvent`, and provides entry-specific information such as the old and new entry values and whether the event resulted from a `load` operation. + +## <a id="concept_AB12290E89CA4724AC9F51EFF7B8B8EA__section_42764C6327944514AE4A26684D7EBCB0" class="no-quick-link"></a>Statistics API + +The `StatisticsType` API represents a blueprint for the same type of `Statistics`. The `StatisticsType` API is a collection of `StatisticDescriptor`. Internally, each `StatisticDescriptor` describes data of each individual statistic. `StatisticsFactory` provides functionality for creating `StatisticDescriptor`, `StatisticsType`, and `Statistics`. + +- **CacheStatistics** --This class defines common statistics functions. `Region` and `RegionEntry` both have functions that return a `CacheStatistics` object for accessing and resetting their statistics counts. +- **StatisticDescriptor**. An instance of this class describes a statistic whose value is updated by an application and may be archived by the native client. Each statistic has a type of either `int`, `long`, or `double`, and either a gauge or a counter. The value of a gauge can increase and decrease, and the value of a counter strictly increases. Create an instance of `StatisticDescriptor` by calling one of these `StatisticsFactory` functions: `createDoubleCounter`, `createDoubleGauge`, `createIntCounter`, `createIntGauge`, `createLongCounter`, `createLongGauge`. +- **StatisticsType**. An instance of this class describes a logical collection of `StatisticDescriptors`. These descriptions are used to create an instance of `Statistics`. Create an instance of `StatisticsType` by calling `StatisticsFactory::createType`. +- **Statistics**. An instance of this class represents concrete `Statistics` of the associated `StatisticsType`. This class stores data related to all individual statistic objects. Create an instance by calling `StatisticsFactory::createStatistics`. This class has functions to get, set, and increment statistic values. +- **StatisticsFactory**. This class provides functions for creating instances of `StatisticDescriptor`, `StatisticsType`, and `Statistics objects`. This is a singleton class, and you acquire its instance by using `StatisticsFactory::getExistingInstance`. + +To create new statistics, see [Creating New Statistics](creating-new-statistics.html#concept_664156CBD79C44C4B200DA2D64180A65). http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/object-graphs.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/object-graphs.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/object-graphs.html.md.erb new file mode 100644 index 0000000..9cced86 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/object-graphs.html.md.erb @@ -0,0 +1,9 @@ +--- +title: Serializing Object Graphs +--- + +If you have a graph of objects where each node can be serializable, the parent node can call `DataOutput::writeObject` to delegate the serialization responsibility to its child nodes. Similarly, your application can call `DataInput::readObject` to deserialize the object graph. + +For more information, see the API documentation for `DataOutput` and `DataInput`. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_auto_serialization.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_auto_serialization.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_auto_serialization.html.md.erb new file mode 100644 index 0000000..0bdda28 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_auto_serialization.html.md.erb @@ -0,0 +1,355 @@ +--- +title: Using Automatic PDX Serialization +--- + +You can allow your native client C++ applications to automatically PDX serialize and deserialize domain objects without having to add any extra code by using the `pdxautoserializer` command line tool provided with the native client. + +When using the native client C++ API, you can automatically serialize and deserialize domain objects without making any code changes to those objects or having to implement a `PdxSerializer` or `PdxSerializable` interface and their related `fromData` and `toData` methods. The Geode native client includes a command-line utility, `pdxautoserializer`, that allows you to generate C++ code that will serialize your domain objects in the PDX format for you. + +## <a id="task_czj_wnw_dl" class="no-quick-link"></a>How to Use Automatic PDX Serialization + +**Prerequisites:** + +- Understand generally how to configure the Geode cache. + +- Understand how PDX serialization works and how to configure your application to use PdxSerializer. + +The procedure below uses the following sample class: + +``` pre +class PortfolioPdx +{ + private: + int32_t id; + char* pkid; + PositionPdxPtr position1; + PositionPdxPtr position2; + CacheableHashMapPtr positions; + char** names; + int8_t* newVal; + CacheableDatePtr creationDate; + int8_t* arrayNull; + int8_t* arrayZeroSize; + public: + // CTOR + // DTORS + // Other Methods declarations +``` + +For each domain class you provide, all fields are considered for serialization except those defined as static or transient and those you explicitly exclude using macros. + +1. Inherit your class from `gemfire::PdxSerializable`. + + ``` pre + class PortfolioPdx : public PdxSerializable + ``` + +2. Add the following method declarations in the public part of the class. + + ``` pre + const char* getClassName() const; + virtual void toData(gemfire::PdxWriterPtr pw); + virtual void fromData(gemfire::PdxReaderPtr pr); + static PdxSerializable* createDeserializable(); + ``` + +3. In your pre-build environment (for example in your **makefiles**), call `pdxautoserializer` as follows: + + ``` pre + <GFCPP>/bin/pdxautoserializer.exe --outDir=<location to generate files> <SOURCE_DIR>/PortfolioPdx.hpp + ``` + +4. Include the generated file in your project and compile. + +The following is an example of a generated file: + +``` pre +#include "PortfolioPdx.hpp" +#include <gfcpp/PdxWriter.hpp> +#include <gfcpp/PdxReader.hpp> +#include <gfcpp/PdxAutoSerializer.hpp> +namespace testobject +{ + void PortfolioPdx::toData(gemfire::PdxWriterPtr var) + { + gemfire::PdxAutoSerializable::writePdxObject(var, "id", id); + gemfire::PdxAutoSerializable::writePdxObject(var, "pkid", pkid); + gemfire::PdxAutoSerializable::writePdxObject(var, "position1", position1); + gemfire::PdxAutoSerializable::writePdxObject(var, "position2", position2); + gemfire::PdxAutoSerializable::writePdxObject(var, "positions", positions); + gemfire::PdxAutoSerializable::writePdxObject(var, "status", status); + gemfire::PdxAutoSerializable::writePdxObject(var, "creationDate", creationDate); + } + + void PortfolioPdx::fromData(PdxReaderPtr var) + { + gemfire::PdxAutoSerializable::readPdxObject(var, "id", id); + gemfire::PdxAutoSerializable::readPdxObject(var, "pkid", pkid); + gemfire::PdxAutoSerializable::readPdxObject(var, "position1", position1); + gemfire::PdxAutoSerializable::readPdxObject(var, "position2", position2); + gemfire::PdxAutoSerializable::readPdxObject(var, "positions", positions); + gemfire::PdxAutoSerializable::readPdxObject(var, "status", status); + gemfire::PdxAutoSerializable::readPdxObject(var, "creationDate", creationDate); + } + + const char* PortfolioPdx::getClassName() const + { + return "PortfolioPdx"; + } +} +``` + +## <a id="task_fs4_vkj_2l" class="no-quick-link"></a>Handling Arrays + +1. Define the following macro in your header file: + + ``` pre + #define GFARRAYSIZE(x) + ``` + +2. Assuming that the following is the class member of type array: + + ``` pre + int8_t* newVal; + ``` + + Then define a new variable which sets the length of the array: + + ``` pre + int32_t newValSize; + ``` + +3. Tag the new variable with the `GFARRAYSIZE` macro as follows: + + ``` pre + GFARRAYSIZE(newVal) int32_t newValSize; + ``` + +## Using a Single Variable as Length for Multiple Arrays + +You can use the GFARRAYSIZES to have single length for multiple arrays. + +Define the GFARRAYSIZES macro as follows: + +``` pre +#define GFARRAYSIZES(x) +``` + +The following is an example usage: + +``` pre +class ArrayOfSizes? + { + public: + int32_t* array1; + int32_t* array2; + int32_t* array3; + int32_t* array4; + int32_t* array5; + + GFARRAYSIZE(array1) int32_t singleSize; + GFARRAYSIZES("array2,array3,array4,array5") int32_t SingleSizeToMultipleArrays?; + };â +``` + +## <a id="task_hph_mrw_dl" class="no-quick-link"></a>Excluding Member Variables from Serialization + +1. Define the following macro in your header file: + + ``` pre + #define GFEXCLUDE + ``` + +2. Tag your member variable with this macro: + + ``` pre + GFEXCLUDE char* type; + ``` + +## <a id="task_en2_4rw_dl" class="no-quick-link"></a>Marking Identity Fields + +Identity fields are used when comparing objects using the `hashCode` and `equals` methods. + +1. Define the following macro in your header file. + + ``` pre + #define GFID(x) + ``` + +2. Assuming that the following is the class member you want to use as IdentityField: + + ``` pre + int8_t* newVal; + ``` + + Tag the member with the GFID macro as follows: + + ``` pre + GFID(newVal)int8_t* newVal; + ``` + +## Ignoring User Defined Keywords + +You might have certain user defined keywords after the class name. Current C++ grammar does not support this. If you have some keywords user will have to ignore them by using the `GFIGNORE` macro. + +For example, consider the following class definition: + +``` pre +#ifdef _WIN32 +#ifdef BUILD_TESTOBJECT +#define TESTOBJECT_EXPORT LIBEXP +#else +#define TESTOBJECT_EXPORT LIBIMP +#endif +#else +#define TESTOBJECT_EXPORT +#endif + +namespace PdxAutoTests { + class TESTOBJECT_EXPORT PdxAutoMegaType : public PdxSerializable { + } +``` + +Currently, the `pdxautoserializer` tool will fail to recognize `TESTOBJECT_EXPORT`. Change your class by adding the `GFIGNORE` macro as follows: + +``` pre +#ifdef _WIN32 +#ifdef BUILD_TESTOBJECT +#define TESTOBJECT_EXPORT LIBEXP +#else +#define TESTOBJECT_EXPORT LIBIMP +#endif +#else +#define TESTOBJECT_EXPORT +#endif + +using namespace gemfire; + +#define GFIGNORE(X) X +#define GFID + +namespace PdxAutoTests { + class GFIGNORE(TESTOBJECT_EXPORT) PdxAutoMegaType : public PdxSerializable { +``` + +## <a id="topic_d3q_v3c_2l" class="no-quick-link"></a>Additional Usage Information for the pdxautoserializer Tool + +The `pdxautoserializer` tool takes classes as input and generates code that will serialize the class into the PDX format for you. + +The `pdxautoserializer` tool is located in `$GFCPP/bin` where `$GFCPP` corresponds to the installation location of the native client. + +Some additional notes about using the `pdxautoserializer` tool: + +- Any const type in the class members are ignored by the `pdxserializer` tool. +- Generated files will have namespace in the file name. + +To view the command-line help for the tool, type: + +``` pre +prompt> pdxautoserializer.exe --help +``` + +Help returns the following syntax and usage information: + +``` pre +Usage: pdxautoserializer.exe [OPTIONS] <resources e.g. header> ... + +Resource name should be the path to the header containing the classes to be +auto-serialized. + +[OPTIONS] may be one of those given below. + +SINGLE denotes that the option should be specified only once. +MULTIPLE denotes that the option can be specified more than once. +OPTIONAL denotes that the option may be skipped in which case the default +for that shall be chosen. + +--className=VALUE Name of the class for which to generate auto-serialization code (MULTIPLE,OPTIONAL) +--classNameStr=VALUE Name of the class in string (MULTIPLE,OPTIONAL) +--help This help message. +--outDir The output directory of the generated files (SINGLE,OPTIONAL) +--suffix The suffix of the generated filenames -- default is 'Serializable' (SINGLE,OPTIONAL) +--usage This usage message. + +Examples: +pdxautoserializer -outDir=<DIR NAME> <RESOURCE> +pdxautoserializer -outDir=<DIR NAME> --className=<CLASSNAME1> --className=<CLASSNAME2> <RESOURCE> +pdxautoserializer -outDir=<DIR NAME> --classNameStr=<CLASSNAME1:User defined String> --classNameStr=<CLASSNAME:User defined String> <RESOURCE> + +Helper Macros to be defined in Input Header File : +GFINCLUDE for including a specific member for serialization +GFEXCLUDE for excluding a specific member for serialization +GFID for considering a member as Identify Field +GFARRAYSIZE for specifying a array length member +GFIGNORE for ignoring certain keywords +For more details refer to documentation on this utility. +``` + +## Generating Automatic Code for a Single Class + +Many times there are multiple classes in a single header file. For example: + +``` pre +#ifndef HEADER_HEADER +#define HEADER_HEADER + +class class1{ +}; +class class2{ +}; +class class3 : public PdxSerializable{ +}; +#endif +``` + +If you want to generate code for only one of the classes, then use the `--className` option. For example, if you only want to generate code for class3, then you would use the following command: + +``` pre +pdxautoserializer --outDir=<outDir> --className=class3 +``` + +## Choosing Your Own Suffix to Identify the Generated Files. + +The `pdxserializer` tool also provides the option to choose your own suffix for the generated C++ files. This can help you write less code in your makefiles. Here's an example command: + +``` pre +pdxautoserializer --outDir=<outDir> --className=CharTypes --suffix="generated" +``` + +## <a id="topic_f33_fsw_dl" class="no-quick-link"></a>Example of Using PDX Serialization in Your Application + +``` pre +CacheFactoryPtr cacheFactory = CacheFactory::createCacheFactory(); + // Create a GemFire Cache with the "clientPdxRemoteQuery.xml" Cache XML file. + CachePtr cachePtr = cacheFactory->set("cache-xml-file", "XMLs\\clientPdxRemoteQuery.xml") + ->create(); + + LOGINFO("Created the Cache"); + + // Get the example Region from the Cache which is declared in the Cache XML file. + RegionPtr regionPtr = cachePtr->getRegion( "Portfolios"); + + LOGINFO( "Obtained the Region from the Cache"); + + // Register our Serializable/Cacheable Query objects, viz. PortfolioPdx and PositionPdx. + Serializable::registerPdxType(PortfolioPdx::createDeserializable); + PortfolioPdxPtr port1Ptr(new PortfolioPdx(1 /*ID*/, 10 /*size*/)); + PortfolioPdxPtr port2Ptr(new PortfolioPdx(2 /*ID*/, 20 /*size*/)); + PortfolioPdxPtr port3Ptr(new PortfolioPdx(3 /*ID*/, 30 /*size*/)); + regionPtr->put("Key1", port1Ptr); + regionPtr->put("Key2", port2Ptr); + regionPtr->put("Key3", port3Ptr); + + // Get the QueryService from the Cache. + QueryServicePtr qrySvcPtr = cachePtr->getQueryService( "examplePool"); + + LOGINFO( "Got the QueryService from the Cache"); + + // Execute a Query which returns a ResultSet. + QueryPtr qryPtr = qrySvcPtr->newQuery("SELECT DISTINCT * FROM /Portfolios"); + SelectResultsPtr resultsPtr = qryPtr->execute(); + + LOGINFO( "ResultSet Query returned %d rows", resultsPtr->size()); +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_ignore_unread_fields.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_ignore_unread_fields.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_ignore_unread_fields.html.md.erb new file mode 100644 index 0000000..07093d1 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_ignore_unread_fields.html.md.erb @@ -0,0 +1,20 @@ +--- +title: Configuring PDX to Ignore Unread Fields During Deserialization +--- + +Use the `setPdxIgnoreUnreadFields` API to control whether PDX ignores fields that were unread during deserialization. + +The default is to preserve unread fields by including their data during serialization. However, if you configure the cache to ignore unread fields then their data will be lost during serialization. + +You should only set this attribute to `true` if you know this member will only be reading cache data. In this use case you do not need to pay the cost of preserving unread fields since you will never reserialize the PDX data. + +For example: + +``` pre +CacheFactoryPtr cfPtr = CacheFactory::createCacheFactory(PropertiesObj); +cfPtr->setPdxReadSerialized(tue); +cfPtr->setPdxIgnoreUnreadFields(false); +cachePtr = cfPtr->create(); +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_serialization.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_serialization.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_serialization.html.md.erb new file mode 100644 index 0000000..c9f0987 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_serialization.html.md.erb @@ -0,0 +1,43 @@ +--- +title: Serializing Data with PDX Serialization +--- + +PDX is a cross-language data format that can reduce the cost of distributing and serializing your objects. PDX stores data in named fields that you can access individually to avoid the cost of deserializing the entire data object. When you use PDX serialization with the native client C++ API, you can register a `PdxSerializer` for the entire cache, implement PDX serialization for each domain object or use automatic PDX serialization by running the `pdxautoserializer` tool. + +You can also set the object preference of the cache to the `PdxInstance` type, which allows you to access fields of a PDX object without deserializing the entire object. + +When using the native client C++ API, you can opt to use PDX autoserialization. The Geode native client provides a command line tool called `pdxautoserializer` that will automatically generate C++ code to PDX serialize the class you want to serialize. + +- **[Serialize Your Domain Objects with PdxSerializer and PdxWrapper](using_pdxserializer.html)** + + For domain objects that you cannot or do not want to modify, use the `PdxSerializer` and the `PdxWrapper` classes to serialize and deserialize the object's fields. + +- **[Serialize Using the PdxSerializable Class](pdxserializable_interface.html)** + + Domain classes need to inherit the `PdxSerializable` abstract class to serialize and de-serialize the object. When you write objects using PDX serialization, they are distributed to the server tier in PDX serialized form. + +- **[Using Automatic PDX Serialization](pdx_auto_serialization.html)** + + You can allow your native client C++ applications to automatically PDX serialize and deserialize domain objects without having to add any extra code by using the `pdxautoserializer` command line tool provided with the native client. + +- **[Programming Your Application to Use PdxInstances](using_pdxinstance.html)** + + A `PdxInstance` is a lightweight wrapper around the raw bytes of the PDX serialized objects kept in the cache. It provides applications with run-time access to files of a PDX serialized object. Geode provides the implementation of the `PdxInstance` class. + +- **[Configuring PDX to Ignore Unread Fields During Deserialization](pdx_ignore_unread_fields.html)** + + Use the `setPdxIgnoreUnreadFields` API to control whether PDX ignores fields that were unread during deserialization. + +- **[Using PdxInstanceFactory to Create PdxInstances](using_pdxinstancefactory.html)** + + You can use the `PdxInstanceFactory` API to create a `PdxInstance` from raw data when the domain class is not available on the server. + +- **[Using C++ Enum Type with PDX Serialization](using_enum_type_with_pdx.html)** + + Because there is no "object" base type in C++, enums cannot be directly passed as parameters to the `writeObject` and `readObject` API. + +- **[Using PDX Serialization with Delta Propagation](pdx_with_delta_propagation.html)** + + To use delta propagation with PDX serialization, you must implement the `Delta` interface methods. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_with_delta_propagation.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_with_delta_propagation.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_with_delta_propagation.html.md.erb new file mode 100644 index 0000000..492840c --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/pdx_with_delta_propagation.html.md.erb @@ -0,0 +1,28 @@ +--- +title: Using PDX Serialization with Delta Propagation +--- + +<a id="concept_F33AC930A8F14F0A9EE07AC31FFD8C8F__section_6C08121D7A034993A7422985FBC9A0D9"></a> +You can include delta propagation support with PDX serialization by implementing the `Delta` interface methods. +However, using delta propagation with PDX will requires that you implement Java side classes. The objects will remain in deserialized form at all times on the server and you will lose one of the main benefits of PDX. + +In addition, you must set `read-serialized` to `false`. Otherwise, Java objects will be deserialized to instances of `PdxInstance`, which never implements deltas. + +The following code snippet is a sample implementation of the Delta interface methods for using with PDX serialization. + +``` pre +class PdxWithDelta : public PdxSerializable, public Delta +{ +public: + + bool hasDelta(); + void toDelta(DataOutput& output); + void fromDelta(DataInput& input); + DeltaPtr clone(); + +// other PdxSerializable methods here... + +}; +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/pdxserializable_interface.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/pdxserializable_interface.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/pdxserializable_interface.html.md.erb new file mode 100644 index 0000000..1b879d6 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/pdxserializable_interface.html.md.erb @@ -0,0 +1,100 @@ +--- +title: Serialize Using the PdxSerializable Class +--- + +Domain classes need to inherit the `PdxSerializable` abstract class to serialize and de-serialize the object. When you write objects using PDX serialization, they are distributed to the server tier in PDX serialized form. + +When you run queries against the objects on the servers, only the fields you specify are deserialized. A domain class should serialize and de-serialize all its member fields in the same order in its `toData` and `fromData` method. + +Use this procedure to program your domain object for PDX serialization using the `PdxSerializable` abstract class. + +1. In your domain class, implement `PdxSerializable`. Example: + + ``` pre + class PdxObject: public PdxSerializable + ``` + +2. Program the `toData` function to serialize your object as required by your application. + + If you also use PDX serialization in Java or .NET for the object, serialize the object in the same way for each language. Serialize the same fields in the same order and mark the same identity fields. + +3. Program the `fromData` method to read your data fields from the serialized form into the object's fields. + + In your `fromData` implementation, use the same name as you did in `toData` and call the read operations in the same order as you called the write operations in your `toData` implementation. + +4. Optionally, program your domain object's hashCode and equality methods. + + Use the `markIdentityField` method to indicate that the given field name should be included in hashCode and equality checks of this object on a server. + + The fields that are marked as identity fields are used to generate the hashCode and equality methods of PdxInstance. Because of this, the identity fields should themselves either be primitives, or implement hashCode and equals. + + If no fields are set as identity fields, then all fields will be used in hashCode and equality checks. The identity fields should make marked after they are written using a `write`\* method. + +## PdxSerializable Example + +``` pre +class PdxObject: public PdxSerializable { + +private: + uint32_t m_id; + char* m_str; + +public: + PdxObject(){}; + PdxObject(uint32_t id, char* str); + virtual ~PdxObject(); + + uint32_t getID() { + return m_id; + } + + char* getStr(){ + return m_str; + } + + virtual void toData(PdxWriterPtr pw) const; + virtual void fromData(PdxReaderPtr pr); + CacheableStringPtr toString() const; + virtual char* getClassName() const; + static Cacheable* createDeserializable() { + return new PdxObject(); + } +}; + +PdxObject::PdxObject(uint32_t i, char* str) { + m_id = i; + m_str = str; +} + +PdxObject::~PdxObject() { +} + +void PdxObject::toData( PdxWriterPtr pw ) const { + pw->writeInt("id", m_id); + pw->markIdentityField("id"); + pw->writeString("str", m_str); +} + +void PdxObject::fromData( PdxReaderPtr pr ) +{ + m_id = pr->readInt("id"); + m_str = pr->readString("str"); +} + +char* getClassName() const{ +{ + return "com.example.PdxType"; +} + +CacheableStringPtr PdxObject::toString() const { + char idbuf[1024]; + sprintf(idbuf,"PdxObject: [ ID=%d ]",m_id); + return CacheableString::create( idbuf ); +} +``` + +- **[Performing put, get, and localDestroy Operations with a PDX Domain Object](performing_ops_with_pdx_object.html)** + + This topic demonstrates how you can perform operations on a PDX domain object after you have implemented PDX serializable in your domain class. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/performing_ops_with_pdx_object.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/performing_ops_with_pdx_object.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/performing_ops_with_pdx_object.html.md.erb new file mode 100644 index 0000000..50ed34a --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/performing_ops_with_pdx_object.html.md.erb @@ -0,0 +1,43 @@ +--- +title: Performing put, get, and localDestroy Operations with a PDX Domain Object +--- + +This topic demonstrates how you can perform operations on a PDX domain object after you have implemented PDX serializable in your domain class. + +For example, you can perform operations like put, get, and localDestroy with the domain class you defined for PDX serialization in the [PdxSerializable Example](pdxserializable_interface.html#concept_79E4C10E5F634A7F84F96633694B3D69__example_70237026967A42898584AE644D437E69). + +To perform operations, you could write the following application code: + +1. Register the PDX domain class. + + ``` pre + Serializable::registerPdxType(PdxObject::createDeserializable); + ``` + +2. Create the PDX domain object `PdxObject`. + + ``` pre + CacheablePtr pdxobj(new PdxObject(100, "Value-1")); + CacheableKeyPtr keyport = CacheableKey::create("ABC"); + ``` + +3. Here's an example of a put operation. + + ``` pre + rptr->put(keyport, pdxobj); + ``` + +4. Here's an example of locally destroying the entry. + + ``` pre + rptr->localDestroy(keyport); + ``` + +5. Here's an example of a get operation. + + ``` pre + PdxObject *obj2 = dynamic_cast<PdxObject *> ((rptr->get(keyport)).ptr()); + LOGINFO("Debug:Returned ID = %d", obj2->getID()); + ``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/region_data_requiring_serialization.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/region_data_requiring_serialization.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/region_data_requiring_serialization.html.md.erb new file mode 100644 index 0000000..13ee10b --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/region_data_requiring_serialization.html.md.erb @@ -0,0 +1,19 @@ +--- +title: Region Data Requiring Serialization +--- + +Certain region types (including client regions) require serialization. + +Region data in the following types of regions must be serializable: + +- Partitioned regions (except functions that add data locally to a partitioned region use the deserialized form). +- Distributed regions. +- Regions that are persisted or overflowed to disk. +- Server or client regions in a client/server installation. +- Regions distributed between gateways in a multi-site installation. +- Regions that receive events from remote caches. +- Regions that provide function arguments and results. + +To minimize the cost of serialization and deserialization, Geode avoids changing the data format whenever possible. This means your data may be stored in the cache in serialized or deserialized form, depending on how you use it. For example, if a server acts only as a storage location for data distribution between clients, it makes sense to leave the data in serialized form, ready to be transmitted to clients that request it. Partitioned region data is always stored in serialized form with one exceptionâfunctions that add data to a partitioned region locally use the deserialized form. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/cpp-caching-api/removing-entry.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/cpp-caching-api/removing-entry.html.md.erb b/geode-docs/docs/geode-native-docs/cpp-caching-api/removing-entry.html.md.erb new file mode 100644 index 0000000..d661f40 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/cpp-caching-api/removing-entry.html.md.erb @@ -0,0 +1,19 @@ +--- +title: Removing an Entry +--- + +The standard `Region::remove` API removes the entry with specified key and provides a user-defined parameter object to any `CacheWriter` or `CacheListener` invoked in the process. + +The `remove` call not only removes the value, but also the key and entry from this region. The remove operation is propagated to the Geode cache server to which the native client is connected. If the destroy operation fails due to an exception on the server (for example, a `CacheServerException` or security exception), then the local entry is still removed. + +The `remove` operation updates `CacheStatistics::getLastAccessedTime` and `CacheStatistics::getLastModifiedTime` for this region and the entry. + +The `remove` API returns true if the entry (key, value) has been removed or false if the entry (key, value) has not been removed. + +## Bulk Remove Operations Using removeAll + +You can use the `Region::removeAll` API to remove all entries from the region for a collection of specified keys. The effect of this call is equivalent to that of calling `destroy` on this region once for each key in the specified collection. If an entry does not exist, then that key is skipped. Note that an `EntryNotFoundException` is not thrown. + +The `removeAll` API also supports providing a callback argument to any cache loaders or cache writers that are invoked in the operation. See the Region API documentation for more information about using `removeAll`. + +
