1 /** 2 * @file SBMLConverter.h 3 * @brief Definition of SBMLConverter, the base class for SBML conversion. 4 * @author Sarah Keating 5 * 6 * <!-------------------------------------------------------------------------- 7 * This file is part of libSBML. Please visit http://sbml.org for more 8 * information about SBML, and the latest version of libSBML. 9 * 10 * Copyright (C) 2020 jointly by the following organizations: 11 * 1. California Institute of Technology, Pasadena, CA, USA 12 * 2. University of Heidelberg, Heidelberg, Germany 13 * 3. University College London, London, UK 14 * 15 * Copyright (C) 2019 jointly by the following organizations: 16 * 1. California Institute of Technology, Pasadena, CA, USA 17 * 2. University of Heidelberg, Heidelberg, Germany 18 * 19 * Copyright (C) 2013-2018 jointly by the following organizations: 20 * 1. California Institute of Technology, Pasadena, CA, USA 21 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 22 * 3. University of Heidelberg, Heidelberg, Germany 23 * 24 * Copyright (C) 2009-2013 jointly by the following organizations: 25 * 1. California Institute of Technology, Pasadena, CA, USA 26 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 27 * 28 * Copyright (C) 2006-2008 by the California Institute of Technology, 29 * Pasadena, CA, USA 30 * 31 * Copyright (C) 2002-2005 jointly by the following organizations: 32 * 1. California Institute of Technology, Pasadena, CA, USA 33 * 2. Japan Science and Technology Agency, Japan 34 * 35 * This library is free software; you can redistribute it and/or modify it 36 * under the terms of the GNU Lesser General Public License as published by 37 * the Free Software Foundation. A copy of the license agreement is provided 38 * in the file named "LICENSE.txt" included with this software distribution 39 * and also available online as http://sbml.org/software/libsbml/license.html 40 * ------------------------------------------------------------------------ --> 41 * 42 * @class SBMLConverter 43 * @sbmlbrief{core} Base class for SBML converters. 44 * 45 * @htmlinclude libsbml-facility-only-warning.html 46 * 47 * The SBMLConverter class is the base class for the various SBML @em 48 * converters: classes of objects that transform or convert SBML documents. 49 * These transformations can involve essentially anything that can be written 50 * algorithmically; examples include converting the units of measurement in a 51 * model, or converting from one Level+Version combination of SBML to 52 * another. Applications can also create their own converters by subclassing 53 * SBMLConverter and following the examples of the existing converters. 54 * 55 * @copydetails doc_section_using_sbml_converters 56 */ 57 58 #ifndef SBMLConverter_h 59 #define SBMLConverter_h 60 61 #include <string> 62 63 #include <sbml/SBMLNamespaces.h> 64 #include <sbml/conversion/ConversionProperties.h> 65 66 #ifndef LIBSBML_USE_STRICT_INCLUDES 67 #include <sbml/SBMLTypes.h> 68 #endif 69 70 #ifdef __cplusplus 71 72 73 LIBSBML_CPP_NAMESPACE_BEGIN 74 75 76 class LIBSBML_EXTERN SBMLConverter 77 { 78 public: 79 80 /** 81 * Creates a new SBMLConverter object. 82 */ 83 SBMLConverter (); 84 85 86 /** 87 * Creates a new SBMLConverter object with a given name. 88 * 89 * @param name the name for the converter to create. 90 */ 91 SBMLConverter (const std::string& name); 92 93 94 /** 95 * Copy constructor. 96 * 97 * This creates a copy of an SBMLConverter object. 98 * 99 * @param orig the SBMLConverter object to copy. 100 */ 101 SBMLConverter(const SBMLConverter& orig); 102 103 104 /** 105 * Destroy this SBMLConverter object. 106 */ 107 virtual ~SBMLConverter (); 108 109 110 /** 111 * Assignment operator for SBMLConverter. 112 * 113 * @param rhs the object whose values are used as the basis of the 114 * assignment. 115 */ 116 SBMLConverter& operator=(const SBMLConverter& rhs); 117 118 119 /** 120 * Creates and returns a deep copy of this SBMLConverter object. 121 * 122 * @return the (deep) copy of this SBMLConverter object. 123 */ 124 virtual SBMLConverter* clone() const; 125 126 127 /** 128 * Returns the SBML document that is the subject of the conversions. 129 * 130 * @return the current SBMLDocument object. 131 */ 132 virtual SBMLDocument* getDocument(); 133 134 135 /** 136 * Returns the SBML document that is the subject of the conversions. 137 * 138 * @return the current SBMLDocument object. 139 */ 140 virtual const SBMLDocument* getDocument() const; 141 142 143 /** 144 * Returns the default properties of this converter. 145 * 146 * A given converter exposes one or more properties that can be adjusted 147 * in order to influence the behavior of the converter. This method 148 * returns the @em default property settings for this converter. It is 149 * meant to be called in order to discover all the settings for the 150 * converter object. The run-time properties of the converter object can 151 * be adjusted by using the method 152 * SBMLConverter::setProperties(const ConversionProperties *props). 153 * 154 * @return the default properties for the converter. 155 * 156 * @see setProperties(@if java ConversionProperties@endif) 157 * @see matchesProperties(@if java ConversionProperties@endif) 158 */ 159 virtual ConversionProperties getDefaultProperties() const; 160 161 162 /** 163 * Returns the target SBML namespaces of the currently set properties. 164 * 165 * SBML namespaces are used by libSBML to express the Level+Version of the 166 * SBML document (and, possibly, any SBML Level 3 packages in 167 * use). Some converters' behavior is affected by the SBML namespace 168 * configured in the converter. For example, in SBMLLevelVersionConverter 169 * (the converter for converting SBML documents from one Level+Version 170 * combination to another), the actions are fundamentally dependent on the 171 * SBML namespaces targeted. 172 * 173 * @return the SBMLNamespaces object that describes the SBML namespaces 174 * in effect, or @c NULL if none are set. 175 */ 176 virtual SBMLNamespaces* getTargetNamespaces(); 177 178 179 /** 180 * Returns @c true if this converter matches the given properties. 181 * 182 * Given a ConversionProperties object @p props, this method checks that @p 183 * props possesses an option value to enable this converter. If it does, 184 * this method returns @c true. 185 * 186 * @param props the properties to match. 187 * 188 * @return @c true if the properties @p props would match the necessary 189 * properties for this type of converter, @c false otherwise. 190 */ 191 virtual bool matchesProperties(const ConversionProperties &props) const; 192 193 194 /** 195 * Sets the SBML document to be converted. 196 * 197 * @param doc the document to use for this conversion. 198 * 199 * @return integer value indicating the success/failure of the operation. 200 * @if clike The value is drawn from the enumeration 201 * #OperationReturnValues_t. @endif@~ The set of possible values that may 202 * be returned ultimately depends on the specific subclass of 203 * SBMLConverter being used, but the default method can return the 204 * following: 205 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 206 * 207 * @if cpp 208 * @warning Even though the argument @p doc is 'const', it is immediately 209 * cast to a non-const version, which is then usually changed by the 210 * converter upon a successful conversion. This variant of the 211 * setDocument() method is here solely to preserve backwards compatibility. 212 * @endif 213 */ 214 virtual int setDocument(const SBMLDocument* doc); 215 216 217 /** 218 * Sets the SBML document to be converted. 219 * 220 * @param doc the document to use for this conversion. 221 * 222 * @return integer value indicating the success/failure of the operation. 223 * @if clike The value is drawn from the enumeration 224 * #OperationReturnValues_t. @endif@~ The set of possible values that may 225 * be returned ultimately depends on the specific subclass of 226 * SBMLConverter being used, but the default method can return the 227 * following: 228 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 229 */ 230 virtual int setDocument(SBMLDocument* doc); 231 232 233 /** 234 * Sets the configuration properties to be used by this converter. 235 * 236 * @param props the ConversionProperties object defining the properties 237 * to set. 238 * 239 * @return integer value indicating the success/failure of the operation. 240 * @if clike The value is drawn from the enumeration 241 * #OperationReturnValues_t. @endif@~ The set of possible values that may 242 * be returned ultimately depends on the specific subclass of 243 * SBMLConverter being used, but the default method can return the 244 * following values: 245 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 246 * @li @sbmlconstant{LIBSBML_OPERATION_FAILED, OperationReturnValues_t} 247 * 248 * @see getProperties() 249 * @see matchesProperties(@if java ConversionProperties@endif) 250 */ 251 virtual int setProperties(const ConversionProperties *props); 252 253 254 /** 255 * Returns the current properties in effect for this converter. 256 * 257 * A given converter exposes one or more properties that can be adjusted 258 * in order to influence the behavior of the converter. This method 259 * returns the current properties for this converter; in other words, the 260 * settings in effect at this moment. To change the property values, you 261 * can use SBMLConverter::setProperties(const ConversionProperties *props). 262 * 263 * @return the currently set configuration properties. 264 * 265 * @see setProperties(@if java ConversionProperties@endif) 266 * @see matchesProperties(@if java ConversionProperties@endif) 267 */ 268 virtual ConversionProperties* getProperties() const; 269 270 271 /** 272 * Perform the conversion. 273 * 274 * This method causes the converter to do the actual conversion work, 275 * that is, to convert the SBMLDocument object set by 276 * SBMLConverter::setDocument(@if java const SBMLDocument@endif) and 277 * with the configuration options set by 278 * SBMLConverter::setProperties(@if java const ConversionProperties@endif). 279 * 280 * @return integer value indicating the success/failure of the operation. 281 * @if clike The value is drawn from the enumeration 282 * #OperationReturnValues_t. @endif@~ The set of possible values that may 283 * be returned depends on the converter subclass; please consult 284 * the documentation for the relevant class to find out what the 285 * possibilities are. 286 */ 287 virtual int convert(); 288 289 290 /** 291 * Returns the name of this converter. 292 * 293 * @return a string, the name of this converter. 294 */ 295 const std::string& getName() const; 296 297 298 protected: 299 /** @cond doxygenLibsbmlInternal */ 300 SBMLDocument * mDocument; 301 ConversionProperties *mProps; 302 std::string mName; 303 304 friend class SBMLDocument; 305 /** @endcond */ 306 307 private: 308 /** @cond doxygenLibsbmlInternal */ 309 /** @endcond */ 310 }; 311 312 LIBSBML_CPP_NAMESPACE_END 313 314 #endif /* __cplusplus */ 315 316 317 #ifndef SWIG 318 319 LIBSBML_CPP_NAMESPACE_BEGIN 320 BEGIN_C_DECLS 321 322 323 END_C_DECLS 324 LIBSBML_CPP_NAMESPACE_END 325 326 #endif /* !SWIG */ 327 #endif /* SBMLConverter_h */ 328 329