...

1. An application must not hold onto an embedded entity reference post return from an AEP message handler unless a reference to the container message has been acquired by the application or the embedded entity copied or 'taken' from the message prior to return from the handler. Alternatively (or in-addition), the application can hold onto the serialized form of the message post return from the handler and re-materialize the entity from the serialized form at a later point when structured access to the entity's contents is needed. Note that embedded entities are read-only in received messages and, therefore, cannot be modified.
2. The act of 'setting' an instance of an embedded entity onto an outbound message effectively transfers ownership of the embedded entity to the message (and indirectly to the AEP engine through which the message is being sent). The act of sending a message sent via an AEP engine effectively transfers ownership of the message to the AEP engine. The engine disposes the message once stabilized. Message stabilization occurs in an asynchronous, pipelined manner outside the scope of the AEP engine's sendMessage() method. If the application wants to set an embedded entity onto a message without transferring ownership of the entity to the message, the application needs to 'lend' the entity to the message. When lent, the message will acquire its own reference to the entity assuming that the application wishes to retain its reference to the entity. Regardless of whether an entity is 'set' on or 'lent' to a message, the application must ensure that the entity is not concurrently modified while the entity is in-flight with its container message.  

...

When using a getXXX() method it is important to keep in mind that the embedded entity is still attached to the message. And An application cannot hold on to an entity from a getXXX() call beyond the scope of the message from whence it came since it will be disposed along with the message. 

Copying Embedded Entities from Messages

...

// Create an embedded entity. This can be done at application
// startup to prevent allocation at runtime. 
MyEmbeddedEntity entityCopy = MyEmbeddedEntity.create();
.
.
.
if(message.hasMyEntity()) {
  message.copyMyEntityTogetMyEntityTo(entityCopy);
}
.
.
.

// At some later date, dispose of the embedded entity.
// It will be returned to the global pool.  
entityCopy.dispose();

...

// Create an embedded entity. This can be done at application
// startup to prevent allocation at runtime. 
MyEmbeddedEntity entityCopy = MyEmbeddedEntity.create();
.
.
.
if(message.hasMyEntity()) {
  message.getMyEntity().copyInto(entityCopy);
}
.
.
.

// At some later date, dispose of the embedded entity.
// It will be returned to the global pool.  
entityCopy.dispose();

This approach is useful in cases where the embedded entity field is an array as ADM doesn't generate copying getters for arrays, But an application can iterate them in a zero garbage fashion and copy the values it needs to retain:

XIterator<MyEntity> iterator = message.getMyEntityIterator();
while(iterator.hasNext() {
  MyEntity copy = MyEntity.create();
  message.getMyEntity().copyInto(copy);
  .
  .
  .
  // Do something with the copy. 
}

takeXXX()

An embedded entity reference returned by getXXX() is only valid until the entity is disposed i.e. the act of getting an entity does not transfer ownership of the entity to the application A message disposes of its reference to its contained entities when it is disposed itself. An AEP engine disposes a message on return from its message handler. Therefore, applications working with AEP engines that wish to hold onto an embedded entity reference post return from its containing message's handler must either acquire a reference to the container message or 'take' the embedded entity itself from the container message. The act of 'taking' an entity differs from 'getting' an entity in that 'take' does what is necessary to ensure that the entity contents are not cleared and the entity not disposed when the message itself is disposed. For a taken entity to be disposed, the application must explicitly dispose it when done working with it.

...

Embedded Entities that are taken from an inbound messages are marked as read only. 

serializeToXXX()

Embedded entities can be serialized to byte array/buffers and native memory using the serializeToXXX() methods present on embedded entities.

...

Note that backing buffers are sourced from buffer pools managed by the platform ... the actual size of the buffer allocated will be a power of 2. Therefore applications should use a power of 2 when specifying the backing buffer size. 

When an embedded entity is deserialized or copied to another embedded entity with an insufficient backing buffer size, the inadequate buffer is disposed back to its pool and a new backing buffer is created. 

Pass-through

...

Fields 

Anchor
PassThroughFields PassThroughFields

Xbuf supports the ability for an application to preserve fields received on the wire that are not defined in the ADM model that generated them. These fields are referred to as pass-through fields and they are preserved by in the backing buffer of the embedded entity in their serialized protobuf wire format. Because the backing buffer stores the fields in protobuf wire format it is event possible to serialize and deserialize between different embedded field types that share the same field ids and types. These are called pass-through fields because an intermediate app that receives fields it doesn't recognize can pass them between a sender and receiver application without them being lost. 

...

• Taken from inbound to outbound message using take e.g:

  Code Block
  language java
  OutboundMessage.setEmbeddedEntity(inboundMessage.takeEmbeddedEntity());

• When an embedded entity is deserialized from another embedded entity:

  Code Block
  language java
  EmbeddedEntity.deserializeFrom(embeddedEntity.serializeToByteBuffer());

• When an embedded entity is copied from another embedded entity:

  Code Block
  language java
  EmbeddedEntity copy = EmbeddedEntity.copy(); //or message.getEmbeddedEntityTo(copy);

...

Pass through fields are not preserved when:

...