chemaxon.formats

Class MolExporter

java.lang.Object

chemaxon.formats.MolExporter

public class MolExporter
extends Object

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.

By default, in case of machines with multiple processors processing is concurrent, otherwise single-threaded. By default, the number of worker threads is the number of processors - the number of concurrent threads can be set in setThreadCount(int). Experimental feature (may change in the future!): "chemaxon.struc.Molecule" format for testing Molecule serialization. In this case processing is single-threaded.

Version:

5.3, 07/07/2009

Author:

Peter Csizmadia

Field Summary

Fields

Modifier and Type	Field and Description
static int	C_CLOSE_STREAM Close the underlying stream.
static int	C_FLUSH_STREAM Flush the output stream and force any buffered output bytes to be written out.
static MolFilter	FILTER_DIM0 Molecule filter for cleaning 0D molecules only.
static int	MULTIPLE Use this flag to produce multiple output files.
static int	TEXT Use this flag to write text files with OS dependent line separators.

Constructor Summary

Constructors

Constructor and Description
MolExporter(OutputStream out, String fmtWithOpts) Creates a molecule exporter.
MolExporter(OutputStream out, String fmtWithOpts, boolean text, String[] incFields) Creates a molecule exporter.
MolExporter(OutputStream out, String fmtWithOpts, boolean text, String[] incFields, String enc) Creates a molecule exporter.
MolExporter(OutputStream out, String fmtWithOpts, String enc) Creates a molecule exporter.
MolExporter(String fname, String fmtWithOpts) Creates a molecule exporter.
MolExporter(String fname, String fmtWithOpts, int outflags, String[] incFields, String enc) Creates a molecule exporter.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Closes the MolExportModule and the underlying stream.
void	close(int opts) Closes the MolExportModule and, optionally, the underlying stream.
static String	convertToString(MDocument document, String fmt, int flags) Converts the document to text format.
static byte[]	exportToBinFormat(MDocument document, String fmt) Creates a binary representation of the document.
static byte[]	exportToBinFormat(Molecule molecule, String fmt) Creates a binary representation of the molecule.
static String	exportToFormat(MDocument document, String fmt) Creates a string representation of the document.
static String	exportToFormat(Molecule molecule, String fmt) Creates a string representation of the molecule.
static Object	exportToObject(MDocument document, String fmt) Creates a String, byte[] array or Image representation of the document.
static Object	exportToObject(Molecule[] mols, String fmt, MolExportModule cv) Creates a String, byte[] array or Image representation of the given molecules.
static Object	exportToObject(Molecule molecule, String fmt) Creates a String, byte[] array or Image representation of the molecule.
protected void	finalize()
void	flush() Flushes the output stream and forces any buffered output bytes to be written out.
String	getFormat() Gets the output file format.
boolean	isCleanable() Tests whether cleaning is meaningful for the chosen output format.
void	setClean(int cleanDim, String cleanOpts) Sets molecule cleaning in exporter.
void	setClean(int cleanDim, String cleanOpts, MolFilter cleanFilter) Sets molecule cleaning in exporter.
void	setErrorProcessor(ErrorProcessor errorProcessor) Sets the error handler interface for concurrent mode.
void	setThreadCount(int threadCount) Sets the number of threads for concurrent processing.
boolean	write(Molecule m) Writes a molecule into the stream.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TEXT

public static final int TEXT

Use this flag to write text files with OS dependent line separators. If not specified, then LF ('\n') is used as in Unix.

Since:

Marvin 5.2.2, 04/20/2009

See Also:

MolExporter(String, String, int, String[], String), Constant Field Values

MULTIPLE

public static final int MULTIPLE

Use this flag to produce multiple output files.

Since:

Marvin 5.2.2, 04/20/2009

See Also:

MolExporter(String, String, int, String[], String), Constant Field Values

C_CLOSE_STREAM

public static final int C_CLOSE_STREAM

Close the underlying stream.

Since:

Marvin 5.1.1, 08/17/2008

See Also:

close(int), Constant Field Values

C_FLUSH_STREAM

public static final int C_FLUSH_STREAM

Flush the output stream and force any buffered output bytes to be written out.

Since:

Marvin 5.1.1, 08/17/2008

See Also:

close(int), Constant Field Values

FILTER_DIM0

public static final MolFilter FILTER_DIM0

Molecule filter for cleaning 0D molecules only.

See Also:

setClean(int, java.lang.String, chemaxon.util.MolFilter)

Constructor Detail

MolExporter

public MolExporter(String fname,
           String fmtWithOpts,
           int outflags,
           String[] incFields,
           String enc)
            throws MolExportException,
                   IOException,
                   IllegalArgumentException

Creates a molecule exporter.

Parameters:

fname - the output filename

fmtWithOpts - the output file format and the options

outflags - output flags, it can be a combination of TEXT and MULTIPLE

incFields - SDF fields to include in table or null

enc - charset name or null

Throws:

MolExportException - export error occured

IOException - output error occurred when writing the header

IllegalArgumentException - Invalid format string (fmtWithOpts).

IllegalCharsetNameException - if the encoding is illegal

UnsupportedCharsetException - if the encoding is unsupported

Since:

Marvin 5.2.2, 04/20/2009

MolExporter

public MolExporter(String fname,
           String fmtWithOpts)
            throws IOException,
                   IllegalArgumentException

Creates a molecule exporter.

Parameters:

fname - the output filename with extension

fmtWithOpts - the output file format and the options

Throws:

MolExportException - export error occurred

IOException - output error occurred when writing the header

IllegalArgumentException - Invalid format string (fmtWithOpts).

IllegalCharsetNameException - if the encoding is illegal

UnsupportedCharsetException - if the encoding is unsupported

Since:

Marvin 5.4.1, 01/10/2010

MolExporter

public MolExporter(OutputStream out,
           String fmtWithOpts,
           boolean text,
           String[] incFields,
           String enc)
            throws MolExportException,
                   IOException,
                   IllegalArgumentException

Creates a molecule exporter.

Parameters:

out - the output stream

fmtWithOpts - the output file format and the options

text - write OS dependent line.separators instead of '\n'

incFields - SDF fields to include in table or null

enc - charset name or null

Throws:

MolExportException - export error occured

IOException - output error occurred when writing the header

IllegalArgumentException - Invalid format string (fmtWithOpts).

IllegalCharsetNameException - if the encoding is illegal

UnsupportedCharsetException - if the encoding is unsupported

MolExporter

public MolExporter(OutputStream out,
           String fmtWithOpts)
            throws IOException,
                   IllegalArgumentException

Creates a molecule exporter.

Parameters:

out - the output stream

fmtWithOpts - the output file format and the options

Throws:

MolExportException - export error occured

IOException - output error occurred when writing the header

IllegalArgumentException - Invalid format string (fmtWithOpts).

IllegalCharsetNameException - if the encoding is illegal

UnsupportedCharsetException - if the encoding is unsupported

MolExporter

public MolExporter(OutputStream out,
           String fmtWithOpts,
           boolean text,
           String[] incFields)
            throws MolExportException,
                   IOException,
                   IllegalArgumentException

Creates a molecule exporter.

Parameters:

out - the output stream

fmtWithOpts - the output file format and the options

text - write OS dependent line.separators instead of '\n'

incFields - SDF fields to include in table or null

Throws:

MolExportException - export error occured

IOException - output error occurred when writing the header

IllegalArgumentException - Invalid format string (fmtWithOpts).

IllegalCharsetNameException - if the encoding is illegal

UnsupportedCharsetException - if the encoding is unsupported

MolExporter

public MolExporter(OutputStream out,
           String fmtWithOpts,
           String enc)
            throws IOException,
                   IllegalArgumentException

Creates a molecule exporter.

Parameters:

out - the output stream

fmtWithOpts - the output file format and the options

enc - charset name or null

Throws:

MolExportException - export error occured

IOException - output error occurred when writing the header

IllegalArgumentException - Invalid format string (fmtWithOpts).

IllegalCharsetNameException - if the encoding is illegal

UnsupportedCharsetException - if the encoding is unsupported

Method Detail

setThreadCount

public void setThreadCount(int threadCount)
                    throws IllegalStateException

Sets the number of threads for concurrent processing. Default: the number of CPUs, single-threaded processing if there is 1 CPU.

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:

setThreadCount(int)

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:

setThreadCount(int)

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:

setThreadCount(int)

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 MolExportException,
                     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 MolExportException,
                  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.

Throws:

MolExportException - on export error.

IOException - in case of any other I/O error.

close

public void close(int opts)
           throws MolExportException,
                  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 MolExportException,
                  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

finalize

protected void finalize()
                 throws MolExportException,
                        IOException

Overrides:

finalize in class Object

Throws:

MolExportException

IOException

exportToObject

public static Object exportToObject(MDocument document,
                    String fmt)
                             throws IOException

Creates a String, byte[] array 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[] d3 = (byte[])MolExporter.exportToObject(document, "png:w300,h300,b32,#00ffff00");
 byte[] d4 = (byte[])MolExporter.exportToObject(document, "jpeg:w300,h300,Q95,#ffff00,spacefill");
 

Parameters:

document - the document to export

fmt - the format descriptor string

Returns:

a String, a byte[] array or an Image

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(chemaxon.struc.MDocument, java.lang.String), exportToBinFormat(chemaxon.struc.MDocument, java.lang.String)

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 final 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:

 s1 = MolExporter.exportToFormat(document, "mol");
 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(chemaxon.struc.MDocument, java.lang.String), exportToObject(chemaxon.struc.MDocument, java.lang.String)

exportToBinFormat

public static final 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 (jpeg, msbmp, png). 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(chemaxon.struc.MDocument, java.lang.String), exportToObject(chemaxon.struc.MDocument, java.lang.String)

exportToFormat

public static final 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. Examples:

 s1 = MolExporter.exportToFormat(molecule, "mol");
 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

exportToBinFormat

public static final 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 (jpeg, msbmp, png). 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(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

exportToObject

public static Object exportToObject(Molecule molecule,
                    String fmt)
                             throws IOException

Creates a String, byte[] array 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. 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[] d3 = (byte[])MolExporter.exportToObject(molecule, "png:w300,h300,b32,#00ffff00");
 byte[] d4 = (byte[])MolExporter.exportToObject(molecule, "jpeg:w300,h300,Q95,#ffff00,spacefill");
 

Parameters:

molecule - the molecule to export

fmt - the format descriptor string

Returns:

a String, a byte[] array or an Image

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

exportToObject

public static Object exportToObject(Molecule[] mols,
                    String fmt,
                    MolExportModule cv)
                             throws IOException

Creates a String, byte[] array 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, a byte[] array or an Image

Throws:

IOException - export error

See Also:

exportToObject(Molecule, String)