diff options
author | mugisoba <51015092+mugisoba@users.noreply.github.com> | 2020-01-31 03:18:28 +0900 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-01-30 10:18:28 -0800 |
commit | 7418d85872ac2e04eccc037230fa3a8f1c321b69 (patch) | |
tree | b41bebde88c9f6f4851878777ecc551efca6ef98 /docs/source | |
parent | c580fa284c70409bb3b2af303dc7eb772b607caa (diff) | |
download | flatbuffers-7418d85872ac2e04eccc037230fa3a8f1c321b69.tar.gz |
[C#] support Object API (#5710)
* [C#] support Object API
* fix sign-compare
* fix indent
* add new line before for loop.
* using auto whenever possible
* reduce the amout of blank lines.
* wip: support vectors of union
* done: support unions of vectors
* set C# version to 4.0
* remove null propagation operator
* remove auto property initializer
* remove expression-bodied method
* remove pattern matching
* add Example2 to NetTest.sh
* separate JavaUsage.md and CsharpUsage.md from JavaCsharpUsage.md
* add C# Object based API notes.
* support vs2010.
* remove range based for loop.
* remove System.Linq
* fix indent
* CreateSharedString to CreateString
* check shared attribute
* snake case
Diffstat (limited to 'docs/source')
-rw-r--r-- | docs/source/CsharpUsage.md (renamed from docs/source/JavaCsharpUsage.md) | 126 | ||||
-rw-r--r-- | docs/source/FlatBuffers.md | 4 | ||||
-rw-r--r-- | docs/source/JavaUsage.md | 114 | ||||
-rw-r--r-- | docs/source/Tutorial.md | 4 | ||||
-rw-r--r-- | docs/source/doxygen_layout.xml | 6 |
5 files changed, 177 insertions, 77 deletions
diff --git a/docs/source/JavaCsharpUsage.md b/docs/source/CsharpUsage.md index 102ce371..90a757fb 100644 --- a/docs/source/JavaCsharpUsage.md +++ b/docs/source/CsharpUsage.md @@ -1,54 +1,30 @@ -Use in Java/C# {#flatbuffers_guide_use_java_c-sharp} +Use in C# {#flatbuffers_guide_use_c-sharp} ============== ## Before you get started -Before diving into the FlatBuffers usage in Java or C#, it should be noted that +Before diving into the FlatBuffers usage in C#, it should be noted that the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to -general FlatBuffers usage in all of the supported languages (including both Java -and C#). This page is designed to cover the nuances of FlatBuffers usage, -specific to Java and C#. +general FlatBuffers usage in all of the supported languages (including C#). +This page is designed to cover the nuances of FlatBuffers usage, +specific to C#. You should also have read the [Building](@ref flatbuffers_guide_building) documentation to build `flatc` and should be familiar with [Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and [Writing a schema](@ref flatbuffers_guide_writing_schema). -## FlatBuffers Java and C-sharp code location - -#### Java - -The code for the FlatBuffers Java library can be found at -`flatbuffers/java/com/google/flatbuffers`. You can browse the library on the -[FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/ -java/com/google/flatbuffers). - -#### C-sharp +## FlatBuffers C-sharp code location The code for the FlatBuffers C# library can be found at `flatbuffers/net/FlatBuffers`. You can browse the library on the [FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/net/ FlatBuffers). -## Testing the FlatBuffers Java and C-sharp libraries +## Testing the FlatBuffers C-sharp libraries The code to test the libraries can be found at `flatbuffers/tests`. -#### Java - -The test code for Java is located in [JavaTest.java](https://github.com/google -/flatbuffers/blob/master/tests/JavaTest.java). - -To run the tests, use either [JavaTest.sh](https://github.com/google/ -flatbuffers/blob/master/tests/JavaTest.sh) or [JavaTest.bat](https://github.com/ -google/flatbuffers/blob/master/tests/JavaTest.bat), depending on your operating -system. - -*Note: These scripts require that [Java](https://www.oracle.com/java/index.html) -is installed.* - -#### C-sharp - The test code for C# is located in the [FlatBuffers.Test](https://github.com/ google/flatbuffers/tree/master/tests/FlatBuffers.Test) subfolder. To run the tests, open `FlatBuffers.Test.csproj` in [Visual Studio]( @@ -63,62 +39,44 @@ by running the following commands from inside the `FlatBuffers.Test` folder: mono Assert.exe ~~~ -## Using the FlatBuffers Java (and C#) library +## Using the FlatBuffers C# library *Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth -example of how to use FlatBuffers in Java or C#.* +example of how to use FlatBuffers in C#.* -FlatBuffers supports reading and writing binary FlatBuffers in Java and C#. +FlatBuffers supports reading and writing binary FlatBuffers in C#. -To use FlatBuffers in your own code, first generate Java classes from your -schema with the `--java` option to `flatc`. (Or for C# with `--csharp`). +To use FlatBuffers in your own code, first generate C# classes from your +schema with the `--csharp` option to `flatc`. Then you can include both FlatBuffers and the generated code to read or write a FlatBuffer. -For example, here is how you would read a FlatBuffer binary file in Java: +For example, here is how you would read a FlatBuffer binary file in C#: First, import the library and generated code. Then, you read a FlatBuffer binary file into a `byte[]`. You then turn the `byte[]` into a `ByteBuffer`, which you -pass to the `getRootAsMyRootType` function: - -*Note: The code here is written from the perspective of Java. Code for both -languages is both generated and used in nearly the exact same way, with only -minor differences. These differences are -[explained in a section below](#differences_in_c-sharp).* +pass to the `GetRootAsMyRootType` function: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java} - import MyGame.Example.*; - import com.google.flatbuffers.FlatBufferBuilder; +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cs} + using MyGame.Example; + using FlatBuffers; // This snippet ignores exceptions for brevity. - File file = new File("monsterdata_test.mon"); - RandomAccessFile f = new RandomAccessFile(file, "r"); - byte[] data = new byte[(int)f.length()]; - f.readFully(data); - f.close(); - - ByteBuffer bb = ByteBuffer.wrap(data); - Monster monster = Monster.getRootAsMonster(bb); + byte[] data = File.ReadAllBytes("monsterdata_test.mon"); + + ByteBuffer bb = new ByteBuffer(data); + Monster monster = Monster.GetRootAsMonster(bb); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Now you can access the data from the `Monster monster`: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java} - short hp = monster.hp(); - Vec3 pos = monster.pos(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cs} + short hp = monster.Hp; + Vec3 pos = monster.Pos; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -<a name="differences_in_c-sharp"> -#### Differences in C-sharp -</a> - -C# code works almost identically to Java, with only a few minor differences. -You can see an example of C# code in -`tests/FlatBuffers.Test/FlatBuffersExampleTests.cs` or -`samples/SampleBinary.cs`. - -First of all, naming follows standard C# style with `PascalCasing` identifiers, +C# code naming follows standard C# style with `PascalCasing` identifiers, e.g. `GetRootAsMyRootType`. Also, values (except vectors and unions) are -available as properties instead of parameterless accessor methods as in Java. +available as properties instead of parameterless accessor methods. The performance-enhancing methods to which you can pass an already created object are prefixed with `Get`, e.g.: @@ -147,13 +105,11 @@ To use it: array. - Instead of calling standard generated method, e.g.: `Monster.createTestarrayoftablesVector`, - call `CreateSortedVectorOfMonster` in C# or - `createSortedVectorOfTables` (from the `FlatBufferBuilder` object) in Java, + call `CreateSortedVectorOfMonster` in C# which will first sort all offsets such that the tables they refer to are sorted by the key field, then serialize it. - Now when you're accessing the FlatBuffer, you can use the `ByKey` accessor to access elements of the vector, e.g.: - `monster.testarrayoftablesByKey("Frodo")` in Java or `monster.TestarrayoftablesByKey("Frodo")` in C#, which returns an object of the corresponding table type, or `null` if not found. @@ -165,8 +121,34 @@ To use it: ## Text parsing There currently is no support for parsing text (Schema's and JSON) directly -from Java or C#, though you could use the C++ parser through native call +from C#, though you could use the C++ parser through native call interfaces available to each language. Please see the C++ documentation for more on text parsing. +## Object based API + +FlatBuffers is all about memory efficiency, which is why its base API is written +around using as little as possible of it. This does make the API clumsier +(requiring pre-order construction of all data, and making mutation harder). + +For times when efficiency is less important a more convenient object based API +can be used (through `--gen-object-api`) that is able to unpack & pack a +FlatBuffer into objects and standard System.Collections.Generic containers, allowing for convenient +construction, access and mutation. + +To use: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cs} + // Deserialize from buffer into object. + MonsterT monsterobj = GetMonster(flatbuffer).UnPack(); + + // Update object directly like a C# class instance. + Console.WriteLine(monsterobj.Name); + monsterobj.Name = "Bob"; // Change the name. + + // Serialize into new flatbuffer. + FlatBufferBuilder fbb = new FlatBufferBuilder(1); + fbb.Finish(Monster.Pack(fbb, monsterobj).Value); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + <br> diff --git a/docs/source/FlatBuffers.md b/docs/source/FlatBuffers.md index 45ffbf22..2a2133f7 100644 --- a/docs/source/FlatBuffers.md +++ b/docs/source/FlatBuffers.md @@ -130,7 +130,9 @@ sections provide a more in-depth usage guide. - How to [write a schema](@ref flatbuffers_guide_writing_schema). - How to [use the generated C++ code](@ref flatbuffers_guide_use_cpp) in your own programs. -- How to [use the generated Java/C# code](@ref flatbuffers_guide_use_java_c-sharp) +- How to [use the generated Java code](@ref flatbuffers_guide_use_java) + in your own programs. +- How to [use the generated C# code](@ref flatbuffers_guide_use_c-sharp) in your own programs. - How to [use the generated Kotlin code](@ref flatbuffers_guide_use_kotlin) in your own programs. diff --git a/docs/source/JavaUsage.md b/docs/source/JavaUsage.md new file mode 100644 index 00000000..30ba0613 --- /dev/null +++ b/docs/source/JavaUsage.md @@ -0,0 +1,114 @@ +Use in Java {#flatbuffers_guide_use_java} +============== + +## Before you get started + +Before diving into the FlatBuffers usage in Java, it should be noted that +the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to +general FlatBuffers usage in all of the supported languages (including Java). +This page is designed to cover the nuances of FlatBuffers usage, +specific to Java. + +You should also have read the [Building](@ref flatbuffers_guide_building) +documentation to build `flatc` and should be familiar with +[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and +[Writing a schema](@ref flatbuffers_guide_writing_schema). + +## FlatBuffers Java code location + +The code for the FlatBuffers Java library can be found at +`flatbuffers/java/com/google/flatbuffers`. You can browse the library on the +[FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/ +java/com/google/flatbuffers). + +## Testing the FlatBuffers Java libraries + +The code to test the libraries can be found at `flatbuffers/tests`. + +The test code for Java is located in [JavaTest.java](https://github.com/google +/flatbuffers/blob/master/tests/JavaTest.java). + +To run the tests, use either [JavaTest.sh](https://github.com/google/ +flatbuffers/blob/master/tests/JavaTest.sh) or [JavaTest.bat](https://github.com/ +google/flatbuffers/blob/master/tests/JavaTest.bat), depending on your operating +system. + +*Note: These scripts require that [Java](https://www.oracle.com/java/index.html) +is installed.* + +## Using the FlatBuffers Java library + +*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth +example of how to use FlatBuffers in Java.* + +FlatBuffers supports reading and writing binary FlatBuffers in Java. + +To use FlatBuffers in your own code, first generate Java classes from your +schema with the `--java` option to `flatc`. +Then you can include both FlatBuffers and the generated code to read +or write a FlatBuffer. + +For example, here is how you would read a FlatBuffer binary file in Java: +First, import the library and generated code. Then, you read a FlatBuffer binary +file into a `byte[]`. You then turn the `byte[]` into a `ByteBuffer`, which you +pass to the `getRootAsMyRootType` function: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java} + import MyGame.Example.*; + import com.google.flatbuffers.FlatBufferBuilder; + + // This snippet ignores exceptions for brevity. + File file = new File("monsterdata_test.mon"); + RandomAccessFile f = new RandomAccessFile(file, "r"); + byte[] data = new byte[(int)f.length()]; + f.readFully(data); + f.close(); + + ByteBuffer bb = ByteBuffer.wrap(data); + Monster monster = Monster.getRootAsMonster(bb); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Now you can access the data from the `Monster monster`: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java} + short hp = monster.hp(); + Vec3 pos = monster.pos(); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +## Storing dictionaries in a FlatBuffer + +FlatBuffers doesn't support dictionaries natively, but there is support to +emulate their behavior with vectors and binary search, which means you +can have fast lookups directly from a FlatBuffer without having to unpack +your data into a `Dictionary` or similar. + +To use it: +- Designate one of the fields in a table as the "key" field. You do this + by setting the `key` attribute on this field, e.g. + `name:string (key)`. + You may only have one key field, and it must be of string or scalar type. +- Write out tables of this type as usual, collect their offsets in an + array. +- Instead of calling standard generated method, + e.g.: `Monster.createTestarrayoftablesVector`, + call `createSortedVectorOfTables` (from the `FlatBufferBuilder` object). + which will first sort all offsets such that the tables they refer to + are sorted by the key field, then serialize it. +- Now when you're accessing the FlatBuffer, you can use + the `ByKey` accessor to access elements of the vector, e.g.: + `monster.testarrayoftablesByKey("Frodo")`. + which returns an object of the corresponding table type, + or `null` if not found. + `ByKey` performs a binary search, so should have a similar + speed to `Dictionary`, though may be faster because of better caching. + `ByKey` only works if the vector has been sorted, it will + likely not find elements if it hasn't been sorted. + +## Text parsing + +There currently is no support for parsing text (Schema's and JSON) directly +from Java, though you could use the C++ parser through native call +interfaces available to each language. Please see the +C++ documentation for more on text parsing. + +<br> diff --git a/docs/source/Tutorial.md b/docs/source/Tutorial.md index f871c4c0..c0f3b9e7 100644 --- a/docs/source/Tutorial.md +++ b/docs/source/Tutorial.md @@ -3374,13 +3374,13 @@ For your chosen language, see: [Use in C++](@ref flatbuffers_guide_use_cpp) </div> <div class="language-java"> -[Use in Java/C#](@ref flatbuffers_guide_use_java_c-sharp) +[Use in Java](@ref flatbuffers_guide_use_java) </div> <div class="language-kotlin"> [Use in Kotlin](@ref flatbuffers_guide_use_kotlin) </div> <div class="language-csharp"> -[Use in Java/C#](@ref flatbuffers_guide_use_java_c-sharp) +[Use in C#](@ref flatbuffers_guide_use_c-sharp) </div> <div class="language-go"> [Use in Go](@ref flatbuffers_guide_use_go) diff --git a/docs/source/doxygen_layout.xml b/docs/source/doxygen_layout.xml index 8253903d..72888f95 100644 --- a/docs/source/doxygen_layout.xml +++ b/docs/source/doxygen_layout.xml @@ -29,8 +29,10 @@ title="Use in C"/> <tab type="user" url="@ref flatbuffers_guide_use_go" title="Use in Go"/> - <tab type="user" url="@ref flatbuffers_guide_use_java_c-sharp" - title="Use in Java/C#"/> + <tab type="user" url="@ref flatbuffers_guide_use_java" + title="Use in Java"/> + <tab type="user" url="@ref flatbuffers_guide_use_c-sharp" + title="Use in C#"/> <tab type="user" url="@ref flatbuffers_guide_use_javascript" title="Use in JavaScript"/> <tab type="user" url="@ref flatbuffers_guide_use_typescript" |