<!-- HTML header for doxygen 1.8.6-->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>

<meta http-equiv="X-UA-Compatible" content="IE=9"/>

<meta name="generator" content="Doxygen 1.8.7"/>

<title>FlatBuffers: Use in Java/C#</title>

<link href="tabs.css" rel="stylesheet" type="text/css"/>

<script type="text/javascript" src="jquery.js"></script>

<script type="text/javascript" src="dynsections.js"></script>

<link href="navtree.css" rel="stylesheet" type="text/css"/>

<script type="text/javascript" src="resize.js"></script>

<script type="text/javascript" src="navtree.js"></script>

<script type="text/javascript">

$(document).ready(initResizable);

$(window).load(resizeHeight);

</script>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<script type="text/javascript" src="search/search.js"></script>

<script type="text/javascript">

$(document).ready(function() { searchBox.OnSelectItem(0); });

</script>

<link href="doxygen.css" rel="stylesheet" type="text/css" />

<link href="https://fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic|Roboto+Mono:400,700" rel="stylesheet">

<link href="style.css" rel="stylesheet" type="text/css"/>

</head>

<body>

<div id="top"><!-- do not remove this div, it is closed by doxygen! -->

<div id="titlearea" style="height: 110px;">

<table cellspacing="0" cellpadding="0">

<tbody>

<tr style="height: 56px;">

<td id="commonprojectlogo">

<img alt="Logo" src="fpl_logo_small.png"/>

</td>

<td style="padding-left: 0.5em;">

<div id="projectname">FlatBuffers

</div>

<div style="font-size:12px;">

An open source project by <a href="https://developers.google.com/games/#Tools">FPL</a>.

</div>

</td>

</tr>

</tbody>

</table>

</div>

<!-- end header part -->

<!-- Generated by Doxygen 1.8.7 -->

<script type="text/javascript">

var searchBox = new SearchBox("searchBox", "search",false,'Search');

</script>

<div id="navrow1" class="tabs">

<ul class="tablist">

<li><a href="index.html"><span>Main&#160;Page</span></a></li>

<li><a href="usergroup0.html"><span>Programmer's&#160;Guide</span></a></li>

<li><a href="flatbuffers_support.html"><span>Platform&#160;/&#160;Language&#160;/&#160;Feature&#160;support</span></a></li>

<li><a href="flatbuffers_benchmarks.html"><span>Benchmarks</span></a></li>

<li><a href="flatbuffers_white_paper.html"><span>FlatBuffers&#160;white&#160;paper</span></a></li>

<li><a href="flatbuffers_internals.html"><span>FlatBuffers&#160;internals</span></a></li>

<li><a href="flatbuffers_grammar.html"><span>Grammar&#160;of&#160;the&#160;schema&#160;language</span></a></li>

<li><a href="usergroup1.html"><span>API&#160;Reference</span></a></li>

<li><a href="contributing.html"><span>Contributing</span></a></li>

<li>

<div id="MSearchBox" class="MSearchBoxInactive">

<span class="left">

<img id="MSearchSelect" src="search/mag_sel.png"

onmouseover="return searchBox.OnSearchSelectShow()"

onmouseout="return searchBox.OnSearchSelectHide()"

alt=""/>

<input type="text" id="MSearchField" value="Search" accesskey="S"

onfocus="searchBox.OnSearchFieldFocus(true)"

onblur="searchBox.OnSearchFieldFocus(false)"

onkeyup="searchBox.OnSearchFieldChange(event)"/>

</span><span class="right">

<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>

</span>

</div>

</li>

</ul>

</div>

</div><!-- top -->

<div id="side-nav" class="ui-resizable side-nav-resizable">

<div id="nav-tree">

<div id="nav-tree-contents">

<div id="nav-sync" class="sync"></div>

</div>

</div>

<div id="splitbar" style="-moz-user-select:none;"

class="ui-resizable-handle">

</div>

</div>

<script type="text/javascript">

$(document).ready(function(){initNavTree('flatbuffers_guide_use_java_c-sharp.html','');});

</script>

<div id="doc-content">

<!-- window showing the filter options -->

<div id="MSearchSelectWindow"

onmouseover="return searchBox.OnSearchSelectShow()"

onmouseout="return searchBox.OnSearchSelectHide()"

