source: finroc_plugins_runtime_construction/tFinstructable.h @ 163:19d7bbecc1fb

17.03
Last change on this file since 163:19d7bbecc1fb was 163:19d7bbecc1fb, checked in by Max Reichardt <max.reichardt@…>, 20 months ago

Improves handling of connectors loaded from XML files with no referenced port present at loading time.

File size: 11.3 KB
Line 
1//
2// You received this file as part of Finroc
3// A framework for intelligent robot control
4//
5// Copyright (C) Finroc GbR (finroc.org)
6//
7// This program is free software; you can redistribute it and/or modify
8// it under the terms of the GNU General Public License as published by
9// the Free Software Foundation; either version 2 of the License, or
10// (at your option) any later version.
11//
12// This program is distributed in the hope that it will be useful,
13// but WITHOUT ANY WARRANTY; without even the implied warranty of
14// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15// GNU General Public License for more details.
16//
17// You should have received a copy of the GNU General Public License along
18// with this program; if not, write to the Free Software Foundation, Inc.,
19// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
20//
21//----------------------------------------------------------------------
22/*!\file    plugins/runtime_construction/tFinstructable.h
23 *
24 * \author  Max Reichardt
25 *
26 * \date    2012-12-02
27 *
28 * \brief   Contains tFinstructable
29 *
30 * \b tFinstructable
31 *
32 * The contents of Finstructable framework elements can be edited using
33 * Finstruct.
34 *
35 * They get a reference to an XML file in the constructor.
36 * The contents of a finstructable are determined by the contents of the
37 * XML file.
38 * Changes made using finstruct can be saved back to this XML file.
39 *
40 * Finstructable can be added as an annotation to any framework element.
41 */
42//----------------------------------------------------------------------
43#ifndef __plugins__runtime_construction__tFinstructable_h__
44#define __plugins__runtime_construction__tFinstructable_h__
45
46//----------------------------------------------------------------------
47// External includes (system with <>, local with "")
48//----------------------------------------------------------------------
49#include "rrlib/xml/tNode.h"
50#include "core/port/tAbstractPort.h"
51
52//----------------------------------------------------------------------
53// Internal includes with ""
54//----------------------------------------------------------------------
55#include "plugins/runtime_construction/tCreateFrameworkElementAction.h"
56#include "plugins/runtime_construction/tOriginData.h"
57
58//----------------------------------------------------------------------
59// Namespace declaration
60//----------------------------------------------------------------------
61namespace finroc
62{
63namespace runtime_construction
64{
65
66//----------------------------------------------------------------------
67// Forward declarations / typedefs / enums
68//----------------------------------------------------------------------
69namespace internal
70{
71class tRuntimeConstructionPlugin;
72}
73
74//----------------------------------------------------------------------
75// Class declaration
76//----------------------------------------------------------------------
77//! Group whose contents can be constructed/edited using finstruct.
78/*!
79 * The contents of Finstructable framework elements can be edited using
80 * Finstruct.
81 *
82 * They get a reference to an XML file in the constructor.
83 * The contents of a finstructable are determined by the contents of the
84 * XML file.
85 * Changes made using finstruct can be saved back to this XML file.
86 *
87 * Finstructable can be added as an annotation to any framework element.
88 */
89class tFinstructable : public core::tAnnotation
90{
91
92//----------------------------------------------------------------------
93// Public methods and typedefs
94//----------------------------------------------------------------------
95public:
96
97  /*!
98   * (if the provided file does not exist, it is created, when contents are saved - and a warning is displayed)
99   * (if the provided file exists, its contents are loaded when group is initialized)
100   * (if the provided file name is empty, nothing is loaded or saved)
101   *
102   * \param xml_file Reference to name of xml file that determines contents of this group
103   */
104  tFinstructable(const std::string& xml_file);
105
106  /*!
107   * Helper method to collect data types that need to be loaded before the contents of
108   * this XML file can be instantiated.
109   * (only has an effect if the current thread is currently saving this group to a file)
110   *
111   * \param dt Data type required to instantiate this .xml
112   */
113  static void AddDependency(const rrlib::rtti::tType& dt);
114
115  /*!
116   * Evaluates connectors loaded from XML that could not be created again
117   *
118   * \param print_warning_messages Whether to print warning messages for all connectors that cannot be instantiated
119   */
120  void CheckPendingConnectors(bool print_warning_messages);
121
122  /*! for rrlib_logging */
123  std::string GetLogDescription() const;
124
125  /*!
126   * "Includes" finstructable XML file: Adds all structure defined in XML file to specified parent element.
127   * Note that the created structure is not marked 'finstructed' (so that saving the main file does not suddenly include all of it).
128   *
129   * \param parent Framework element to add structure to
130   * \param xml_file Finstructable XML file containing structure to add
131   * \param origin Origin (optional). If set, adds tOriginDataAnnotation with this origin to created elements.
132   */
133  static void Include(core::tFrameworkElement& parent, const std::string& xml_file, core::tFrameworkElement* origin = nullptr);
134
135  /*!
136   * Loads and instantiates contents of xml file
137   *
138   * \param xml_file xml file to load
139   */
140  void LoadXml();
141
142  /*!
143   * Save contents of group back to Xml file
144   *
145   * \exception Throws std::runtime_error if saving fails
146   */
147  void SaveXml();
148
149  /*!
150   * Scan for command line arguments in specified .finroc xml file.
151   * (for finroc executable)
152   *
153   * \param finroc_file File to scan in.
154   * \return List of command line arguments.
155   */
156  static std::vector<std::string> ScanForCommandLineArgs(const std::string& finroc_file);
157
158  /*!
159   * Mark element as finstructed
160   * (should only be called by AdminServer and CreateModuleActions)
161   *
162   * \param fe Framework element to mark
163   * \param create_action Action with which framework element was created
164   * \param params Parameters that module was created with (may be null)
165   * \param origin_data Origin data to attach (if not set, order will be set to steady_clock time)
166   */
167  static void SetFinstructed(core::tFrameworkElement& fe, tCreateFrameworkElementAction& create_action, tConstructorParameters* params, tOriginData origin_data = tOriginData());
168
169  /*!
170   * \param main_name Default name when group is main part
171   */
172  void SetMainName(const std::string main_name)
173  {
174    this->main_name = main_name;
175  }
176
177//----------------------------------------------------------------------
178// Private fields and methods
179//----------------------------------------------------------------------
180private:
181
182  friend class internal::tRuntimeConstructionPlugin;
183
184  /*! Default name when group is main part */
185  std::string main_name;
186
187  /*! Reference to string that contains xml file name to load and save */
188  const std::string& xml_file;
189
190  /*! Connector data containing all relevant data loaded from XML */
191  struct tConnectorData
192  {
193    std::string source, destination;
194    core::tUriConnectOptions connect_options;
195    uint structure_file_version = 0;
196    std::string status;
197    bool top_level_composite_component = false;
198  };
199
200  /*! connectors as loaded from XML file that could not be created (yet) */
201  std::vector<tConnectorData> pending_connectors;
202
203  /*! Whether composite component initialization is complete */
204  bool fully_initialized = false;
205
206  /*!
207   * Helper method to collect .so files that need to be loaded before the contents of
208   * this XML file can be instantiated.
209   * (only has an effect if the current thread is currently saving this group to a file)
210   *
211   * \param dependency .so file that needs to be loaded
212   */
213  static void AddDependency(const tSharedLibrary& dependency);
214
215  /*!
216   * \param path Relative path to port
217   * \return Port - or nullptr if it couldn't be found
218   */
219  core::tAbstractPort* GetChildPort(const core::tPath& path);
220
221  /*!
222   * \param target_path Target's absolute path (as from internal URI connector)
223   * \param this_group_path Path of this finstructable group
224   * \return Relative path to target (or absolute path if it is outside this group)
225   */
226  core::tPath GetConnectorPath(const core::tPath& target_path, const core::tPath& this_group_path);
227
228  /*!
229   * \param port Port
230   * \param this_group_path Path of this finstructable group
231   * \return Relative path to port (or absolute path if it is outside this group)
232   */
233  core::tPath GetConnectorPath(core::tAbstractPort& port, const core::tPath& this_group_path);
234
235  /*!
236   * \return Root framework element that this annotation belongs to
237   */
238  core::tFrameworkElement* GetFrameworkElement() const;
239
240  /*!
241   * \return Returns raw xml name to use for loading and saving (either fixed string or from static parameter)
242   */
243  std::string GetXmlFileString();
244
245  /*!
246   * Intantiate element
247   *
248   * \param node xml node that contains data for instantiation
249   * \param parent Parent element
250   */
251  void Instantiate(const rrlib::xml::tNode& node, core::tFrameworkElement* parent);
252
253  /*!
254   * Intantiate connector
255   *
256   * \param connector_data Data of connector
257   * \param path_to_this Path to this composite component
258   * \return Error message if connector could not (yet) be instantiated.
259   */
260  std::string InstantiateConnector(const tConnectorData& connector_data, const core::tPath& path_to_this);
261
262  /*!
263   * Is this finstructable group the one responsible for saving parameter's config entry?
264   *
265   * \param ap Framework element to check this for (usually parameter port)
266   * \return Answer.
267   */
268  bool IsResponsibleForConfigFileConnections(core::tFrameworkElement& ap) const;
269
270  /*!
271   * Helper function for loading parameter links
272   *
273   * \param node Parameter XML node
274   * \param parameter_port Abstract Port that should be a parameter
275   */
276  void LoadParameter(const rrlib::xml::tNode& node, core::tFrameworkElement& parameter_element);
277
278  virtual void OnInitialization() override;
279
280  /*!
281   * Recursive helper function for loading parameter_links section of XML file
282   *
283   * \param node Current XML node
284   * \param element Framework element corresponding to node
285   */
286  void ProcessParameterLinksNode(const rrlib::xml::tNode& node, core::tFrameworkElement& element);
287
288  /*!
289   * Recursive helper function for saving parameter_links section of XML file
290   *
291   * \param node Current XML node
292   * \param element Framework element corresponding to node
293   * \result True if any parameters were saved below node
294   */
295  bool SaveParameterConfigEntries(rrlib::xml::tNode& node, core::tFrameworkElement& element);
296
297  /*!
298   * Recursive helper function for ScanForCommandLineArgs
299   *
300   * \param result Result list
301   * \param parent Node to scan childs of
302   */
303  static void ScanForCommandLineArgsHelper(std::vector<std::string>& result, const rrlib::xml::tNode& parent);
304
305  /*!
306   * Serialize children of specified framework element
307   *
308   * \param node XML node to serialize to
309   * \param current Framework element
310   */
311  void SerializeChildren(rrlib::xml::tNode& node, core::tFrameworkElement& current);
312
313  /*!
314   * Perform some static initialization w.r.t. to state at program startup
315   */
316  static void StaticInit();
317};
318
319//----------------------------------------------------------------------
320// End of namespace declaration
321//----------------------------------------------------------------------
322}
323}
324
325
326#endif
Note: See TracBrowser for help on using the repository browser.