8000 Merge pull request #12 from asafch/documentation · AppsFlyer/unleash-client-clojure@d69d7a7 · GitHub
[go: up one dir, main page]
Skip to content

Commit d69d7a7

Browse files
barkanidobarkanido
authored
Merge pull request #12 from asafch/documentation
Documentation overhaul
2 parents 2a03fbe + 94e9f0b commit d69d7a7

File tree

14 files changed

+335
-197
lines changed

14 files changed

+335
-197
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,4 @@ pom.xml.asc
1616
.lsp
1717
.settings
1818
.project
19+
.idea

‎.travis.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ jobs:
1313
- stage: build
1414
script: lein javac
1515
- stage: test
16-
script: lein do clean, javac, test
16+
script: lein do clean, test
1717
after_success:
1818
- bash -ex test/coveralls.sh
1919
notifications:

‎doc/intro.md

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎project.clj

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
1-
(defproject unleash-client-clojure "0.2.0"
1+
(defproject unleash-client-clojure "0.2.1"
22
:description "A Clojure library wrapping https://github.com/Unleash/unleash-client-java"
33
:url "https://github.com/AppsFlyer/unleash-client-clojure"
44
:license {:name "EPL-2.0 OR GPL-2.0-or-later WITH Classpath-exception-2.0"
5-
:url "https://www.eclipse.org/legal/epl-2.0/"}
5+
:url "https://www.eclipse.org/legal/epl-2.0/"}
66
:dependencies [[no.finn.unleash/unleash-client-java "3.3.3"]]
77
:profiles {:dev {:dependencies [[org.clojure/clojure "1.10.1"]
88
[clj-kondo "RELEASE"]
99
[org.apache.logging.log4j/log4j-core "2.11.2"]]
10-
:aliases {"clj-kondo" ["run" "-m" "clj-kondo.main"]
11-
"lint" ["run" "-m" "clj-kondo.main" "--lint" "src" "test"]}
12-
:plugins [[lein-ancient "0.6.15"]
10+
:aliases {"clj-kondo" ["run" "-m" "clj-kondo.main"]
11+
"lint" ["run" "-m" "clj-kondo.main" "--lint" "src" "test"]}
12+
:plugins [[lein-ancient "0.6.15"]
1313
[lein-cloverage "1.2.0"]]
14-
:global-vars {*warn-on-reflection* true}}})
14+
:global-vars {*warn-on-reflection* true}}})

‎src/unleash_client_clojure/builder.clj

Lines changed: 134 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,142 @@
11
(ns unleash-client-clojure.builder
2+
"Create and configure builders that build instances of UnleashConfig."
23
(:import [no.finn.unleash CustomHttpHeadersProvider UnleashContextProvider]
34
[no.finn.unleash.util UnleashConfig UnleashConfig$Builder UnleashScheduledExecutor]
45
[no.finn.unleash.event UnleashSubscriber]))
56

