...

• Xbuf2 stores field data off-heap. This can result in more complexities in the following areas
  • Troubleshooting issues
  • Monitoring memory utilization
  • Performing capacity planning particularly related to memory utilization.
• Xbuf2 generated classes are larger.

Known Limitations:

• Not currently supported for State Replication applications
• Does not support the UUID and Currency field types (including their array variant)

Incompatibilities with Xbuf:

• With Xbuf, setting a date field using a timestamp of -1 clears the field. This is not the case with Xbuf2
• Xbuf2 does not implement the getXXXField() accessor methods
• With Xbuf, setting a Date[], String[] or Enum[] containing a null element results in an NPE being thrown. With Xbuf2, the null elements are ignored. 

API Differences

For the most part code generated for the different encoding types behaves the same, but there are some key differences that stem from both the underlying serialization mechanisms and features supported. 

...

1. For Json encoding unrecognized enum array values are treated as null, and for non array fields an unrecognized array value will be treated as null and hasXXX will return true.

2. For both Protobuf, Xbuf and Xbuf Xbuf2, unrecognized fields (those with unrecognized field tags) are preserved when an inbound message is written to a transaction log (although they are inaccessible). If the message is copied by serializing to bytes and deserializing into a new message instance, the unrecognized fields from the original message are sent on the wire. If the message is modified prior to sending, the unrecognized fields may be lost. 
3. For repeated enum fields in protobuf Protobuf, unrecognized enum values are ignored. For Protobuf encoding the underlying protobuf may reorder the unrecognized enum values and put them at the end. Xbuf and Xbuf2 generated code preserves the order of unrecognized enums. When deserializing from Json, unrecognized enum values are treated as null so the effect on a deserialized message or entity is the same as adding an enum array with null values (see below). 

...

1. Message and Entities generated with Json encoding support serializing null values and null values in arrays. 
2. For Xbuf setting a timestamp of -1 or less results in the field value being clearedcleared 
   1. Note: This is not the case with Xbuf2. 
3. For Xbuf, Xbuf2 and Protobuf, setting a null value for a String, Date, Enum or Embedded Entity Field results in the field being cleared (protobuf the Google Protobuf wire format doesn't support null values on the wire).
4. For Xbuf and Protobuf, setting a Date[], String[], or Enum[] with containg containing a null value element results in a NullPointerException being thrown. Setting an Embedded Entity [] array or an enum [] with a null value  
   1. Note: With Xbuf2, the behavior is the same as with Entity[] i.e. the null values are ignored
5. For Xbuf, Xbuf2 and Protobuf, setting an Entity[] with a null element results in the null value(s) being ignored during serialization. The same holds true when using the XIterator setters or when calling addXXX to add the set of values.
6. For Xbuf and , Protobuf, when after setting null values in an array field, subsequently calling the getter MAY or MAY NOT result in the null values being returned. Applications are encouraged to use the getXXXIterator accessors, and should be coded to handle either case for maximum portability both between encodings and for handling cases where the null values have been filtered out due to serialization. At present, Xbuf messages generated with protobuf compatibility do not cache a reference to the array passed in, and Protobuf messages do cache values passed in so that nulls are returned ... but this is an implementation detail that could change.  
   1. For Xbuf2, a subsequent call to get or iterator over array elements after setting a null element will NOT return the null element

Pooling Considerations

A major difference between Xbuf/Xbuf2 and Protobuf or Json encoded entities is that Xbuf/Xbuf2 messages and entities are pooled by the platform by default. From a coding standpoint this means that when working with Xbuf Encoded Messages or Entities/Xbuf2 encoded messages or entities:

1. An application may not hold onto an XBuf/Xbuf2 encoded message beyond the scope of a message handler. 
2. An application may not hold onto an XString, or Embedded Entity type from a message beyond the scope of a message handler because these objects are pooled along with the message and will be reset once the message is returned to its pool. See Zero Garbage Nested Entities for detailed usage, but the general rule of thumb is to copy any entity that needs to be retained by applications state, or to use the more advanced 'take' apis. Note that 'take' is not supported for String fields as string fields are not pooled for Xbuf messages. 
3. Setting an XString or Embedded Entity field on a message transfers ownership to the message. If the application wants to retain the entity is application state, then it should copy it into a new entity or use the more advanced 'lend' apis. See  Zero Garbage Nested Entities for more details. 
4. An application may not mutate a returned array type from a message and should not hold onto to the array beyond the duration of a message handler. See Zero Garbage Array Accessors for more details.