diff --git a/Documentation/2.0/Samples/csharp/Raven.Documentation.Samples/ClientApi/ChangesApi.cs b/Documentation/2.0/Samples/csharp/Raven.Documentation.Samples/ClientApi/ChangesApi.cs index 75e83c3497..c718832c27 100644 --- a/Documentation/2.0/Samples/csharp/Raven.Documentation.Samples/ClientApi/ChangesApi.cs +++ b/Documentation/2.0/Samples/csharp/Raven.Documentation.Samples/ClientApi/ChangesApi.cs @@ -1,15 +1,15 @@ namespace RavenCodeSamples.ClientApi { using System; - using Raven.Abstractions.Data; - using Raven.Client.Changes; public class ChangesApi : CodeSampleBase { public ChangesApi() { +/* using (var store = NewDocumentStore()) { + #region getting_database_changes_instance IDatabaseChanges changes = store.Changes("DatabaseName"); @@ -76,6 +76,7 @@ public ChangesApi() }); #endregion } +*/ } } -} \ No newline at end of file +} diff --git a/Documentation/5.4/Samples/csharp/Raven.Documentation.Samples/ClientApi/Operations/Counters/Counters.cs b/Documentation/5.4/Samples/csharp/Raven.Documentation.Samples/ClientApi/Operations/Counters/Counters.cs index 74a2722f23..c58a820bf4 100644 --- a/Documentation/5.4/Samples/csharp/Raven.Documentation.Samples/ClientApi/Operations/Counters/Counters.cs +++ b/Documentation/5.4/Samples/csharp/Raven.Documentation.Samples/ClientApi/Operations/Counters/Counters.cs @@ -157,7 +157,7 @@ public CountersExamples() }, new CounterOperation { - // No delta specified, value will stay the same + // No Delta specified, value will remain unchanged Type = CounterOperationType.Increment, CounterName = "dislikes" diff --git a/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/how-to-subscribe-to-operation-changes.dotnet.markdown b/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/how-to-subscribe-to-operation-changes.dotnet.markdown new file mode 100644 index 0000000000..ea30d0ed3b --- /dev/null +++ b/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/how-to-subscribe-to-operation-changes.dotnet.markdown @@ -0,0 +1,125 @@ +# Changes API: How to Subscribe to Operation Changes + +The following methods allow you to subscribe to operation changes: + +- [ForOperationId](../../client-api/changes/how-to-subscribe-to-operation-changes#foroperationid) +- [ForAllOperations](../../client-api/changes/how-to-subscribe-to-operation-changes#foralloperations) + +{PANEL:ForOperationId} + +Operation changes for one operation can be observed using the `ForOperationId` method. + +{NOTE: } +Please note that from RavenDB 6.1 on, operation changes can be tracked only on a **specific node**. +The purpose of this change is to improve results consistency, as an operation may behave very differently +on different nodes and cross-cluster tracking of an operation may become confusing and ineffective if +the operation fails over from one node to another. +Tracking operations will therefore be possible only if the `Changes` API was +[opened](../../client-api/changes/what-is-changes-api#accessing-changes-api) using a method that limits +tracking to a single node: `store.Changes(dbName, nodeTag)` +{NOTE/} + +### Syntax + +{CODE operation_changes_1@ClientApi\Changes\HowToSubscribeToOperationChanges.cs /} + +| Parameters | | | +| ------------- | ------------- | ----- | +| **operationId** | long | ID of an operation for which notifications will be processed. | + +| Return value | | +| ------------- | ----- | +| IChangesObservable<[OperationStatusChange](../../client-api/changes/how-to-subscribe-to-operation-changes#operationchange)> | Observable that allows you to add subscriptions to notifications for an operation with a given ID. | + +### Example + +{CODE operation_changes_2@ClientApi\Changes\HowToSubscribeToOperationChanges.cs /} + +{PANEL/} + +{PANEL:ForAllOperations} + +Operations changes for all Operations can be observed using the `ForAllOperations` method. + +{NOTE: } +Please note that from RavenDB 6.1 on, operation changes can be tracked only on a **specific node**. +The purpose of this change is to improve results consistency, as an operation may behave very differently +on different nodes and cross-cluster tracking of an operation may become confusing and ineffective if +the operation fails over from one node to another. +Tracking operations will therefore be possible only if the `Changes` API was +[opened](../../client-api/changes/what-is-changes-api#accessing-changes-api) using a method that limits +tracking to a single node: `store.Changes(dbName, nodeTag)` +{NOTE/} + +| Return Value | | +| ------------- | ----- | +| IChangesObservable<[OperationStatusChange](../../client-api/changes/how-to-subscribe-to-operation-changes#operationchange)> | Observable that allows to add subscriptions to notifications for all operations. | + +### Syntax + +{CODE operation_changes_3@ClientApi\Changes\HowToSubscribeToOperationChanges.cs /} + +### Example + +{CODE operation_changes_4@ClientApi\Changes\HowToSubscribeToOperationChanges.cs /} + +{PANEL/} + +{PANEL:OperationChange} + +### Properties + +| Name | Type | Description | +| ------------- | ------------- | ----- | +| **State** | [OperationState](../../client-api/changes/how-to-subscribe-to-operation-changes#operationstate) | Operation state | +| **OperationId** | long | Operation ID | + +{PANEL/} + +{PANEL:OperationState} + +### Members + +| Name | Type | Description | +| ------------- | ------------- | ----- | +| **Result** | [IOperationResult](../../client-api/changes/how-to-subscribe-to-operation-changes#operationresult) | Operation result | +| **Progress** | IOperationProgress| Instance of IOperationProgress (json representation of the progress) | +| **Status** | [OperationStatus](../../client-api/changes/how-to-subscribe-to-operation-changes#operationstatus) | Operation status | +{PANEL/} + +{PANEL:OperationResult} + +### Members + +| Name | Type | Description | +| ------------- | ------------- | ----- | +| **Message** | string | Operation message | +| **ShouldPersist** | bool | determine whether or not the result should be saved in the storage | +{PANEL/} + +{PANEL:OperationStatus} + +# OperationStatus (enum) + +| Name | Description | +| ---- | ----- | +| **InProgress** | `Indicates that the operation made progress` | +| **Completed** | `Indicates that the operation has completed` | +| **Faulted** | `Indicates that the operation is faulted` | +| **Canceled** | `Indicates that the operation has been Canceled` | +{PANEL/} + +## Remarks + +{WARNING: } +To get more method overloads, especially ones supporting **delegates**, please add the +[System.Reactive.Core](https://www.nuget.org/packages/System.Reactive.Core/) package to your project. +{WARNING/} + +## Related Articles + +### Changes API + +- [What is Changes API](../../client-api/changes/what-is-changes-api) +- [How to Subscribe to Document Changes](../../client-api/changes/what-is-changes-api) +- [How to Subscribe to Index Changes](../../client-api/changes/how-to-subscribe-to-index-changes) diff --git a/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/how-to-subscribe-to-operation-changes.java.markdown b/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/how-to-subscribe-to-operation-changes.java.markdown new file mode 100644 index 0000000000..6338a52cb0 --- /dev/null +++ b/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/how-to-subscribe-to-operation-changes.java.markdown @@ -0,0 +1,66 @@ +# Changes API: How to Subscribe to Operation Changes + +The following methods allow you to subscribe to operation changes: + +- [forOperationId](../../client-api/changes/how-to-subscribe-to-operation-changes#foroperation) +- [forAllOperations](../../client-api/changes/how-to-subscribe-to-operation-changes#foralloperations) + +{PANEL:forOperation} + +Operation changes for one operation can be observed using the `forOperationId` method. + +### Syntax + +{CODE:java operation_changes_1@ClientApi\Changes\HowToSubscribeToOperationChanges.java /} + +| Parameters | | | +| ------------- | ------------- | ----- | +| **operationId** | long | ID of an operation for which notifications will be processed. | + +| Return value | | +| ------------- | ----- | +| IChangesObservable<[OperationStatusChange](../../client-api/changes/how-to-subscribe-to-operation-changes#operationchange)> | Observable that allows you to add subscriptions to notifications for an operation with a given ID. | + +### Example + +{CODE:java operation_changes_2@ClientApi\Changes\HowToSubscribeToOperationChanges.java /} + +{PANEL/} + +{PANEL:forAllOperations} + +Operations changes for all Operations can be observed using the `forAllOperations` method. + +| Return Value | | +| ------------- | ----- | +| IChangesObservable<[OperationStatusChange](../../client-api/changes/how-to-subscribe-to-operation-changes#operationchange)> | Observable that allows to add subscriptions to notifications for all operations. | + +### Syntax + +{CODE:java operation_changes_3@ClientApi\Changes\HowToSubscribeToOperationChanges.java /} + +### Example + +{CODE:java operation_changes_4@ClientApi\Changes\HowToSubscribeToOperationChanges.java /} + +{PANEL/} + +{PANEL:OperationChange} + +### Properties + +| Name | Type | Description | +| ------------- | ------------- | ----- | +| **State** | ObjectNode | Operation state | +| **OperationId** | long | Operation ID | + +{PANEL/} + + +## Related Articles + +### Changes API + +- [What is Changes API](../../client-api/changes/what-is-changes-api) +- [How to Subscribe to Document Changes](../../client-api/changes/what-is-changes-api) +- [How to Subscribe to Index Changes](../../client-api/changes/how-to-subscribe-to-index-changes) diff --git a/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/how-to-subscribe-to-operation-changes.js.markdown b/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/how-to-subscribe-to-operation-changes.js.markdown new file mode 100644 index 0000000000..7cc042661c --- /dev/null +++ b/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/how-to-subscribe-to-operation-changes.js.markdown @@ -0,0 +1,66 @@ +# Changes API: How to Subscribe to Operation Changes + +The following methods allow you to subscribe to operation changes: + +- [forOperationId()](../../client-api/changes/how-to-subscribe-to-operation-changes#foroperation) +- [forAllOperations()](../../client-api/changes/how-to-subscribe-to-operation-changes#foralloperations) + +{PANEL:forOperation} + +Operation changes for one operation can be observed using the `forOperationId()` method. + +### Syntax + +{CODE:nodejs operation_changes_1@client-api\changes\howToSubscribeToOperationChanges.js /} + +| Parameters | | | +| ------------- | ------------- | ----- | +| **operationId** | number | ID of an operation for which notifications will be processed. | + +| Return value | | +| ------------- | ----- | +| IChangesObservable<[OperationStatusChange](../../client-api/changes/how-to-subscribe-to-operation-changes#operationchange)> | Observable that allows you to add subscriptions to notifications for an operation with a given ID. | + +### Example + +{CODE:nodejs operation_changes_2@client-api\changes\howToSubscribeToOperationChanges.js /} + +{PANEL/} + +{PANEL:forAllOperations} + +Operations changes for all Operations can be observed using the `forAllOperations()` method. + +| Return Value | | +| ------------- | ----- | +| IChangesObservable<[OperationStatusChange](../../client-api/changes/how-to-subscribe-to-operation-changes#operationchange)> | Observable that allows to add subscriptions to notifications for all operations. | + +### Syntax + +{CODE:nodejs operation_changes_3@client-api\changes\howToSubscribeToOperationChanges.js /} + +### Example + +{CODE:nodejs operation_changes_4@client-api\changes\howToSubscribeToOperationChanges.js /} + +{PANEL/} + +{PANEL:OperationChange} + +### Properties + +| Name | Type | Description | +| ------------- | ------------- | ----- | +| **state** | object | Operation state | +| **operationId** | number | Operation ID | + +{PANEL/} + + +## Related Articles + +### Changes API + +- [What is Changes API](../../client-api/changes/what-is-changes-api) +- [How to Subscribe to Document Changes](../../client-api/changes/what-is-changes-api) +- [How to Subscribe to Index Changes](../../client-api/changes/how-to-subscribe-to-index-changes) diff --git a/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/what-is-changes-api.dotnet.markdown b/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/what-is-changes-api.dotnet.markdown new file mode 100644 index 0000000000..6f8f49d9af --- /dev/null +++ b/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/what-is-changes-api.dotnet.markdown @@ -0,0 +1,187 @@ +# What Is the Changes API + +--- + +{NOTE: } + +* The Changes API is a Push Notifications service, that allows a RavenDB Client to + receive messages from a RavenDB Server regarding events that occurred on the server. +* A client can subscribe to events related to documents, indexes, operations, counters, and time series. +* Using the Changes API allows you to notify users of various changes without requiring + any expensive polling. + +* In this page: + * [Accessing Changes API](../../client-api/changes/what-is-changes-api#accessing-changes-api) + * [Connection interface](../../client-api/changes/what-is-changes-api#connection-interface) + * [Subscribing](../../client-api/changes/what-is-changes-api#subscribing) + * [Unsubscribing](../../client-api/changes/what-is-changes-api#unsubscribing) + * [FAQ](../../client-api/changes/what-is-changes-api#faq) + * [Changes API and Database Timeout](../../client-api/changes/what-is-changes-api#changes-api-and-database-timeout) + * [Changes API and Method Overloads](../../client-api/changes/what-is-changes-api#changes-api-and-method-overloads) + * [Changes API -vs- Data Subscriptions](../../client-api/changes/what-is-changes-api#changes-api--vs--data-subscriptions) +{NOTE/} + +--- + +{PANEL: Accessing Changes API} + +The changes subscription is accessible by a document store through its `IDatabaseChanges` +or `ISingleNodeDatabaseChanges` interfaces. + +{CODE changes_1@ClientApi\Changes\WhatIsChangesApi.cs /} +{CODE changes_ISingleNodeDatabaseChanges@ClientApi\Changes\WhatIsChangesApi.cs /} + +| Parameters | | | +| ------------- | ------------- | ----- | +| **database** | `string` | Name of database to open changes API for. If `null`, the `Database` configured in DocumentStore will be used. | +| **nodeTag** | `string` | Tag of the cluster node to open changes API for. | + +| Return value | | +| ------------- | ----- | +| `IDatabaseChanges` | Instance implementing `IDatabaseChanges` interface. | +| `ISingleNodeDatabaseChanges` | Instance implementing `ISingleNodeDatabaseChanges` interface. | + +* Use `IDatabaseChanges` to subscribe to database changes. +* Use `ISingleNodeDatabaseChanges` to limit tracking to a specific node. + {NOTE: } + Note that from RavenDB 6.1 on, some changes can be tracked not cross-cluster but only + **on a specific node**. In these cases, it is required that you open the Changes API using + the second overload, passing both a database name and a node tag: `store.Changes(dbName, nodeTag)` + {NOTE/} + +{PANEL/} + +{PANEL: Connection interface} + +`IDatabaseChanges` inherits from `IConnectableChanges` interface that represent the connection. + +{CODE connectable_changes@ClientApi\Changes\IConnectableChanges.cs /} + +{PANEL/} + +{PANEL: Subscribing} + +To receive notifications regarding server-side events, subscribe using one of the following methods. + +* **For Document Changes:** + - [ForAllDocuments](../../client-api/changes/how-to-subscribe-to-document-changes#foralldocuments) + Track changes for all document + - [ForDocument](../../client-api/changes/how-to-subscribe-to-document-changes#fordocument) + Track changes for a given document (by Doc ID) + - [ForDocumentsInCollection](../../client-api/changes/how-to-subscribe-to-document-changes#fordocumentsincollection) + Track changes for all documents in a given collection + - [ForDocumentsStartingWith](../../client-api/changes/how-to-subscribe-to-document-changes#fordocumentsstartingwith) + Track changes for documents whose ID contains a given prefix + +* **For Index Changes:** + - [ForAllIndexes](../../client-api/changes/how-to-subscribe-to-index-changes#forallindexes) + Track changes for all indexes + - [ForIndex](../../client-api/changes/how-to-subscribe-to-index-changes#forindex) + Track changes for a given index (by Index Name) + +* **For Operation Changes:** + Operation changes can be tracked only [on a specific node](../../client-api/changes/what-is-changes-api#accessing-changes-api). + - [ForAllOperations](../../client-api/changes/how-to-subscribe-to-operation-changes#foralloperations) + Track changes for all operation + - [ForOperationId](../../client-api/changes/how-to-subscribe-to-operation-changes#foroperationid) + Track changes for a given operation (by Operation ID) + +* **For Counter Changes:** + - [ForAllCounters](../../client-api/changes/how-to-subscribe-to-counter-changes#forallcounters) + Track changes for all counters + - [ForCounter](../../client-api/changes/how-to-subscribe-to-counter-changes#forcounter) + Track changes for a given counter (by Counter Name) + - [ForCounterOfDocument](../../client-api/changes/how-to-subscribe-to-counter-changes#forcounterofdocument) + Track changes for a specific counter of a chosen document (by Doc ID and Counter Name) + - [ForCountersOfDocument](../../client-api/changes/how-to-subscribe-to-counter-changes#forcountersofdocument) + Track changes for all counters of a chosen document (by Doc ID) + +* **For Time Series Changes:** + - [ForAllTimeSeries](../../client-api/changes/how-to-subscribe-to-time-series-changes#foralltimeseries) + Track changes for all time series + - [ForTimeSeries](../../client-api/changes/how-to-subscribe-to-time-series-changes#fortimeseries) + Track changes for all time series with a given name + - [ForTimeSeriesOfDocument](../../client-api/changes/how-to-subscribe-to-time-series-changes#fortimeseriesofdocument) + Track changes for - + * a **specific time series** of a given document (by Doc ID and Time Series Name) + * **any time series** of a given document (by Doc ID) + +{PANEL/} + +{PANEL: Unsubscribing} + +To end a subscription (stop listening for particular notifications) you must +`Dispose` of the subscription. + +{CODE changes_2@ClientApi\Changes\WhatIsChangesApi.cs /} + +{PANEL/} + +{PANEL: FAQ} + +#### Changes API and Database Timeout + +One or more open Changes API connections will prevent a database from becoming +idle and unloaded, regardless of [the configuration value for database idle timeout](../../server/configuration/database-configuration#databases.maxidletimeinsec). + +--- + +#### Changes API and Method Overloads + +{WARNING: } +To get more method overloads, especially ones supporting **delegates**, please add the +[System.Reactive.Core](https://www.nuget.org/packages/System.Reactive.Core/) package to your project. +{WARNING/} + +{PANEL/} + +{PANEL: Changes API -vs- Data Subscriptions} + +**Changes API** and [Data Subscription](../../client-api/data-subscriptions/what-are-data-subscriptions) +are services that a RavenDB Server provides subscribing clients. +Both services respond to events that take place on the server, by sending updates +to their subscribers. + +* **Changes API is a Push Notifications Service**. + * Changes API subscribers receive **notifications** regarding events that + took place on the server, without receiving the actual data entities + affected by these events. + For the modification of a document, for example, the client will receive + a [DocumentChange](../../client-api/changes/how-to-subscribe-to-document-changes#documentchange) + object with details like the document's ID and collection name. + + * The server does **not** keep track of sent notifications or + checks clients' usage of them. It is a client's responsibility + to manage its reactions to such notifications. + +* **Data Subscription is a Data Consumption Service**. + * A Data Subscription task keeps track of document modifications in the + database and delivers the documents in an orderly fashion when subscribers + indicate they are ready to receive them. + * The process is fully managed by the server, leaving very little for + the subscribers to do besides consuming the delivered documents. + +--- + +| | Data Subscriptions | Changes API +| -- | -- | +| What can the server Track | [Documents](../../client-api/data-subscriptions/what-are-data-subscriptions#documents-processing)
[Revisions](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning)
[Counters](../../client-api/data-subscriptions/creation/examples#including-counters)
Time Series | [Documents](../../client-api/changes/how-to-subscribe-to-document-changes)
[Indexes](../../client-api/changes/how-to-subscribe-to-index-changes)
[Operations](../../client-api/changes/how-to-subscribe-to-operation-changes)
[Counters](../../client-api/changes/how-to-subscribe-to-counter-changes)
[Time Series](../../client-api/changes/how-to-subscribe-to-time-series-changes) +| What can the server Deliver | Documents
Revisions
Counters
Time Series | Notifications +| Management | Managed by the Server | Managed by the Client + + +{PANEL/} + +## Related Articles + +### Changes API + +- [How to Subscribe to Document Changes](../../client-api/changes/how-to-subscribe-to-document-changes) +- [How to Subscribe to Index Changes](../../client-api/changes/how-to-subscribe-to-index-changes) +- [How to Subscribe to Operation Changes](../../client-api/changes/how-to-subscribe-to-operation-changes) +- [How to Subscribe to Counter Changes](../../client-api/changes/how-to-subscribe-to-counter-changes) +- [How to Subscribe to Time Series Changes](../../client-api/changes/how-to-subscribe-to-time-series-changes) + +### Data Subscriptions + +- [What Are Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions) diff --git a/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/what-is-changes-api.java.markdown b/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/what-is-changes-api.java.markdown new file mode 100644 index 0000000000..24a4450f10 --- /dev/null +++ b/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/what-is-changes-api.java.markdown @@ -0,0 +1,124 @@ +# What Is the Changes API + +--- + +{NOTE: } + +* The Changes API is a Push Notifications service, that allows a RavenDB Client to + receive messages from a RavenDB Server regarding events that occurred on the server. +* A client can subscribe to events related to documents, indexes, operations, counters, and time series. +* Using the Changes API allows you to notify users of various changes without requiring + any expensive polling. + +* In this page: + * [Accessing Changes API](../../client-api/changes/what-is-changes-api#accessing-changes-api) + * [Connection interface](../../client-api/changes/what-is-changes-api#connection-interface) + * [Subscribing](../../client-api/changes/what-is-changes-api#subscribing) + * [Unsubscribing](../../client-api/changes/what-is-changes-api#unsubscribing) + * [Note](../../client-api/changes/what-is-changes-api#note) + * [Changes API -vs- Data Subscriptions](../../client-api/changes/what-is-changes-api#changes-api--vs--data-subscriptions) +{NOTE/} + +--- + +{PANEL: Accessing Changes API} + +The changes subscription is accessible by a document store through its `IDatabaseChanges` interface. + +{CODE:java changes_1@ClientApi\Changes\WhatIsChangesApi.java /} + +| Parameters | | | +| ------------- | ------------- | ----- | +| **database** | `String` | Name of database to open changes API for. If `null`, the `Database` configured in DocumentStore will be used. | + +| Return value | | +| ------------- | ----- | +| IDatabaseChanges | Instance implementing IDatabaseChanges interface. | + +{PANEL/} + +{PANEL: Connection interface} + +`IDatabaseChanges` inherits from `IConnectableChanges` interface that represent the connection. + +{CODE:java connectable_changes@ClientApi\Changes\IConnectableChanges.java /} + +{PANEL/} + +{PANEL: Subscribing} + +To receive notifications regarding server-side events, subscribe using one of the following methods. + +- [forAllDocuments](../../client-api/changes/how-to-subscribe-to-document-changes#foralldocuments) +- [forAllIndexes](../../client-api/changes/how-to-subscribe-to-index-changes#forallindexes) +- [forAllOperations](../../client-api/changes/how-to-subscribe-to-operation-changes#foralloperations) +- [forDocument](../../client-api/changes/how-to-subscribe-to-document-changes#fordocument) +- [forDocumentsInCollection](../../client-api/changes/how-to-subscribe-to-document-changes#fordocumentsincollection) +- [forDocumentsStartingWith](../../client-api/changes/how-to-subscribe-to-document-changes#fordocumentsstartingwith) +- [forIndex](../../client-api/changes/how-to-subscribe-to-index-changes#forindex) +- [forOperationId](../../client-api/changes/how-to-subscribe-to-operation-changes#foroperation) + +{PANEL/} + +{PANEL: Unsubscribing} + +To end a subscription (stop listening for particular notifications) you must +`close` the subscription. + +{CODE:java changes_2@ClientApi\Changes\WhatIsChangesApi.java /} + +{PANEL/} + +{PANEL: Note} + +{NOTE: } +One or more open Changes API connections will prevent a database from becoming +idle and unloaded, regardless of [the configuration value for database idle timeout](../../server/configuration/database-configuration#databases.maxidletimeinsec). +{NOTE/} + +{PANEL/} + +{PANEL: Changes API -vs- Data Subscriptions} + +**Changes API** and [Data Subscription](../../client-api/data-subscriptions/what-are-data-subscriptions) +are services that a RavenDB Server provides subscribing clients. +Both services respond to events that take place on the server, by sending updates +to their subscribers. + +* **Changes API is a Push Notifications Service**. + * Changes API subscribers receive **notifications** regarding events that + took place on the server, without receiving the actual data entities + affected by these events. + For the modification of a document, for example, the client will receive + a [DocumentChange](../../client-api/changes/how-to-subscribe-to-document-changes#documentchange) + object with details like the document's ID and collection name. + + * The server does **not** keep track of sent notifications or + checks clients' usage of them. It is a client's responsibility + to manage its reactions to such notifications. + +* **Data Subscription is a Data Consumption Service**. + * A Data Subscription task keeps track of document modifications in the + database and delivers the documents in an orderly fashion when subscribers + indicate they are ready to receive them. + * The process is fully managed by the server, leaving very little for + the subscribers to do besides consuming the delivered documents. + +--- + +| | Data Subscriptions | Changes API +| -- | -- | +| What can the server Track | [Documents](../../client-api/data-subscriptions/what-are-data-subscriptions#documents-processing)
[Revisions](../../client-api/data-subscriptions/advanced-topics/subscription-with-revisioning) | [Documents](../../client-api/changes/how-to-subscribe-to-document-changes)
[Indexes](../../client-api/changes/how-to-subscribe-to-index-changes)
[Operations](../../client-api/changes/how-to-subscribe-to-operation-changes)
[Counters](../../client-api/changes/how-to-subscribe-to-counter-changes)
Time Series +| What can the server Deliver | Documents
Revisions | Notifications +| Management | Managed by the Server | Managed by the Client + + +{PANEL/} + +## Related Articles + +### Changes API + +- [How to Subscribe to Document Changes](../../client-api/changes/what-is-changes-api) +- [How to Subscribe to Index Changes](../../client-api/changes/how-to-subscribe-to-index-changes) +- [How to Subscribe to Operation Changes](../../client-api/changes/how-to-subscribe-to-operation-changes) diff --git a/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/what-is-changes-api.js.markdown b/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/what-is-changes-api.js.markdown new file mode 100644 index 0000000000..da41d79fb6 --- /dev/null +++ b/Documentation/6.1/Raven.Documentation.Pages/client-api/changes/what-is-changes-api.js.markdown @@ -0,0 +1,139 @@ +# What Is the Changes API + +--- + +{NOTE: } + +* The Changes API is a Push Notifications service, that allows a RavenDB Client to + receive messages from a RavenDB Server regarding events that occurred on the server. +* A client can subscribe to events related to documents, indexes, operations, counters, and time series. +* Using the Changes API allows you to notify users of various changes without requiring + any expensive polling. + +* In this page: + * [Accessing Changes API](../../client-api/changes/what-is-changes-api#accessing-changes-api) + * [Connection interface](../../client-api/changes/what-is-changes-api#connection-interface) + * [Subscribing](../../client-api/changes/what-is-changes-api#subscribing) + * [Unsubscribing](../../client-api/changes/what-is-changes-api#unsubscribing) + * [FAQ](../../client-api/changes/what-is-changes-api#faq) + * [Changes API and Database Timeout](../../client-api/changes/what-is-changes-api#changes-api-and-database-timeout) + * [Changes API and Method Overloads](../../client-api/changes/what-is-changes-api#changes-api-and-method-overloads) + * [Changes API -vs- Data Subscriptions](../../client-api/changes/what-is-changes-api#changes-api--vs--data-subscriptions) +{NOTE/} + +--- + +{PANEL: Accessing Changes API} + +The changes subscription is accessible by a document store through its `IDatabaseChanges` interface. + +{CODE:nodejs changes_1@client-api\changes\whatIsChangesApi.js /} + +| Parameters | | | +| ------------- | ------------- | ----- | +| **database** | `string` | Name of database to open changes API for. If `null`, the `database` configured in DocumentStore will be used. | + +| Return value | | +| ------------- | ----- | +| `IDatabaseChanges` object | Instance implementing IDatabaseChanges interface. | + +{PANEL/} + +{PANEL: Connection interface} + +Changes object interface extends `IConnectableChanges` interface that represents the connection. It exposes the following properties, methods and events. + +| Properties and methods | | | +| ------------- | ------------- | ----- | +| **connected** | boolean | Indicates whether it's connected or not | +| **on("connectionStatus")** | method | Adds a listener for 'connectionStatus' event | +| **on("error")** | method | Adds a listener for 'error' event | +| **ensureConnectedNow()** | method | Returns a `Promise` resolved once connection to the server is established. | + +{PANEL/} + +{PANEL: Subscribing} + +To receive notifications regarding server-side events, subscribe using one of the following methods. + +- [forAllDocuments()](../../client-api/changes/how-to-subscribe-to-document-changes#foralldocuments) +- [forAllIndexes()](../../client-api/changes/how-to-subscribe-to-index-changes#forallindexes) +- [forAllOperations()](../../client-api/changes/how-to-subscribe-to-operation-changes#foralloperations) +- [forDocument()](../../client-api/changes/how-to-subscribe-to-document-changes#fordocument) +- [forDocumentsInCollection()](../../client-api/changes/how-to-subscribe-to-document-changes#fordocumentsincollection) +- [forDocumentsStartingWith()](../../client-api/changes/how-to-subscribe-to-document-changes#fordocumentsstartingwith) +- [forIndex()](../../client-api/changes/how-to-subscribe-to-index-changes#forindex) +- [forOperationId()](../../client-api/changes/how-to-subscribe-to-operation-changes#foroperation) + +{PANEL/} + +{PANEL: Unsubscribing} + +To end a subscription (stop listening for particular notifications) use `dispose`. + +{CODE:nodejs changes_2@client-api\changes\whatIsChangesApi.js /} + +{PANEL/} + +{PANEL: FAQ} + +#### Changes API and Database Timeout + +One or more open Changes API connections will prevent a database from becoming +idle and unloaded, regardless of [the configuration value for database idle timeout](../../server/configuration/database-configuration#databases.maxidletimeinsec). + +--- + +#### Changes API and Method Overloads + +{WARNING: } +To get more method overloads, especially ones supporting **delegates**, please add the +[System.Reactive.Core](https://www.nuget.org/packages/System.Reactive.Core/) package to your project. +{WARNING/} + +{PANEL/} + +{PANEL: Changes API -vs- Data Subscriptions} + +**Changes API** and [Data Subscription](../../client-api/data-subscriptions/what-are-data-subscriptions) +are services that a RavenDB Server provides subscribing clients. +Both services respond to events that take place on the server, by sending updates +to their subscribers. + +* **Changes API is a Push Notifications Service**. + * Changes API subscribers receive **notifications** regarding events that + took place on the server, without receiving the actual data entities + affected by these events. + For the modification of a document, for example, the client will receive + a [DocumentChange](../../client-api/changes/how-to-subscribe-to-document-changes#documentchange) + object with details like the document's ID and collection name. + + * The server does **not** keep track of sent notifications or + checks clients' usage of them. It is a client's responsibility + to manage its reactions to such notifications. + +* **Data Subscription is a Data Consumption Service**. + * A Data Subscription task keeps track of document modifications in the + database and delivers the documents in an orderly fashion when subscribers + indicate they are ready to receive them. + * The process is fully managed by the server, leaving very little for + the subscribers to do besides consuming the delivered documents. + +--- + +| | Data Subscriptions | Changes API +| -- | -- | +| What can the server Track | [Documents](../../client-api/data-subscriptions/what-are-data-subscriptions#documents-processing)
Revisions | [Documents](../../client-api/changes/how-to-subscribe-to-document-changes)
[Indexes](../../client-api/changes/how-to-subscribe-to-index-changes)
[Operations](../../client-api/changes/how-to-subscribe-to-operation-changes)
Counters
Time Series +| What can the server Deliver | Documents
Revisions | Notifications +| Management | Managed by the Server | Managed by the Client + + +{PANEL/} + +## Related Articles + +### Changes API + +- [How to Subscribe to Document Changes](../../client-api/changes/what-is-changes-api) +- [How to Subscribe to Index Changes](../../client-api/changes/how-to-subscribe-to-index-changes) +- [How to Subscribe to Operation Changes](../../client-api/changes/how-to-subscribe-to-operation-changes) diff --git a/Documentation/6.1/Raven.Documentation.Pages/client-api/operations/compare-exchange/put-compare-exchange-value.dotnet.markdown b/Documentation/6.1/Raven.Documentation.Pages/client-api/operations/compare-exchange/put-compare-exchange-value.dotnet.markdown new file mode 100644 index 0000000000..4e26e9e6bc --- /dev/null +++ b/Documentation/6.1/Raven.Documentation.Pages/client-api/operations/compare-exchange/put-compare-exchange-value.dotnet.markdown @@ -0,0 +1,75 @@ +# Put Compare Exchange Operation + +--- + +{NOTE: } + +* Use `PutCompareExchangeValueOperation` to save a compare-exchange _Value_ for the specified _Key_. + +* Create a new _Key_ or modify an existing one. + +* The _Value_ is saved only if the passed _index_ is equal to the _index_ currently stored in the server for the specified _Key_. + +* Creating a new compare exchange item is possible only when the passed _index_ is `0`. + +* For an overview of the 'Compare Exchange' feature see: [Compare Exchange Overview](../../../client-api/operations/compare-exchange/overview). + +* In this page: + * [Syntax](../../../client-api/operations/compare-exchange/put-compare-exchange-value#syntax) + * [Example I - Create a new key](../../../client-api/operations/compare-exchange/put-compare-exchange-value#example-i---create-a-new-key) + * [Example II - Update an existing key](../../../client-api/operations/compare-exchange/put-compare-exchange-value#example-ii---update-an-existing-key) + * [Example III - Try to create an item with a non-zero index](../../../client-api/operations/compare-exchange/put-compare-exchange-value#example-iii---try-to-create-an-item-with-a-non-zero-index) + +{NOTE/} + +--- + +{PANEL: Syntax} + +**Method**: +{CODE put_0@ClientApi\Operations\CompareExchange\CompareExchange.cs /} + +| Parameter | Type | Description | +| ----------| ---- |------------ | +| **key** | `string` | Object identifier under which _value_ is saved, unique in the database scope across the cluster. This string can be up to 512 bytes. | +| **value** | `T` | The value to be saved for the specified _key_. | +| **index** | `long` | * `0` if creating a new key
* The current version of _Value_ when updating a value for an existing key. | + +**Returned object**: +{CODE compare_exchange_result@ClientApi\Operations\CompareExchange\CompareExchange.cs /} + +| Return Value | Type | Description | +| ------------ | - | - | +| **Successful** | `bool` | * _True_ if the save operation has completed successfully
* _False_ if the save operation failed | +| **Value** | `T` | * The value that was saved if operation was successful
* The currently existing value in the server upon failure | +| **Index** | `long` | * The version number of the value that was saved upon success
* The currently existing version number in the server upon failure | + +{NOTE: Note:} +When calling the 'Put' operation, the index from the request is compared to the index that is currently stored in the server (compare stage). +The value is updated only if the two are **equal** (exchange stage). +{NOTE/} +{PANEL/} + +{PANEL: Example I - Create a new key} + +{CODE put_1@ClientApi\Operations\CompareExchange\CompareExchange.cs /} +{PANEL/} + +{PANEL: Example II - Update an existing key} + +{CODE put_2@ClientApi\Operations\CompareExchange\CompareExchange.cs /} +{PANEL/} + +{PANEL: Example III - Try to create an item with a non-zero index} + +{CODE put_3@ClientApi\Operations\CompareExchange\CompareExchange.cs /} +{PANEL/} + +## Related Articles + +### Compare Exchange + +- [Overview](../../../client-api/operations/compare-exchange/overview) +- [Get compare-exchange value](../../../client-api/operations/compare-exchange/get-compare-exchange-value) +- [Get compare-exchange values](../../../client-api/operations/compare-exchange/get-compare-exchange-values) +- [Delete compare-exchange](../../../client-api/operations/compare-exchange/delete-compare-exchange-value) diff --git a/Documentation/6.1/Raven.Documentation.Pages/client-api/operations/compare-exchange/put-compare-exchange-value.java.markdown b/Documentation/6.1/Raven.Documentation.Pages/client-api/operations/compare-exchange/put-compare-exchange-value.java.markdown new file mode 100644 index 0000000000..3bf23f4655 --- /dev/null +++ b/Documentation/6.1/Raven.Documentation.Pages/client-api/operations/compare-exchange/put-compare-exchange-value.java.markdown @@ -0,0 +1,66 @@ +# Put Compare Exchange Operation + +--- + +{NOTE: } + +* Use `PutCompareExchangeValueOperation` to save a compare-exchange _Value_ for the specified _Key_. + +* Create a new _Key_ or modify an existing one. + +* The _Value_ is saved only if the _index_ passed is equal to the _index_ currently stored in the server for the specified _Key_. + +* For an overview of the 'Compare Exchange' feature see: [Compare Exchange Overview](../../../client-api/operations/compare-exchange/overview). + +* In this page: + * [Syntax](../../../client-api/operations/compare-exchange/put-compare-exchange-value#syntax) + * [Example I - Create a new key](../../../client-api/operations/compare-exchange/put-compare-exchange-value#example-i---create-a-new-key) + * [Example II - Update an existing key](../../../client-api/operations/compare-exchange/put-compare-exchange-value#example-ii---update-an-existing-key) +{NOTE/} + +--- + +{PANEL: Syntax} + +**Method**: +{CODE:java put_0@ClientApi\Operations\CompareExchange\CompareExchange.java /} + +| Parameter | Type | Description | +| ----------| ---- |------------ | +| **key** | String | Object identifier under which _value_ is saved, unique in the database scope across the cluster. This string can be up to 512 bytes. | +| **value** | `T` | The value to be saved for the specified _key_. | +| **index** | long | * `0` if creating a new key
* The current version of _Value_ when updating a value for an existing key. | + +**Returned object**: +{CODE:java compare_exchange_result@ClientApi\Operations\CompareExchange\CompareExchange.java /} + +| Return Value | Type | Description | +| ------------ | - | - | +| **Successful** | boolean | * _True_ if the save operation has completed successfully
* _False_ if the save operation failed | +| **Value** | `T` | * The value that was saved if operation was successful
* The currently existing value in the server upon failure | +| **Index** | long | * The version number of the value that was saved upon success
* The currently existing version number in the server upon failure | + +{NOTE: Note:} +When calling the 'Put' operation, the index from the request is compared to the index that is currently stored in the server (compare stage). +The value is updated only if the two are **equal** (exchange stage). +{NOTE/} +{PANEL/} + +{PANEL: Example I - Create a new key} + +{CODE:java put_1@ClientApi\Operations\CompareExchange\CompareExchange.java /} +{PANEL/} + +{PANEL: Example II - Update an existing key} + +{CODE:java put_2@ClientApi\Operations\CompareExchange\CompareExchange.java /} +{PANEL/} + +## Related Articles + +### Compare Exchange + +- [Overview](../../../client-api/operations/compare-exchange/overview) +- [Get compare-exchange value](../../../client-api/operations/compare-exchange/get-compare-exchange-value) +- [Get compare-exchange values](../../../client-api/operations/compare-exchange/get-compare-exchange-values) +- [Delete compare-exchange](../../../client-api/operations/compare-exchange/delete-compare-exchange-value) diff --git a/Documentation/6.1/Raven.Documentation.Pages/client-api/operations/compare-exchange/put-compare-exchange-value.js.markdown b/Documentation/6.1/Raven.Documentation.Pages/client-api/operations/compare-exchange/put-compare-exchange-value.js.markdown new file mode 100644 index 0000000000..48d19070f8 --- /dev/null +++ b/Documentation/6.1/Raven.Documentation.Pages/client-api/operations/compare-exchange/put-compare-exchange-value.js.markdown @@ -0,0 +1,79 @@ +# Put Compare Exchange Operation +--- + +{NOTE: } + + +* Use the `PutCompareExchangeValueOperation` operation to either: + * **Create** a new compare-exchange item + * **Update** the value or metadata of an existing compare-exchange item + +* Compare-exchange items can also be managed via [advanced session](../../../client-api/session/cluster-transaction/compare-exchange) methods + or from the [Studio](../../../studio/database/documents/compare-exchange-view). + +* In this page: + * [Create new cmpXchg item](../../../client-api/operations/compare-exchange/put-compare-exchange-value#create-new-cmpxchg-item) + * [Create new cmpXchg item with metadata](../../../client-api/operations/compare-exchange/put-compare-exchange-value#create-new-cmpxchg-item-with-metadata) + * [Update existing cmpXchg item](../../../client-api/operations/compare-exchange/put-compare-exchange-value#update-existing-cmpxchg-item) + * [Syntax](../../../client-api/operations/compare-exchange/put-compare-exchange-value#syntax) + +{NOTE/} + +--- + +{PANEL: Create new cmpXchg item} + +{CODE:nodejs put_1@client-api\operations\compareExchange\putCompareExchange.js /} + +* Note: + Using `0` with a key that already exists will Not modify existing compare-exchange item. + +{PANEL/} + +{PANEL: Create new cmpXchg item with metadata} + +{CODE:nodejs put_2@client-api\operations\compareExchange\putCompareExchange.js /} + +* Find more examples of adding metadata to a compare-exchange item in [compare-exchange metadata](../../../client-api/operations/compare-exchange/compare-exchange-metadata). + +{PANEL/} + +{PANEL: Update existing cmpXchg item} + +* When calling `PutCompareExchangeValueOperation`, + the index from the request is compared to the index that is currently stored in the server for the specified _key_. +* The compare-exchange item is updated only if the two are equal. + +{CODE:nodejs put_3@client-api\operations\compareExchange\putCompareExchange.js /} + +{PANEL/} + +{PANEL: Syntax} + +{CODE:nodejs syntax_1@client-api\operations\compareExchange\putCompareExchange.js /} + +| Parameter | Type | Description | +|---------------|-------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| **key** | `string` |