From 02f232a7dd60cdc3e9eb96ed5076235ec06765a4 Mon Sep 17 00:00:00 2001 From: ribes Date: Wed, 7 Mar 2007 09:33:12 +0000 Subject: [PATCH] Doxygen documentation and english comments. --- src/DSC/DSC_User/Superv_Component_i.cxx | 38 +++-- src/DSC/DSC_User/Superv_Component_i.hxx | 188 ++++++++++++++++++------ src/DSC/DSC_User/base_port.hxx | 33 ++++- src/DSC/DSC_User/provides_port.cxx | 24 ++- src/DSC/DSC_User/provides_port.hxx | 50 ++++++- src/DSC/DSC_User/uses_port.cxx | 24 ++- src/DSC/DSC_User/uses_port.hxx | 67 ++++++++- 7 files changed, 351 insertions(+), 73 deletions(-) diff --git a/src/DSC/DSC_User/Superv_Component_i.cxx b/src/DSC/DSC_User/Superv_Component_i.cxx index f1155e2e9..9f238a1b6 100644 --- a/src/DSC/DSC_User/Superv_Component_i.cxx +++ b/src/DSC/DSC_User/Superv_Component_i.cxx @@ -1,4 +1,28 @@ -// André Ribes - EDF R&D +// Copyright (C) 2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN, +// CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2.1 of the License. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +// +// See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com +// +// +// +// File : Superv_Component_i.cxx +// Author : André RIBES (EDF), Eric Fayolle (EDF) +// Module : KERNEL + #include "Superv_Component_i.hxx" DSC_EXCEPTION_CXX(Superv_Component_i,BadFabType); @@ -29,14 +53,6 @@ Superv_Component_i::~Superv_Component_i() { delete _my_basic_factory; } -// Dans ces méthodes, on analyse le type pour connaître -// quel constructeur appelé. -// Le nom du port est sous la forme : -// TYPE_name, exemple : BASIC_short -// : PALM_sequence_long -// : CALCIUM_long -// : etc ... - provides_port * Superv_Component_i::create_provides_data_port(const char* port_fab_type) throw (BadFabType) @@ -230,8 +246,6 @@ Superv_Component_i::provides_port_changed(const char* provides_port_name, int connection_nbr, const Engines::DSC::Message message) { - // On cherche tout d'abord à savoir si le port - // est un port que l'on a dans la liste ... my_superv_ports_it = my_superv_ports.find(provides_port_name); if (my_superv_ports_it != my_superv_ports.end()) my_superv_ports[provides_port_name]->p_ref->provides_port_changed(connection_nbr, @@ -243,8 +257,6 @@ Superv_Component_i::uses_port_changed(const char* uses_port_name, Engines::DSC::uses_port * new_uses_port, const Engines::DSC::Message message) { - // On cherche tout d'abord à savoir si le port - // est un port que l'on a dans la liste ... my_superv_ports_it = my_superv_ports.find(uses_port_name); if (my_superv_ports_it != my_superv_ports.end()) my_superv_ports[uses_port_name]->u_ref->uses_port_changed(new_uses_port, diff --git a/src/DSC/DSC_User/Superv_Component_i.hxx b/src/DSC/DSC_User/Superv_Component_i.hxx index 5cb74f7d1..f7ea45fa8 100644 --- a/src/DSC/DSC_User/Superv_Component_i.hxx +++ b/src/DSC/DSC_User/Superv_Component_i.hxx @@ -1,32 +1,27 @@ -// André Ribes - EDF R&D 2006 +// Copyright (C) 2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN, +// CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2.1 of the License. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +// +// See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com // -// Cette classe implémente le moteur de la plate-forme Salomé // -// Elle dispose de deux types méthodes : -// Des méthodes pour les ports provides -// Des méthodes pour les ports uses // -// Les ports provides sont des ports fournis par la plate-forme réalisant -// par exemple le fonctionnement des ports Calcium ou des ports Basiques sur les -// types CORBA -// -// Les ports uses sont des objets C++ faisant office de proxy pour le code du service afin -// de réaliser des fonctionnalités avant le transfert des données. Ces fonctionnalités doivent d'ailleurs -// être écrites par le développeur s'il utilise un port spécifique à son application. -// -// -// -// Pour ces besoins le moteur redéfini la méthode connect et fourni une méthode register -// pour les proxy -// -// On notera que la méthode init n'est pas implémenté. Elle est laissée à l'implémentation -// du moteur et des services. -// -// Author : ribes -// -// Modified by : $LastChangedBy: fayolle $ -// Date : $LastChangedDate: 2007-03-01 13:36:05 +0100 (jeu, 01 mar 2007) $ -// Id : $Id$ +// File : Superv_Component_i.hxx +// Author : André RIBES (EDF), Eric Fayolle (EDF) +// Module : KERNEL #ifndef _SUPERV_COMPONENT_I_HXX_ #define _SUPERV_COMPONENT_I_HXX_ @@ -46,6 +41,18 @@ using namespace std; +/*! \class Superv_Component_i + * \brief This class implements DSC_User component. + * + * This class allows a higher programming level than DSC_Basic. It enables + * a programming level for service's developpers who want to use DSC ports. + * + * This class has two level for using and declare ports. The higher level proposes + * operations to add ports that are provided by default by Salomé like Calcium ports. + * It provides too some methods to add their own DSC_User ports. + * + * \note This class doesn't implement the init_service CORBA operation. + */ class Superv_Component_i : public Engines_DSC_i, virtual public POA_Engines::Superv_Component @@ -59,8 +66,9 @@ public: bool notif = false); virtual ~Superv_Component_i(); - // Déclarations des Exceptions - // Les définitions sont dans le .cxx + // Exceptions declarations. + // There are also declared on the Superv_Component_i.cxx to avoid problems + // from dlopen. DSC_EXCEPTION(BadFabType); DSC_EXCEPTION(BadType); DSC_EXCEPTION(BadCast); @@ -71,70 +79,156 @@ public: DSC_EXCEPTION(NilPort); DSC_EXCEPTION(BadProperty); - // C++ methods currently disabled + /*! + * \warning currently disabled. + */ virtual provides_port * create_provides_control_port() {return NULL;} + + /*! + * \warning currently disabled. + */ virtual provides_port * create_provides_data_and_control_port(const char* port_type) {return NULL;} + + /*! + * \warning currently disabled. + */ virtual uses_port * create_uses_control_port() {return NULL;} + + /*! + * \warning currently disabled. + */ virtual uses_port * create_uses_data_and_control_port(const char* port_type) {return NULL;} - // Fabriques - // Note: Il manque les méthodes pour ajouter des fabriques - // Dans ce cas là, les fabriques doivent contenir le constructeur - // Bref à revoir éventuellement puisque'on peut faire - // autrement en surchargement ces méthodes dans le composant - // utilisateur + /*! + * This methode permits to create a provides port provided by the platform. + * (See documentation of DSC for knoing these ports). + * + * + * \param port_fab_type type provides port. + * \return the provides port. + * + * \note It's user repsonsability to destroy the provides port. + */ virtual provides_port * create_provides_data_port(const char* port_fab_type) throw (BadFabType); + + + /*! + * This methode permits to create a uses port provided by the platform. + * (See documentation of DSC for knoing these ports). + * + * + * \param port_fab_type type uses port. + * \return the uses port. + * + * \note It's user repsonsability to destroy the uses port. + */ virtual uses_port * create_uses_data_port(const char* port_fab_type) throw (BadFabType); - // Ajouts/Récuperations + /*! + * Adds a port to the component. With this method only Salomé's provided DSC ports + * can be added. + * + * \param port_fab_type type of the port. + * \param port_type uses or provides. + * \param port_name the name of the port in the component. + */ virtual void add_port(const char * port_fab_type, const char * port_type, const char * port_name) throw (PortAlreadyDefined, BadFabType, BadType, BadProperty); + /*! + * Adds a port to the component. With this method only Salomé's provided DSC ports + * can be added. + * + * \param port_fab_type type of the port. + * \param port_type uses or provides. + * \param port_name the name of the port in the component. + * \return the created port. + */ template < typename SpecificPortType > SpecificPortType * add_port(const char * port_fab_type, const char * port_type, const char * port_name) throw (PortAlreadyDefined, BadFabType, BadType, BadCast, BadProperty); + /*! + * Adds a created provides port to the component. + * + * \param port the provides port. + * \param provides_port_name the name of the port in the component. + */ virtual void add_port(provides_port * port, const char* provides_port_name) throw (PortAlreadyDefined, NilPort, BadProperty); + + /*! + * Adds a created uses port to the component. + * + * \param port the uses port. + * \param uses_port_name the name of the port in the component. + */ virtual void add_port(uses_port * port, const char* uses_port_name) throw (PortAlreadyDefined, NilPort, BadProperty); + /*! + * Gets the provides port already added in the component. + * + * \param port the provides port pointer. + * \param provides_port_name the name of the port. + */ virtual void get_port(provides_port *& port, const char* provides_port_name) throw (PortNotDefined, PortNotConnected); + /*! + * Gets the uses port already added in the component. + * + * \param port the uses port pointer. + * \param uses_port_name the name of the port. + */ virtual void get_port(uses_port *& port, const char* uses_port_name) throw (PortNotDefined, PortNotConnected); + /*! + * Gets the list of the ports of a service. + * If servicename is not set, all the ports of the component are + * returned. + * + * \param port_names the ports's list. + * \param servicename service's name. + */ virtual void get_uses_port_names(std::vector & port_names, const std::string servicename="") const; + /*! + * Gets a port already added in the component. + * + * \param provides_port_name the name of the port. + * \return a port's pointer. + */ template - SpecificPortType * get_port( const char * provides_port_name) + SpecificPortType * get_port( const char * port_name) throw (PortNotDefined, PortNotConnected, BadCast, UnexpectedState); - - // Connexions/Déconnexions - // Actuellement vide, mais on rajoutera bientôt des - // méthodes afin de gérer la connexion dans un même container. - - // Callbacks + + /*! + * \see DSC_Callbacks::provides_port_changed + */ virtual void provides_port_changed(const char* provides_port_name, int connection_nbr, const Engines::DSC::Message message); + /*! + * \see DSC_Callbacks::uses_port_changed + */ virtual void uses_port_changed(const char* uses_port_name, Engines::DSC::uses_port * new_uses_port, const Engines::DSC::Message message); @@ -142,18 +236,18 @@ public: private: - // Les fabriques + // Fabrics basic_port_factory * _my_basic_factory; palm_port_factory * _my_palm_factory; calcium_port_factory * _my_calcium_factory; /*-------------------------------------------------*/ - // Gestion des ports + // A Superv_Component port. struct superv_port_t { superv_port_t():u_ref(NULL),p_ref(NULL){}; - // Specifique aux uses port + // For uses ports. uses_port * u_ref; - // Specifique aux provides port; + // For provides ports. provides_port * p_ref; }; diff --git a/src/DSC/DSC_User/base_port.hxx b/src/DSC/DSC_User/base_port.hxx index 55aa42f9e..c3d7bb6c3 100644 --- a/src/DSC/DSC_User/base_port.hxx +++ b/src/DSC/DSC_User/base_port.hxx @@ -1,11 +1,36 @@ -// Eric Fayolle - EDF R&D -// Modified by : $LastChangedBy$ -// Date : $LastChangedDate: 2007-01-08 18:41:18 +0100 (lun, 08 jan 2007) $ -// Id : $Id$ +// Copyright (C) 2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN, +// CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2.1 of the License. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +// +// See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com +// +// +// +// File : base_port.hxx +// Author : Eric Fayolle (EDF), André RIBES (EDF) +// Module : KERNEL #ifndef _PORT_HXX_ #define _PORT_HXX_ +/*! \class base_port + * \brief This class is the base class of DSC_User's C++ ports. + * + * This class is the base class of DSC_User's C++ ports. + */ class base_port { public : diff --git a/src/DSC/DSC_User/provides_port.cxx b/src/DSC/DSC_User/provides_port.cxx index 4787bc306..701b7b07e 100644 --- a/src/DSC/DSC_User/provides_port.cxx +++ b/src/DSC/DSC_User/provides_port.cxx @@ -1,5 +1,27 @@ -// André Ribes EDF R&D - 2006 +// Copyright (C) 2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN, +// CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2.1 of the License. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +// +// See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com // +// +// +// File : provides_port.cxx +// Author : André RIBES (EDF) +// Module : KERNEL #include "provides_port.hxx" diff --git a/src/DSC/DSC_User/provides_port.hxx b/src/DSC/DSC_User/provides_port.hxx index 673f56716..0647f9aeb 100644 --- a/src/DSC/DSC_User/provides_port.hxx +++ b/src/DSC/DSC_User/provides_port.hxx @@ -1,5 +1,27 @@ -// André Ribes - EDF R&D - 2006 +// Copyright (C) 2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN, +// CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2.1 of the License. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +// +// See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com // +// +// +// File : provides_port.hxx +// Author : André RIBES (EDF) +// Module : KERNEL #ifndef _PROVIDES_PORT_HXX_ #define _PROVIDES_PORT_HXX_ @@ -9,15 +31,41 @@ #include "DSC_Engines.hh" #include "PortProperties_i.hxx" +/*! \class provides_port + * \brief This class implements a DSC_User provides C++ port. + * + * This class is base class for all DSC_User provides port. + * It's an abstract class. + * It provides a default property object for the port. + */ class provides_port : public base_port { public : provides_port(); virtual ~provides_port(); + /*! + * This method permits to get the CORBA reference of the port. + * + * \return port's CORBA reference. + */ virtual Ports::Port_ptr get_port_ref() = 0; + + /*! + * This method is the callback called by the component to inform + * the provides port of a new or a removed connection. + * + * \param connection_nbr current connection number. + * \param message message associated with this connection. + */ virtual void provides_port_changed(int connection_nbr, const Engines::DSC::Message message) {} + + /*! + * This is used to get the property object of the port. + * + * \return property's CORBA reference. + */ virtual Ports::PortProperties_ptr get_port_properties(); private : diff --git a/src/DSC/DSC_User/uses_port.cxx b/src/DSC/DSC_User/uses_port.cxx index 85881da85..b110e48d8 100644 --- a/src/DSC/DSC_User/uses_port.cxx +++ b/src/DSC/DSC_User/uses_port.cxx @@ -1,5 +1,27 @@ -// André Ribes EDF R&D - 2006 +// Copyright (C) 2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN, +// CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2.1 of the License. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +// +// See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com // +// +// +// File : uses_port.cxx +// Author : André RIBES (EDF) +// Module : KERNEL #include "uses_port.hxx" diff --git a/src/DSC/DSC_User/uses_port.hxx b/src/DSC/DSC_User/uses_port.hxx index 0e91c877e..93a2ad757 100644 --- a/src/DSC/DSC_User/uses_port.hxx +++ b/src/DSC/DSC_User/uses_port.hxx @@ -1,10 +1,27 @@ -// André Ribes - EDF R&D - 2006 +// Copyright (C) 2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN, +// CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2.1 of the License. +// +// This library 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 +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +// +// See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com // - -// Tous les proxy hérites de cette classe -// Elle permet d'identifier un proxy, de gérer -// la référence réelle de l'objet distant ainsi qu'un support -// aux ports multiples +// +// +// File : uses_port.hxx +// Author : André RIBES (EDF) +// Module : KERNEL #ifndef _USES_PORT_HXX_ #define _USES_PORT_HXX_ @@ -14,17 +31,55 @@ #include "DSC_Engines.hh" #include "PortProperties_i.hxx" +/*! \class provides_port + * \brief This class implements a DSC_User uses C++ port. + * + * This class is base class for all DSC_User uses port. + * It's an abstract class. + * It provides a default property object for the port. + * + * Contrary to DSC_Basic layer, a uses port as an implementation + * provided by this class which permits to manipulate the uses port. + */ class uses_port : public base_port { public : uses_port(); virtual ~uses_port(); + /*! + * This is used by the component to get the CORBA repository id + * of the uses port. It's an abstract method. + * + * \return port's CORBA repository id. + */ virtual const char * get_repository_id() = 0; + + /*! + * DEPRECATED --- WILL BE REMOVED + * It was used when uses port where not multiple. + * It's an abstract method. + * + */ virtual bool set_port(Ports::Port_ptr port) = 0; + /*! + * This is method is the uses port's callback to be aware of + * connections states. + * It's an abstract method. The uses port uses this method + * to manage the sequence of the DSC_Basic uses port. + * + * \param new_uses_port new uses port sequence. + * \param message message associated with this modification. + */ virtual void uses_port_changed(Engines::DSC::uses_port * new_uses_port, const Engines::DSC::Message message) = 0; + + /*! + * This is used to get the property object of the port. + * + * \return property's CORBA reference. + */ virtual Ports::PortProperties_ptr get_port_properties(); private : -- 2.39.2