coherence/lang/Immutable.hpp

/*
* Immutable.hpp
*
* Copyright 2001-2008 by Oracle. All rights reserved.
*
* Oracle is a registered trademarks of Oracle Corporation and/or its
* affiliates.
*
* This software is the confidential and proprietary information of Oracle
* Corporation. You shall not disclose such confidential and proprietary
* information and shall use it only in accordance with the terms of the
* license agreement you entered into with Oracle.
*
* This notice may not be removed or altered.
*/
#ifndef COH_IMMUTABLE_HPP
#define COH_IMMUTABLE_HPP

#include "coherence/lang/compatibility.hpp"

#include "coherence/lang/IllegalArgumentException.hpp"
#include "coherence/lang/Object.hpp"
#include "coherence/lang/TypedHandle.hpp"

#include <sstream>

COH_OPEN_NAMESPACE2(coherence,lang)


/**
* A Handle implementation which upon assignment ensures that it will
* reference an immutable Object. If the passed Object is immutable
* (as defined by Object::isImmutable()) then the handle simply holds a const
* pointer to the Object. If the passed Object is not immutable, then a clone
* attempt is made, and held via a const pointer.  If the supplied Object is
* not immutable and not cloneable then assignment will fail with a
* CloneNotSupport exception.
*
* @author mf  2007.07.05
*/
template<class T>
class Immutable
    : public TypedHandle<const T>
    {
    // ----- constructors ---------------------------------------------------

    public:
        /**
        * Construct a @c NULL handle.
        */
        Immutable()
                : TypedHandle<const T>()
            {
            }

        /**
        * Construct an Immutable handle to the given Object.
        *
        * @param po the pointer to the Object to reference
        */
        Immutable(const T* po)
                : TypedHandle<const T>()
            {
            set(po);
            }

        /**
        * Construct an Immutable handle from another Handle
        *
        * @param h another handle
        */
        template<class O> Immutable<T>(const TypedHandle<O>& h)
                : TypedHandle<const T>()
            {
            set(get_pointer(h));
            }

        /**
        * Construct an Immutable handle from another Handle
        *
        * @param h another handle
        */
        Immutable<T>(const Immutable<T>& h)
                : TypedHandle<const T>()
            {
            set(h.get());
            }

        /**
        * Destruct the handle
        */
        ~Immutable()
            {
            }


    // ----- helper methods -------------------------------------------------

    protected:

        /**
        * Set this handle to point to immutable version of the given object,
        * or unset the handle.
        *
        * If the given pointer points to the immutable object, then this
        * handle will point it. If the given pointer points to the mutable
        * object, then this handle will point to the clone of that object.
        * If the given pointer is NULL, then this handle will point to no
        * object.
        */
        Immutable<T>& set(const T* cpo)
            {
            if (cpo == NULL || cpo->isImmutable())
                {
                TypedHandle<const T>::set(cpo);
                }
            else
                {
                Object::View vClone;
                    {
                    // With the Sun compiler the temporary handle created
                    // here will live for the duration of the surrounding
                    // scope, we must pop the scope to ensure that the
                    // temporary handle is destroyed/detached, so the
                    // immutability check can pass
                    vClone = cpo->clone();
                    }
                if (NULL == vClone || !vClone->isImmutable())
                    {
                    COH_THROW_STREAM(IllegalArgumentException,
                        "Object of type '" << typeid(*cpo).name() <<
                        "' cannot be made immutable through cloneing.");
                    }
                TypedHandle<const T>::set(get_pointer(
                        cast<typename T::View>(vClone)));
                }
            return *this;
            }
    };

/**
* Return an immutable version of the supplied Object. If the supplied view
* does not refer to an immutable Object, then a clone of the orginal Object
* is returned.
*
* @param v  view to the Object to return an immutable copy of
*
* @return a view to an immutable version of the supplied Object, or the
*         supplied Object if it was already immutable
*/
template<class T> typename T::View immutable_view(const typename T::View& v)
    {
    return Immutable<T>(v);
    }

COH_CLOSE_NAMESPACE2

#endif // COH_IMMUTABLE_HPP

Copyright (c) 2000-2008 Oracle. All rights reserved.