| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- NewPage --> |
| <html lang="en"> |
| <head> |
| <!-- Generated by javadoc --> |
| <title>org.apache.geode.pdx (Apache Geode 1.15.0)</title> |
| <link rel="stylesheet" type="text/css" href="../../../../stylesheet.css" title="Style"> |
| <script type="text/javascript" src="../../../../script.js"></script> |
| </head> |
| <body> |
| <script type="text/javascript"><!-- |
| try { |
| if (location.href.indexOf('is-external=true') == -1) { |
| parent.document.title="org.apache.geode.pdx (Apache Geode 1.15.0)"; |
| } |
| } |
| catch(err) { |
| } |
| //--> |
| </script> |
| <noscript> |
| <div>JavaScript is disabled on your browser.</div> |
| </noscript> |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <div class="topNav"><a name="navbar.top"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.top.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../../overview-summary.html">Overview</a></li> |
| <li class="navBarCell1Rev">Package</li> |
| <li>Class</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> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li><a href="../../../../org/apache/geode/net/package-summary.html">Prev Package</a></li> |
| <li><a href="../../../../org/apache/geode/ra/package-summary.html">Next Package</a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../../index.html?org/apache/geode/pdx/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.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> |
| <a name="skip.navbar.top"> |
| <!-- --> |
| </a></div> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| <div class="header"> |
| <h1 title="Package" class="title">Package org.apache.geode.pdx</h1> |
| <div class="docSummary"> |
| <div class="block">The <code>org.apache.geode.pdx</code> package provides APIs used |
| for object serialization.</div> |
| </div> |
| <p>See: <a href="#package.description">Description</a></p> |
| </div> |
| <div class="contentContainer"> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Interface Summary table, listing interfaces, and an explanation"> |
| <caption><span>Interface Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Interface</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/PdxInstance.html" title="interface in org.apache.geode.pdx">PdxInstance</a></td> |
| <td class="colLast"> |
| <div class="block">PdxInstance provides run time access to the fields of a PDX without deserializing the PDX.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/PdxInstanceFactory.html" title="interface in org.apache.geode.pdx">PdxInstanceFactory</a></td> |
| <td class="colLast"> |
| <div class="block">PdxInstanceFactory gives you a way to create PdxInstances.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/PdxReader.html" title="interface in org.apache.geode.pdx">PdxReader</a></td> |
| <td class="colLast"> |
| <div class="block">A PdxReader will be passed to <a href="../../../../org/apache/geode/pdx/PdxSerializable.html#fromData-org.apache.geode.pdx.PdxReader-"><code>fromData</code></a> or |
| <a href="../../../../org/apache/geode/pdx/PdxSerializer.html#fromData-java.lang.Class-org.apache.geode.pdx.PdxReader-"><code>PdxSerializer fromData</code></a> by GemFire during |
| deserialization of a PDX.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/PdxSerializable.html" title="interface in org.apache.geode.pdx">PdxSerializable</a></td> |
| <td class="colLast"> |
| <div class="block">When a domain class implements PdxSerializable it marks itself as a PDX.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/PdxSerializer.html" title="interface in org.apache.geode.pdx">PdxSerializer</a></td> |
| <td class="colLast"> |
| <div class="block">The PdxSerializer interface allows domain classes to be serialized and deserialized as PDXs |
| without modification of the domain class.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/PdxUnreadFields.html" title="interface in org.apache.geode.pdx">PdxUnreadFields</a></td> |
| <td class="colLast"> |
| <div class="block">Marker interface for an object that GemFire creates and returns from |
| <a href="../../../../org/apache/geode/pdx/PdxReader.html#readUnreadFields--"><code>readUnreadFields</code></a>.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/PdxWriter.html" title="interface in org.apache.geode.pdx">PdxWriter</a></td> |
| <td class="colLast"> |
| <div class="block">A PdxWriter will be passed to <a href="../../../../org/apache/geode/pdx/PdxSerializable.html#toData-org.apache.geode.pdx.PdxWriter-"><code>toData</code></a> or |
| <a href="../../../../org/apache/geode/pdx/PdxSerializer.html#toData-java.lang.Object-org.apache.geode.pdx.PdxWriter-"><code>PdxSerializer toData</code></a> by GemFire when it is |
| serializing the domain class.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/WritablePdxInstance.html" title="interface in org.apache.geode.pdx">WritablePdxInstance</a></td> |
| <td class="colLast"> |
| <div class="block">WritablePdxInstance is a <a href="../../../../org/apache/geode/pdx/PdxInstance.html" title="interface in org.apache.geode.pdx"><code>PdxInstance</code></a> that also supports field modification using the |
| <a href="../../../../org/apache/geode/pdx/WritablePdxInstance.html#setField-java.lang.String-java.lang.Object-"><code>setField</code></a> method.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Class Summary table, listing classes, and an explanation"> |
| <caption><span>Class Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Class</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/JSONFormatter.html" title="class in org.apache.geode.pdx">JSONFormatter</a></td> |
| <td class="colLast"> |
| <div class="block"> |
| JSONFormatter has a static method <a href="../../../../org/apache/geode/pdx/JSONFormatter.html#fromJSON-java.lang.String-java.lang.String...-"><code>JSONFormatter.fromJSON(String, String...)</code></a> to convert a |
| JSON document into a <a href="../../../../org/apache/geode/pdx/PdxInstance.html" title="interface in org.apache.geode.pdx"><code>PdxInstance</code></a> and a static method |
| <a href="../../../../org/apache/geode/pdx/JSONFormatter.html#toJSON-org.apache.geode.pdx.PdxInstance-"><code>JSONFormatter.toJSON(PdxInstance)</code></a> to convert a <a href="../../../../org/apache/geode/pdx/PdxInstance.html" title="interface in org.apache.geode.pdx"><code>PdxInstance</code></a> into a JSON Document.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/ReflectionBasedAutoSerializer.html" title="class in org.apache.geode.pdx">ReflectionBasedAutoSerializer</a></td> |
| <td class="colLast"> |
| <div class="block">This class uses Java reflection in conjunction with <a href="../../../../org/apache/geode/pdx/PdxSerializer.html" title="interface in org.apache.geode.pdx"><code>PdxSerialzer</code></a> to perform automatic serialization of domain objects.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Enum Summary table, listing enums, and an explanation"> |
| <caption><span>Enum Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Enum</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/FieldType.html" title="enum in org.apache.geode.pdx">FieldType</a></td> |
| <td class="colLast"> |
| <div class="block">Every field of a pdx must have one of these types.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Exception Summary table, listing exceptions, and an explanation"> |
| <caption><span>Exception Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Exception</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/JSONFormatterException.html" title="class in org.apache.geode.pdx">JSONFormatterException</a></td> |
| <td class="colLast"> |
| <div class="block">This exception will be thrown, when {link @JSONFormatter} is unable to parse the JSON document or |
| {link @PdxInstance}.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/NonPortableClassException.html" title="class in org.apache.geode.pdx">NonPortableClassException</a></td> |
| <td class="colLast"> |
| <div class="block">Thrown if "check-portability" is enabled and an attempt is made to pdx serialize a class that is |
| not portable to non-java platforms.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/PdxConfigurationException.html" title="class in org.apache.geode.pdx">PdxConfigurationException</a></td> |
| <td class="colLast"> |
| <div class="block">Thrown when a configuration that is now allowed by PDX is detected.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/PdxFieldAlreadyExistsException.html" title="class in org.apache.geode.pdx">PdxFieldAlreadyExistsException</a></td> |
| <td class="colLast"> |
| <div class="block">Thrown when writing a field if the named field already exists.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/PdxFieldDoesNotExistException.html" title="class in org.apache.geode.pdx">PdxFieldDoesNotExistException</a></td> |
| <td class="colLast"> |
| <div class="block">Thrown when a PDX field does not exist and the current operation requires its existence.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/PdxFieldTypeMismatchException.html" title="class in org.apache.geode.pdx">PdxFieldTypeMismatchException</a></td> |
| <td class="colLast"> |
| <div class="block">Thrown if the type of a PDX field was changed or the wrong type was used.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/PdxInitializationException.html" title="class in org.apache.geode.pdx">PdxInitializationException</a></td> |
| <td class="colLast"> |
| <div class="block">Thrown if the PDX system could not be successfully initialized.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/PdxRegistryMismatchException.html" title="class in org.apache.geode.pdx">PdxRegistryMismatchException</a></td> |
| <td class="colLast"> |
| <div class="block">Thrown when an attempt is made to reuse a PDX Type.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../org/apache/geode/pdx/PdxSerializationException.html" title="class in org.apache.geode.pdx">PdxSerializationException</a></td> |
| <td class="colLast"> |
| <div class="block">Thrown if a problem occurred during serialization or deserialization of a PDX.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| </ul> |
| <a name="package.description"> |
| <!-- --> |
| </a> |
| <h2 title="Package org.apache.geode.pdx Description">Package org.apache.geode.pdx Description</h2> |
| <div class="block">The <code>org.apache.geode.pdx</code> package provides APIs used |
| for object serialization. PDX stands for Portable Data eXchange and has the following |
| advantages over other object serialization APIs: |
| <ul> |
| <li> The serialized form is portable between Java and C#. |
| <li> The data in a PDX serialized object can be accessed without deserializing the object. |
| This allows data to be accessed even if the domain class is unavailable. |
| So GemFire servers are able to do things like queries without needing to deserialize |
| the domain objects. Being able to keep the serialized form in the server cache |
| saves time and memory. |
| This also allows a C# developer to only write a C# domain class without needing |
| to also write a corresponding Java domain class. |
| <li> PDX supports class versioning. Different versions of the same PDX class are allowed |
| in the same distributed system. So you can add a new version of your application |
| without by just starting a new client. No need to shutdown clients using the |
| old version of the PDX data or of restarting your servers. |
| <li> The PDX serialized form is compact because a minimal amount of type information |
| is encoded in the serialized form. This saves memory and time. |
| </ul> |
| <p> |
| To use PDX either implement <a href="../../../../org/apache/geode/pdx/PdxSerializable.html" title="interface in org.apache.geode.pdx"><code>PdxSerializable</code></a> |
| on your domain class or implement a <a href="../../../../org/apache/geode/pdx/PdxSerializer.html" title="interface in org.apache.geode.pdx"><code>PdxSerializer</code></a>. |
| In either case you use a <a href="../../../../org/apache/geode/pdx/PdxWriter.html" title="interface in org.apache.geode.pdx"><code>PdxWriter</code></a> |
| to serialize your data and a |
| <a href="../../../../org/apache/geode/pdx/PdxReader.html" title="interface in org.apache.geode.pdx"><code>PdxReader</code></a> to deserialize. |
| <p> |
| An auto serialization mechanism is also provided as an early access feature. |
| This has the potential to obviate the need for any augmentation of domain |
| classes to allow them to be serialized. See <a href="../../../../org/apache/geode/pdx/ReflectionBasedAutoSerializer.html" title="class in org.apache.geode.pdx"><code>ReflectionBasedAutoSerializer</code></a> |
| for more details. |
| <p> |
| The PDX object model is that a PDX type has a name and an ordered list of PDX fields. |
| A PDX field has a name and a field type. For your domain class to be serialized |
| by PDX you must define this meta information. You do this by calling methods on |
| PdxWriter and PdxReader that define the PDX fields. For example calling |
| writeString("stringField", this.stringField) defines a field whose name is |
| "stringField" and whose field type is "String". The PDX type name is the fully |
| qualified domain class name. PDX field names are case sensitive. They do not need |
| to match your instance variable names but this is a good convention to follow. |
| The order in which you write your fields must be the order in which you read them. |
| |
| <p> |
| As your PDX domain class changes you are free to add and remove fields. But you can |
| not change the field type of a PDX field. For example you can not change from |
| calling writeString to writeDate for the same field name. |
| Once the domain class has changed then some of your fields will not be read during |
| deserialization. For example if you have a PDX class with one field (lets call it |
| version 1) and you then add a second field (lets call it version 2) then when |
| the version 1 code deserializes data from version 2 it will only read field one. |
| So field two will be unread. But when this object is reserialized it will preserve |
| the unread field data and include it in the serialized form (unless you configure |
| ignore-unread-fields to true). You can optimize the amount of memory consumed |
| by unread fields by managing them yourself by calling |
| <a href="../../../../org/apache/geode/pdx/PdxReader.html#readUnreadFields--"><code>PdxReader.readUnreadFields()</code></a> |
| and <a href="../../../../org/apache/geode/pdx/PdxWriter.html#writeUnreadFields-org.apache.geode.pdx.PdxUnreadFields-"><code>PdxWriter.writeUnreadFields(org.apache.geode.pdx.PdxUnreadFields)</code></a>. |
| <p> |
| To read the fields of a PDX without deserializing it see |
| <a href="../../../../org/apache/geode/pdx/PdxInstance.html" title="interface in org.apache.geode.pdx"><code>PdxInstance</code></a>. |
| To modify the fields of a PDX without deserializing it see |
| <a href="../../../../org/apache/geode/pdx/WritablePdxInstance.html" title="interface in org.apache.geode.pdx"><code>WritablePdxInstance</code></a>. |
| |
| <p> |
| <em>PDX Configuration</em> |
| <p> |
| The GemFire Cache has a number of configuration attributes related to PDX. |
| They can be configured using API method on |
| <a href="../../../../org/apache/geode/cache/CacheFactory.html" title="class in org.apache.geode.cache"><code>CacheFactory</code></a> |
| or <a href="../../../../org/apache/geode/cache/client/ClientCacheFactory.html" title="class in org.apache.geode.cache.client"><code>ClientCacheFactory</code></a>. |
| They can also be configured in a cache.xml using the <code>pdx</code> element. |
| The following describes the dtd elements and attribute names but corresponding |
| method names are also available on the cache factories. |
| <ul> |
| <li><code>read-serialized</code> Set it to true if you want PDX deserialization |
| to produce a PdxInstance instead of an instance of the domain class. |
| <li><code>ignore-unread-fields</code> Set it to true if you do not want unread |
| PDX fields to be preserved during deserialization. This can save you memory |
| and is safe to use in a member that only reads data from the cache. |
| <li><code>persistent</code> Set to true if you are using persistent regions |
| or WAN gateways. This causes the PDX type information to be written to disk. |
| <li><code>disk-store-name</code> If using persistence this attribute allows you |
| to configure what disk store the PDX type data will be store in. By default |
| the default disk store is used. |
| <li><code>pdx-serializer</code> Allows you to configure the |
| <a href="../../../../org/apache/geode/pdx/PdxSerializer.html" title="interface in org.apache.geode.pdx"><code>PdxSerializer</code></a> for this GemFire member. |
| <li><code>distributed-system-id</code> When using PDX with WAN gateways each |
| distributed system must set this gemfire property to a unique value in the |
| range 0..255 inclusive. |
| </ul></div> |
| </div> |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <div class="bottomNav"><a name="navbar.bottom"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.bottom.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../../overview-summary.html">Overview</a></li> |
| <li class="navBarCell1Rev">Package</li> |
| <li>Class</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> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li><a href="../../../../org/apache/geode/net/package-summary.html">Prev Package</a></li> |
| <li><a href="../../../../org/apache/geode/ra/package-summary.html">Next Package</a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../../index.html?org/apache/geode/pdx/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.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> |
| <a name="skip.navbar.bottom"> |
| <!-- --> |
| </a></div> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| </body> |
| </html> |
