001/*
002 *  $RCSfile: ByValue.java,v $
003 *  $Revision: 1.1.2.1 $ $Date: 2012/01/20 22:10:35 $
004 * 
005 *  Copyright 2012 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 &#64ByValue-marked field can be of any Serializable type that is not Managed.
022 * Using an illegal type will cause an exception to be thrown at class-load time.
023 * <p>
024 * Each set of a &#64ByValue field will marshall the given object into shared memory,
025 * using Java serialization.
026 * Each read of the field will instantiate a new instance from the unmarshalled
027 * data. This means that reference equivalence is not preserved!
028 * <p>
029 * Assume that 'valueField' is a &#64ByValue field of a managed class. The instance read
030 * from the field will be a new object with the same content as the original.
031<pre>
032    Something orig = new Something("Hi!");
033    managed.valueField = orig;
034    copy = managed.valueField;
035
036    assert copy != orig;       // not the same object;
037    assert copy.equals(orig);  // but equivalence relationship is maintained.
038</pre>
039 * 
040 * Also note there is an implication for garbage collection. Because a reference
041 * to the local object is not kept, it may be available for garbage collection.
042 * 
043<pre>
044    managed.valueField = new Something("Hi!");
045    
046    // the new instance created above will be garbage collected after
047    // it is serialized into 'valueField'. Each time the field is read, a 
048    // brand-new instance will be created with the data.
049</pre>
050 * Objects stored in a &#64ByValue field can be transmitted across engines and nodes.
051 *<p>
052 * This annotation has no effect when used in a non-Managed class.
053 */
054@Documented
055@Inherited
056@Retention(RetentionPolicy.RUNTIME)
057@Target(ElementType.FIELD)
058public @interface ByValue
059{
060    
061}