onkeydown="return searchBox.OnSearchSelectKey(event)">

<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Properties</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->

<div id="MSearchResultsWindow">

<iframe src="javascript:void(0)" frameborder="0"

name="MSearchResults" id="MSearchResults">

</iframe>

</div>

<div class="header">

<div class="headertitle">

<div class="title">Use in Java/C# </div> </div>

</div><!--header-->

<div class="contents">

<div class="textblock"><h2>Before you get started</h2>

<p>Before diving into the FlatBuffers usage in Java or C#, it should be noted that the <a class="el" href="flatbuffers_guide_tutorial.html">Tutorial</a> 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#.</p>

<p>You should also have read the <a class="el" href="flatbuffers_guide_building.html">Building</a> documentation to build <code>flatc</code> and should be familiar with <a class="el" href="flatbuffers_guide_using_schema_compiler.html">Using the schema compiler</a> and <a class="el" href="flatbuffers_guide_writing_schema.html">Writing a schema</a>.</p>

<h2>FlatBuffers Java and C-sharp code location</h2>

<h4>Java</h4>

<p>The code for the FlatBuffers Java library can be found at <code>flatbuffers/java/com/google/flatbuffers</code>. You can browse the library on the <a href="https://github.com/google/flatbuffers/tree/master/

java/com/google/flatbuffers">FlatBuffers GitHub page</a>.</p>

<h4>C-sharp</h4>

<p>The code for the FlatBuffers C# library can be found at <code>flatbuffers/net/FlatBuffers</code>. You can browse the library on the <a href="https://github.com/google/flatbuffers/tree/master/net/

FlatBuffers">FlatBuffers GitHub page</a>.</p>

<h2>Testing the FlatBuffers Java and C-sharp libraries</h2>

<p>The code to test the libraries can be found at <code>flatbuffers/tests</code>.</p>

<h4>Java</h4>

<p>The test code for Java is located in <a href="https://github.com/google

/flatbuffers/blob/master/tests/JavaTest.java">JavaTest.java</a>.</p>

<p>To run the tests, use either <a href="https://github.com/google/

flatbuffers/blob/master/tests/JavaTest.sh">JavaTest.sh</a> or <a href="https://github.com/

google/flatbuffers/blob/master/tests/JavaTest.bat">JavaTest.bat</a>, depending on your operating system.</p>

<p><em>Note: These scripts require that <a href="https://www.oracle.com/java/index.html">Java</a> is installed.</em></p>

<h4>C-sharp</h4>

<p>The test code for C# is located in the <a href="https://github.com/

google/flatbuffers/tree/master/tests/FlatBuffers.Test">FlatBuffers.Test</a> subfolder. To run the tests, open <code>FlatBuffers.Test.csproj</code> in <a href="https://www.visualstudio.com">Visual Studio</a>, and compile/run the project.</p>

<p>Optionally, you can run this using <a href="http://www.mono-project.com/">Mono</a> instead. Once you have installed <code>Mono</code>, you can run the tests from the command line by running the following commands from inside the <code>FlatBuffers.Test</code> folder:</p>

<div class="fragment"><div class="line">mcs *.cs ../MyGame/Example<span class="comment">/*.cs ../../net/FlatBuffers/*.cs</span></div>

<div class="line"><span class="comment">mono Assert.exe</span></div>

</div><!-- fragment --><h2>Using the FlatBuffers Java (and C#) library</h2>

<p><em>Note: See <a class="el" href="flatbuffers_guide_tutorial.html">Tutorial</a> for a more in-depth example of how to use FlatBuffers in Java or C#.</em></p>

<p>FlatBuffers supports reading and writing binary FlatBuffers in Java and C#.</p>

<p>To use FlatBuffers in your own code, first generate Java classes from your schema with the <code>--java</code> option to <code>flatc</code>. (Or for C# with <code>--csharp</code>). Then you can include both FlatBuffers and the generated code to read or write a FlatBuffer.</p>

<p>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 <code>byte[]</code>. You then turn the <code>byte[]</code> into a <code>ByteBuffer</code>, which you pass to the <code>getRootAsMyRootType</code> function:</p>

<p><em>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 <a href="#differences_in_c-sharp">explained in a section below</a>.</em></p>

<div class="fragment"><div class="line"><span class="keyword">import</span> MyGame.Example.*;</div>

<div class="line"><span class="keyword">import</span> <a class="code" href="classcom_1_1google_1_1flatbuffers_1_1_flat_buffer_builder.html">com.google.flatbuffers.FlatBufferBuilder</a>;</div>

<div class="line"></div>

<div class="line"><span class="comment">// This snippet ignores exceptions for brevity.</span></div>

<div class="line">File file = <span class="keyword">new</span> File(<span class="stringliteral">&quot;monsterdata_test.mon&quot;</span>);</div>

<div class="line">RandomAccessFile f = <span class="keyword">new</span> RandomAccessFile(file, <span class="stringliteral">&quot;r&quot;</span>);</div>

<div class="line">byte[] data = <span class="keyword">new</span> byte[(int)f.length()];</div>

<div class="line">f.readFully(data);</div>

<div class="line">f.close();</div>

<div class="line"></div>

<div class="line">ByteBuffer bb = ByteBuffer.wrap(data);</div>

<div class="line">Monster monster = Monster.getRootAsMonster(bb);</div>

</div><!-- fragment --><p>Now you can access the data from the <code>Monster monster</code>:</p>

<div class="fragment"><div class="line"><span class="keywordtype">short</span> hp = monster.hp();</div>

<div class="line">Vec3 pos = monster.pos();</div>

</div><!-- fragment --><p><a class="anchor" id="differences_in_c-sharp"></a> </p><h4>Differences in C-sharp</h4>

<p>C# code works almost identically to Java, with only a few minor differences. You can see an example of C# code in <code>tests/FlatBuffers.Test/FlatBuffersExampleTests.cs</code> or <code>samples/SampleBinary.cs</code>.</p>

<p>First of all, naming follows standard C# style with <code>PascalCasing</code> identifiers, e.g. <code>GetRootAsMyRootType</code>. Also, values (except vectors and unions) are available as properties instead of parameterless accessor methods as in Java. The performance-enhancing methods to which you can pass an already created object are prefixed with <code>Get</code>, e.g.:</p>

<div class="fragment"><div class="line"><span class="comment">// property</span></div>

<div class="line">var pos = monster.Pos;</div>

<div class="line"></div>

<div class="line"><span class="comment">// method filling a preconstructed object</span></div>

<div class="line">var preconstructedPos = <span class="keyword">new</span> Vec3();</div>

<div class="line">monster.GetPos(preconstructedPos);</div>

</div><!-- fragment --><h2>Storing dictionaries in a FlatBuffer</h2>

<p>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 <code>Dictionary</code> or similar.</p>

<p>To use it:</p><ul>

<li>Designate one of the fields in a table as they "key" field. You do this by setting the <code>key</code> attribute on this field, e.g. <code>name:string (key)</code>. You may only have one key field, and it must be of string or scalar type.</li>

<li>Write out tables of this type as usual, collect their offsets in an array.</li>

<li>Instead of calling standard generated method, e.g.: <code>Monster.createTestarrayoftablesVector</code>, call <code>CreateMySortedVectorOfTables</code> in C# or <code>createSortedVectorOfTables</code> (from the <code>FlatBufferBuilder</code> object) in Java, which will first sort all offsets such that the tables they refer to are sorted by the key field, then serialize it.</li>

<li>Now when you're accessing the FlatBuffer, you can use <code>LookupByKey</code> to access elements of the vector, e.g.: <code>Monster.lookupByKey(tablesVectorOffset, "Frodo", dataBuffer)</code>, which returns an object of the corresponding table type, or <code>null</code> if not found. <code>LookupByKey</code> performs a binary search, so should have a similar speed to <code>Dictionary</code>, though may be faster because of better caching. <code>LookupByKey</code> only works if the vector has been sorted, it will likely not find elements if it hasn't been sorted.</li>

</ul>

<h2>Text parsing</h2>

<p>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 interfaces available to each language. Please see the C++ documentation for more on text parsing.</p>

<p><br />

</p>

</div></div><!-- contents -->

</div><!-- doc-content -->

<!-- Google Analytics -->

<script>

(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){

(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),

m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)

})(window,document,'script','//www.google-analytics.com/analytics.js','ga');

ga('create', 'UA-49880327-7', 'auto');

ga('send', 'pageview');

</script>

</body>

</html>