001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 3.0.8 004 * 005 * Do not make changes to this file unless you know what you are doing--modify 006 * the SWIG interface file instead. 007 * ----------------------------------------------------------------------------- */ 008 009package org.sbml.libsbml; 010 011/** 012 * Converter for replacing object identifiers. 013 <p> 014 * <p style='color: #777; font-style: italic'> 015This class of objects is defined by libSBML only and has no direct 016equivalent in terms of SBML components. It is a class used in 017the implementation of extra functionality provided by libSBML. 018</p> 019 020 <p> 021 * This converter translates all instances of a given identifier (i.e., SBML object 'id' 022 * attribute value) of type 'SId' in a {@link Model} to another identifier. It does this based on a list of source 023 * identifiers, translating each one to its corresponding replacement value 024 * in a list of replacement identifiers. It also updates all references to 025 * the identifiers so replaced. (More technically, it replaces all values 026 * known as type <code>SIdRef</code> in the SBML Level 3 specifications.) 027 <p> 028 * This converter only searches the global SId namespace for the {@link Model} child of the 029 * {@link SBMLDocument}. It does not replace any IDs or SIdRefs for LocalParameters, nor 030 * does it replace any UnitSIds or UnitSIdRefs. It likewise does not replace any IDs 031 * in a new namespace introduced by a package, such as the PortSId namespace 032 * from the Hierarchical Model Composition package, nor any {@link Model} objects that are 033 * not the direct child of the {@link SBMLDocument}, such as the ModelDefinitions from 034 * the Hierarchical Model Composition package. 035 <p> 036 * If, however, a package introduces a new element with an 'id' attribute 037 * of type SId, any attribute of type SIdRef, or child of type SIdRef (such as 038 * a new Math child of a package element), those IDs will be replaced if they 039 * match a source identifier. 040 <p> 041 * <h2>Configuration and use of {@link SBMLIdConverter}</h2> 042 <p> 043 * {@link SBMLIdConverter} is enabled by creating a {@link ConversionProperties} object with 044 * the option <code>'renameSIds'</code>, and passing this properties object to 045 * {@link SBMLDocument#convert(ConversionProperties)}. 046 * The converter accepts two options, and both must 047 * be set or else no conversion is performed: 048 <p> 049 * <ul> 050 * <li> <code>'currentIds':</code> A comma-separated list of identifiers to replace. 051 * <li> <code>'newIds':</code> A comma-separated list of identifiers to use as the 052 * replacements. The values should correspond one-to-one with the identifiers 053 * in <code>'currentIds'</code> that should be replaced. 054 * 055 * </ul> <p> 056 * <p> 057 * <h2>General information about the use of SBML converters</h2> 058 <p> 059 * The use of all the converters follows a similar approach. First, one 060 * creates a {@link ConversionProperties} object and calls 061 * {@link ConversionProperties#addOption(ConversionOption)} 062 * on this object with one arguments: a text string that identifies the desired 063 * converter. (The text string is specific to each converter; consult the 064 * documentation for a given converter to find out how it should be enabled.) 065 <p> 066 * Next, for some converters, the caller can optionally set some 067 * converter-specific properties using additional calls to 068 * {@link ConversionProperties#addOption(ConversionOption)}. 069 * Many converters provide the ability to 070 * configure their behavior to some extent; this is realized through the use 071 * of properties that offer different options. The default property values 072 * for each converter can be interrogated using the method 073 * {@link SBMLConverter#getDefaultProperties()} on the converter class in question . 074 <p> 075 * Finally, the caller should invoke the method 076 * {@link SBMLDocument#convert(ConversionProperties)} 077 * with the {@link ConversionProperties} object as an argument. 078 <p> 079 * <h3>Example of invoking an SBML converter</h3> 080 <p> 081 * The following code fragment illustrates an example using 082 * {@link SBMLReactionConverter}, which is invoked using the option string 083 * <code>'replaceReactions':</code> 084 <p> 085<pre class='fragment'> 086{@link ConversionProperties} props = new {@link ConversionProperties}(); 087if (props != null) { 088 props.addOption('replaceReactions'); 089} else { 090 // Deal with error. 091} 092</pre> 093<p> 094 * In the case of {@link SBMLReactionConverter}, there are no options to affect 095 * its behavior, so the next step is simply to invoke the converter on 096 * an {@link SBMLDocument} object. Continuing the example code: 097 <p> 098<pre class='fragment'> 099 // Assume that the variable 'document' has been set to an {@link SBMLDocument} object. 100 status = document.convert(config); 101 if (status != libsbml.LIBSBML_OPERATION_SUCCESS) 102 { 103 // Handle error somehow. 104 System.out.println('Error: conversion failed due to the following:'); 105 document.printErrors(); 106 } 107</pre> 108<p> 109 * Here is an example of using a converter that offers an option. The 110 * following code invokes {@link SBMLStripPackageConverter} to remove the 111 * SBML Level 3 <em>Layout</em> package from a model. It sets the name 112 * of the package to be removed by adding a value for the option named 113 * <code>'package'</code> defined by that converter: 114 <p> 115<pre class='fragment'> 116{@link ConversionProperties} config = new {@link ConversionProperties}(); 117if (config != None) { 118 config.addOption('stripPackage'); 119 config.addOption('package', 'layout'); 120 status = document.convert(config); 121 if (status != LIBSBML_OPERATION_SUCCESS) { 122 // Handle error somehow. 123 System.out.println('Error: unable to strip the {@link Layout} package'); 124 document.printErrors(); 125 } 126} else { 127 // Handle error somehow. 128 System.out.println('Error: unable to create {@link ConversionProperties} object'); 129} 130</pre> 131<p> 132 * <h3>Available SBML converters in libSBML</h3> 133 <p> 134 * LibSBML provides a number of built-in converters; by convention, their 135 * names end in <em>Converter</em>. The following are the built-in converters 136 * provided by libSBML 5.12.0 137: 138 <p> 139 * <p> 140 * <ul> 141 * <li> {@link CobraToFbcConverter} 142 * <li> {@link CompFlatteningConverter} 143 * <li> {@link FbcToCobraConverter} 144 * <li> {@link FbcV1ToV2Converter} 145 * <li> {@link FbcV2ToV1Converter} 146 * <li> {@link SBMLFunctionDefinitionConverter} 147 * <li> {@link SBMLIdConverter} 148 * <li> {@link SBMLInferUnitsConverter} 149 * <li> {@link SBMLInitialAssignmentConverter} 150 * <li> {@link SBMLLevel1Version1Converter} 151 * <li> {@link SBMLLevelVersionConverter} 152 * <li> {@link SBMLLocalParameterConverter} 153 * <li> {@link SBMLReactionConverter} 154 * <li> {@link SBMLRuleConverter} 155 * <li> {@link SBMLStripPackageConverter} 156 * <li> {@link SBMLUnitsConverter} 157 * 158 * </ul> 159 */ 160 161public class SBMLIdConverter extends SBMLConverter { 162 private long swigCPtr; 163 164 protected SBMLIdConverter(long cPtr, boolean cMemoryOwn) 165 { 166 super(libsbmlJNI.SBMLIdConverter_SWIGUpcast(cPtr), cMemoryOwn); 167 swigCPtr = cPtr; 168 } 169 170 protected static long getCPtr(SBMLIdConverter obj) 171 { 172 return (obj == null) ? 0 : obj.swigCPtr; 173 } 174 175 protected static long getCPtrAndDisown (SBMLIdConverter obj) 176 { 177 long ptr = 0; 178 179 if (obj != null) 180 { 181 ptr = obj.swigCPtr; 182 obj.swigCMemOwn = false; 183 } 184 185 return ptr; 186 } 187 188 protected void finalize() { 189 delete(); 190 } 191 192 public synchronized void delete() { 193 if (swigCPtr != 0) { 194 if (swigCMemOwn) { 195 swigCMemOwn = false; 196 libsbmlJNI.delete_SBMLIdConverter(swigCPtr); 197 } 198 swigCPtr = 0; 199 } 200 super.delete(); 201 } 202 203 204/** * @internal */ public 205 static void init() { 206 libsbmlJNI.SBMLIdConverter_init(); 207 } 208 209 210/** 211 * Creates a new {@link SBMLIdConverter} object. 212 */ public 213 SBMLIdConverter() { 214 this(libsbmlJNI.new_SBMLIdConverter__SWIG_0(), true); 215 } 216 217 218/** 219 * Copy constructor; creates a copy of an {@link SBMLIdConverter} 220 * object. 221 <p> 222 * @param obj the {@link SBMLIdConverter} object to copy. 223 */ public 224 SBMLIdConverter(SBMLIdConverter obj) { 225 this(libsbmlJNI.new_SBMLIdConverter__SWIG_1(SBMLIdConverter.getCPtr(obj), obj), true); 226 } 227 228 229/** 230 * Creates and returns a deep copy of this {@link SBMLIdConverter} 231 * object. 232 <p> 233 * @return a (deep) copy of this converter. 234 */ public 235 SBMLConverter cloneObject() { 236 long cPtr = libsbmlJNI.SBMLIdConverter_cloneObject(swigCPtr, this); 237 return (cPtr == 0) ? null : new SBMLIdConverter(cPtr, true); 238 } 239 240 241/** 242 * Returns <code>true</code> if this converter object's properties match the given 243 * properties. 244 <p> 245 * A typical use of this method involves creating a {@link ConversionProperties} 246 * object, setting the options desired, and then calling this method on 247 * an {@link SBMLIdConverter} object to find out if the object's 248 * property values match the given ones. This method is also used by 249 * {@link SBMLConverterRegistry#getConverterFor(ConversionProperties)} 250 * to search across all registered converters for one matching particular 251 * properties. 252 <p> 253 * @param props the properties to match. 254 <p> 255 * @return <code>true</code> if this converter's properties match, <code>false</code> 256 * otherwise. 257 */ public 258 boolean matchesProperties(ConversionProperties props) { 259 return libsbmlJNI.SBMLIdConverter_matchesProperties(swigCPtr, this, ConversionProperties.getCPtr(props), props); 260 } 261 262 263/** 264 * Perform the conversion. 265 <p> 266 * This method causes the converter to do the actual conversion work, 267 * that is, to convert the {@link SBMLDocument} object set by 268 * {@link SBMLConverter#setDocument(SBMLDocument)} and 269 * with the configuration options set by 270 * {@link SBMLConverter#setProperties(ConversionProperties)}. 271 <p> 272 * <p> 273 * @return integer value indicating success/failure of the 274 * function. The possible values 275 * returned by this function are: 276 * <ul> 277 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 278 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 279 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT} 280 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 281 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 282 * </ul> 283 */ public 284 int convert() { 285 return libsbmlJNI.SBMLIdConverter_convert(swigCPtr, this); 286 } 287 288 289/** 290 * Returns the default properties of this converter. 291 <p> 292 * A given converter exposes one or more properties that can be adjusted 293 * in order to influence the behavior of the converter. This method 294 * returns the <em>default</em> property settings for this converter. It is 295 * meant to be called in order to discover all the settings for the 296 * converter object. 297 <p> 298 * @return the {@link ConversionProperties} object describing the default properties 299 * for this converter. 300 */ public 301 ConversionProperties getDefaultProperties() { 302 return new ConversionProperties(libsbmlJNI.SBMLIdConverter_getDefaultProperties(swigCPtr, this), true); 303 } 304 305}