blob: 0c6217ea2452cacd06825f839c78fe504e2ac22f [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<link rel="canonical" href="https://ignite.apache.org/releases/2.0.0/javadoc/org/apache/ignite/binary/BinaryObject.html" />
<META NAME="ROBOTS" CONTENT="NOINDEX">
<!-- Generated by javadoc (version 1.7.0_80) on Sun Apr 30 12:27:11 MSK 2017 -->
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>BinaryObject (Ignite 2.0.0)</title>
<meta name="date" content="2017-04-30">
<link rel="stylesheet" type="text/css" href="../../../../javadoc.css" title="Style">
<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','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-61232409-1', 'auto');
ga('send', 'pageview');
</script></head>
<body>
<script type="text/javascript"><!--
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="BinaryObject (Ignite 2.0.0)";
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar_top">
<!-- -->
</a><a href="#skip-navbar_top" title="Skip navigation links"></a><a name="navbar_top_firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/BinaryObject.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage"><em>Ignite - In-Memory Data Fabric</em></div>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../org/apache/ignite/binary/BinaryNameMapper.html" title="interface in org.apache.ignite.binary"><span class="strong">Prev Class</span></a></li>
<li><a href="../../../../org/apache/ignite/binary/BinaryObjectBuilder.html" title="interface in org.apache.ignite.binary"><span class="strong">Next Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../index.html?org/apache/ignite/binary/BinaryObject.html" target="_top">Frames</a></li>
<li><a href="BinaryObject.html" target="_top">No Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../allclasses-noframe.html">All Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method_summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method_detail">Method</a></li>
</ul>
</div>
<a name="skip-navbar_top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">org.apache.ignite.binary</div>
<h2 title="Interface BinaryObject" class="title">Interface BinaryObject</h2>
</div>
<div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<dl>
<dt>All Superinterfaces:</dt>
<dd><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Cloneable.html?is-external=true" title="class or interface in java.lang">Cloneable</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/io/Serializable.html?is-external=true" title="class or interface in java.io">Serializable</a></dd>
</dl>
<hr>
<br>
<pre>public interface <span class="strong">BinaryObject</span>
extends <a href="http://docs.oracle.com/javase/7/docs/api/java/io/Serializable.html?is-external=true" title="class or interface in java.io">Serializable</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Cloneable.html?is-external=true" title="class or interface in java.lang">Cloneable</a></pre>
<div class="block">Wrapper for binary object in binary format. Once an object is defined as binary,
Ignite will always store it in memory in the binary format.
User can choose to work either with the binary format or with the deserialized form
(assuming that class definitions are present in the classpath).
<p>
<b>NOTE:</b> user does not need to (and should not) implement this interface directly.
<p>
To work with the binary format directly, user should create a cache projection
over <code>BinaryObject</code> class and then retrieve individual fields as needed:
<pre name=code class=java>
IgniteCache&lt;BinaryObject, BinaryObject&gt; prj = cache.withKeepBinary();
// Convert instance of MyKey to binary format.
// We could also use BinaryObjectBuilder to create the key in binary format directly.
BinaryObject key = ignite.binary().toBinary(new MyKey());
BinaryObject val = prj.get(key);
String field = val.field("myFieldName");
</pre>
Alternatively, if we have class definitions in the classpath, we may choose to work with deserialized
typed objects at all times. In this case we do incur the deserialization cost.
<pre name=code class=java>
IgniteCache&lt;MyKey.class, MyValue.class&gt; cache = grid.cache(null);
MyValue val = cache.get(new MyKey());
// Normal java getter.
String fieldVal = val.getMyFieldName();
</pre>
<h1 class="header">Working With Maps and Collections</h1>
All maps and collections in binary objects are serialized automatically. When working
with different platforms, e.g. C++ or .NET, Ignite will automatically pick the most
adequate collection or map in either language. For example, <a href="http://docs.oracle.com/javase/7/docs/api/java/util/ArrayList.html?is-external=true" title="class or interface in java.util"><code>ArrayList</code></a> in Java will become
<code>List</code> in C#, <a href="http://docs.oracle.com/javase/7/docs/api/java/util/LinkedList.html?is-external=true" title="class or interface in java.util"><code>LinkedList</code></a> in Java is <a href="http://docs.oracle.com/javase/7/docs/api/java/util/LinkedList.html?is-external=true" title="class or interface in java.util"><code>LinkedList</code></a> in C#, <a href="http://docs.oracle.com/javase/7/docs/api/java/util/HashMap.html?is-external=true" title="class or interface in java.util"><code>HashMap</code></a>
in Java is <code>Dictionary</code> in C#, and <a href="http://docs.oracle.com/javase/7/docs/api/java/util/TreeMap.html?is-external=true" title="class or interface in java.util"><code>TreeMap</code></a> in Java becomes <code>SortedDictionary</code>
in C#, etc.
<h1 class="header">Dynamic Structure Changes</h1>
Since objects are always cached in the binary format, server does not need to
be aware of the class definitions. Moreover, if class definitions are not present or not
used on the server, then clients can continuously change the structure of the binary
objects without having to restart the cluster. For example, if one client stores a
certain class with fields A and B, and another client stores the same class with
fields B and C, then the server-side binary object will have the fields A, B, and C.
As the structure of a binary object changes, the new fields become available for SQL queries
automatically.
<h1 class="header">Building Binary Objects</h1>
Ignite comes with <a href="../../../../org/apache/ignite/binary/BinaryObjectBuilder.html" title="interface in org.apache.ignite.binary"><code>BinaryObjectBuilder</code></a> which allows to build binary objects dynamically:
<pre name=code class=java>
BinaryObjectBuilder builder = Ignition.ignite().binary().builder("org.project.MyObject");
builder.setField("fieldA", "A");
builder.setField("fieldB", "B");
BinaryObject binaryObj = builder.build();
</pre>
For the cases when class definition is present
in the class path, it is also possible to populate a standard POJO and then
convert it to binary format, like so:
<pre name=code class=java>
MyObject obj = new MyObject();
obj.setFieldA("A");
obj.setFieldB(123);
BinaryObject binaryObj = Ignition.ignite().binary().toBinary(obj);
</pre>
<h1 class="header">Binary Type Metadata</h1>
Even though Ignite binary protocol only works with hash codes for type and field names
to achieve better performance, Ignite provides metadata for all binary types which
can be queried ar runtime via any of the <a href="../../../../org/apache/ignite/IgniteBinary.html#type(java.lang.Class)"><code>IgniteBinary.type(Class)</code></a>
methods. Having metadata also allows for proper formatting of <code>BinaryObject.toString()</code> method,
even when binary objects are kept in binary format only, which may be necessary for audit reasons.</div>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- ========== METHOD SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="method_summary">
<!-- -->
</a>
<h3>Method Summary</h3>
<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">
<caption><span>Methods</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Method and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code><a href="../../../../org/apache/ignite/binary/BinaryObject.html" title="interface in org.apache.ignite.binary">BinaryObject</a></code></td>
<td class="colLast"><code><strong><a href="../../../../org/apache/ignite/binary/BinaryObject.html#clone()">clone</a></strong>()</code>
<div class="block">Copies this binary object.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>&lt;T&gt;&nbsp;T</code></td>
<td class="colLast"><code><strong><a href="../../../../org/apache/ignite/binary/BinaryObject.html#deserialize()">deserialize</a></strong>()</code>
<div class="block">Gets fully deserialized instance of binary object.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>int</code></td>
<td class="colLast"><code><strong><a href="../../../../org/apache/ignite/binary/BinaryObject.html#enumOrdinal()">enumOrdinal</a></strong>()</code>
<div class="block">Get ordinal for this enum object.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>&lt;F&gt;&nbsp;F</code></td>
<td class="colLast"><code><strong><a href="../../../../org/apache/ignite/binary/BinaryObject.html#field(java.lang.String)">field</a></strong>(<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&nbsp;fieldName)</code>
<div class="block">Gets field value.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>boolean</code></td>
<td class="colLast"><code><strong><a href="../../../../org/apache/ignite/binary/BinaryObject.html#hasField(java.lang.String)">hasField</a></strong>(<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&nbsp;fieldName)</code>
<div class="block">Checks whether field exists in the object.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code><a href="../../../../org/apache/ignite/binary/BinaryObjectBuilder.html" title="interface in org.apache.ignite.binary">BinaryObjectBuilder</a></code></td>
<td class="colLast"><code><strong><a href="../../../../org/apache/ignite/binary/BinaryObject.html#toBuilder()">toBuilder</a></strong>()</code>
<div class="block">Creates a new <a href="../../../../org/apache/ignite/binary/BinaryObjectBuilder.html" title="interface in org.apache.ignite.binary"><code>BinaryObjectBuilder</code></a> based on this binary object.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code><a href="../../../../org/apache/ignite/binary/BinaryType.html" title="interface in org.apache.ignite.binary">BinaryType</a></code></td>
<td class="colLast"><code><strong><a href="../../../../org/apache/ignite/binary/BinaryObject.html#type()">type</a></strong>()</code>
<div class="block">Gets type information for this binary object.</div>
</td>
</tr>
</table>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ METHOD DETAIL ========== -->
<ul class="blockList">
<li class="blockList"><a name="method_detail">
<!-- -->
</a>
<h3>Method Detail</h3>
<a name="type()">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>type</h4>
<pre><a href="../../../../org/apache/ignite/binary/BinaryType.html" title="interface in org.apache.ignite.binary">BinaryType</a>&nbsp;type()
throws <a href="../../../../org/apache/ignite/binary/BinaryObjectException.html" title="class in org.apache.ignite.binary">BinaryObjectException</a></pre>
<div class="block">Gets type information for this binary object.</div>
<dl><dt><span class="strong">Returns:</span></dt><dd>Binary object type information.</dd>
<dt><span class="strong">Throws:</span></dt>
<dd><code><a href="../../../../org/apache/ignite/binary/BinaryObjectException.html" title="class in org.apache.ignite.binary">BinaryObjectException</a></code> - In case of error.</dd></dl>
</li>
</ul>
<a name="field(java.lang.String)">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>field</h4>
<pre>&lt;F&gt;&nbsp;F&nbsp;field(<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&nbsp;fieldName)
throws <a href="../../../../org/apache/ignite/binary/BinaryObjectException.html" title="class in org.apache.ignite.binary">BinaryObjectException</a></pre>
<div class="block">Gets field value.</div>
<dl><dt><span class="strong">Parameters:</span></dt><dd><code>fieldName</code> - Field name.</dd>
<dt><span class="strong">Returns:</span></dt><dd>Field value.</dd>
<dt><span class="strong">Throws:</span></dt>
<dd><code><a href="../../../../org/apache/ignite/binary/BinaryObjectException.html" title="class in org.apache.ignite.binary">BinaryObjectException</a></code> - In case of any other error.</dd></dl>
</li>
</ul>
<a name="hasField(java.lang.String)">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>hasField</h4>
<pre>boolean&nbsp;hasField(<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&nbsp;fieldName)</pre>
<div class="block">Checks whether field exists in the object.</div>
<dl><dt><span class="strong">Parameters:</span></dt><dd><code>fieldName</code> - Field name.</dd>
<dt><span class="strong">Returns:</span></dt><dd><code>True</code> if field exists.</dd></dl>
</li>
</ul>
<a name="deserialize()">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>deserialize</h4>
<pre>&lt;T&gt;&nbsp;T&nbsp;deserialize()
throws <a href="../../../../org/apache/ignite/binary/BinaryObjectException.html" title="class in org.apache.ignite.binary">BinaryObjectException</a></pre>
<div class="block">Gets fully deserialized instance of binary object.</div>
<dl><dt><span class="strong">Returns:</span></dt><dd>Fully deserialized instance of binary object.</dd>
<dt><span class="strong">Throws:</span></dt>
<dd><code><a href="../../../../org/apache/ignite/binary/BinaryInvalidTypeException.html" title="class in org.apache.ignite.binary">BinaryInvalidTypeException</a></code> - If class doesn't exist.</dd>
<dd><code><a href="../../../../org/apache/ignite/binary/BinaryObjectException.html" title="class in org.apache.ignite.binary">BinaryObjectException</a></code> - In case of any other error.</dd></dl>
</li>
</ul>
<a name="clone()">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>clone</h4>
<pre><a href="../../../../org/apache/ignite/binary/BinaryObject.html" title="interface in org.apache.ignite.binary">BinaryObject</a>&nbsp;clone()
throws <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/CloneNotSupportedException.html?is-external=true" title="class or interface in java.lang">CloneNotSupportedException</a></pre>
<div class="block">Copies this binary object.</div>
<dl><dt><span class="strong">Returns:</span></dt><dd>Copy of this binary object.</dd>
<dt><span class="strong">Throws:</span></dt>
<dd><code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/CloneNotSupportedException.html?is-external=true" title="class or interface in java.lang">CloneNotSupportedException</a></code></dd></dl>
</li>
</ul>
<a name="toBuilder()">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>toBuilder</h4>
<pre><a href="../../../../org/apache/ignite/binary/BinaryObjectBuilder.html" title="interface in org.apache.ignite.binary">BinaryObjectBuilder</a>&nbsp;toBuilder()
throws <a href="../../../../org/apache/ignite/binary/BinaryObjectException.html" title="class in org.apache.ignite.binary">BinaryObjectException</a></pre>
<div class="block">Creates a new <a href="../../../../org/apache/ignite/binary/BinaryObjectBuilder.html" title="interface in org.apache.ignite.binary"><code>BinaryObjectBuilder</code></a> based on this binary object. The following code
<pre name=code class=java>
BinaryObjectBuilder builder = binaryObject.toBuilder();
</pre>
is equivalent to
<pre name=code class=java>
BinaryObjectBuilder builder = ignite.binary().builder(binaryObject);
</pre></div>
<dl><dt><span class="strong">Returns:</span></dt><dd>Binary object builder.</dd>
<dt><span class="strong">Throws:</span></dt>
<dd><code><a href="../../../../org/apache/ignite/binary/BinaryObjectException.html" title="class in org.apache.ignite.binary">BinaryObjectException</a></code> - If builder cannot be created.</dd></dl>
</li>
</ul>
<a name="enumOrdinal()">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>enumOrdinal</h4>
<pre>int&nbsp;enumOrdinal()
throws <a href="../../../../org/apache/ignite/binary/BinaryObjectException.html" title="class in org.apache.ignite.binary">BinaryObjectException</a></pre>
<div class="block">Get ordinal for this enum object. Use <a href="../../../../org/apache/ignite/binary/BinaryType.html#isEnum()"><code>BinaryType.isEnum()</code></a> to check if object is of enum type.</div>
<dl><dt><span class="strong">Returns:</span></dt><dd>Ordinal.</dd>
<dt><span class="strong">Throws:</span></dt>
<dd><code><a href="../../../../org/apache/ignite/binary/BinaryObjectException.html" title="class in org.apache.ignite.binary">BinaryObjectException</a></code> - If object is not enum.</dd></dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar_bottom">
<!-- -->
</a><a href="#skip-navbar_bottom" title="Skip navigation links"></a><a name="navbar_bottom_firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/BinaryObject.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage"><em>Ignite - In-Memory Data Fabric</em></div>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../org/apache/ignite/binary/BinaryNameMapper.html" title="interface in org.apache.ignite.binary"><span class="strong">Prev Class</span></a></li>
<li><a href="../../../../org/apache/ignite/binary/BinaryObjectBuilder.html" title="interface in org.apache.ignite.binary"><span class="strong">Next Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../index.html?org/apache/ignite/binary/BinaryObject.html" target="_top">Frames</a></li>
<li><a href="BinaryObject.html" target="_top">No Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../allclasses-noframe.html">All Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method_summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method_detail">Method</a></li>
</ul>
</div>
<a name="skip-navbar_bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<p class="legalCopy"><small><table width="100%" border="0" cellspacing=0 cellpadding=0 style="padding: 5px"> <tr> <td> <table style="padding-left: 0; margin: 0"> <tbody style="padding: 0; margin: 0"> <tr style="padding: 0; margin: 0"> <td> <a target=_blank href="https://ignite.apache.org"><nobr>2017 Copyright &#169; Apache Software Foundation</nobr></a> </td> </tr> </tbody> </table> </td> <td width="100%" align="right" valign="center"> <a href="https://twitter.com/ApacheIgnite" class="twitter-follow-button" data-show-count="false" data-size="large">Follow @ApacheIgnite</a> </td> </tr> <tr> <td colspan="2" valign="top" align="left"> <table style="padding-left: 0; margin: 0"> <tbody style="padding: 0; margin: 0"> <tr style="padding: 0; margin: 0"> <td> <b>Ignite Fabric</b> </td> <td>:&nbsp;&nbsp; ver. <strong>2.0.0</strong> </td> </tr> <tr style="padding: 0; margin: 0"> <td> <b>Release Date</b> </td> <td>:&nbsp;&nbsp; April 30 2017 </td> </tr> </tbody> </table> </td> </tr> </table></small></p>
</body>
</html>