Package chemaxon.formats

Class MolExporter

java.lang.Object
chemaxon.formats.MolExporter
All Implemented Interfaces:
Closeable, AutoCloseable
@PublicApi public class MolExporter extends Object implements Closeable
Molecule exporter class.

The output file format can be specified as an argument to the constructor of this class. Many different output file formats are supported like "mol", "sdf", "smiles", "png", "jpeg", etc.

The processing is single-threaded by default. Concurrent mode can be enabled using setThreadCount(int).

Experimental feature (may change in the future!): "chemaxon.struc.Molecule" format for testing Molecule serialization. In this case, processing is always single-threaded, regardless of the configured thread count.

  • Field Details

  • Constructor Details

  • Method Details

    • setThreadCount

      public void setThreadCount(int threadCount) throws IllegalStateException
      Sets the number of threads for concurrent processing. The default value is 1 (single-threaded mode).

      In concurrent mode, multiple threads are started in the background, which adds a considerable overhead to the processing, so only use this mode if the number of molecules is huge. In single-threaded mode, no background thread is used, every action is done on the caller thread.

      Parameters:
      threadCount - the number of threads, set 0 for the number of CPUs, 1 for single-threaded mode
      Throws:
      IllegalStateException - if called after call to write(chemaxon.struc.Molecule)
      Since:
      Marvin 5.3

    • setClean

      public void setClean(int cleanDim, String cleanOpts) throws IllegalStateException
      Sets molecule cleaning in exporter. Sets cleaning dimension and options. If processing is in concurrent mode, then cleaning is also performed concurrently.
      Parameters:
      cleanDim - the cleaning dimension
      cleanOpts - the cleaning options
      Throws:
      IllegalStateException - if called after call to write(chemaxon.struc.Molecule)
      Since:
      Marvin 5.3
      See Also:

    • setClean

      public void setClean(int cleanDim, String cleanOpts, MolFilter cleanFilter) throws IllegalStateException
      Sets molecule cleaning in exporter. Sets cleaning dimension and options. If processing is in concurrent mode, then cleaning is also performed concurrently.
      Parameters:
      cleanDim - the cleaning dimension
      cleanOpts - the cleaning options
      cleanFilter - the molecule filter to tell which molecule is to be cleaned, set FILTER_DIM0 to clean only 0D molecules null for no filtering (cleaning all)
      Throws:
      IllegalStateException - if called after call to write(chemaxon.struc.Molecule)
      Since:
      Marvin 5.3
      See Also:

    • setErrorProcessor

      public void setErrorProcessor(ErrorProcessor errorProcessor) throws IllegalStateException
      Sets the error handler interface for concurrent mode. By default, export is stopped on first error and this error is thrown in close() in concurrent mode. To change this, set specific ErrorProcessor implementation which can handle each error individually during the writing process and can decide whether to continue the export or not. If the export is stopped on an error then this error is always thrown in close(). In single-threaded mode export errors are thrown in write(chemaxon.struc.Molecule), separately for each molecule.
      Throws:
      IllegalStateException - if called after call to write(chemaxon.struc.Molecule)
      Since:
      Marvin 5.3
      See Also:

    • getFormat

      public String getFormat()
      Gets the output file format.
      Returns:
      the format

    • isCleanable

      public boolean isCleanable()
      Tests whether cleaning is meaningful for the chosen output format.
      Returns:
      true if cleaning is meaningful, false otherwise
      Since:
      Marvin 4.1, 02/12/2006

    • write

      public boolean write(Molecule m) throws IOException
      Writes a molecule into the stream.
      Parameters:
      m - the molecule
      Returns:
      true on success, false if Molecule is not written due to a previous error in concurrent mode - in this case, call close() which will throw the error and close the exporter
      Throws:
      MolExportException - export error
      IOException

    • close

      public void close() throws IOException
      Closes the MolExportModule and the underlying stream. IMPORTANT: call this or close(int) at the end, after the last call to write(chemaxon.struc.Molecule), because this method flushes the output stream and closes concurrent processing properly.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      MolExportException - on export error.
      IOException - in case of any other I/O error.

    • close

      public void close(int opts) throws IOException
      Closes the MolExportModule and, optionally, the underlying stream. IMPORTANT: call this or close() at the end, after the last call to write(chemaxon.struc.Molecule), because this method flushes the output stream and closes concurrent processing properly.
      Parameters:
      opts - closing options, C_CLOSE_STREAM or C_FLUSH_STREAM.
      Throws:
      MolExportException - export error.
      IOException - in case of any other I/O error.
      Since:
      Marvin 5.1.1, 08/17/2008

    • flush

      public void flush() throws IOException
      Flushes the output stream and forces any buffered output bytes to be written out.
      Throws:
      MolExportException - on export error.
      IOException - if an I/O error occurs.
      Since:
      Marvin 5.1.1, 08/15/2008

    • exportToObject

      public static Object exportToObject(MDocument document, String fmt) throws IOException
      Creates a String, byte[] or Image representation of the document. When creating an image, display options can also be specified in the format descriptor string. Format and options are separated by a colon, multiple options can be separated by commas. See the possible formats and their options on the File Formats in Marvin page.

      Examples: 

       import java.awt.Image;
 ...
 String s1 = (String) MolExporter.exportToObject(document, "mol");
 String s2 = (String) MolExporter.exportToObject(document, "smiles:a-H"); // aromatize, remove H
 Image img = (Image) MolExporter.exportToObject(document, "image:w300,h300,#ffff00");
 byte[] d1 = (byte[]) MolExporter.exportToObject(document, "png:w300,h300,b32,#00ffff00");
 byte[] d2 = (byte[]) MolExporter.exportToObject(document, "jpeg:w300,h300,Q95,#ffff00,spacefill");
      Parameters:
      document - the document to export
      fmt - the format descriptor string
      Returns:
      a String, byte[] or Image representation of the molecule in the specified format
      Throws:
      IOException - Export error.
      IllegalArgumentException - Invalid format string.
      SecurityException - Export module cannot be loaded because of security reasons (firewall).
      Since:
      Marvin 5.8, 08/25/2011
      See Also:

    • convertToString

      public static String convertToString(MDocument document, String fmt, int flags) throws IOException
      Converts the document to text format.
      Parameters:
      document - the document to convert
      fmt - the molecule file format or null
      flags - conversion options
      Returns:
      the string
      Throws:
      IOException - Export error
      Since:
      Marvin 5.8, 08/25/2011

    • exportToFormat

      public static String exportToFormat(MDocument document, String fmt) throws IOException
      Creates a string representation of the document. The format descriptor string can also contain export options. Format and options are separated by a colon, multiple options can be separated by commas. The line separator is '\n'. See the text formats and their options on the File Formats in Marvin page.

      Examples: 

       String s1 = MolExporter.exportToFormat(document, "mol");
 String s2 = MolExporter.exportToFormat(document, "smiles:a-H"); // aromatize and remove Hydrogens
      Parameters:
      document - the document to export
      fmt - the format descriptor string
      Returns:
      string representation of the document in the specified format
      Throws:
      IOException - Export error
      IllegalArgumentException - Invalid format string.
      SecurityException - Export module cannot be loaded because of security reasons (firewall).
      Since:
      Marvin 5.8, 08/25/2011
      See Also:

    • exportToBinFormat

      public static byte[] exportToBinFormat(MDocument document, String fmt) throws IOException
      Creates a binary representation of the document. Works with all the text formats that are supported by the exportToFormat method, and also with the binary image formats (png, jpeg, etc.). When creating an image, display options can also be specified in the format descriptor string. Format and options are separated by a colon, multiple options can be separated by commas. See the possible formats and their options on the File Formats in Marvin page.

      Examples: 

       byte[] d1 = MolExporter.exportToBinFormat(document, "mrv");
 byte[] d2 = MolExporter.exportToBinFormat(document, "smiles:a-H"); // aromatize and remove H
 byte[] d3 = MolExporter.exportToBinFormat(document, "png:w300,h300,b32,#00ffff00");
 byte[] d4 = MolExporter.exportToBinFormat(document, "jpeg:w300,h300,Q95,#ffff00,spacefill");
      Parameters:
      document - the document to export
      fmt - the format descriptor string
      Returns:
      a binary representation of the document in the specified format
      Throws:
      IOException - Export error.
      IllegalArgumentException - Invalid format string.
      SecurityException - Export module cannot be loaded because of security reasons (firewall).
      Since:
      Marvin 5.8, 08/25/2011
      See Also:

    • exportToFormat

      public static String exportToFormat(Molecule molecule, String fmt) throws IOException
      Creates a string representation of the molecule. The format descriptor string can also contain export options. Format and options are separated by a colon, multiple options can be separated by commas. The line separator is '\n'. See the text formats and their options on the File Formats in Marvin page.

      For a similar method that does not throw checked exceptions, see toFormat(Molecule, String).

      Examples: 

       String s1 = MolExporter.exportToFormat(molecule, "mol");
 String s2 = MolExporter.exportToFormat(molecule, "smiles:a-H"); // aromatize and remove Hydrogens
      Parameters:
      molecule - the molecule to export
      fmt - the format descriptor string
      Returns:
      string representation of the molecule in the specified format
      Throws:
      IOException - Export error.
      IllegalArgumentException - Invalid format string.
      SecurityException - Export module cannot be loaded because of security reasons (firewall).
      Since:
      Marvin 5.8, 08/25/2011
      See Also:

    • exportToBinFormat

      public static byte[] exportToBinFormat(Molecule molecule, String fmt) throws IOException
      Creates a binary representation of the molecule. Works with all the text formats that are supported by the exportToFormat method, and also with the binary image formats (png, jpeg, etc.). When creating an image, display options can also be specified in the format descriptor string. Format and options are separated by a colon, multiple options can be separated by commas. See the possible formats and their options on the File Formats in Marvin page.

      For a similar method that does not throw checked exceptions, see toBinFormat(Molecule, String).

      Examples: 

       byte[] d1 = MolExporter.exportToBinFormat(molecule, "mol");
 byte[] d2 = MolExporter.exportToBinFormat(molecule, "smiles:a-H"); // aromatize and remove H
 byte[] d3 = MolExporter.exportToBinFormat(molecule, "png:w300,h300,b32,#00ffff00");
 byte[] d4 = MolExporter.exportToBinFormat(molecule, "jpeg:w300,h300,Q95,#ffff00,spacefill");
      Parameters:
      molecule - the molecule to export
      fmt - the format descriptor string
      Returns:
      a binary representation of the molecule in the specified format
      Throws:
      IOException - Export error.
      IllegalArgumentException - Invalid format string.
      SecurityException - Export module cannot be loaded because of security reasons (firewall).
      Since:
      Marvin 5.8, 08/25/2011
      See Also:

    • exportToObject

      public static Object exportToObject(Molecule molecule, String fmt) throws IOException
      Creates a String, byte[] or Image representation of the molecule. When creating an image, display options can also be specified in the format descriptor string. Format and options are separated by a colon, multiple options can be separated by commas. See the possible formats and their options on the File Formats in Marvin page.

      For a similar method that does not throw checked exceptions, see toObject(Molecule, String).

      Examples: 

       import java.awt.Image;
 ...
 String s1 = (String) MolExporter.exportToObject(molecule, "mol");
 String s2 = (String) MolExporter.exportToObject(molecule, "smiles:a-H"); // aromatize, remove H
 Image img = (Image) MolExporter.exportToObject(molecule, "image:w300,h300,#ffff00");
 byte[] d1 = (byte[]) MolExporter.exportToObject(molecule, "png:w300,h300,b32,#00ffff00");
 byte[] d2 = (byte[]) MolExporter.exportToObject(molecule, "jpeg:w300,h300,Q95,#ffff00,spacefill");
      Parameters:
      molecule - the molecule to export
      fmt - the format descriptor string
      Returns:
      a String, byte[] or Image representation of the molecule in the specified format
      Throws:
      IOException - Export error.
      IllegalArgumentException - Invalid format string.
      SecurityException - Export module cannot be loaded because of security reasons (firewall).
      Since:
      Marvin 5.8, 08/25/2011
      See Also:

    • toFormat

      public static String toFormat(Molecule molecule, String format)
      Returns a string representation of the given molecule. The format descriptor string can also contain export options. Format and options are separated by a colon, multiple options can be separated by commas. The line separator is '\n'. See the text formats and their options on the File Formats in Marvin page.

      This method works the same way as exportToFormat(Molecule, String), with the only exception that an unchecked exception is thrown on export error.

      Examples: 

       String s1 = MolExporter.toFormat(molecule, "mol");
 String s2 = MolExporter.toFormat(molecule, "smiles:a-H"); // aromatize and remove Hydrogens
      Parameters:
      molecule - the molecule to export
      format - the format descriptor string
      Returns:
      string representation of the molecule in the specified format
      Throws:
      UncheckedIOException - on export error
      IllegalArgumentException - for invalid format string
      See Also:

    • toBinFormat

      public static byte[] toBinFormat(Molecule molecule, String format)
      Returns a binary representation of the given molecule. Works with all the text formats that are supported by the toFormat method, and also with the binary image formats (png, jpeg, etc.). When creating an image, display options can also be specified in the format descriptor string. Format and options are separated by a colon, multiple options can be separated by commas. See the possible formats and their options on the File Formats in Marvin page.

      This method works the same way as exportToBinFormat(Molecule, String), with the only exception that an unchecked exception is thrown on export error.

      Examples: 

       byte[] d1 = MolExporter.toBinFormat(molecule, "mol");
 byte[] d2 = MolExporter.toBinFormat(molecule, "smiles:a-H"); // aromatize and remove H
 byte[] d3 = MolExporter.toBinFormat(molecule, "png:w300,h300,b32,#00ffff00");
 byte[] d4 = MolExporter.toBinFormat(molecule, "jpeg:w300,h300,Q95,#ffff00,spacefill");
      Parameters:
      molecule - the molecule to export
      format - the format descriptor string
      Returns:
      a binary representation of the molecule in the specified format
      Throws:
      UncheckedIOException - on export error
      IllegalArgumentException - for invalid format string
      See Also:

    • toObject

      public static Object toObject(Molecule molecule, String format)
      Returns a String, byte[] or Image representation of the given molecule. When creating an image, display options can also be specified in the format descriptor string. Format and options are separated by a colon, multiple options can be separated by commas. See the possible formats and their options on the File Formats in Marvin page.

      This method works the same way as exportToObject(Molecule, String), with the only exception that an unchecked exception is thrown on export error.

      Examples: 

       import java.awt.Image;
 ...
 String s1 = (String) MolExporter.exportToObject(molecule, "mol");
 String s2 = (String) MolExporter.exportToObject(molecule, "smiles:a-H"); // aromatize, remove H
 Image img = (Image) MolExporter.exportToObject(molecule, "image:w300,h300,#ffff00");
 byte[] d1 = (byte[]) MolExporter.exportToObject(molecule, "png:w300,h300,b32,#00ffff00");
 byte[] d2 = (byte[]) MolExporter.exportToObject(molecule, "jpeg:w300,h300,Q95,#ffff00,spacefill");
      Parameters:
      molecule - the molecule to export
      format - the format descriptor string
      Returns:
      a String, byte[] or Image representation of the molecule in the specified format
      Throws:
      UncheckedIOException - on export error
      IllegalArgumentException - for invalid format string
      See Also:

    • exportToObject

      public static Object exportToObject(Molecule[] mols, String fmt, MolExportModule cv) throws IOException
      Creates a String, byte[] or Image representation of the given molecules.
      Parameters:
      mols - the molecules to export
      fmt - the format descriptor string
      cv - the export module
      Returns:
      a String, byte[] or Image representation of the molecules in the specified format
      Throws:
      IOException - export error
      See Also: