com.kabira.platform.annotation

Annotation Type ByValue

@Documented
 @Inherited
 @Retention(value=RUNTIME)
 @Target(value=FIELD)
public @interface ByValue

Marks a Serializable field for inclusion in a Managed class, using copy-by-value. This allows a Managed type to easily maintain a reference to a non-Managed type that can be used across VMs and nodes.

A @ByValue-marked field can be of any Serializable type that is not Managed. Using an illegal type will cause an exception to be thrown at class-load time.

Each set of a @ByValue field will marshall the given object into shared memory, using Java serialization. Each read of the field will instantiate a new instance from the unmarshalled data. This means that reference equivalence is not preserved!

Assume that 'valueField' is a @ByValue field of a managed class. The instance read from the field will be a new object with the same content as the original.

    Something orig = new Something("Hi!");
    managed.valueField = orig;
    copy = managed.valueField;

    assert copy != orig;       // not the same object;
    assert copy.equals(orig);  // but equivalence relationship is maintained.

Also note there is an implication for garbage collection. Because a reference to the local object is not kept, it may be available for garbage collection.

    managed.valueField = new Something("Hi!");
    
    // the new instance created above will be garbage collected after
    // it is serialized into 'valueField'. Each time the field is read, a 
    // brand-new instance will be created with the data.

Objects stored in a @ByValue field can be transmitted across engines and nodes.

This annotation has no effect when used in a non-Managed class.