001/*
002 *  $RCSfile: ByValue.java,v $
003 *  $Revision: 1.1.2.2 $ $Date: 2015/01/27 03:24:08 $
004 * 
005 *  Copyright 2012-2015 Cloud Software Group, Inc. All rights reserved.
006 */
007package com.kabira.platform.annotation;
008
009import java.lang.annotation.Documented;
010import java.lang.annotation.ElementType;
011import java.lang.annotation.Inherited;
012import java.lang.annotation.Retention;
013import java.lang.annotation.RetentionPolicy;
014import java.lang.annotation.Target;
015
016/**
017 * Marks a Serializable field for inclusion in a Managed class, 
018 * using copy-by-value. This allows a Managed type to easily maintain 
019 * a reference to a non-Managed type that can be used across VMs and nodes.
020 * <p>
021 * A &#64;ByValue-marked field can be of any Serializable type that is not
022 * Managed. Using an illegal type will cause an exception to be thrown at
023 * class-load time.
024 * <p>
025 * Each set of a &#64;ByValue field will marshall the given object into
026 * shared memory, using Java serialization.
027 * Each read of the field will instantiate a new instance from the unmarshalled
028 * data. This means that reference equivalence is not preserved!
029 * <p>
030 * Assume that 'valueField' is a &#64;ByValue field of a managed class. The
031 * instance read from the field will be a new object with the same content
032 * as the original.
033<pre>
034    Something orig = new Something("Hi!");
035    managed.valueField = orig;
036    copy = managed.valueField;
037
038    assert copy != orig;       // not the same object;
039    assert copy.equals(orig);  // but equivalence relationship is maintained.
040</pre>
041 * 
042 * Also note there is an implication for garbage collection. Because a reference
043 * to the local object is not kept, it may be available for garbage collection.
044 * 
045<pre>
046    managed.valueField = new Something("Hi!");
047    
048    // the new instance created above will be garbage collected after
049    // it is serialized into 'valueField'. Each time the field is read, a 
050    // brand-new instance will be created with the data.
051</pre>
052 * Objects stored in a &#64;ByValue field can be transmitted across engines
053 * and nodes.
054 *<p>
055 * This annotation has no effect when used in a non-Managed class.
056 */
057@Documented
058@Inherited
059@Retention(RetentionPolicy.RUNTIME)
060@Target(ElementType.FIELD)
061public @interface ByValue
062{
063    
064}