Page History

...

Accessor	Description
Array Accessors
void setXXX(T [] val)	Sets the value in the entity. Note that when setting entity values, this operation transfers ownership of each reference in the array ... the application must not modify them after transferring ownership. The application may first clonecopy() each value before adding it if it intends to modify or reuse them. For performance reasons, this operation may store a reference to the val itself so after setting the value the application should not modify the array's contents.
void lendXXX(T [] val)	Lends each value in the array to this entity and sets them as the new values for this entity's backing array. For performance reasons, this operation may store a reference to the val itself so after setting the value the application should not modify the array's contents. Note that when lending entities, serialization of the values can happen in another thread, the application must therefore not modify the values that it lends. The application may first clonecopy() each entity before adding it if it intends to modify or reuse it.
T [] getXXX()	Gets the field as an array. This call is not zero garbage ... use getXXXIterator() instead Applications may not retain a reference to the returned array and should treat it as immutable.
T [] takeXXX()	Gets the field as an array acquiring a reference to each element taken. This call is not zero garbage ... use getXXXIterator() instead, and call acquire on each element that the application will retain. Applications may not retain a reference to the returned array and should treat it as immutable.
T [] getXXXEmptyIfNull()	Gets the field as an array, If there are no values an empty array is returned. This call is not zero garbage ... use getXXXIterator() instead. Applications may not retain a reference to the returned array and should treat it as immutable.
Iterative Accessors
void setXXXFrom(XIterator<T> val)	Calls toFirst() on the iterator and sets the value in the entity to the remainingvalues in val. Note that when setting entity values, t his operation transfers ownership of each reference in the array ... the application must not modify them after transferring ownership. The application may first clonecopy() each value before adding it if it intends to modify or reuse them.
void lendXXXFrom(XIterator<T> val)	Calls toFirst() on the iterator and lends all of the remainingvalues as the new values for this entity. Note that when lending entities, serialization of the values can happen in another thread, the application must therefore not modify the values that it lends. The application may first clonecopy() each entity before adding it if it intends to modify or reuse it.
XIterator getXXXIterator()	Provides zero garbage iterative access to the backing values in the array. This call may return the same instance of the iterator for each invocation; when this is the case each call to get the iterator will result in toFirst() being called for it. Applications may not retain a reference to the iterator beyond the scope of a message handler as it is may be tied to the pooling lifecycle of the entity that returns it. Additionally, if the iterator contains pooled embedded entities, the application may not retain references to the elements itself without first acquiring them. This iterator is not thread safe and concurrent modification of the field by either another thread or by the iterating thread will result in unspecified behavior.

void addXXX(T val)	Adds a value to the array of values in the message. Note that when setting an entity value, t his operation transfers ownership of the value ... the application must not modify the value after transferring ownership. The application may first clonecopy() the value before adding it if it intends to modify or reuse it.
void lendXXX(T val)	Lends the provided value to the entity and adds it to the backing array for the field. Note that when lending an entity, serialization of the value can happen in another thread, the application must therefore not modify the value that it lends. The application may first clonecopy() the value before adding it if it intends to modify or reuse it.
clearXXX()	Clears all of the values in the backing array. Each value is disposed().

...

Code Block

language	java

public class MyStateObject {
  	// preallocated array to hold values from a message
	private final ArrayList<MyEntity> myEntities = new ArrayList<MyEntity>(5); 
 
	public final void update(final Message message) {
       clearEntities();
       XIterator<MyEntity> iterator = message.getMyEntityIterator();
       while(iterator.hasNext()) {
		  final MyEntity entity = iterator.next();	
		  if(entity.getQuantity() > 0) {
              //Acquire a reference since this is owned by the 
              //by the message:
              entity.acquire(); 
              myEntities.add(entity.copy()); 
          }
       }
    }
 
    public void clearEntities() {
       //Dereference and clear previously acquired entities:
       if(!myEntities.isEmpty()) {
          for(int i = 0; i < myEntities.size(); i++) {
             myEntities.get(i).dispose();
          }
		  myEntities.clear();
       }
    }
}

Note that the embedded entity copy() method was introduced in the 3.5.1 and 3.6.1 versions of the ADM code generator. Prior versions can use the clone() method, but be advised that the clone operation does not preserve pass-through fields.

Known Limitations

At this time Arrays Accessors for Wrapped primitive types are not zero garbage. This includes String[], Uuid[] and Date[] fields. For zero garbage operation with these types consider using XBuf - Repeated Field Bulk Copies.

The Talon Manual

Additional Links

Versions Compared

Old Version 2

New Version Current

Key

Known Limitations