coherence/lang/MemberView.hpp

/*
* MemberView.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_MEMBER_VIEW_HPP
#define COH_MEMBER_VIEW_HPP

#include "coherence/lang/compatibility.hpp"

#include "coherence/lang/IllegalStateException.hpp"
#include "coherence/lang/MemberHandle.hpp"
#include "coherence/lang/Object.hpp"
#include "coherence/lang/SmartMember.hpp"
#include "coherence/lang/SynchronizedMemberReadBlock.hpp"
#include "coherence/lang/SynchronizedMemberWriteBlock.hpp"
#include "coherence/lang/TypedHandle.hpp"
#include "coherence/lang/TypedHolder.hpp"

#include <ostream>

COH_OPEN_NAMESPACE2(coherence,lang)

class Object;


/**
* MemberView is a thread-safe view intended for use as a data-member within
* Objects.
*
* @author mf  2008.01.09
*
* @see MemberHandle
* @see MemberHolder
*/
template<class T>
class MemberView
        : public SmartMember
    {
    // ----- typedefs -------------------------------------------------------

    public:
        /**
        * The type of the values the holder can reference.
        */
        typedef T ValueType;

        /**
        * The View type for the referenced Object.
        */
        typedef typename T::View ValueView;

        /**
        * Result type for a non-const get operation.
        */
        typedef ValueView GetType;


    // -------- constructors ------------------------------------------------

    public:
        /**
        * Construct a new MemberView referencing NULL via a handle.
        *
        * @param oParent  the self() on the object this data member is a
        *                 member of
        */
        MemberView(Object& oParent)
                : SmartMember(oParent), m_cpo(NULL)
            {
            }

        /**
        * Construct a new MemberView refrencing specified Object via a View.
        *
        * @param oParent  the self() on the object this data member is a
        *                 member of
        * @param h        a handle to the Object to reference
        */
        template<class DT> MemberView(Object& oParent, const TypedHandle<DT>& h)
                : SmartMember(oParent), m_cpo(NULL)
            {
            set(h);
            }

        /**
        * Construct a new MemberView refrencing the same Object as the
        * specified TypedHolder.
        *
        * @param oParent  the self() on the object this data member is a
        *                 member of
        * @param th       the TypedHolder to initialize from
        */
        template<class DT> MemberView(Object& oParent, const TypedHolder<DT>& th)
                : SmartMember(oParent), m_cpo(NULL)
            {
            operator=(th);
            }

        /**
        * Construct a new MemberView refrencing the same Object as the
        * specified MemberHolder.
        *
        * @param oParent  the self() on the object this data member is a
        *                 member of
        * @param mh       the MemberHolder to initialize from
        */
        template<class DT> MemberView(Object& oParent, const MemberHolder<DT>& mh)
                : SmartMember(oParent), m_cpo(NULL)
            {
            operator=(mh);
            }

        /**
        * Construct a new MemberView refrencing the same Object as the
        * specified MemberView.
        *
        * @param oParent  the self() on the object this data member is a
        *                 member of
        * @param that     the MemberView to initialize from
        */
        template<class DT> MemberView(Object& oParent, const MemberView<DT>& that)
                : SmartMember(oParent), m_cpo(NULL)
            {
            operator=(that);
            }

        /**
        * Construct a new MemberView refrencing the same Object as the
        * specified MemberView.
        *
        * @param oParent  the self() on the object this data member is a
        *                 member of
        * @param that     the MemberView to initialize from
        */
        template<class DT> MemberView(Object& oParent, const MemberHandle<DT>& that)
                : SmartMember(oParent), m_cpo(NULL)
            {
            operator=(that);
            }

        /**
        * Destroy the MemberView.
        */
        ~MemberView()
            {
            set(ValueView());
            }

    private:
        /**
        * Blocked copy constructor.
        */
        MemberView(const MemberView&);


    // ----- operators ------------------------------------------------------

    public:
        /**
        * Assign this MemberView to refrence the same Object as the specified
        * MemberView.
        *
        * @param that  the MemberView to assign from
        *
        * @return a reference to this MemberView
        */
        MemberView& operator=(const MemberView& that)
            {
            operator=((ValueView) that); // assign from snapshot
            return *this;
            }

        /**
        * Assign this MemberView to refrence the same Object as the specified
        * MemberView.
        *
        * @param mv  the MemberView to assign from
        *
        * @return a reference to this MemberView
        */
        template<class DT> MemberView& operator=(const MemberView<DT>& mv)
            {
            operator=((TypedHandle<const DT>) mv);
            return *this;
            }

        /**
        * Assign this MemberView to refrence the same Object as the specified
        * MemberView.
        *
        * @param th  the TypedHolder to assign from
        *
        * @return a reference to this MemberView
        */
        template<class DT> MemberView& operator=(const TypedHolder<DT>& th)
            {
            set(th);
            return *this;
            }

        /**
        * Assign this MemberView to refrence the same Object as the specified
        * MemberHolder.
        *
        * @param mh  the MemberHolder to assign from
        *
        * @return a reference to this MemberView
        */
        template<class DT> MemberView& operator=(const MemberHolder<DT>& mh)
            {
            set(mh);
            return *this;
            }

        /**
        * Assign this MemberView to refrence the same Object as the specified
        * MemberHandle.
        *
        * @param mh  the MemberHandle to assign from
        *
        * @return a reference to this MemberView
        */
        template<class DT> MemberView& operator=(const MemberHandle<DT>& mh)
            {
            set((typename MemberHandle<DT>::ValueView) mh);
            return *this;
            }

        /**
        * Assign this MemberView to refrence the same Object (and in the
        * same manner) as the specified MemberView.
        *
        * @param h  the TypedHandle to assign from
        *
        * @return a reference to this MemberView
        */
        template<class DT> MemberView& operator=(const TypedHandle<DT>& h)
            {
            set(h);
            return *this;
            }

        /**
        * Assign this MemberView to refrence the same Object (and in the
        * same manner) as the specified pointer.
        *
        * @param cp  the pointer to assign from
        *
        * @return a reference to this MemberView
        */
        MemberView& operator=(const T* cp)
            {
            return operator=((ValueView) cp);
            }

        /**
        * Return a View to the referenced Object.
        *
        * @return a View to the referenced Object
        */
        operator ValueView() const
            {
            SynchronizedMemberReadBlock syncRead(getParent());
            return m_cpo;
            }

        /**
        * Return a View to the referenced Object.
        *
        * @return a View to the referenced Object
        */
        template<class PT>
        operator TypedHandle<const PT>() const
            {
            return (ValueView) *this;
            }

        /**
        * Return a TypedHolder to the referenced Object.
        *
        * @return a TypedHolder to the referenced Object
        */
        template<class PT>
        operator TypedHolder<PT>() const
            {
            return (ValueView) *this;
            }

        /**
        * Derefrence the MemberView.
        *
        * @return a const pointer to the referenced Object
        */
        ValueView operator->() const
            {
            return (ValueView) *this;
            }

        /**
        * Compare the supplied MemberView to this MemberView.
        *
        * @param mv  the MemberView to compare against
        *
        * @return true iff the same object is referenced
        */
        template<class AT>
        bool operator==(const MemberView<AT>& mv) const
            {
            typename MemberView<AT>::ValueView v = mv;
            return operator==(v);
            }

        /**
        * Compare the supplied MemberView to this view.
        *
        * @param mv  the holder to compare against
        *
        * @return true iff different objects are referenced
        */
        template<class AT>
        bool operator!=(const MemberView<AT>& mv) const
            {
            return !operator==(mv);
            }

        /**
        * Compare the supplied MemberHolder to this MemberView.
        *
        * @param mh  the MemberHolder to compare against
        *
        * @return true iff the same object is referenced
        */
        template<class AT>
        bool operator==(const MemberHolder<AT>& mh) const
            {
            typename TypedHolder<AT>::ValueView v = mh;
            return operator==(v);
            }

        /**
        * Compare the supplied MemberHolder to this MemberView.
        *
        * @param mh  the holder to compare against
        *
        * @return true iff different objects are referenced
        */
        template<class AT>
        bool operator!=(const MemberHolder<AT>& mh) const
            {
            return !operator==(mh);
            }

        /**
        * Compare the supplied MemberHandle to this MemberView.
        *
        * @param mh  the MemberHandle to compare against
        *
        * @return true iff the same object is referenced
        */
        template<class AT>
        bool operator==(const MemberHandle<AT>& mh) const
            {
            typename MemberHandle<AT>::ValueView v = mh;
            return operator==(v);
            }

        /**
        * Compare the supplied MemberHandle to this MemberView.
        *
        * @param mh  the handle to compare against
        *
        * @return true iff different objects are referenced
        */
        template<class AT>
        bool operator!=(const MemberHandle<AT>& mh) const
            {
            return !operator==(mh);
            }

        /**
        * Compare the supplied holder to this view.
        *
        * @param th  the holder to compare against
        *
        * @return true iff the same object is referenced
        */
        template<class AT>
        bool operator==(const TypedHolder<AT>& th) const
            {
            return operator==(get_pointer((typename TypedHolder<AT>::ValueView) th));
            }

        /**
        * Compare the supplied holder to this view.
        *
        * @param th  the holder to compare against
        *
        * @return true iff different objects are referenced
        */
        template<class AT>
        bool operator!=(const TypedHolder<AT>& th) const
            {
            return !operator==(th);
            }

        /**
        * Compare the supplied handle to this view.
        *
        * @param h  the handle to compare against
        *
        * @return true iff the same object is referenced
        */
        template<class AT>
        bool operator==(const TypedHandle<AT>& h) const
            {
            return operator==(get_pointer(h));
            }

        /**
        * Compare the supplied handle to this view.
        *
        * @param h  the handle to compare against
        *
        * @return true iff the different objects are referenced
        */
        template<class AT>
        bool operator!=(const TypedHandle<AT>& h) const
            {
            return !operator==(h);
            }

        /**
        * Compare the supplied pointer to this view.
        *
        * @param cpThat  the pointer to compare against
        *
        * @return true iff the same object is referenced
        */
        bool operator==(const Object* cpThat) const
            {
            SynchronizedMemberReadBlock syncRead(getParent());
            return ((const Object*) m_cpo) == cpThat;
            }

        /**
        * Compare the supplied pointer to this view.
        *
        * @param cpThat  the pointer to compare against
        *
        * @return true iff different objects are referenced
        */
        bool operator!=(const Object* cpThat) const
            {
            return !operator==(cpThat);
            }


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

    protected:
        /**
        * Set the view to reference an Object via a View.
        *
        * @param v      the View to the Object to reference
        * @param pSync  optional external SyncornizedMemberWriteBlock to use
        *               to avoid internal synchronization.
        *
        */
        void set(ValueView v, SynchronizedMemberWriteBlock* pSync = NULL)
            {
            const T*      cpo      = get_pointer(v);
            const Object* cpAttach = NULL == cpo ? NULL : cpo->_attach();
            const T*      cpDetach = NULL;

            // sync block
                {
                SynchronizedMemberWriteBlock syncWrite(getParent(), pSync);
                cpDetach = m_cpo;
                m_cpo = NULL == cpAttach ? NULL : cpo;
                }

            if (cpDetach)
                {
                cpDetach->_detach();
                }
            }

        /**
        * Return a View to the referenced Object.
        *
        * @param pSync  optional external SyncornizedMemberReadBlock to use
        *               to avoid internal synchronization.
        *
        * @return a View to the referenced Object
        */
        ValueView get(SynchronizedMemberReadBlock* pSync = NULL) const
            {
            SynchronizedMemberReadBlock syncRead(getParent(), pSync);
            return m_cpo;
            }


    // ----- data members ---------------------------------------------------

    private:
        /**
        * The referenced Object.
        */
        const T* m_cpo;


    // ----- friends --------------------------------------------------------

    /**
    * @internal
    */
    friend class SynchronizedMemberReadBlock;

    /**
    * @internal
    */
    friend class SynchronizedMemberWriteBlock;
    };


