org.mule.api.ThreadSafeAccess Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of mule-core
Mule server and core classes
There is a newer version: 3.9.0
/*
 * $Id: ThreadSafeAccess.java 20321 2010-11-24 15:21:24Z dfeist $
 * --------------------------------------------------------------------------------------
 * Copyright (c) MuleSoft, Inc.  All rights reserved.  http://www.mulesoft.com
 *
 * The software in this package is published under the terms of the CPAL v1.0
 * license, a copy of which has been included with this distribution in the
 * LICENSE.txt file.
 */

package org.mule.api;

import org.mule.api.config.MuleProperties;

import org.apache.commons.lang.BooleanUtils;


/**
 * Interface implemented by message-related objects that avoid exposing mutable data to multiple threads
 * by providing immutable copies.  This interface is optional - it is an implementation detail that is
 * tested for dynamically and used only if available.
 *
 * To avoid "scribbling" where several threads change state within in a single method (typically
 * in inconsistent ways, causing subtle and intermittent errors) we use the following access policy for
 * message related objects:
 *
 * 
 *
 * A new object is "unbound" and "mutable".
 *
 * An object is "bound" to the first thread that calls the object after it is created.
 *
 * A "mutable" object can be modified only by the thread to which it is bound.
 *
 * An object is "sealed" (no longer "mutable") when it is accessed by a thread other than the
 * thread to which it is "bound".  It is an error to attempt to change a "sealed" object.
 *
 * 
 *
 * In practice this means that objects are initially mutable, but become immutable once they are
 * shared.
 */
public interface ThreadSafeAccess
{
     boolean WRITE = true;
     boolean READ = false;
     
    /**
     * This method may be called before data in the object are accessed.  It should verify that the
     * access policy is followed correctly (if not, a runtime exception may be thrown).
     *
     * @param write True if the access will mutate values.
     */
    void assertAccess(boolean write);

    /**
     * This method should ONLY be used in the construction of composite ThreadSafeAccess instances.
     * For example, a ThreadSafeAccess MuleEvent contains a ThreadSafeAccess MuleMessage. During
     * the construction of the event, the message may be bound to the contructing thread.
     * Calling this method releases that binding so that the event as a whole can be passed to a new
     * thread unbound.
     */
    void resetAccessControl();

    /**
     * @return A new instance of the implementing class, unbound to any thread and mutable.
     */
    ThreadSafeAccess newThreadCopy();
    
    /**
     * This helper class can be used by code implementing this interface to determine whether
     * the thread safety of a message should be enforced or not.
     */
    class AccessControl
    {
        private static boolean assertMessageAccess = true;
        private static boolean failOnMessageScribbling = true;
        
        static
        {
            String propertyValue = System.getProperty(MuleProperties.SYSTEM_PROPERTY_PREFIX + "message.assertAccess");
            if (propertyValue != null)
            {
                assertMessageAccess = BooleanUtils.toBoolean(propertyValue);
            }

            propertyValue = System.getProperty(MuleProperties.SYSTEM_PROPERTY_PREFIX + "disable.threadsafemessages");
            if (propertyValue != null)
            {
                failOnMessageScribbling = !BooleanUtils.toBoolean(propertyValue);
            }
        }
        
        public static boolean isAssertMessageAccess()
        {
            return assertMessageAccess;
        }
        
        public static void setAssertMessageAccess(boolean flag)
        {
            assertMessageAccess = flag;
        }
        
        /**
         * Should we fail when we detect "message scribbling"?  
         * (see AbstractMessageAdapter#checkMutable())
         */
        public static boolean isFailOnMessageScribbling()
        {
            return failOnMessageScribbling;
        }
        
        public static void setFailOnMessageScribbling(boolean flag)
        {
            failOnMessageScribbling = flag;
        }
    }

}