1 Use in Java/C# {#flatbuffers_guide_use_java_c-sharp} 2 ============== 3 4 ## Before you get started 5 6 Before diving into the FlatBuffers usage in Java or C#, it should be noted that 7 the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to 8 general FlatBuffers usage in all of the supported languages (including both Java 9 and C#). This page is designed to cover the nuances of FlatBuffers usage, 10 specific to Java and C#. 11 12 You should also have read the [Building](@ref flatbuffers_guide_building) 13 documentation 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 and C-sharp code location 18 19 #### Java 20 21 The code for the FlatBuffers Java library can be found at 22 `flatbuffers/java/com/google/flatbuffers`. You can browse the library on the 23 [FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/ 24 java/com/google/flatbuffers). 25 26 #### C-sharp 27 28 The code for the FlatBuffers C# library can be found at 29 `flatbuffers/net/FlatBuffers`. You can browse the library on the 30 [FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/net/ 31 FlatBuffers). 32 33 ## Testing the FlatBuffers Java and C-sharp libraries 34 35 The code to test the libraries can be found at `flatbuffers/tests`. 36 37 #### Java 38 39 The test code for Java is located in [JavaTest.java](https://github.com/google 40 /flatbuffers/blob/master/tests/JavaTest.java). 41 42 To run the tests, use either [JavaTest.sh](https://github.com/google/ 43 flatbuffers/blob/master/tests/JavaTest.sh) or [JavaTest.bat](https://github.com/ 44 google/flatbuffers/blob/master/tests/JavaTest.bat), depending on your operating 45 system. 46 47 *Note: These scripts require that [Java](https://www.oracle.com/java/index.html) 48 is installed.* 49 50 #### C-sharp 51 52 The test code for C# is located in the [FlatBuffers.Test](https://github.com/ 53 google/flatbuffers/tree/master/tests/FlatBuffers.Test) subfolder. To run the 54 tests, open `FlatBuffers.Test.csproj` in [Visual Studio]( 55 https://www.visualstudio.com), and compile/run the project. 56 57 Optionally, you can run this using [Mono](http://www.mono-project.com/) instead. 58 Once you have installed `Mono`, you can run the tests from the command line 59 by running the following commands from inside the `FlatBuffers.Test` folder: 60 61 ~~~{.sh} 62 mcs *.cs ../MyGame/Example/*.cs ../../net/FlatBuffers/*.cs 63 mono Assert.exe 64 ~~~ 65 66 ## Using the FlatBuffers Java (and C#) library 67 68 *Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth 69 example of how to use FlatBuffers in Java or C#.* 70 71 FlatBuffers supports reading and writing binary FlatBuffers in Java and C#. 72 73 To use FlatBuffers in your own code, first generate Java classes from your 74 schema with the `--java` option to `flatc`. (Or for C# with `--csharp`). 75 Then you can include both FlatBuffers and the generated code to read 76 or write a FlatBuffer. 77 78 For example, here is how you would read a FlatBuffer binary file in Java: 79 First, import the library and generated code. Then, you read a FlatBuffer binary 80 file into a `byte[]`. You then turn the `byte[]` into a `ByteBuffer`, which you 81 pass to the `getRootAsMyRootType` function: 82 83 *Note: The code here is written from the perspective of Java. Code for both 84 languages is both generated and used in nearly the exact same way, with only 85 minor differences. These differences are 86 [explained in a section below](#differences_in_c-sharp).* 87 88 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java} 89 import MyGame.Example.*; 90 import com.google.flatbuffers.FlatBufferBuilder; 91 92 // This snippet ignores exceptions for brevity. 93 File file = new File("monsterdata_test.mon"); 94 RandomAccessFile f = new RandomAccessFile(file, "r"); 95 byte[] data = new byte[(int)f.length()]; 96 f.readFully(data); 97 f.close(); 98 99 ByteBuffer bb = ByteBuffer.wrap(data); 100 Monster monster = Monster.getRootAsMonster(bb); 101 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 102 103 Now you can access the data from the `Monster monster`: 104 105 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java} 106 short hp = monster.hp(); 107 Vec3 pos = monster.pos(); 108 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 109 110 <a name="differences_in_c-sharp"> 111 #### Differences in C-sharp 112 </a> 113 114 C# code works almost identically to Java, with only a few minor differences. 115 You can see an example of C# code in 116 `tests/FlatBuffers.Test/FlatBuffersExampleTests.cs` or 117 `samples/SampleBinary.cs`. 118 119 First of all, naming follows standard C# style with `PascalCasing` identifiers, 120 e.g. `GetRootAsMyRootType`. Also, values (except vectors and unions) are 121 available as properties instead of parameterless accessor methods as in Java. 122 The performance-enhancing methods to which you can pass an already created 123 object are prefixed with `Get`, e.g.: 124 125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cs} 126 // property 127 var pos = monster.Pos; 128 129 // method filling a preconstructed object 130 var preconstructedPos = new Vec3(); 131 monster.GetPos(preconstructedPos); 132 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 133 134 ## Storing dictionaries in a FlatBuffer 135 136 FlatBuffers doesn't support dictionaries natively, but there is support to 137 emulate their behavior with vectors and binary search, which means you 138 can have fast lookups directly from a FlatBuffer without having to unpack 139 your data into a `Dictionary` or similar. 140 141 To use it: 142 - Designate one of the fields in a table as the "key" field. You do this 143 by setting the `key` attribute on this field, e.g. 144 `name:string (key)`. 145 You may only have one key field, and it must be of string or scalar type. 146 - Write out tables of this type as usual, collect their offsets in an 147 array. 148 - Instead of calling standard generated method, 149 e.g.: `Monster.createTestarrayoftablesVector`, 150 call `CreateSortedVectorOfMonster` in C# or 151 `createSortedVectorOfTables` (from the `FlatBufferBuilder` object) in Java, 152 which will first sort all offsets such that the tables they refer to 153 are sorted by the key field, then serialize it. 154 - Now when you're accessing the FlatBuffer, you can use 155 the `ByKey` accessor to access elements of the vector, e.g.: 156 `monster.testarrayoftablesByKey("Frodo")` in Java or 157 `monster.TestarrayoftablesByKey("Frodo")` in C#, 158 which returns an object of the corresponding table type, 159 or `null` if not found. 160 `ByKey` performs a binary search, so should have a similar 161 speed to `Dictionary`, though may be faster because of better caching. 162 `ByKey` only works if the vector has been sorted, it will 163 likely not find elements if it hasn't been sorted. 164 165 ## Text parsing 166 167 There currently is no support for parsing text (Schema's and JSON) directly 168 from Java or C#, though you could use the C++ parser through native call 169 interfaces available to each language. Please see the 170 C++ documentation for more on text parsing. 171 172 <br> 173