// ----- non-member operators and functions ---------------------------------

/**
* Output a human-readable description of the given MemberView to the
* specified stream.
*
* @param out  the stream used to output the description
* @param mv   the MemberView to describe
*
* @return the supplied stream
*/
template<class T> std::ostream& operator<<(std::ostream& out, const MemberView<T>& mv)
    {
    out << (typename T::View) mv;
    return out;
    }

/**
* Assign the specified holder to NULL.
*
* @param mv the MemberView to clear
*/
template<class T> void clear_handle(MemberView<T>& mv)
    {
    static TypedHandle<const T> vNull;
    mv = vNull;
    }

/**
* Return true if the supplied holder equals NULL.
*
* @param mv  the MemberView to test
*
* @return true iff the supplied MemberView equals NULL
*/
template<class T>
bool is_null(const MemberView<T>& mv)
    {
    return NULL == mv;
    }

/**
* Perform a dynamic cast the pointer associated with the MemberView
* to a the specified handle/view type.
*
* @param mv      the MemberView from which to perform the cast
* @param fThrow  true if an exception is to be thrown on a failed cast
*
* @return the casted pointer, or NULL if the cast fails and fThrow is false
*
* @throws ClassCastException if the cast fails and fThrow is true
*/
template<class D, class T>
D cast(const MemberView<T>& mv, bool fThrow = true)
    {
    return cast<D>((typename MemberView<T>::ValueView) mv, fThrow);
    }

