torc/generic/om/InterfaceJoinedInfo.hpp

// Torc - Copyright 2011 University of Southern California.  All Rights Reserved.
// $HeadURL: https://torc-isi.svn.sourceforge.net/svnroot/torc-isi/branches/staging/0.9/src/torc/generic/om/InterfaceJoinedInfo.hpp $
// $Id: InterfaceJoinedInfo.hpp 10 2011-10-12 18:40:16Z nsteiner $

// This program is free software: you can redistribute it and/or modify it under the terms of the 
// GNU General Public License as published by the Free Software Foundation, either version 3 of the 
// License, or (at your option) any later version.
// 
// This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; 
// without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See 
// the GNU General Public License for more details.
// 
// You should have received a copy of the GNU General Public License along with this program.  If 
// not, see <http://www.gnu.org/licenses/>.

#ifndef TORC_GENERIC_OM_INTERFACEJOINEDINFO_HPP
#define TORC_GENERIC_OM_INTERFACEJOINEDINFO_HPP

#include "torc/generic/om/PointerTypes.hpp"
#include "torc/generic/util/Error.hpp"
#include "torc/generic/om/FactoryType.hpp"
#include "torc/generic/om/Visitable.hpp"
#include "torc/generic/om/VisitorType.hpp"
#include "torc/generic/om/SelfReferencing.hpp"

#include <list>
#include <vector>

namespace torc { namespace generic { class Port; }  } 
namespace torc { namespace generic { class PortList; }  } 
namespace torc { namespace generic { class BaseVisitor; }  } 

