Merge pull request #36071 from rwike77/deleteinternals

Delete reliable collection internals
bennage · Mar 23, 2018 · a734cdf · a734cdf
2 parents 5cd736e + caa1f50
commit a734cdf
Show file tree

Hide file tree

Showing 10 changed files with 25 additions and 144 deletions.
diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json
@@ -8319,6 +8319,16 @@
             "redirect_url": "./end-user/microsoft-authenticator-app-how-to",
             "redirect_document_id": false
         },
+        {
+            "source_path": "articles/service-fabric/service-fabric-reliable-services-advanced-usage.md",
+            "redirect_url": "/azure/service-fabric/service-fabric-reliable-services-lifecycle",
+            "redirect_document_id": false
+        },
+        {
+            "source_path": "articles/service-fabric/service-fabric-reliable-services-reliable-collections-internals.md",
+            "redirect_url": "/azure/service-fabric/service-fabric-reliable-services-introduction",
+            "redirect_document_id": false
+        },
         {
             "source_path": "articles/service-fabric/service-fabric-add-a-web-frontend.md",
             "redirect_url": "/azure/service-fabric/service-fabric-reliable-services-communication-aspnetcore",

diff --git a/articles/service-fabric/service-fabric-cluster-capacity.md b/articles/service-fabric/service-fabric-cluster-capacity.md
@@ -85,7 +85,7 @@ You get to choose durability level for each of your node-types.You can choose on
 **Disadvantages of using Silver or Gold durability levels**
 
 1. Deployments to your Virtual Machine Scale Set and other related Azure resources) can be delayed, can time out, or can be blocked entirely by problems in your cluster or at the infrastructure level. 