/**
* Perform an instanceof check on a MemberView.
*
* @param mv  the MemberView from which to perform the test
*
* @return true if the supplied handle is an instance of the specified type
*/
template<class D, class T>
bool instanceof(const MemberView<T>& mv)
    {
    return NULL != cast<D>(mv, false);
    }

/**
* Compare a handle to a MemberView.
*
* @param h   handle to compare
* @param mv  MemberView to compare
*
* @return true if both reference the same Object
*/
template<class AT, class T>
bool operator==(const TypedHandle<AT>& h, const MemberView<T>& mv)
    {
    return mv == h;
    }

/**
* Compare a Object pointer to a holder.
*
* @param cpo  handle to compare
* @param mv   MemberView to compare
*
* @return true if both reference the same Object
*/
template<class T>
bool operator==(const Object* cpo, const MemberView<T>& mv)
    {
    return mv == cpo;
    }

/**
* Compare a handle to a holder.
*
* @param h   handle to compare
* @param mv  MemberView to compare
*
* @return true if each references a different Object
*/
template<class AT, class T>
bool operator!=(const TypedHandle<AT>& h, const MemberView<T>& mv)
    {
    return mv != h;
    }

/**
* Compare a Object pointer to a MemberView.
*
* @param cpo  handle to compare
* @param mv   holder to compare
*
* @return true if each references a different Object
*/
template<class T>
bool operator!=(const Object* cpo, const MemberView<T>& mv)
    {
    return mv != cpo;
    }

COH_CLOSE_NAMESPACE2

#endif // COH_MEMBER_VIEW_HPP

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