namespace torc {

namespace generic {

/**
 * @brief Represents the Interface joining information.
 * 
 * The InterfaceJoinedInfo class is used to hold interface joining information.
 * Joining information specify which ports (scalar port, array of ports, bundle of ports)
 * or port lists are shorted together.
 */
class InterfaceJoinedInfo : 
    public Visitable,
    public SelfReferencing<InterfaceJoinedInfo> 
{
    friend class FactoryType<InterfaceJoinedInfo>;

  public:
    /**
     * @enum JoinedType
     * Interface joining type
     */
    enum JoinedType
    {
      eJoinedTypeJoin = 0,
      eJoinedTypeWeak,
      eJoinedTypeMust
    };

    /**
     * @enum RelationType
     *
     * Type of the InterfaceJoinedInfo, Is it parent or child.
     */
    enum RelationType
    {
        eRelationTypeParent = 0,
        eRelationTypeChild
    };


    /**
     * Convenience class to visit an interface joining information.
     */
    typedef VisitorType<InterfaceJoinedInfo> Visitor;

    /**
     * Convenience class to create an interface joining information.
     */
    class Factory: public FactoryType<InterfaceJoinedInfo>
    {
        public:
            using FactoryType<InterfaceJoinedInfo>::create;
        /**
         * Create an interface joining information .
         *
         * @param[in] inPorts List of ports to this joining information.
         * @param[in] inPortLists List of portLists to this joining information.
         * @param[in] inViewPtr Pointer to parented(View) object.
         * @param[in] inParentJoinedInfo Pointer to parent joining information.
         *
         * @return Pointer to created interface joining information.
         */
         InterfaceJoinedInfoSharedPtr
         virtual newInterfaceJoinedInfoPtr( const std::list< PortSharedPtr > & inPorts,
                const std::list< PortListSharedPtr > & inPortLists,
                const ViewSharedPtr & inViewPtr,
                const InterfaceJoinedInfoSharedPtr & inParentJoinedInfo
                        = InterfaceJoinedInfoSharedPtr() ) throw(Error);
    };

    /**
     * @brief Recive a visitor to this class. 
     * The visit method of the visitor is called and a reference to this 
     * object is passed as a parameter. It has to be noted however, 
     * that a dynamic_cast is performed inside this method. If the cast fails, 
     * an appropriate exception is thrown by this method. This sitation can arise 
     * when the passed Visitor object does not inherit from the appropriate 
     * visitor specialization. See Visitor documentation for more details.
     * 
     * @param[in,out] visitor A reference to the visitor object
     * @exception Error Visitor type inappropriate for visiting this object 
     * or any other error thrown by the Visitor::throw() method.
     */
    virtual void 
    accept(BaseVisitor & visitor) throw(Error);

    /**
     * Get the interface joining type
     *
     * @return Interface joining type
     */
    inline const JoinedType 
    getJoinedType() const throw();

    /**
     * Set the interface joining type
     *
     * @param[in] inSource Interface joining type
     */
    void 
    setJoinedType( const JoinedType & inSource ) throw();

     /**
     * Add a port to the list of ports. Empty pointer is ignored.
     *
     * @param[in] inPort Pointer to port to be added.
     * @exception Error Could not add port, because Port name is empty
    */
    void
    addPort( const PortSharedPtr & inPort ) throw(Error);

    /**
     * Get the list of pointers to the joined ports of an interface
     *
     * @return outPorts List of ports to be appended to
     */
    inline void
    getPorts( std::list< PortSharedPtr > & outPorts ) const throw();

    /**
     * Set the list of joined ports of an interface
     *
     * @param[in] inSource List of ports to be joined to an interface
     */
    void 
    setPorts( const std::list< PortSharedPtr > & inSource ) throw();

     /**
     * Add a portList to the list of portLists. Empty pointer is ignored.
     *
     * @param[in] inPortList Pointer to portList to be added.
    */
    void
    addPortList( const PortListSharedPtr & inPortList ) throw();

    /**
     * Get the list of joined portLists of an interface
     *
     * @return outPortLists List of joined portLists to be appended to
     */
    inline void
    getPortLists( std::list< PortListSharedPtr > & outPortLists) const throw();

    /**
     * Set the list of joined portLists of an interface
     *
     * @param[in] inSource List of portLists to be joined to an interface
     */
    void 
    setPortLists( const std::list< PortListSharedPtr > & inSource ) throw();

    /**
     * Get the nested interface joined info.
     *
     * @param[out] outJoinedInfos Vector of interface joined info to be appended to
     */
    inline void
    getChildren( std::vector< InterfaceJoinedInfoSharedPtr >
            & outJoinedInfos ) const throw();

    /**
     * Set the nested joining information
     * 
     * @param[in] inSource Vector containing joining informations
     * @exception Error Could not add child joined info because 
     * pointer to the joined info does not exist
     */
    void 
    setChildren(const std::vector< InterfaceJoinedInfoSharedPtr > 
            & inSource) throw();

    /**
     * Add a joined info to parent joined info
     * 
     * @param[in] inChildJoinInfo Child interface joined info to be added to parent
     */
    bool 
    addChildJoinedInfo( 
            const InterfaceJoinedInfoSharedPtr & inChildJoinInfo) throw();

    /**
     * Apply action on all children
     * @param[in] action Action to be applied 
     */
    template<typename _Action> 
    inline void applyOnAllChildren(const _Action & action) throw(Error);

    /**
     * Get the relation type.
     *
     * @return RelationType
     */
    inline const RelationType
    getRelationType() const throw();

    /**
     * Set the relation type.
     *
     * @param[in] inSource RelationType
     */
    void
    setRelationType(const RelationType & inSource) throw();

    /**
     * Get the total number of bits of the composition
     * @return Number of bits
     */
    size_t
    getSize() const throw();

    virtual ~InterfaceJoinedInfo() throw();

  protected:
    InterfaceJoinedInfo();

  private:
    JoinedType mJoinedType;
    RelationType mRelationType;
    std::list< PortSharedPtr > mJoinedPorts;
    std::list< PortListSharedPtr > mJoinedPortLists;
    std::vector< InterfaceJoinedInfoSharedPtr > mChildren;

};

/**
 * Get the interface joining type
 *
 * @return Interface joining type
 */
inline const InterfaceJoinedInfo::JoinedType 
InterfaceJoinedInfo::getJoinedType() const throw() {
    return mJoinedType;
}

/**
 * Get the list of pointers to the joined ports of an interface
 *
 * @return outPorts List of ports to be appended to
 */
inline void
InterfaceJoinedInfo::getPorts( 
            std::list< PortSharedPtr > & outPorts ) const throw() {
    outPorts.insert( outPorts.end(),
            mJoinedPorts.begin(), mJoinedPorts.end() );
}

/**
 * Get the list of joined portLists of an interface
 *
 * @return outPorts List of joined portLists to be appended to
 */
inline void
InterfaceJoinedInfo::getPortLists( 
            std::list< PortListSharedPtr > & outPortLists ) const throw() {
    outPortLists.insert( outPortLists.end(), 
                mJoinedPortLists.begin(), mJoinedPortLists.end() );
}

/**
 * Get the nested interface joined info.
 *
 * @param[out] outJoinedInfos Vector of interface joined info to be appended to
 */
inline void
InterfaceJoinedInfo::getChildren( std::vector< InterfaceJoinedInfoSharedPtr >
        & outJoinedInfos ) const throw() {
    outJoinedInfos.insert( outJoinedInfos.end(),
            mChildren.begin(), mChildren.end() );
}

/**
 * Apply action on all children
 * @param[in] action Action to be applied 
 */
template<typename _Action> 
inline void 
InterfaceJoinedInfo::applyOnAllChildren(const _Action & action) throw(Error) {
    try
    {
        std::vector< InterfaceJoinedInfoSharedPtr >::iterator it 
                = mChildren.begin();
        for(; it != mChildren.end(); ++ it )
        {
            action( *it );
        }
    }
    catch(Error &e)
    {
        e.setCurrentLocation( __FUNCTION__, __FILE__, __LINE__ );
        throw;
    }
}

/**
 * Get the relation type.
 *
 * @return RelationType
 */
inline const InterfaceJoinedInfo::RelationType
InterfaceJoinedInfo::getRelationType() const throw() {
   return mRelationType; 
}

} // namespace torc::generic

} // namespace torc
#endif // TORC_GENERIC_OM_INTERFACEJOINEDINFO_HPP

---