Skip to content

Commit 91ced91

Browse files
author
Mike Davis
authored
Add more documentation. (#323)
1 parent 3de29fe commit 91ced91

File tree

3 files changed

+114
-2
lines changed

3 files changed

+114
-2
lines changed

‎core-api/README.md

+105
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Java SDK Core API
2+
This package contains the core APIs and interfaces for the Optimizely Full Stack API in Java.
3+
4+
Full product documentation is in the [Optimizely developers documentation](https://docs.developers.optimizely.com/full-stack/docs/welcome).
5+
6+
## Installation
7+
8+
### Gradle
9+
```groovy
10+
compile 'com.optimizely.ab:core-api:{VERSION}'
11+
```
12+
13+
### Maven
14+
```xml
15+
<dependency>
16+
<groupId>com.optimizely.ab</groupId>
17+
<artifactId>core-api</artifactId>
18+
<version>{VERSION}</version>
19+
</dependency>
20+
21+
```
22+
23+
## Optimizely
24+
[`Optimizely`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/Optimizely.java)
25+
provides top level API access to the Full Stack project.
26+
27+
### Usage
28+
```Java
29+
Optimizely optimizely = Optimizely.builder()
30+
.withConfigManager(configManager)
31+
.withEventProcessor(eventProcessor)
32+
.build();
33+
34+
Variation variation = optimizely.activate("ad-test");
35+
optimizely.track("conversion");
36+
```
37+
38+
## ErrorHandler
39+
The [`ErrorHandler`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/error/ErrorHandler.java)
40+
interface is available for handling errors from the SDK without interfering with the host application.
41+
42+
### NoOpErrorHandler
43+
The [`NoOpErrorHandler`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/error/NoOpErrorHandler.java)
44+
is the default `ErrorHandler` implemetation that silently consumes all errors raised from the SDK.
45+
46+
### RaiseExceptionErrorHandler
47+
The [`RaiseExceptionErrorHandler`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/error/RaiseExceptionErrorHandler.java)
48+
is an implementation of `ErrorHandler` best suited for testing and development where **all** errors are raised, potentially crashing
49+
the hosting application.
50+
51+
## EventProcessor
52+
The [`EventProcessor`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/event/EventProcessor.java)
53+
interface is used to provide an intermediary processing stage within event production.
54+
It's assumed that the `EventProcessor` dispatches events via a provided `EventHandler`.
55+
56+
### BatchEventProcessor
57+
[`BatchEventProcessor`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/event/BatchEventProcessor.java)
58+
is an implementation of `EventProcessor` where events are batched. The class maintains a single consumer thread that pulls
59+
events off of the `BlockingQueue` and buffers them for either a
60+
configured batch size or a maximum duration before the resulting `LogEvent` is sent to the `EventDispatcher` and `NotificationCenter`.
61+
62+
### ForwardingEventProcessor
63+
The [`ForwardingEventProcessor`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/event/ForwardingEventProcessor.java)
64+
implements `EventProcessor` for backwards compatibility. Each event processed is converted into a [`LogEvent`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/event/ForwardingEventProcessor.java)
65+
message before it is sent synchronously to the supplied `EventHandler`.
66+
67+
## EventHandler
68+
The [`EventHandler`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/event/EventHandler.java)
69+
interface is used for dispatching events to the Optimizely event endpoint. Implementations of `EventHandler#dispatchEvent(LogEvent)` are expected
70+
to make an HTTP request of type `getRequestMethod()` to the `LogEvent#getEndpointUrl()` location. The corresponding request parameters and body
71+
are available via `LogEvent#getRequestParams()` and `LogEvent#getBody()` respectively.
72+
73+
### NoopEventHandler
74+
The [`NoopEventHandler`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/event/NoopEventHandler.java)
75+
implements `EventHandler` with no side-effects. `NoopEventHandler` is useful for testing or non-production environments.
76+
77+
## NotificationCenter
78+
The [`NotificationCenter`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/notification/NotificationCenter.java)
79+
is the centralized component for subscribing to notifications from the SDK. Subscribers must implement the `NotificationHandler<T>` interface
80+
and are registered via `NotificationCenterxaddNotificationHandler`. Note that notifications are called synchronously and have the potential to
81+
block the main thread.
82+
83+
## ProjectConfig
84+
The [`ProjectConfig`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/config/ProjectConfig.java)
85+
represents the current state of the Optimizely project as configured through [optimizely.com](https://www.optimizely.com/).
86+
The interface is currently unstable and only used internally. All public access to this implementation is subject to change
87+
with each subsequent version.
88+
89+
### DatafileProjectConfig
90+
The [`DatafileProjectConfig`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/config/DatafileProjectConfig.java)
91+
is an implementation of `ProjectConfig` backed by a file, typically sourced from the Optimizely CDN.
92+
93+
## ProjectConfigManager
94+
The [`ProjectConfigManager`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/config/ProjectConfigManager.java)
95+
is a factory class that provides `ProjectConfig`. Implementations of this class provide a consistent representation
96+
of a `ProjectConfig` that can be references between service calls.
97+
98+
### AtomicProjectConfigManager
99+
The [`AtomicProjectConfigManager`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/config/AtomicProjectConfigManager.java)
100+
is a static provider that can be updated atomically to provide a consistent view of a `ProjectConfig`.
101+
102+
### PollingProjectConfigManager
103+
The [`PollingProjectConfigManager`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/config/PollingProjectConfigManager.java)
104+
is an abstract class that provides the framework for a dynamic factory that updates asynchronously within a background thread.
105+
Implementations of this class can be used to poll from an externalized sourced without blocking the main application thread.

‎core-api/src/main/java/com/optimizely/ab/event/BatchEventProcessor.java

+2-1
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,8 @@
3636
*
3737
* The BatchEventProcessor maintains a single consumer thread that pulls events off of
3838
* the BlockingQueue and buffers them for either a configured batch size or for a
39-
* maximum duration before the resulting LogEvent is sent to the NotificationManager.
39+
* maximum duration before the resulting LogEvent is sent to the EventHandler
40+
* and NotificationCenter.
4041
*/
4142
public class BatchEventProcessor implements EventProcessor, AutoCloseable {
4243

‎core-httpclient-impl/README.md

+7-1
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,6 @@ The following properties can be set to override the default configuration.
119119
|**async.event.handler.event.max.per.route**|20|Maximum number of connections per route|
120120
|**async.event.handler.validate.after**|5000|Time to maintain idol connections (in milliseconds)|
121121

122-
123122
## HttpProjectConfigManager
124123

125124
[`HttpProjectConfigManager`](https://github.com/optimizely/java-sdk/blob/master/core-httpclient-impl/src/main/java/com/optimizely/ab/config/HttpProjectConfigManager.java)
@@ -230,3 +229,10 @@ If you provide the SDK via a global property, use the empty signature:
230229
```Java
231230
Optimizely optimizely = OptimizelyFactory.newDefaultInstance();
232231
```
232+
233+
### Event batching
234+
`OptimizelyFactory` uses the [`BatchEventProcessor`](https://github.com/optimizely/java-sdk/blob/master/core-api/src/main/java/com/optimizely/ab/event/BatchEventProcessor.java)
235+
to enable request batching to the Optimizely logging endpoint. By default, a maximum of 10 events are included in each batch
236+
for a maximum interval of 30 seconds. These parameters are configurable via systems properties or through the
237+
`OptimizelyFactory#setMaxEventBatchSize` and `OptimizelyFactory#setMaxEventBatchInterval` methods.
238+

0 commit comments

Comments
 (0)