diff --git a/Documentation/5.4/Raven.Documentation.Pages/client-api/data-subscriptions/advanced-topics/maintenance-operations.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/client-api/data-subscriptions/advanced-topics/maintenance-operations.dotnet.markdown new file mode 100644 index 000000000..7bd523087 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/client-api/data-subscriptions/advanced-topics/maintenance-operations.dotnet.markdown @@ -0,0 +1,151 @@ +# Data Subscriptions: Maintenance Operations + +--- + +{NOTE: } + +* This article covers data subscriptions maintenance operations. + +* In this page: + * [DocumentSubscriptions class](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#documentsubscriptions-class) + * [Delete subscription](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#delete-subscription) + * [Disabling subscription](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#disable-subscription) + * [Enable subscription](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#enable-subscription) + * [Update subscription](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#update-subscription) + * [Drop Connection](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#drop-connection) + * [Get subscription state](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#get-subscription-state) + +{NOTE/} + +--- + +{PANEL: DocumentSubscriptions class} + +The `DocumentSubscriptions` class is the class that manages all interaction with the data subscriptions. +The class is available through `DocumentStore`'s `Subscriptions` property. + +| Method Signature | Return type | Description | +|---------------------------------------------------------------------------------------------------------------|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| +| **Create(SubscriptionCreationOptions options, string database)** | `string` | Create a new data subscription. | +| **Create(SubscriptionCreationOptions criteria, string database)** | `string` | Create a new data subscription. | +| **Create(SubscriptionCreationOptions criteria, string database)** | `string` | Create a new data subscription. | +| **CreateAsync(SubscriptionCreationOptions options, string database)** | `Task` | Create a new data subscription. | +| **CreateAsync(Expression> predicate, SubscriptionCreationOptions options, string database)** | `Task` | Create a new data subscription. | +| **Delete(string name, string database)** | `void` | Delete subscription. | +| **DeleteAsync(string name, string database)** | `Task` | Delete subscription. | +| **DropConnection(string name, string database)** | `void` | Drop all existing subscription connections with workers. | +| **DropConnectionAsync(string name, string database)** | `Task` | Drop all existing subscription connections with workers. | +| **DropSubscriptionWorker(SubscriptionWorker worker, string database = null)** | `void` | Drop an existing subscription connection with a worker | +| **Enable(string name, string database)** | `void` | Enable existing subscription. | +| **EnableAsync(string name, string database)** | `Task` | Enable existing subscription. | +| **Disable(string name, string database)** | `void` | Disable existing subscription. | +| **DisableAsync(string name, string database)** | `Task` | Disable existing subscription. | +| **GetSubscriptions(int start, int take, string database)** | `List` | Returns subscriptions list. | +| **GetSubscriptionsAsync(int start, int take, string database)** | `Task>` | Returns subscriptions list. | +| **GetSubscriptionState(string subscriptionName, string database)** | `SubscriptionState ` | Get specific subscription state. | +| **GetSubscriptionStateAsync(string subscriptionName, string database)** | `Task ` | Get specific subscription state. | +| **GetSubscriptionWorker(string subscriptionName, string database)** | `SubscriptionWorker` | Generate a subscription worker, using default configurations, that processes documents deserialized to `T` type . | +| **GetSubscriptionWorker(string subscriptionName, string database)** | `SubscriptionWorker` | Generate a subscription worker, using default configurations, that processes documents in its raw `BlittableJsonReader`, wrapped by dynamic object. | +| **GetSubscriptionWorker(SubscriptionWorkerOptions options, string database)** | `SubscriptionWorker` | Generate a subscription worker, using default configurations, that processes documents deserialized to `T` type . | +| **GetSubscriptionWorker(SubscriptionWorkerOptions options, string database)** | `SubscriptionWorker` | Generate a subscription worker, using default configurations, that processes documents in its raw `BlittableJsonReader`, wrapped by dynamic object. | +| **Update(SubscriptionUpdateOptions options, string database = null)** | `string` | Update an existing data subscription. | +| **UpdateAsync(SubscriptionUpdateOptions options, string database = null, CancellationToken token = default)** | `Task` | Update an existing data subscription. | + +{PANEL/} + +{PANEL: Delete subscription} + +Subscriptions can be entirely deleted from the system. + +This operation can be very useful in ad-hoc subscription scenarios when a lot of subscriptions tasks information may accumulate, making tasks management very hard. + +{CODE interface_subscription_deletion@ClientApi\DataSubscriptions\DataSubscriptions.cs /} + +usage: + +{CODE subscription_deletion@ClientApi\DataSubscriptions\DataSubscriptions.cs /} + +{PANEL/} + +{PANEL: Disable subscription} + +Existing subscription tasks can be disabled from the client. + +{CODE interface_subscription_disabling@ClientApi\DataSubscriptions\DataSubscriptions.cs /} + +usage: + +{CODE subscription_disabling@ClientApi\DataSubscriptions\DataSubscriptions.cs /} + +{PANEL/} + +{PANEL: Enable subscription} + +Existing subscription tasks can be enabled from the client. +This operation can be useful for already disabled subscriptions. + +{CODE interface_subscription_enabling@ClientApi\DataSubscriptions\DataSubscriptions.cs /} + +usage: + +{CODE subscription_enabling@ClientApi\DataSubscriptions\DataSubscriptions.cs /} + +{PANEL/} + +{PANEL: Update subscription} + +See [examples](../../../client-api/data-subscriptions/creation/examples#update-existing-subscription) +and [API description](../../../client-api/data-subscriptions/creation/api-overview#update-subscription). + +{CODE updating_subscription@ClientApi\DataSubscriptions\DataSubscriptions.cs /} + +{PANEL/} + +{PANEL: Drop connection} + +Active subscription connections established by workers can be dropped remotely from the client. +Once dropped, the worker will not attempt to reconnect to the server. + +{CODE interface_subscription_dropping@ClientApi\DataSubscriptions\DataSubscriptions.cs /} + +usage: + +{CODE connection_dropping@ClientApi\DataSubscriptions\DataSubscriptions.cs /} + +{PANEL/} + +{PANEL: Get subscription state} + +{CODE interface_subscription_state@ClientApi\DataSubscriptions\DataSubscriptions.cs /} + +usage: + +{CODE subscription_state@ClientApi\DataSubscriptions\DataSubscriptions.cs /} + +{INFO: } + +##### SubscriptionState + +| Member | Type | Description | +|-------------------------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Query** | `string` | Subscription's RQL like query. | +| **LastBatchAckTime** | `DateTime?` | Last time a batch processing progress was acknowledged. | +| **NodeTag** | `string` | Processing server's node tag. | +| **MentorNode** | `string` | The mentor node that was manually set. | +| **SubscriptionName** | `string` | The subscription's name, which is also its unique identifier. | +| **SubscriptionId** | `long` | Subscription's internal identifier (cluster's operation etag during subscription creation). | +| **ChangeVectorForNextBatchStartingPoint** | `string` | The Change Vector from which the subscription will begin sending documents. clazz)** | `String` | Creates a new data subscription. | +| **create(Class clazz, SubscriptionCreationOptions options)** | `String` | Creates a new data subscription. | +| **create(Class clazz, SubscriptionCreationOptions options, String database)** | `String` | Creates a new data subscription. | +| **createForRevisions(Class clazz)** | `String` | Creates a new data subscription. | +| **createForRevisions(Class clazz, SubscriptionCreationOptions options)** | `String` | Creates a new data subscription. | +| **createForRevisions(Class clazz, SubscriptionCreationOptions options, String database)** | `String` | Creates a new data subscription. | +| **delete(String name)** | `void` | Deletes subscription. | +| **delete(String name, String database)** | `void` | Deletes subscription. | +| **dropConnection(String name)** | `void` | Drops existing subscription connection with worker. | +| **dropConnection(String name, String database)** | `void` | Drops existing subscription connection with worker. | +| **getSubscriptions(int start, int take)** | `List` | Returns subscriptions list. | +| **getSubscriptions(int start, int take, String database)** | `List` | Returns subscriptions list. | +| **getSubscriptionState(String subscriptionName)** | `SubscriptionState ` | Get specific subscription state. | +| **getSubscriptionState(String subscriptionName, String database)** | `SubscriptionState ` | Get specific subscription state. | +| **getSubscriptionWorker(string subscriptionName)** | `SubscriptionWorker` | Generates a subscription worker, using default configurations, that processes documents in it's raw `ObjectNode` type . | +| **getSubscriptionWorker(string subscriptionName, String database)** | `SubscriptionWorker` | Generates a subscription worker, using default configurations, that processes documents in it's raw `ObjectNode` type . | +| **getSubscriptionWorker(SubscriptionWorkerOptions options)** | `SubscriptionWorker` | Generates a subscription worker, using default configurations, that processes documents in it's raw `ObjectNode` type . | +| **getSubscriptionWorker(SubscriptionWorkerOptions options, String database)** | `SubscriptionWorker` | Generates a subscription worker, using default configurations, that processes documents in it's raw `ObjectNode` type . | +| **getSubscriptionWorker(Class clazz, String subscriptionName)** | `SubscriptionWorker` | Generates a subscription worker, using default configurations, that processes documents deserialized to `T` type . | +| **getSubscriptionWorker(Class clazz, String subscriptionName, String database)** | `SubscriptionWorker` | Generates a subscription worker, using default configurations, that processes documents deserialized to `T` type . | +| **getSubscriptionWorker(Class clazz, SubscriptionWorkerOptions options)** | `SubscriptionWorker` | Generates a subscription worker, using provided configuration, that processes documents deserialized to `T` type . | +| **getSubscriptionWorker(Class clazz, SubscriptionWorkerOptions options, String database)** | `SubscriptionWorker` | Generates a subscription worker, using provided configuration, that processes documents deserialized to `T` type . | +| **getSubscriptionWorkerForRevisions(Class clazz, String subscriptionName)** | `SubscriptionWorker` | Generates a subscription worker, using default configurations, that processes documents deserialized to `T` type . | +| **getSubscriptionWorkerForRevisions(Class clazz, String subscriptionName, String database)** | `SubscriptionWorker` | Generates a subscription worker, using default configurations, that processes documents deserialized to `T` type . | +| **getSubscriptionWorkerForRevisions(Class clazz, SubscriptionWorkerOptions options)** | `SubscriptionWorker` | Generates a subscription worker, using provided configuration, that processes documents deserialized to `T` type . | +| **getSubscriptionWorkerForRevisions(Class clazz, SubscriptionWorkerOptions options, String database)** | `SubscriptionWorker` | Generates a subscription worker, using provided configuration, that processes documents deserialized to `T` type . | + +{PANEL/} + +## Related Articles + +**Data Subscriptions**: + +- [What are Data Subscriptions](../../../client-api/data-subscriptions/what-are-data-subscriptions) +- [How to Create a Data Subscription](../../../client-api/data-subscriptions/creation/how-to-create-data-subscription) +- [How to Consume a Data Subscription](../../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription) diff --git a/Documentation/5.4/Raven.Documentation.Pages/client-api/data-subscriptions/advanced-topics/maintenance-operations.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/client-api/data-subscriptions/advanced-topics/maintenance-operations.js.markdown new file mode 100644 index 000000000..44129418e --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/client-api/data-subscriptions/advanced-topics/maintenance-operations.js.markdown @@ -0,0 +1,147 @@ +# Data Subscriptions: Maintenance Operations +--- + +{NOTE: } + +* This article covers data subscriptions maintenance operations. + +* In this page: + * [Delete subscription](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#delete-subscription) + * [Disable subscription](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#disable-subscription) + * [Enable subscription](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#enable-subscription) + * [Update subscription](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#update-subscription) + * [Drop connection](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#drop-connection) + * [Get subscriptions](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#get-subscriptions) + * [Get subscription state](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#get-subscription-state) + * [DocumentSubscriptions class](../../../client-api/data-subscriptions/advanced-topics/maintenance-operations#documentsubscriptions-class) + +{NOTE/} + +--- + +{PANEL: Delete subscription} + +Subscription tasks can be entirely deleted from the system. + +{CODE:nodejs delete@client-api\dataSubscriptions\advanced\maintenance.js /} +{CODE:nodejs delete_syntax@client-api\dataSubscriptions\advanced\maintenance.js /} + +{PANEL/} + +{PANEL: Disable subscription} + +Existing subscription tasks can be disabled from the client. + +{CODE:nodejs disable@client-api\dataSubscriptions\advanced\maintenance.js /} +{CODE:nodejs disable_syntax@client-api\dataSubscriptions\advanced\maintenance.js /} + +{PANEL/} + +{PANEL: Enable subscription} + +Existing subscription tasks can be enabled from the client. +This operation can be useful for already disabled subscriptions. + +{CODE:nodejs enable@client-api\dataSubscriptions\advanced\maintenance.js /} +{CODE:nodejs enable_syntax@client-api\dataSubscriptions\advanced\maintenance.js /} + +{PANEL/} + +{PANEL: Update subscription} + +See [examples](../../../client-api/data-subscriptions/creation/examples#update-existing-subscription) +and [API description](../../../client-api/data-subscriptions/creation/api-overview#update-subscription). + +{CODE:nodejs update@client-api\dataSubscriptions\advanced\maintenance.js /} +{CODE:nodejs update_syntax@client-api\dataSubscriptions\advanced\maintenance.js /} + +{PANEL/} + +{PANEL: Drop connection} + +Active subscription connections established by workers can be dropped remotely from the client. +Once dropped, the worker will not attempt to reconnect to the server. + +{CODE:nodejs drop_connection@client-api\dataSubscriptions\advanced\maintenance.js /} +{CODE:nodejs drop_connection_syntax@client-api\dataSubscriptions\advanced\maintenance.js /} + +{PANEL/} + +{PANEL: Get subscriptions} + +Get a list of all existing subscription tasks in the database. + +{CODE:nodejs get_subscriptions@client-api\dataSubscriptions\advanced\maintenance.js /} +{CODE:nodejs get_subscriptions_syntax@client-api\dataSubscriptions\advanced\maintenance.js /} + +{PANEL/} + +{PANEL: Get subscription state} + +{CODE:nodejs get_state@client-api\dataSubscriptions\advanced\maintenance.js /} +{CODE:nodejs get_state_syntax@client-api\dataSubscriptions\advanced\maintenance.js /} + +{INFO: } + +##### SubscriptionState + +| Member | Type | Description | +|-------------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **query** | `string` | Subscription's RQL like query. | +| **lastBatchAckTime** | `string` | Last time a batch processing progress was acknowledged. | +| **nodeTag** | `string` | Processing server's node tag. | +| **mentorNode** | `string` | The mentor node that was manually set. | +| **subscriptionName** | `string` | The subscription's name, which is also its unique identifier. | +| **subscriptionId** | `number` | Subscription's internal identifier (cluster's operation etag during subscription creation). | +| **changeVectorForNextBatchStartingPoint** | `string` | The Change Vector from which the subscription will begin sending documents.
This value is updated on batch acknowledgement and can also be set manually. | +| **disabled** | `boolean` | If `true`, subscription will not allow workers to connect. | +| **lastClientConnectionTime** | `string` | Time when last client was connected (value sustained after disconnection). | + +{INFO/} + +{PANEL/} + +{PANEL: DocumentSubscriptions class} + +The `DocumentSubscriptions` class manages all interaction with the data subscriptions. +The class is available through the `subscriptions` property in the `documentStore`. + +| Method Signature | Return type | Description | +|----------------------------------------------------------|--------------------------------|--------------------------------------------------------------| +| **create(options)** | `Promise` | Create a new data subscription. | +| **create(options, database)** | `Promise` | Create a new data subscription. | +| **create(documentType)** | `Promise` | Create a new data subscription. | +| **create(optionsOrDocumentType, database)** | `Promise` | Create a new data subscription. | +| **createForRevisions(options)** | `Promise` | Create a new data subscription. | +| **createForRevisions(options, database)** | `Promise` | Create a new data subscription. | +| **delete(name)** | `Promise` | Delete subscription. | +| **delete(name, database)** | `Promise` | Delete subscription. | +| **dropConnection(name)** | `Promise` | Drop all existing subscription connections with workers. | +| **dropConnection(name, database)** | `Promise` | Drop all existing subscription connections with workers. | +| **dropSubscriptionWorker(worker, database)** | `Promise` | Drop an existing subscription connection with a worker. | +| **enable(name)** | `Promise` | Enable existing subscription. | +| **enable(name, database)** | `Promise` | Enable existing subscription. | +| **disable(name)** | `Promise` | Disable existing subscription. | +| **disable(name, database)** | `Promise` | Disable existing subscription. | +| **update(updateOptions)** | `Promise` | Update an existing data subscription. | +| **update(updateOptions, database)** | `Promise` | Update an existing data subscription. | +| **getSubscriptions(start, take)** | `Promise` | Returns subscriptions list. | +| **getSubscriptions(start, take, database)** | `Promise` | Returns subscriptions list. | +| **getSubscriptionState(subscriptionName)** | `Promise ` | Get the state of a specific subscription. | +| **getSubscriptionState(subscriptionName, database)** | `Promise ` | Get the state of a specific subscription. | +| **getSubscriptionWorker(options)** | `SubscriptionWorker` | Generate a subscription worker. | +| **getSubscriptionWorker(options, database)** | `SubscriptionWorker` | Generate a subscription worker. | +| **getSubscriptionWorker(subscriptionName)** | `SubscriptionWorker` | Generate a subscription worker. | +| **getSubscriptionWorker(subscriptionName, database)** | `SubscriptionWorker` | Generate a subscription worker. | +| **getSubscriptionWorkerForRevisions(options)** | `SubscriptionWorker` | Generate a subscription worker for a revisions subscription. | +| **getSubscriptionWorkerForRevisions(options, database)** | `SubscriptionWorker` | Generate a subscription worker for a revisions subscription. | + +{PANEL/} + +## Related Articles + +### Data Subscriptions + +- [What are Data Subscriptions](../../../client-api/data-subscriptions/what-are-data-subscriptions) +- [How to Create a Data Subscription](../../../client-api/data-subscriptions/creation/how-to-create-data-subscription) +- [How to Consume a Data Subscription](../../../client-api/data-subscriptions/consumption/how-to-consume-data-subscription) diff --git a/Documentation/5.4/Samples/nodejs/client-api/dataSubscriptions/advanced/maintenance.js b/Documentation/5.4/Samples/nodejs/client-api/dataSubscriptions/advanced/maintenance.js new file mode 100644 index 000000000..3381fb9a5 --- /dev/null +++ b/Documentation/5.4/Samples/nodejs/client-api/dataSubscriptions/advanced/maintenance.js @@ -0,0 +1,132 @@ +import * as assert from "assert"; +import { DocumentStore } from "ravendb"; + +const documentStore = new DocumentStore(); +const session = documentStore.openSession(); + +async function revisionsSubscription() { + + { + //region delete + await documentStore.subscriptions.delete("subscriptionNameToDelete"); + //endregion + } + { + //region disable + await documentStore.subscriptions.disable("subscriptionNameToDisable"); + //endregion + } + { + //region enable + await documentStore.subscriptions.enable("subscriptionNameToEnable"); + //endregion + } + { + //region update + const updateOptions = { + id: "", + query: "" + // ... + } + await documentStore.subscriptions.update(updateOptions); + //endregion + } + { + //region drop_connection + // Drop all connections to the subscription: + // ========================================= + + await documentStore.subscriptions.dropConnection("subscriptionName"); + + // Drop specific worker connection: + // =============================== + + const workerOptions = { + subscriptionName: "subscriptionName", + // ... + }; + + const worker = documentStore.subscriptions.getSubscriptionWorker(workerOptions); + + + worker.on("batch", (batch, callback) => { + // worker processing logic + }); + + await documentStore.subscriptions.dropConnection(worker); + //endregion + } + { + //region get_subscriptions + const subscriptions = await documentStore.subscriptions.getSubscriptions(0, 10); + //endregion + } + { + //region get_state + const subscriptionState = + await documentStore.subscriptions.getSubscriptionState("subscriptionName"); + //endregion + } +} + +{ +//region create_syntax +// Available overloads: +create(options); +create(options, database); +create(documentType); +createForRevisions(options) +createForRevisions(options, database) +//endregion +} +{ +//region delete_syntax +// Available overloads: +delete(name); +delete(name, database); +//endregion +} +{ +//region disable_syntax +// Available overloads: +disable(name); +disable(name, database); +//endregion +} +{ +//region enable_syntax +// Available overloads: +enable(name); +enable(name, database); +//endregion +} +{ +//region update_syntax +// Available overloads: +update(options); +update(options, database); +//endregion +} +{ +//region drop_connection_syntax +// Available overloads: +dropConnection(options); +dropConnection(options, database); +dropSubscriptionWorker(worker); +dropSubscriptionWorker(worker, database); +//endregion +} +{ +//region get_subscriptions_syntax +// Available overloads: +getSubscriptions(start, take); +getSubscriptions(start, take, database); +//endregion +} +{ +//region get_state_syntax +// Available overloads: +getSubscriptionState(subscriptionName); +getSubscriptionState(subscriptionName, database); +//endregion +}