6-
(defn build ^UnleashConfig [& fs]
7-
(let [bldr (UnleashConfig$Builder.)]
7+
(defn build
8+
"Expects to be applied with a variadic number of arguments, each of which is a function that expects an
9+
UnleashConfig$Builder instance.
10+
Returns an instance of UnleashConfig that had all of its parameters set by said functions.
11+
12+
Using this building pattern allows users to manipulate the builder instance in ways that aren't
13+
implemented in this library by passing a function that expects an UnleashConfig$Builder.
14+
15+
Example:
16+
(build (app-name \"test-app\")
17+
(unleash-api \"http://example.unleash.com/api\"))"
18+
^UnleashConfig [& builder-param-setters]
19+
(let [builder (UnleashConfig$Builder.)]
820
(.build ^UnleashConfig$Builder
921
(reduce
1022
(fn
11-
([] bldr)
12-
([bldr f]
13-
(f bldr)))
14-
bldr
15-
fs))))
16-
17-
(defn app-name [^String name]
18-
(fn [^UnleashConfig$Builder bldr]
19-
(.appName bldr name)))
20-
21-
(defn instance-id [^String id]
22-
(fn [^UnleashConfig$Builder bldr]
23-
(.instanceId bldr id)))
24-
25-
(defn unleash-api [^String api]
26-
(fn [^UnleashConfig$Builder bldr]
27-
(.unleashAPI bldr api)))
28-
29-
(defn custom-http-header [header-name header-value]
30-
(fn [^UnleashConfig$Builder bldr]
31-
(.customHttpHeader bldr header-name header-value)))
32-
33-
(defn send-metrics-interval [^Long interval-seconds]
34-
(fn [^UnleashConfig$Builder bldr]
35-
(.sendMetricsInterval bldr interval-seconds)))
36-
37-
(defn fetch-toggles-interval [^Long interval-seconds]
38-
(fn [^UnleashConfig$Builder bldr]
39-
(.fetchTogglesInterval bldr interval-seconds)))
40-
41-
(defn synchronous-fetch-on-initialisation [enable?]
42-
(fn [^UnleashConfig$Builder bldr]
43-
(.synchronousFetchOnInitialisation bldr enable?)))
44-
45-
(defn enable-proxy-authentication-by-jvm-properties []
46-
(fn [^UnleashConfig$Builder bldr]
47-
(.enableProxyAuthenticationByJvmProperties bldr)))
48-
49-
(defn backup-file [^String backup-file]
50-
(fn [^UnleashConfig$Builder bldr]
51-
(.backupFile bldr backup-file)))
52-
53-
(defn environment [^String environment]
54-
(fn [^UnleashConfig$Builder bldr]
55-
(.environment bldr environment)))
56-
57-
(defn custom-http-header-provider [^CustomHttpHeadersProvider provider]
58-
(fn [^UnleashConfig$Builder bldr]
59-
(.customHttpHeadersProvider bldr provider)))
60-
61-
(defn unleash-context-provider [^UnleashContextProvider provider]
62-
(fn [^UnleashConfig$Builder bldr]
63-
(.unleashContextProvider bldr provider)))
64-
65-
(defn scheduled-executor [^UnleashScheduledExecutor executor]
66-
(fn [^UnleashConfig$Builder bldr]
67-
(.scheduledExecutor bldr executor)))
68-
69-
(defn subscriber [^UnleashSubscriber subscriber]
70-
(fn [^UnleashConfig$Builder bldr]
71-
(.subscriber bldr subscriber)))
23+
([] builder)
24+
([builder set-builder-param]
25+
(set-builder-param builder)))
26+
builder
27+
builder-param-setters))))
28+
29+
(defn app-name
30+
"Expects an application name.
31+
Returns a function that expects an UnleashConfig$Builder, and sets the appName property of the builder."
32+
[^String name]
33+
(fn [^UnleashConfig$Builder builder]
34+
(.appName builder name)))
35+
36+
(defn instance-id
37+
"Expects an instance ID.
38+
Returns a function that expects an UnleashConfig$Builder, and sets the instanceId property of the builder."
39+
[^String id]
40+
(fn [^UnleashConfig$Builder builder]
41+
(.instanceId builder id)))
42+
43+
(defn unleash-api
44+
"Expects a URL for an Unleash server.
45+
Returns a function that expects an UnleashConfig$Builder, and sets the unleashAPI property of the builder."
46+
[^String api]
47+
(fn [^UnleashConfig$Builder builder]
48+
(.unleashAPI builder api)))
49+
50+
(defn custom-http-header
51+
"Expects an HTTP header name and value.
52+
Returns a function that expects an UnleashConfig$Builder, and adds the relevant HTTP header name and value to the headers used by the builder.
53+
These headers would be added to outgoing HTTP requests sent by the Unleash client to the Unleash server.
54+
55+
Can be used multiple times to set multiple headers.
56+
57+
Example:
58+
(build [(unleash-api \"http://example.unleash.com/api\")
59+
(custom-http-header \"X-AF-HEADER-1\" \"a\")
60+
(custom-http-header \"X-AF-HEADER-2\" \"b\")
61+
(custom-http-header \"X-AF-HEADER-3\" \"c\")])"
62+
[header-name header-value]
63+
(fn [^UnleashConfig$Builder builder]
64+
(.customHttpHeader builder header-name header-value)))
65+
66+
(defn send-metrics-interval
67+
"Expects a long that marks the interval (in seconds) of sending metrics.
68+
Returns a function that expects an UnleashConfig$Builder, and sets the sendMetricsInterval property of the builder."
69+
[^Long interval-seconds]
70+
(fn [^UnleashConfig$Builder builder]
71+
(.sendMetricsInterval builder interval-seconds)))
72+
73+
(defn fetch-toggles-interval
74+
"Expects a long that marks the interval (in seconds) of fetching toggles' states from the Unleash server.
75+
Returns a function that expects an UnleashConfig$Builder, and sets the fetchTogglesInterval property of the builder."
76+
[^Long interval-seconds]
77+
(fn [^UnleashConfig$Builder builder]
78+
(.fetchTogglesInterval builder interval-seconds)))
79+
80+
(defn synchronous-fetch-on-initialisation
81+
"Expects a boolean that controls if toggles are fetched synchronously when the Unleash client is initialised.
82+
Returns a function that expects an UnleashConfig$Builder, and sets the synchronousFetchOnInitialisation property of
83+
the builder."
84+
[enable?]
85+
(fn [^UnleashConfig$Builder builder]
86+
(.synchronousFetchOnInitialisation builder enable?)))
87+
88+
(defn enable-proxy-authentication-by-jvm-properties
89+
"Expects a boolean that controls if authentication against an HTTP proxy would use the JVM settings http.proxyUser and
90+
http.proxyPassword.
91+
Returns a function that expects an UnleashConfig$Builder, and sets the isProxyAuthenticationByJvmProperties property of the builder."
92+
[]
93+
(fn [^UnleashConfig$Builder builder]
94+
(.enableProxyAuthenticationByJvmProperties builder)))
95+
96+
(defn backup-file
97+
"Expects a backup file path, into which the Unleash client would backup its state to be used when the Unleash server
98+
is unavailable. By defeault this would be unleash-repo.json in the directory set by the JVM property java.io.tmpdir.
99+
Returns a function that expects an UnleashConfig$Builder, and sets the backupFile property of the builder."
100+
[^String backup-file]
101+
(fn [^UnleashConfig$Builder builder]
102+
(.backupFile builder backup-file)))
103+
104+
(defn environment
105+
"Expects an application environment.
106+
Returns a function that expects an UnleashConfig$Builder, and sets the environment property of the builder."
107+
[^String environment]
108+
(fn [^UnleashConfig$Builder builder]
109+
(.environment builder environment)))
110+
111+
(defn custom-http-header-provider
112+
"Expects an instance of CustomHttpHeadersProvider, which adds headers to outgoing HTTP requests that are sent to the
113+
Unleash server, based on the contents of the request itself.
114+
Returns a function that expects an UnleashConfig$Builder, and sets the custom-http-headers-provider property of the
115+
builder."
116+
[^CustomHttpHeadersProvider provider]
117+
(fn [^UnleashConfig$Builder builder]
118+
(.customHttpHeadersProvider builder provider)))
119+
120+
121+
(defn unleash-context-provider
122+
"Expects an instance of UnleashContextProvider, which would provide the context for calls of enabled? instead of
123+
having it provided as an arguments in the call site.
124+
Returns a function that expects an UnleashConfig$Builder, and sets the contextProvider property of the builder."
125+
[^UnleashContextProvider provider]
126+
(fn [^UnleashConfig$Builder builder]
127+
(.unleashContextProvider builder provider)))
128+
129+
(defn scheduled-executor
130+
"Expects an instance of UnleashScheduledExecutor, which would be used to periodically send usage metrics. The interval
131+
of sending those metrics can be set with 'send-metrics-interval'.
132+
Returns a function that expects an UnleashConfig$Builder, and sets the scheduledExecutor property of the builder."
133+
[^UnleashScheduledExecutor executor]
134+
(fn [^UnleashConfig$Builder builder]
135+
(.scheduledExecutor builder executor)))
136+
137+
(defn subscriber
138+
"Expects an instance of UnleashSubscriber, which would be notified when the Unleash client's internal state changes.
139+
Returns a function that expects an UnleashConfig$Builder, and sets the subscriber property of the builder."
140+
[^UnleashSubscriber subscriber]
141+
(fn [^UnleashConfig$Builder builder]
142+
(.subscriber builder subscriber)))

‎src/unleash_client_clojure/context.clj

Lines changed: 86 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,112 @@
11
(ns unleash-client-clojure.context
2+
"Create and configure builders that build instances of UnleashContext."
23
(:import [no.finn.unleash UnleashContext UnleashContext$Builder]))
34

4-
(defn build ^UnleashContext
5-
[& fs]
6-
(let [bldr (UnleashContext$Builder.)]
5+
(defn build
6+
"Expects to be applied with a variadic number of arguments, each of which is a function that expects an
7+
UnleashContext$Builder instance.
8+
Returns an instance of UnleashContext that had all of its parameters set by said functions.
9+
10+
Using this building pattern allows users to manipulate the builder instance in ways that aren't
11+
implemented in this library by passing a function that expects an UnleashContext$Builder.
12+
13+
Example:
14+
(build (app-name \"test-app\")
15+
(environment \"STG\"))
16+
17+
The UnleashContext instance can be attached to an Unleash client via
18+
unleash-client-clojure.builder/unleash-context-provider."
19+
^UnleashContext
20+
[& builder-param-setters]
21+
(let [builder (UnleashContext$Builder.)]
722
(.build ^UnleashContext$Builder
823
(reduce
924
(fn
10-
([] bldr)
11-
([bldr f]
12-
(f bldr)))
13-
bldr
14-
fs))))
25+
([] builder)
26+
([builder set-builder-param]
27+
(set-builder-param builder)))
28+
builder
29+
builder-param-setters))))
1530

16-
(defn get-app-name [^UnleashContext ctx]
31+
(defn get-app-name
32+
"Returns the app's name from the context."
33+
[^UnleashContext ctx]
1734
(.get (.getAppName ctx)))
1835

19-
(defn get-environment [^UnleashContext ctx]
36+
(defn get-environment
37+
"Returns the environment from the context."
38+
[^UnleashContext ctx]
2039
(.get (.getEnvironment ctx)))
2140

22-
(defn get-user-id [^UnleashContext ctx]
41+
(defn get-user-id
42+
"Returns the user ID from the context."
43+
[^UnleashContext ctx]
2344
(.get (.getUserId ctx)))
2445

25-
(defn get-session-id [^UnleashContext ctx]
46+
(defn get-session-id
47+
"Returns the session ID from the context."
48+
[^UnleashContext ctx]
2649
(.get (.getSessionId ctx)))
2750

28-
(defn get-remote-address [^UnleashContext ctx]
51+
(defn get-remote-address
52+
"Returns the remote address from the context."
53+
[^UnleashContext ctx]
2954
(.get (.getRemoteAddress ctx)))
3055

31-
(defn get-property [^UnleashContext ctx ^String property-name]
56+
(defn get-property
57+
"Returns a context property"
58+
[^UnleashContext ctx ^String property-name]
3259
(.get (.getProperties ctx) property-name))
3360

34-
(defn get-by-name [^UnleashContext ctx ^String contextName]
61+
(defn get-by-name
62+
"Returns a context property, explicitly looking for:
63+
- environment
64+
- appName
65+
- userId
66+
- sessionId
67+
- remoteAddress
68+
Otherwise, behaves as 'get-property'."
69+
[^UnleashContext ctx ^String contextName]
3570
(.get (.getByName ctx contextName)))
3671

37-
(defn app-name [^String app-name]
38-
(fn [^UnleashContext$Builder bldr]
39-
(.appName bldr app-name)))
40-
41-
(defn environment [^String environment]
42-
(fn [^UnleashContext$Builder bldr]
43-
(.environment bldr environment)))
72+
(defn app-name
73+
"Expects an application's name.
74+
Returns a function that expects an UnleashContext$Builder, and sets the appName property of the builder."
75+
[^String app-name]
76+
(fn [^UnleashContext$Builder builder]
77+
(.appName builder app-name)))
4478

45-
(defn user-id [^String id]
46-
(fn [^UnleashContext$Builder bldr]
47-
(.userId bldr id)))
79+
(defn environment
80+
"Expects an application environment.
81+
Returns a function that expects an UnleashContext$Builder, and sets the environment property of the builder."
82+
[^String environment]
83+
(fn [^UnleashContext$Builder builder]
84+
(.environment builder environment)))
4885

49-
(defn session-id [^String id]
50-
(fn [^UnleashContext$Builder bldr]
51-
(.sessionId bldr id)))
86+
(defn user-id
87+
"Expects a user ID.
88+
Returns a function that expects an UnleashContext$Builder, and sets the userId property of the builder."
89+
[^String id]
90+
(fn [^UnleashContext$Builder builder]
91+
(.userId builder id)))
5292

53-
(defn remote-address [^String address]
54-
(fn [^UnleashContext$Builder bldr]
55-
(.remoteAddress bldr address)))
93+
(defn session-id
94+
"Expects a session ID.
95+
Returns a function that expects an UnleashContext$Builder, and sets the sessionId property of the builder."
96+
[^String id]
97+
(fn [^UnleashContext$Builder builder]
98+
(.sessionId builder id)))
5699

57-
(defn add-property [^String name ^String value]
58-
(fn [^UnleashContext$Builder bldr]
59-
(.addProperty bldr name value)))
100+
(defn remote-address
101+
"Expects a remote address (IP address). Used by RemoteAddressStrategy.
102+
Returns a function that expects an UnleashContext$Builder, and sets the remoteAddress property of the builder."
103+
[^String address]
104+
(fn [^UnleashContext$Builder builder]
105+
(.remoteAddress builder address)))
60106

107+
(defn add-property
108+
"Expects a property name-value pair.
109+
Returns a function that expects an UnleashContext$Builder, and adds the key-value pair to the context's properties."
110+
[^String name ^String value]
111+
(fn [^UnleashContext$Builder builder]
112+
(.addProperty builder name value)))

0 commit comments

Comments
 (0)
0