Skip to content

Commit 4ac4cdb

Browse files
greenrobot-teamgreenrobot-team
committed
Sync client: make url a builder option
1 parent 5a4b02b commit 4ac4cdb

6 files changed

Lines changed: 50 additions & 60 deletions

File tree

‎objectbox-java/src/main/java/io/objectbox/sync/Sync.java‎

Lines changed: 13 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,6 @@
1616

1717
package io.objectbox.sync;
1818

19-
import java.util.Collections;
20-
import java.util.List;
21-
2219
import io.objectbox.BoxStore;
2320
import io.objectbox.BoxStoreBuilder;
2421
import io.objectbox.sync.server.SyncServer;
@@ -54,40 +51,20 @@ public static boolean isHybridAvailable() {
5451
}
5552

5653
/**
57-
* Starts building a {@link SyncClient} for the given {@link BoxStore} and server URL.
54+
* Starts building a {@link SyncClient} for the given {@link BoxStore}.
5855
* <p>
5956
* This does not initiate any connection attempts yet: call {@link SyncBuilder#buildAndStart()} to do so. Before,
60-
* you must configure credentials via {@link SyncBuilder#credentials(SyncCredentials)}.
57+
* you must configure the server URL via {@link SyncBuilder#url(String)} and add credentials via
58+
* {@link SyncBuilder#credentials(SyncCredentials)}.
6159
* <p>
6260
* By default, a Sync client automatically receives updates from the server once login succeeded. To configure this
6361
* differently, call {@link SyncBuilder#requestUpdatesMode(SyncBuilder.RequestUpdatesMode)} with the wanted mode.
6462
*
6563
* @param boxStore The {@link BoxStore} the client should use.
66-
* @param url The URL of the Sync server on which the Sync protocol is exposed. This is typically a WebSockets URL
67-
* starting with {@code ws://} or {@code wss://} (for encrypted connections), for example
68-
* {@code ws://127.0.0.1:9999}.
6964
* @return a builder to configure the Sync client
70-
* @see #client(BoxStore, List)
7165
*/
72-
public static SyncBuilder client(BoxStore boxStore, String url) {
73-
return client(boxStore, Collections.singletonList(url));
74-
}
75-
76-
/**
77-
* Like {@link #client(BoxStore, String)}, but supports passing multiple URLs.
78-
* <p>
79-
* Passing multiple URLs allows high availability and load balancing (i.e. using an ObjectBox Sync Server Cluster).
80-
* <p>
81-
* A random URL is selected for each connection attempt.
82-
*
83-
* @param boxStore The {@link BoxStore} the client should use.
84-
* @param urls A list of URLs of Sync servers on which the Sync protocol is exposed. These are typically WebSockets
85-
* URLs starting with {@code ws://} or {@code wss://} (for encrypted connections), for example
86-
* {@code ws://127.0.0.1:9999}.
87-
* @return a builder to configure the Sync client
88-
*/
89-
public static SyncBuilder client(BoxStore boxStore, List<String> urls) {
90-
return new SyncBuilder(boxStore, urls);
66+
public static SyncBuilder client(BoxStore boxStore) {
67+
return new SyncBuilder(boxStore);
9168
}
9269

9370
/**
@@ -98,24 +75,26 @@ public static SyncBuilder client(BoxStore boxStore, List<String> urls) {
9875
* starting with {@code ws://} or {@code wss://} (for encrypted connections), for example
9976
* {@code ws://127.0.0.1:9999}.
10077
* @param credentials {@link SyncCredentials} to authenticate with the server.
101-
* @deprecated Use {@link #client(BoxStore, String)} and {@link SyncBuilder#credentials(SyncCredentials)} instead.
78+
* @deprecated Use {@link #client(BoxStore)}, {@link SyncBuilder#url(String)} and
79+
* {@link SyncBuilder#credentials(SyncCredentials)} instead.
10280
*/
10381
@Deprecated
10482
public static SyncBuilder client(BoxStore boxStore, String url, SyncCredentials credentials) {
105-
SyncBuilder builder = client(boxStore, url);
106-
builder.credentials(credentials);
107-
return builder;
83+
return client(boxStore)
84+
.url(url)
85+
.credentials(credentials);
10886
}
10987

11088
/**
11189
* Like {@link #client(BoxStore, String, SyncCredentials)}, but supports passing a set of authentication methods.
11290
*
11391
* @param multipleCredentials An array of {@link SyncCredentials} to be used to authenticate with the server.
114-
* @deprecated Use {@link #client(BoxStore, String)} and {@link SyncBuilder#credentials(SyncCredentials)} instead.
92+
* @deprecated Use {@link #client(BoxStore)}, {@link SyncBuilder#url(String)} and
93+
* {@link SyncBuilder#credentials(SyncCredentials)} instead.
11594
*/
11695
@Deprecated
11796
public static SyncBuilder client(BoxStore boxStore, String url, SyncCredentials[] multipleCredentials) {
118-
SyncBuilder builder = client(boxStore, url);
97+
SyncBuilder builder = client(boxStore).url(url);
11998
//noinspection ConstantValue
12099
if (multipleCredentials != null) {
121100
for (SyncCredentials credentials : multipleCredentials) {

‎objectbox-java/src/main/java/io/objectbox/sync/SyncBuilder.java‎

Lines changed: 30 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,6 @@
2525
import javax.annotation.Nullable;
2626

2727
import io.objectbox.BoxStore;
28-
import io.objectbox.annotation.apihint.Internal;
2928
import io.objectbox.exception.FeatureNotAvailableException;
3029
import io.objectbox.sync.internal.Platform;
3130
import io.objectbox.sync.listener.SyncChangeListener;
@@ -36,19 +35,13 @@
3635
import io.objectbox.sync.listener.SyncTimeListener;
3736

3837
/**
39-
* A builder to create a {@link SyncClient}; the builder itself should be created via
40-
* {@link Sync#client(BoxStore, String, SyncCredentials)}.
38+
* A builder to create a {@link SyncClient}; the builder itself should be created via {@link Sync#client(BoxStore)}.
4139
*/
4240
@SuppressWarnings({"unused", "WeakerAccess"})
4341
public final class SyncBuilder {
4442

4543
final Platform platform;
4644
final BoxStore boxStore;
47-
/**
48-
* The server URLs this client may connect to.
49-
* <p>
50-
* See {@link Sync#client(BoxStore, List)} for notes on multiple URLs.
51-
*/
5245
final List<String> urls = new ArrayList<>();
5346
final List<SyncCredentials> credentials = new ArrayList<>();
5447

@@ -107,30 +100,49 @@ private static void checkSyncFeatureAvailable() {
107100
/**
108101
* Creates a builder for a {@link SyncClient}.
109102
* <p>
110-
* Don't use this directly, use the {@link Sync#client} methods instead.
103+
* Don't use this directly, use the {@link Sync#client} method instead.
111104
*/
112-
SyncBuilder(BoxStore boxStore, List<String> urls) {
105+
SyncBuilder(BoxStore boxStore) {
113106
checkNotNull(boxStore, "boxStore");
114-
checkNotNull(urls, "urls");
115107
this.boxStore = boxStore;
116-
// For SyncHybridBuilder, delay validating there is a URL until the build call
117-
for (String url : urls) {
118-
url(url);
119-
}
120108
checkSyncFeatureAvailable();
121109
this.platform = Platform.findPlatform(); // Requires APIs only present in Android Sync library
122110
}
123111

124112
/**
125-
* Allows internal code to set the Sync server URL after creating this builder.
113+
* Adds a Sync server URL the client should connect to.
114+
* <p>
115+
* This is typically a WebSockets URL starting with {@code ws://} or {@code wss://} (for encrypted connections), for
116+
* example if the server is running on localhost {@code ws://127.0.0.1:9999}.
117+
* <p>
118+
* Can be called multiple times to add multiple URLs for high availability and load balancing (like when using an
119+
* ObjectBox Sync Server Cluster). A random URL is selected for each connection attempt.
120+
*
121+
* @param url The URL of the Sync server on which the Sync protocol is exposed.
122+
* @return this builder for chaining
123+
* @see #urls(List)
126124
*/
127-
@Internal
128-
SyncBuilder url(String url) {
125+
public SyncBuilder url(String url) {
129126
checkNotNull(url, "url");
130127
this.urls.add(url);
131128
return this;
132129
}
133130

131+
/**
132+
* Like {@link #url(String)}, but accepts a list of URLs.
133+
*
134+
* @param urls A list of URLs of Sync servers on which the Sync protocol is exposed.
135+
* @return this builder for chaining
136+
* @see #url(String)
137+
*/
138+
public SyncBuilder urls(List<String> urls) {
139+
checkNotNull(urls, "urls");
140+
for (String url : urls) {
141+
url(url);
142+
}
143+
return this;
144+
}
145+
134146
/**
135147
* Adds {@link SyncCredentials} to authenticate the client with the server.
136148
*/

‎objectbox-java/src/main/java/io/objectbox/sync/SyncClient.java‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,6 @@
2121

2222
import javax.annotation.Nullable;
2323

24-
import io.objectbox.BoxStore;
2524
import io.objectbox.annotation.apihint.Experimental;
2625
import io.objectbox.sync.SyncBuilder.RequestUpdatesMode;
2726
import io.objectbox.sync.listener.SyncChangeListener;
@@ -53,7 +52,7 @@ public interface SyncClient extends Closeable {
5352
/**
5453
* Gets the sync server URLs this client may connect to.
5554
* <p>
56-
* See {@link Sync#client(BoxStore, List)} for notes on multiple URLs.
55+
* See {@link SyncBuilder#url(String)} for notes on multiple URLs.
5756
*/
5857
List<String> getUrls();
5958

‎objectbox-java/src/main/java/io/objectbox/sync/SyncHybridBuilder.java‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,6 @@
1616

1717
package io.objectbox.sync;
1818

19-
import java.util.Collections;
20-
2119
import io.objectbox.BoxStore;
2220
import io.objectbox.BoxStoreBuilder;
2321
import io.objectbox.InternalAccess;
@@ -48,7 +46,8 @@ public final class SyncHybridBuilder {
4846
boxStore = storeBuilder.build();
4947
boxStoreServer = storeBuilderServer.build();
5048
SyncCredentials clientCredentials = authenticatorCredentials.createClone();
51-
clientBuilder = new SyncBuilder(boxStore, Collections.emptyList()).credentials(clientCredentials); // Do not yet set URL, port may be dynamic
49+
// Do not yet set URL, port may only be chosen once server is started, see buildAndStart()
50+
clientBuilder = new SyncBuilder(boxStore).credentials(clientCredentials);
5251
serverBuilder = new SyncServerBuilder(boxStoreServer, url, authenticatorCredentials);
5352
}
5453

‎objectbox-java/src/main/java/io/objectbox/sync/package-info.java‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,9 @@
2222
* <ol>
2323
* <li>Create a BoxStore as usual (using MyObjectBox).</li>
2424
* <li>Build a {@link io.objectbox.sync.SyncClient} using
25-
* {@link io.objectbox.sync.Sync#client(io.objectbox.BoxStore, java.lang.String) Sync.client(boxStore, url)} and at
26-
* least one set of credentials with {@link io.objectbox.sync.SyncBuilder#credentials(io.objectbox.sync.SyncCredentials)}.</li>
25+
* {@link io.objectbox.sync.Sync#client(io.objectbox.BoxStore) Sync.client(boxStore)}, a
26+
* {@link io.objectbox.sync.SyncBuilder#url(java.lang.String)} and at least one set of credentials with
27+
* {@link io.objectbox.sync.SyncBuilder#credentials(io.objectbox.sync.SyncCredentials)}.</li>
2728
* <li>Optional: use the {@link io.objectbox.sync.SyncBuilder} instance from the last step to configure the sync
2829
* client and set initial listeners.</li>
2930
* <li>Call {@link io.objectbox.sync.SyncBuilder#buildAndStart()} to get an instance of

‎tests/objectbox-java-test/src/test/java/io/objectbox/sync/SyncTest.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ public void creatingSyncClient_throws() {
6060
// If no Sync feature is available
6161
FeatureNotAvailableException exception = assertThrows(
6262
FeatureNotAvailableException.class,
63-
() -> Sync.client(store, SERVER_URL)
63+
() -> Sync.client(store)
6464
);
6565
String message = exception.getMessage();
6666
assertTrue(message, message.contains("does not include ObjectBox Sync") &&

0 commit comments

Comments
 (0)