Skip to content

Commit e288ecd

Browse files
greenrobotgreenrobot
committed
TreeTest: rename root() to getRoot(), add getRootId(), implement Closeable, add JavaDocs
1 parent 2b6c36e commit e288ecd

2 files changed

Lines changed: 128 additions & 9 deletions

File tree

  • objectbox-java/src/main/java/io/objectbox/tree
  • tests/objectbox-java-test/src/test/java/io/objectbox/tree

‎objectbox-java/src/main/java/io/objectbox/tree/Tree.java‎

Lines changed: 123 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,31 @@
77
import io.objectbox.model.PropertyType;
88

99
import javax.annotation.Nullable;
10+
import java.io.Closeable;
1011
import java.util.concurrent.Callable;
1112

1213
/**
1314
* Points to a root branch, can traverse child branches and read and write data in leafs.
15+
* <p>
16+
* To navigate in the tree, you typically start with {@link #getRoot()}, which returns a {@link Branch}.
17+
* From one branch you can navigate to other branches and also {@link Leaf}s, which carry data attributes.
18+
* <p>
19+
* You can easily navigate the tree by using a path, which is either a string or a string array.
20+
* A path refers to the names of the meta tree nodes, e.g. "Book.Author.Name".
21+
* <p>
22+
* If you already know the IDs, you can efficiently access branches, data leaves, and data values directly.
23+
* <p>
24+
* To access any data in the tree, you must use explicit transactions offer by methods such as
25+
* {@link #runInTx(Runnable)}, {@link #runInReadTx(Runnable)}, {@link #callInTx(Callable)}, or
26+
* {@link #callInReadTx(Callable)}.
1427
*/
1528
@SuppressWarnings("SameParameterValue")
1629
@Experimental
17-
public class Tree {
30+
public class Tree implements Closeable {
1831

1932
private long handle;
2033
private final BoxStore store;
34+
private long rootId;
2135

2236
/**
2337
* Create a tree instance for the given meta-branch root {@code uid}, or find a singular root if 0 is given.
@@ -36,10 +50,11 @@ public Tree(BoxStore store, String uid) {
3650
}
3751

3852
/**
39-
* Create a tree instance for the given meta-branch root {@code uid}, or find a singular root if 0 is given.
53+
* Create a tree instance for the given data-branch root ID.
4054
*/
4155
public Tree(BoxStore store, long rootId) {
4256
this.store = store;
57+
this.rootId = rootId;
4358
//noinspection ConstantConditions Nullability annotations are not enforced.
4459
if (store == null) {
4560
throw new IllegalArgumentException("store must not be null");
@@ -51,29 +66,51 @@ long getHandle() {
5166
return handle;
5267
}
5368

69+
/**
70+
* The root ID, which the tree was constructed with.
71+
*/
72+
public long getRootId() {
73+
return rootId;
74+
}
75+
5476
public BoxStore getStore() {
5577
return store;
5678
}
5779

58-
public Branch root() {
80+
/**
81+
* Gets the root of the data tree.
82+
*/
83+
public Branch getRoot() {
5984
long dataBranchId = nativeGetRootId(handle);
6085
return new Branch(this, dataBranchId);
6186
}
6287

88+
/**
89+
* Cleans up any (native) resources associated with this tree.
90+
*/
6391
public void close() {
6492
long handle = this.handle;
6593
nativeDelete(handle);
6694
this.handle = 0;
6795
}
6896

97+
/**
98+
* Similar to {@link BoxStore#runInTx(Runnable)}, but allows Tree functions.
99+
*/
69100
public void runInTx(Runnable runnable) {
70101
store.runInTx(createTxRunnable(runnable));
71102
}
72103

104+
/**
105+
* Similar to {@link BoxStore#runInReadTx(Runnable)}, but allows Tree functions.
106+
*/
73107
public void runInReadTx(Runnable runnable) {
74108
store.runInReadTx(createTxRunnable(runnable));
75109
}
76110

111+
/**
112+
* Similar to {@link BoxStore#callInReadTx(Callable)}, but allows Tree functions.
113+
*/
77114
public <T> T callInTx(Callable<T> callable) throws Exception {
78115
return store.callInTx(createTxCallable(callable));
79116
}
@@ -89,6 +126,9 @@ public <T> T callInTxNoThrow(Callable<T> callable) {
89126
}
90127
}
91128

129+
/**
130+
* Similar to {@link BoxStore#callInReadTx(Callable)}, but allows Tree functions.
131+
*/
92132
public <T> T callInReadTx(Callable<T> callable) {
93133
return store.callInReadTx(createTxCallable(callable));
94134
}
@@ -154,33 +194,54 @@ public Double getDouble(long id) {
154194
return leaf != null ? leaf.asDouble() : null;
155195
}
156196

197+
/**
198+
* Puts (persists) a branch in the metamodel.
199+
*/
157200
public long putMetaBranch(long id, long parentBranchId, String name) {
158201
return nativePutMetaBranch(handle, id, parentBranchId, name, null);
159202
}
160203

204+
/**
205+
* Puts (persists) a branch in the metamodel with an optional description.
206+
*/
161207
public long putMetaBranch(long id, long parentBranchId, String name, @Nullable String description) {
162208
return nativePutMetaBranch(handle, id, parentBranchId, name, description);
163209
}
164210

211+
/**
212+
* Puts (persists) several branches in the metamodel to create the given path from the root.
213+
*/
165214
public long[] putMetaBranches(String[] path) {
166215
return nativePutMetaBranches(handle, 0, path);
167216
}
168217

218+
/**
219+
* Puts (persists) several branches in the metamodel from the given parent ID (must be a meta branch).
220+
*/
169221
public long[] putMetaBranches(long parentBranchId, String[] path) {
170222
return nativePutMetaBranches(handle, parentBranchId, path);
171223
}
172224

225+
/**
226+
* Puts (persists) a data leaf in the metamodel (describes values).
227+
*/
173228
public long putMetaLeaf(long id, long parentBranchId, String name, short valueType) {
174229
return nativePutMetaLeaf(handle, id, parentBranchId, name, valueType, false, null);
175230
}
176231

232+
/**
233+
* Puts (persists) a data leaf in the metamodel (describes values).
234+
*/
177235
public long putMetaLeaf(long id, long parentBranchId, String name, short valueType,
178-
boolean isUnsigned) {
236+
boolean isUnsigned) {
179237
return nativePutMetaLeaf(handle, id, parentBranchId, name, valueType, isUnsigned, null);
180238
}
181239

240+
/**
241+
* Puts (persists) a data leaf in the metamodel (describes values).
242+
*/
182243
public long putMetaLeaf(long id, long parentBranchId, String name, short valueType,
183-
boolean isUnsigned, @Nullable String description) {
244+
boolean isUnsigned, @Nullable String description) {
184245
return nativePutMetaLeaf(handle, id, parentBranchId, name, valueType, isUnsigned, description);
185246
}
186247

@@ -205,30 +266,87 @@ public long putBranch(long parentBranchId, long metaId) {
205266
return nativePutBranch(handle, 0, parentBranchId, metaId, null);
206267
}
207268

269+
270+
/**
271+
* Puts (persists) a data value (using a data leaf). If a data leaf exists at the given ID, it's overwritten.
272+
*
273+
* @param id Existing ID or zero to insert a new data leaf.
274+
* @param parentBranchId ID of the data branch, this data value belongs to.
275+
* @param metaId ID of the metadata leaf "describing" this data value.
276+
* @param value the actual data value.
277+
* @return the ID of the put data leaf.
278+
*/
208279
public long putValue(long id, long parentBranchId, long metaId, long value) {
209280
return nativePutValueInteger(handle, id, parentBranchId, metaId, value);
210281
}
211282

283+
/**
284+
* Puts (inserts) a new data value (using a data leaf).
285+
*
286+
* @param parentBranchId ID of the data branch, this data value belongs to.
287+
* @param metaId ID of the metadata leaf "describing" this data value.
288+
* @param value the actual data value.
289+
* @return the ID of the new data leaf.
290+
*/
212291
public long putValue(long parentBranchId, long metaId, long value) {
213292
return nativePutValueInteger(handle, 0, parentBranchId, metaId, value);
214293
}
215294

295+
/**
296+
* Puts (inserts) a new data value (using a data leaf).
297+
*
298+
* @param parentBranchId ID of the data branch, this data value belongs to.
299+
* @param metaId ID of the metadata leaf "describing" this data value.
300+
* @param value the actual data value.
301+
* @return the ID of the new data leaf.
302+
*/
216303
public long putValue(long parentBranchId, long metaId, double value) {
217304
return nativePutValueFP(handle, 0, parentBranchId, metaId, value);
218305
}
219306

307+
/**
308+
* Puts (persists) a data value (using a data leaf). If a data leaf exists at the given ID, it's overwritten.
309+
*
310+
* @param id Existing ID or zero to insert a new data leaf.
311+
* @param parentBranchId ID of the data branch, this data value belongs to.
312+
* @param metaId ID of the metadata leaf "describing" this data value.
313+
* @param value the actual data value.
314+
* @return the ID of the put data leaf.
315+
*/
220316
public long putValue(long id, long parentBranchId, long metaId, double value) {
221317
return nativePutValueFP(handle, id, parentBranchId, metaId, value);
222318
}
223319

320+
/**
321+
* Puts (persists) a data value (using a data leaf). If a data leaf exists at the given ID, it's overwritten.
322+
*
323+
* @param id Existing ID or zero to insert a new data leaf.
324+
* @param parentBranchId ID of the data branch, this data value belongs to.
325+
* @param metaId ID of the metadata leaf "describing" this data value.
326+
* @param value the actual data value.
327+
* @return the ID of the put data leaf.
328+
*/
224329
public long putValue(long id, long parentBranchId, long metaId, String value) {
225330
return nativePutValueString(handle, id, parentBranchId, metaId, value);
226331
}
227332

333+
/**
334+
* Puts (inserts) a new data value (using a data leaf).
335+
*
336+
* @param parentBranchId ID of the data branch, this data value belongs to.
337+
* @param metaId ID of the metadata leaf "describing" this data value.
338+
* @param value the actual data value.
339+
* @return the ID of the new data leaf.
340+
*/
228341
public long putValue(long parentBranchId, long metaId, String value) {
229342
return nativePutValueString(handle, 0, parentBranchId, metaId, value);
230343
}
231344

345+
/**
346+
* Puts (persists) a data leaf (containing a data value). If a data leaf exists with the same ID, it's overwritten.
347+
*
348+
* @return the ID of the put data leaf.
349+
*/
232350
public long put(Leaf leaf) {
233351
long id = leaf.getId();
234352
long parentId = leaf.getParentBranchId();

‎tests/objectbox-java-test/src/test/java/io/objectbox/tree/TreeTest.java‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,10 @@ public void createTree() {
3333
return prepTree.putBranch(0, metaBranchIds[0]); // Library data branch (data tree root)
3434
});
3535
tree = new Tree(store, rootId);
36-
root = tree.root();
36+
root = tree.getRoot();
3737
this.rootId = root.getId();
3838
assertNotEquals(0, this.rootId);
39+
assertEquals(rootId, tree.getRootId());
3940
assertEquals(3, metaBranchIds.length);
4041
}
4142

@@ -221,7 +222,7 @@ public void concurrentTxs() throws InterruptedException {
221222
} catch (InterruptedException e) {
222223
e.printStackTrace();
223224
}
224-
assertNull(tree.root().branch("Book"));
225+
assertNull(tree.getRoot().branch("Book"));
225226
readThreadOK.set(true);
226227
});
227228
});
@@ -236,7 +237,7 @@ public void concurrentTxs() throws InterruptedException {
236237
} catch (InterruptedException e) {
237238
e.printStackTrace();
238239
}
239-
long id = tree.putBranch(tree.root().getId(), metaBranchIds[1]);
240+
long id = tree.putBranch(tree.getRoot().getId(), metaBranchIds[1]);
240241
bookBranchId.set(id);
241242
});
242243
});
@@ -246,7 +247,7 @@ public void concurrentTxs() throws InterruptedException {
246247
System.out.println("Thread " + Thread.currentThread().getId() + " entered tree TX");
247248
latch.countDown();
248249
latch.await();
249-
return tree.root().branch("Book");
250+
return tree.getRoot().branch("Book");
250251
};
251252
Branch branch = tree.callInReadTx(branchCallable);
252253
assertNull(branch);

0 commit comments

Comments
 (0)