1Use in Java {#flatbuffers_guide_use_java} 2============== 3 4## Before you get started 5 6Before diving into the FlatBuffers usage in Java, it should be noted that 7the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to 8general FlatBuffers usage in all of the supported languages (including Java). 9This page is designed to cover the nuances of FlatBuffers usage, 10specific to Java. 11 12You should also have read the [Building](@ref flatbuffers_guide_building) 13documentation to build `flatc` and should be familiar with 14[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and 15[Writing a schema](@ref flatbuffers_guide_writing_schema). 16 17## FlatBuffers Java code location 18 19The code for the FlatBuffers Java library can be found at 20`flatbuffers/java/com/google/flatbuffers`. You can browse the library on the 21[FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/ 22java/com/google/flatbuffers). 23 24## Testing the FlatBuffers Java libraries 25 26The code to test the libraries can be found at `flatbuffers/tests`. 27 28The test code for Java is located in [JavaTest.java](https://github.com/google 29/flatbuffers/blob/master/tests/JavaTest.java). 30 31To run the tests, use either [JavaTest.sh](https://github.com/google/ 32flatbuffers/blob/master/tests/JavaTest.sh) or [JavaTest.bat](https://github.com/ 33google/flatbuffers/blob/master/tests/JavaTest.bat), depending on your operating 34system. 35 36*Note: These scripts require that [Java](https://www.oracle.com/java/index.html) 37is installed.* 38 39## Using the FlatBuffers Java library 40 41*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth 42example of how to use FlatBuffers in Java.* 43 44FlatBuffers supports reading and writing binary FlatBuffers in Java. 45 46To use FlatBuffers in your own code, first generate Java classes from your 47schema with the `--java` option to `flatc`. 48Then you can include both FlatBuffers and the generated code to read 49or write a FlatBuffer. 50 51For example, here is how you would read a FlatBuffer binary file in Java: 52First, import the library and generated code. Then, you read a FlatBuffer binary 53file into a `byte[]`. You then turn the `byte[]` into a `ByteBuffer`, which you 54pass to the `getRootAsMyRootType` function: 55 56~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java} 57 import MyGame.Example.*; 58 import com.google.flatbuffers.FlatBufferBuilder; 59 60 // This snippet ignores exceptions for brevity. 61 File file = new File("monsterdata_test.mon"); 62 RandomAccessFile f = new RandomAccessFile(file, "r"); 63 byte[] data = new byte[(int)f.length()]; 64 f.readFully(data); 65 f.close(); 66 67 ByteBuffer bb = ByteBuffer.wrap(data); 68 Monster monster = Monster.getRootAsMonster(bb); 69~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 70 71Now you can access the data from the `Monster monster`: 72 73~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java} 74 short hp = monster.hp(); 75 Vec3 pos = monster.pos(); 76~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 77 78## Storing dictionaries in a FlatBuffer 79 80FlatBuffers doesn't support dictionaries natively, but there is support to 81emulate their behavior with vectors and binary search, which means you 82can have fast lookups directly from a FlatBuffer without having to unpack 83your data into a `Dictionary` or similar. 84 85To use it: 86- Designate one of the fields in a table as the "key" field. You do this 87 by setting the `key` attribute on this field, e.g. 88 `name:string (key)`. 89 You may only have one key field, and it must be of string or scalar type. 90- Write out tables of this type as usual, collect their offsets in an 91 array. 92- Instead of calling standard generated method, 93 e.g.: `Monster.createTestarrayoftablesVector`, 94 call `createSortedVectorOfTables` (from the `FlatBufferBuilder` object). 95 which will first sort all offsets such that the tables they refer to 96 are sorted by the key field, then serialize it. 97- Now when you're accessing the FlatBuffer, you can use 98 the `ByKey` accessor to access elements of the vector, e.g.: 99 `monster.testarrayoftablesByKey("Frodo")`. 100 which returns an object of the corresponding table type, 101 or `null` if not found. 102 `ByKey` performs a binary search, so should have a similar 103 speed to `Dictionary`, though may be faster because of better caching. 104 `ByKey` only works if the vector has been sorted, it will 105 likely not find elements if it hasn't been sorted. 106 107## Text parsing 108 109There currently is no support for parsing text (Schema's and JSON) directly 110from Java, though you could use the C++ parser through native call 111interfaces available to each language. Please see the 112C++ documentation for more on text parsing. 113 114<br> 115