Merge branch 'master' into bug/TimeSync_State_Shutdown_State_Fix

Author: stefaneberl

README.md

@@ -114,7 +114,7 @@ requested from an `Action`.
 
 A named `Event` is attached to an `Action` and contains a name.
 
-### Key-Value pairs
+### Key-Value Pairs
 
 For an `Action` key-value pairs can also be reported. The key is always a String
 and the value may be an Integer (int), a floating point (double) or a String.

docs/example.md

@@ -1,9 +1,9 @@
-# Dynatrace OpenKit - Java example
+# Dynatrace OpenKit - Java Example
 
-The following document shall provide an in depth overview, how OpenKit can be used from
+The following document provides an in depth overview, how OpenKit can be used from
 developer's point of view. It explains the usage of all the API methods.
 
-## Obtaining an OpenKit instance
+## Obtaining an OpenKit Instance
 
 OpenKit instances are obtained from the `OpenKitFactory` class.  
 Depending on the used backend system (Dynatrace SaaS/Dynatrace Managed/AppMon), the factory provides 
@@ -135,7 +135,7 @@ long timeoutInMilliseconds = 10 * 1000;
 boolean success = openKit.waitForInitCompletion(timeoutInMilliseconds);
 ```
 
-The method returns `false` in case the timeout expired or `shutdown` has been invoked in the mean time
+The method returns `false` in case the timeout expired or `shutdown` has been invoked in the meantime
 and `true` to indicate successful initialization.  
 
 To verify if OpenKit has been initialized, use the `isInitialized` method as shown in the example below.
@@ -148,7 +148,7 @@ if (isInitialized) {
 }
 ```
 
-## Providing further Application information
+## Providing further Application Information
 
 If multiple version's of the same applications are monitored by OpenKit, it's quite useful
 to set the application's version in OpenKit.  
@@ -158,7 +158,7 @@ String applicationVersion = "1.2.3.4";
 openKit.setApplicationVersion(applicationVersion);
 ```
 
-## Providing Device specific information
+## Providing Device specific Information
 
 Sometimes it might also be quite useful to provide information about the device the application
 is running on. The example below shows how to achieve this.
@@ -243,7 +243,7 @@ RootAction rootAction = session.enterAction(rootActionName);
 Since `RootAction` extends the `Action` interface all further methods are the same for both interfaces, except
 for creating child actions, which can only be done with a `RootAction`.
 
-## Entering a child Action
+## Entering a Child Action
 
 To start a child `Action` from a previously started `RootAction` use the `enterAction` method from
 `RootAction`, as demonstrated below.
@@ -274,7 +274,7 @@ action.reportEvent(eventName);
 rootAction.reportEvent(eventName);
 ```
 
-## Report Key-value pairs
+## Report Key-Value Pairs
 
 Key-value pairs can also be reported via an `Action` as shown in the example below.
 Overloaded methods exist for the following value types:
@@ -314,7 +314,7 @@ action.reportError(errorName, errorCode, reason);
 
 One of the most powerful OpenKit features is web request tracing. When the application starts a web
 request (e.g. HTTP GET) a special tag can be attached to the header. This special header allows
-Dynatrace SaaS/Dynatrace Managed/AppMon to correlate with a server side PurePath. 
+Dynatrace SaaS/Dynatrace Managed/AppMon to correlate actions with a server side PurePath. 
 
 An example is shown below.
 ```java
@@ -364,7 +364,7 @@ webRequestTracer.stopTiming();
 ```
 
 
-## Terminating the OpenKit instance
+## Terminating the OpenKit Instance
 
 When an OpenKit instance is no longer needed (e.g. the application using OpenKit is shut down), the previously
 obtained instance can be cleared by invoking the `shutdown` method.  

docs/internals.md

@@ -3,11 +3,10 @@
 ## Data Sending (Beacon sending)
 
 All data sending, including synchronization with the backend (Dynatrace SaaS/Dynatrace Managed/AppMon)
-happens asynchronously by starting an own Thread when OpenKit is initialized.  
+happens asynchronously by starting an own thread when OpenKit is initialized.  
 
-This sending thread runs through several states, before sending data actually happens.  
-
-The following diagram illustrates these states. Each of them, including transitions, is explained later.
+Beacon sending in OpenKit is implemented using a state pattern. The following 
+diagram illustrates the states.
 
 ![diagram](./pics/OpenKit-state_diagram.svg)
 
@@ -19,30 +18,27 @@ delays between consecutive retries.
 If the server returned a status response a state transition to TimeSync is performed, otherwise
 OpenKit stays in the Initialize state, but sleeps some time until the next status request is sent. 
 
-In case the application developer calls `OpenKit.shutdown()` while in Init state, an immediate 
-transition to the Terminal state is performed.
+If `OpenKit.shutdown()` is called while OpenKit is in the Init state, 
+a transition to the Terminal state is performed.
 
 ## TimeSync
 
 In the TimeSync state (class `BeaconSendingTimeSyncState`) 5 time sync timestamp pairs, in total
-10 timestamps, are fetched from the server to calculate the time offset to the backend. To retrieve
-a pair of timestamps one time sync request is sent with a maximum amount of retries 
+10 timestamps, are fetched. The timestamps are used to calculate the time offset to the backend. 
+To retrieve a pair of timestamps one time sync request is sent with a maximum amount of retries 
 (by default 5 retries, therefore in total 6 requests for one timestamp pair).  
-If a server does not support time sync (e.g. AppMon), indicated by at least one negative timestamp
-returned in a time sync response, all further retries are skipped and no further time sync will happen. 
-In this case a transition to either CaptureOn state or CaptureOff state is performed, based on the 
-initial configuration obtained in Init state.
+If a server does not support time sync (e.g. AppMon) all further retries are skipped and no 
+further time sync will happen.  In this case a transition to either CaptureOn state or CaptureOff 
+state is performed, based on the initial configuration obtained in Init state.
 If the number of time sync retries is exceeded the time sync is unsuccessful and therefore a
 transition to CaptureOff is performed.
-In case the time sync was successful a transition to either CaptureOn state or CaptureOff 
-state is performed, based on the initial configuration obtained in Init state.  
 
 The algorithm used to compute the cluster time offset is similar to the algorithm used by 
 [NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol#Clock_synchronization_algorithm).
 
-In case the application developer calls `OpenKit.shutdown()` while in TimeSync state a transition
-to TerminalState is performed if it's the initial time sync, otherwise a transition to 
-FlushSessions state is done.
+If `OpenKit.shutdown()` is called while OpenKit is in the TimeSync state, a transition to either 
+Terminal state or FlushSession state is performed. The transition to the Terminal state 
+is only performed if the initial time sync was not completed before the call to `shutdown()`.
 
 ## CaptureOff
 
@@ -51,7 +47,7 @@ status request was sent to the server and sleeps some time before performing the
 request.  
 If time sync is supported by the server and the initial time sync failed a state transition
 to time sync is performed.  
-In case an initial time sync is not needed any more a transition to CaptureOn state is performed
+If the initial time sync was successfully performed, a transition to CaptureOn state is performed
 if capturing was enabled by the server's status response. If capturing is disabled
 then no transition is performed and the state machine stays in CaptureOff state.  
 
@@ -78,4 +74,4 @@ data which has not been transferred so far to the server.
 
 The Terminal state (class `BeaconSendingTerminalState`) is the last state in OpenKit's internal 
 state machine. After this state is reached the background thread responsible for sending data 
-will end itself.
+is terminated gracefully.