-2. Increases the number of [replica lifecycle events](service-fabric-reliable-services-advanced-usage.md#stateful-service-replica-lifecycle ) (for example, primary swaps) due to automated node deactivations during Azure infrastructure operations.
+2. Increases the number of [replica lifecycle events](service-fabric-reliable-services-lifecycle.md) (for example, primary swaps) due to automated node deactivations during Azure infrastructure operations.
 3. Takes nodes out of service for periods of time while Azure platform software updates or hardware maintenance activities are occurring. You may see nodes with status Disabling/Disabled during these activities. This reduces the capacity of your cluster temporarily, but should not impact the availability of your cluster or applications.
 
 ### Recommendations on when to use Silver or Gold durability levels
@@ -99,10 +99,10 @@ Use Silver or Gold durability for all node types that host stateful services you
 
 ### Operational Recommendations for the node type that you have set to silver or gold durability level.
 
-1. Keep your cluster and applications healthy at all times, and make sure that applications respond to all [Service replica lifecycle events](service-fabric-reliable-services-advanced-usage.md#stateful-service-replica-lifecycle) (like replica in build is stuck) in a timely fashion.
+1. Keep your cluster and applications healthy at all times, and make sure that applications respond to all [Service replica lifecycle events](service-fabric-reliable-services-lifecycle.md) (like replica in build is stuck) in a timely fashion.
 2. Adopt safer ways to make a VM SKU change (Scale up/down): Changing the VM SKU of a Virtual Machine Scale Set is inherently an unsafe operation and so should be avoided if possible. Here is the process you can follow to avoid common issues.
 	- **For non-primary nodetypes:** It is recommended that you create new Virtual Machine Scale Set, modify the service placement constraint to include the new Virtual Machine Scale Set/node type and then reduce the old Virtual Machine Scale Set instance count to 0, one node at a time (this is to make sure that removal of the nodes do not impact the reliability of the cluster).
-	- **For the primary nodetype:** Our recommendation is that you do not change VM SKU of the primary node type. Changing of the primary node type SKU is not supported. If the reason for the new SKU is capacity, we recommend adding more instances. If that not possible, create a new cluster and [restore application state](service-fabric-reliable-services-backup-restore.md) (if applicable) from your old cluster. You do not need to restore any system service state, they are recreated when you deploy your applications to your new cluster. If you were just running stateless applications on your cluster, then all you do is deploy your applications to the new cluster, you have nothing to restore. If you decide to go the unsupported route and want to change the VM SKU, then make modifications to the Virtual Machine Scale Set Model definition to reflect the new SKU. If your cluster has only one nodetype, then make sure that all your stateful applications respond to all [Service replica lifecycle events](service-fabric-reliable-services-advanced-usage.md#stateful-service-replica-lifecycle) (like replica in build is stuck) in a timely fashion and that your service replica rebuild duration is less than five minutes (for Silver durability level). 
+	- **For the primary nodetype:** Our recommendation is that you do not change VM SKU of the primary node type. Changing of the primary node type SKU is not supported. If the reason for the new SKU is capacity, we recommend adding more instances. If that not possible, create a new cluster and [restore application state](service-fabric-reliable-services-backup-restore.md) (if applicable) from your old cluster. You do not need to restore any system service state, they are recreated when you deploy your applications to your new cluster. If you were just running stateless applications on your cluster, then all you do is deploy your applications to the new cluster, you have nothing to restore. If you decide to go the unsupported route and want to change the VM SKU, then make modifications to the Virtual Machine Scale Set Model definition to reflect the new SKU. If your cluster has only one nodetype, then make sure that all your stateful applications respond to all [Service replica lifecycle events](service-fabric-reliable-services-lifecycle.md) (like replica in build is stuck) in a timely fashion and that your service replica rebuild duration is less than five minutes (for Silver durability level). 
 
 
 > [!WARNING]

diff --git a/articles/service-fabric/service-fabric-reliable-services-advanced-usage.md b/articles/service-fabric/service-fabric-reliable-services-advanced-usage.md
diff --git a/articles/service-fabric/service-fabric-reliable-services-introduction.md b/articles/service-fabric/service-fabric-reliable-services-introduction.md
@@ -109,5 +109,5 @@ If any of the following characterize your application service needs, then you sh
 
 ## Next steps
 * [Reliable Services quick start](service-fabric-reliable-services-quick-start.md)
-* [Reliable Services advanced usage](service-fabric-reliable-services-advanced-usage.md)
+* [Reliable collections](service-fabric-reliable-services-reliable-collections.md)
 * [The Reliable Actors programming model](service-fabric-reliable-actors-introduction.md)
diff --git a/articles/service-fabric/service-fabric-reliable-services-lifecycle-java.md b/articles/service-fabric/service-fabric-reliable-services-lifecycle-java.md
@@ -62,11 +62,11 @@ When shutting down a stateless service, the same pattern is followed, but in rev
 1. These events occur in parallel:
     - Any open listeners are closed. `CommunicationListener.closeAsync()` is called on each listener.
     - The cancellation token that was passed to `runAsync()` is canceled. Checking the cancellation token's `isCancelled` property returns `true`, and if called, the token's `throwIfCancellationRequested` method throws a `CancellationException`.
-2. When `closeAsync()` finishes on each listener and `runAsync()` also finishes, the service's `StatelessService.onCloseAsync()` method is called, if it's present. Again, this is not a common override.
+2. When `closeAsync()` finishes on each listener and `runAsync()` also finishes, the service's `StatelessService.onCloseAsync()` method is called, if it's present. Again, this is not a common override, but it can be used to safely close resources, stop background processing, finish saving external state, or close down existing connections.
 3. After `StatelessService.onCloseAsync()` finishes, the service object is destructed.
 
 ## Stateful service startup
-Stateful services have a pattern that is similar to stateless services, with a few changes. Here's the order of events for starting a stateful service:
+Stateful services have a pattern that is similar to stateless services, with a few changes.  Here's the order of events for starting a stateful service:
 
 1. The service is constructed.
 2. `StatefulServiceBase.onOpenAsync()` is called. This call is not commonly overridden in the service.
@@ -124,15 +124,14 @@ Exceptions thrown by Service Fabric are either permanent [(`FabricException`)](h
 An important part of testing and validating Reliable Services is handling the exceptions that come from using the `ReliableCollections` in conjunction with service lifecycle events. We recommend that you always run your service under load. You should also perform upgrades and [chaos testing](service-fabric-controlled-chaos.md) before deploying to production. These basic steps help ensure that your service is implemented correctly, and that it handles lifecycle events correctly.
 
 ## Notes on service lifecycle
-* Both the `runAsync()` method and the `createServiceInstanceListeners/createServiceReplicaListeners` calls are optional. A service might have one, both, or neither. For example, if the service does all its work in response to user calls, there's no need for it to implement `runAsync()`. Only the communication listeners and their associated code are necessary. 
-
-  Similarly, creating and returning communication listeners is optional. The service might have only background work to do, so it only needs to implement `runAsync()`.
+* Both the `runAsync()` method and the `createServiceInstanceListeners/createServiceReplicaListeners` calls are optional. A service might have one, both, or neither. For example, if the service does all its work in response to user calls, there's no need for it to implement `runAsync()`. Only the communication listeners and their associated code are necessary.  Similarly, creating and returning communication listeners is optional. The service might have only background work to do, so it only needs to implement `runAsync()`.
 * It's valid for a service to complete `runAsync()` successfully and return from it. This isn't considered a failure condition. It represents the background work of the service finishing. For stateful Reliable Services, `runAsync()` would be called again if the service is demoted from primary, and then promoted back to primary.
 * If a service exits from `runAsync()` by throwing some unexpected exception, this is a failure. The service object is shut down, and a health error is reported.
 * Although there's no time limit on returning from these methods, you immediately lose the ability to write. Therefore, you can't complete any real work. We recommend that you return as quickly as possible upon receiving the cancellation request. If your service doesn't respond to these API calls in a reasonable amount of time, Service Fabric might forcibly terminate your service. Usually, this happens only during application upgrades or when a service is being deleted. This timeout is 15 minutes by default.
-* Failures in the `onCloseAsync()` path result in `onAbort()` being called. This call is a last-chance, best-effort opportunity for the service to clean up and release any resources that they have claimed.
+* Failures in the `onCloseAsync()` path result in `onAbort()` being called. This call is a last-chance, best-effort opportunity for the service to clean up and release any resources that they have claimed. This is generally called when a permanent fault is detected on the node, or when Service Fabric cannot reliably manage the service instance's lifecycle due to internal failures.
+* `OnChangeRoleAsync()` is called when the stateful service replica is changing role, for example to primary or secondary. Primary replicas are given write status (are allowed to create and write to Reliable Collections). Secondary replicas are given read status (can only read from existing Reliable Collections). Most work in a stateful service is performed at the primary replica. Secondary replicas can perform read-only validation, report generation, data mining, or other read-only jobs.
 
 ## Next steps
 * [Introduction to Reliable Services](service-fabric-reliable-services-introduction.md)
 * [Reliable Services quickstart](service-fabric-reliable-services-quick-start-java.md)
-* [Reliable Services advanced usage](service-fabric-reliable-services-advanced-usage.md)
+