Skip to content

Commit 636db67

Browse files
author
Mike Davis
committed
Incorporate copy edits. (#306)
1 parent 3fbabc2 commit 636db67

File tree

1 file changed

+66
-64
lines changed

1 file changed

+66
-64
lines changed

core-httpclient-impl/README.md

Lines changed: 66 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
1-
# Java SDK Async Http Client
1+
# Java SDK Async HTTP Client
22

3-
This package provides default implementations of an Optimizely `EventHandler` and `ProjectConfigManager`. Also included
4-
in this package is a factory class, `OptimizelyFactory`, which can be used to reliably instantiate the Optimizely SDK
5-
with the default configuration of the `AsyncEventHandler` and `HttpProjectConfigManager`.
3+
This package provides default implementations of an Optimizely `EventHandler` and `ProjectConfigManager`.
4+
The package also includes a factory class, `OptimizelyFactory`, which you can use to instantiate the Optimizely SDK
5+
with the default configuration of `AsyncEventHandler` and `HttpProjectConfigManager`.
66

77
## Installation
88

99
### Gradle
10-
1110
```groovy
1211
compile 'com.optimizely.ab:core-httpclient-impl:{VERSION}'
1312
```
@@ -22,7 +21,8 @@ compile 'com.optimizely.ab:core-httpclient-impl:{VERSION}'
2221

2322
```
2423

25-
### Basic usage
24+
25+
## Basic usage
2626
```java
2727
import com.optimizely.ab.Optimizely;
2828
import com.optimizely.ab.OptimizelyFactory;
@@ -34,22 +34,19 @@ public class App {
3434
Optimizely optimizely = OptimizelyFactory.newDefaultInstance(sdkKey);
3535
}
3636
}
37-
3837
```
3938

40-
### Advanced usage
39+
## Advanced usage
4140
```java
4241
import com.optimizely.ab.Optimizely;
4342
import com.optimizely.ab.config.HttpProjectConfigManager;
4443
import com.optimizely.ab.event.AsyncEventHandler;
45-
4644
import java.util.concurrent.TimeUnit;
4745

4846
public class App {
4947

5048
public static void main(String[] args) {
5149
String sdkKey = args[0];
52-
5350
EventHandler eventHandler = AsyncEventHandler.builder()
5451
.withQueueCapacity(20000)
5552
.withNumWorkers(5)
@@ -68,19 +65,20 @@ public class App {
6865
}
6966
```
7067

71-
## AsyncEventHandler
68+
## `AsyncEventHandler`
69+
70+
[`AsyncEventHandler`](https://github.com/optimizely/java-sdk/blob/master/core-httpclient-impl/src/main/java/com/optimizely/ab/event/AsyncEventHandler.java)
71+
provides an implementation of [`EventHandler`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/event/EventHandler.java)
72+
backed by a `ThreadPoolExecutor`. Events triggered from the Optimizely SDK are queued immediately as discrete tasks to
73+
the executor and processed in the order they were submitted.
7274

73-
The [`AsyncEventHandler`](https://github.com/optimizely/java-sdk/blob/master/core-httpclient-impl/src/main/java/com/optimizely/ab/event/AsyncEventHandler.java)
74-
provides an implementation of the the [`EventHandler`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/event/EventHandler.java)
75-
backed by a `ThreadPoolExecutor`. When events are
76-
triggered from the Optimizely SDK, they are immediately queued as discrete tasks to the executor and processed in the
77-
order they were submitted. Each worker is responsible for making outbound http requests to the
78-
Optimizely log endpoint for metric tracking. The default queue size and the number of workers are configurable via
79-
global properties and can be overridden via the `AsyncEventHandler.Builder`.
75+
Each worker is responsible for making outbound HTTP requests to the Optimizely log endpoint for metrics tracking.
76+
Configure the default queue size and number of workers via global properties. Use `AsyncEventHandler.Builder` to
77+
override the default queue size and number of workers.
8078

81-
### Usage
79+
### Use `AsyncEventHandler`
8280

83-
To use the AsyncEventHandler, an instance must be built via the `AsyncEventHandler.Builder` then passed to the `Optimizely.Builder`
81+
To use `AsyncEventHandler`, you must build an instance with `AsyncEventHandler.Builder` and pass the instance to the `Optimizely.Builder`:
8482

8583
```java
8684
EventHandler eventHandler = AsyncEventHandler.builder()
@@ -91,36 +89,37 @@ EventHandler eventHandler = AsyncEventHandler.builder()
9189

9290
#### Queue capacity
9391

94-
The queue capacity can be set to initialize the backing queue for the executor service. If the queue fills up, then
95-
events will be dropped and exception will be logged. Setting a higher queue value will prevent event loss, but will
96-
use up more memory in the event the workers can not keep up if the production rate.
92+
You can set the queue capacity to initialize the backing queue for the executor service. If the queue fills up, events
93+
will be dropped and an exception will be logged. Setting a higher queue value will prevent event loss but will use more
94+
memory if the workers cannot keep up with the production rate.
9795

9896
#### Number of workers
9997

100-
The number of workers determines the number of threads used by the thread pool.
98+
The number of workers determines the number of threads the thread pool uses.
10199

102-
#### Advanced configurations
100+
### Advanced configuration
103101

104102
|Property Name|Default Value|Description|
105103
|---|---|---|
106-
|async.event.handler.queue.capacity|10000|Queue size for pending LogEvents|
107-
|async.event.handler.num.workers|2|Number of worker threads|
108-
|async.event.handler.max.connections|200|Max number of connections|
109-
|async.event.handler.event.max.per.route|20|Max number of connections per route|
110-
|async.event.handler.validate.after|5000|Time in milliseconds to maintain idol connections|
104+
|`async.event.handler.queue.capacity`|10000|Queue size for pending logEvents|
105+
|`async.event.handler.num.workers`|2|Number of worker threads|
106+
|`async.event.handler.max.connections`|200|Maximum number of connections|
107+
|`async.event.handler.event.max.per.route`|20|Maximum number of connections per route|
108+
|`async.event.handler.validate.after`|5000|Time to maintain idol connections (in milliseconds)|
111109

112110

113-
## HttpProjectConfigManager
111+
## `HttpProjectConfigManager`
114112

115-
The [`HttpProjectConfigManager`](https://github.com/optimizely/java-sdk/blob/master/core-httpclient-impl/src/main/java/com/optimizely/ab/config/HttpProjectConfigManager.java)
113+
[`HttpProjectConfigManager`](https://github.com/optimizely/java-sdk/blob/master/core-httpclient-impl/src/main/java/com/optimizely/ab/config/HttpProjectConfigManager.java)
116114
is an implementation of the abstract [`PollingProjectConfigManager`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/config/PollingProjectConfigManager.java).
117-
The `poll` method is extended and makes an http GET request to the configured url to asynchronously download the project data file
118-
and initialize an instance of the ProjectConfig. By default, the `HttpProjectConfigManager` will block until the
119-
first successful retrieval of the datafile, up to a configurable timeout. The frequency of the polling method and the
120-
blocking timeout can be set via the `HttpProjectConfigManager.Builder` with the default values being pulled from global
121-
properties.
115+
The `poll` method is extended and makes an HTTP GET request to the configured URL to asynchronously download the
116+
project datafile and initialize an instance of the ProjectConfig.
122117

123-
### Usage
118+
By default, `HttpProjectConfigManager` will block until the first successful datafile retrieval, up to a configurable timeout.
119+
Set the frequency of the polling method and the blocking timeout with `HttpProjectConfigManager.Builder`,
120+
pulling the default values from global properties.
121+
122+
### Use `HttpProjectConfigManager`
124123

125124
```java
126125
ProjectConfigManager projectConfigManager = HttpProjectConfigManager.builder()
@@ -129,37 +128,37 @@ ProjectConfigManager projectConfigManager = HttpProjectConfigManager.builder()
129128
.build();
130129
```
131130

132-
#### SDK Key
131+
#### SDK key
133132

134-
The SDK key is used to compose the outbound http request to the default datafile location hosted on the Optimizely CDN.
133+
The SDK key is used to compose the outbound HTTP request to the default datafile location on the Optimizely CDN.
135134

136135
#### Polling interval
137136

138-
The polling interval is used to determine a fixed delay between consecutive http requests for the datafile.
137+
The polling interval is used to specify a fixed delay between consecutive HTTP requests for the datafile.
139138

140-
#### Initial Datafile
139+
#### Initial datafile
141140

142-
An initial datafile can be provided via the builder to bootstrap the the `ProjectConfigManager` so that it can be used
141+
You can provide an initial datafile via the builder to bootstrap the `ProjectConfigManager` so that it can be used
143142
immediately without blocking execution.
144143

145-
#### Advanced configurations
144+
### Advanced configuration
146145

147146
|Property Name|Default Value|Description|
148147
|---|---|---|
149-
|http.project.config.manager.polling.duration|5|Fixed delay between fetches for the datafile|
150-
|http.project.config.manager.polling.unit|MINUTES|Time unit corresponding to polling interval|
151-
|http.project.config.manager.blocking.duration|10|Max duration spent waiting for initial bootstrapping|
152-
|http.project.config.manager.blocking.unit|SECONDS|Time unit corresponding to blocking duration|
153-
|http.project.config.manager.sdk.key|null|Optimizely project SDK key|
148+
|`http.project.config.manager.polling.duration`|5|Fixed delay between fetches for the datafile|
149+
|`http.project.config.manager.polling.unit`|MINUTES|Time unit corresponding to polling interval|
150+
|`http.project.config.manager.blocking.duration`|10|Maximum time to wait for initial bootstrapping|
151+
|`http.project.config.manager.blocking.unit`|SECONDS|Time unit corresponding to blocking duration|
152+
|`http.project.config.manager.sdk.key`|null|Optimizely project SDK key|
153+
154154

155+
## `optimizely.properties`
155156

156-
## Optimizely properties file
157+
When an `optimizely.properties` file is available within the runtime classpath it can be used to provide
158+
default values of a given Optimizely resource. Refer to the resource implementation for available configuration parameters.
157159

158-
An Optimizely properties file, `optimizely.properties`, that is available within the runtime classpath can be used to configure
159-
the default values of a given Optimizely resource. Refer to the resource implementation for available configuration
160-
parameters.
160+
### Example `optimizely.properties` file
161161

162-
#### Example:
163162
```properties
164163
http.project.config.manager.polling.duration = 1
165164
http.project.config.manager.polling.unit = MINUTES
@@ -168,22 +167,25 @@ async.event.handler.queue.capacity = 20000
168167
async.event.handler.num.workers = 5
169168
```
170169

171-
## OptimizelyFactory
172170

173-
The [`OptimizelyFactory`](https://github.com/optimizely/java-sdk/blob/master/core-httpclient-impl/src/main/java/com/optimizely/ab/OptimizelyFactory.java)
174-
included in this package provides basic utility to instantiate the Optimizely SDK
175-
with a minimal number of provided configuration options. Configuration properties are sourced from Java system properties,
176-
environment variables or from an `optimizely.properties` file, in that order. Not all configuration and initialization
177-
are captured via the `OptimizelyFactory`, for those use cases the resources can be built via their respective builder
178-
classes.
171+
## `OptimizelyFactory`
172+
173+
In this package, [`OptimizelyFactory`](https://github.com/optimizely/java-sdk/blob/master/core-httpclient-impl/src/main/java/com/optimizely/ab/OptimizelyFactory.java)
174+
provides basic utility to instantiate the Optimizely SDK with a minimal number of configuration options.
175+
Configuration properties are sourced from Java system properties, environment variables, or an
176+
`optimizely.properties` file, in that order.
177+
178+
`OptimizelyFactory` does not capture all configuration and initialization options. For more use cases,
179+
build the resources via their respective builder classes.
180+
181+
### Use `OptimizelyFactory`
179182

180-
### Usage
181-
The SDK key is required to be provided at runtime either directly via the factory method:
183+
You must provide the SDK key at runtime, either directly via the factory method:
182184
```Java
183185
Optimizely optimizely = OptimizelyFactory.newDefaultInstance(<<SDK_KEY>>);
184186
```
185187

186-
If the SDK is provided via a global property then the empty signature can be used:
188+
If you provide the SDK via a global property, use the empty signature:
187189
```Java
188190
Optimizely optimizely = OptimizelyFactory.newDefaultInstance();
189191
```

0 commit comments

Comments
 (0)