/*
 *  $RCSfile: ByReference.java,v $
 *  $Revision: 1.1.2.2 $ $Date: 2015/01/27 03:24:04 $
 * 
 *  Copyright 2012-2015 Cloud Software Group, Inc. All rights reserved.
 */
package com.kabira.platform.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;


/**
 * Marks a field of a non-Managed object type for inclusion in a Managed class,
 * using copy-by-reference. This allows a Managed type to safely maintain a 
 * reference to process-local resources.
 * <p>
 * A &#64;ByReference-marked field can be of any Object type that is not itself
 * a legal Managed type.
 * Fundamental classes in the java.lang and java.util packages - meaning String,
 * Date, and all auto-boxed types - may not be used in &#64;ByReference fields.
 * Using an illegal type will cause an exception to be thrown at class-load time.
 * <p>
 * Objects stored in a &#64;ByReference field will never be transmitted between 
 * engines or nodes. A single shared memory instance, which may 
 * be represented in multiple VMs, will maintain independent storage for the 
 * &#64;ByReference field on each of those VMs.
 * <p>
 * Exercise caution when using a process-local reference - as a result of 
 * failover or migration, an object may be re-homed on a new VM. The
 * &#64;ByReference fields will be null when examined on that VM.
 * <p>
 * There is no transaction locking provided for non-Managed Java types. 
 * Note that locking occurs only on the Managed object, as part of
 * accessing or updating the ByReference-marked field.
 * <p>
 * This annotation has no effect when used in a non-Managed class.
 */
@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface ByReference
{

}