001    /*
002     * Copyright (c) 1998-2014 ChemAxon Ltd. All Rights Reserved.
003     *
004     * This software is the confidential and proprietary information of
005     * ChemAxon. You shall not disclose such Confidential Information
006     * and shall use it only in accordance with the terms of the agreements
007     * you entered into with ChemAxon.
008     *
009     */
010    
011    package com.chemaxon.overlap.io;
012    
013    import chemaxon.formats.MolFormatException;
014    import chemaxon.formats.MolImporter;
015    import chemaxon.marvin.io.MRecord;
016    import chemaxon.struc.Molecule;
017    import com.google.common.annotations.Beta;
018    import com.google.common.base.Optional;
019    
020    /**
021     * Wraps an imported molecule.
022     *
023     * <p>This intermediate wrapper supplies read molecules from {@link MRecordReader} and {@link MolImporter} based
024     * implementations.</p>
025     *
026     * <p>Thread safety: a single record instance is not thread safe, however method {@link #parseMolecule()} of multiple
027     * instances resulting from the same source can accessed on different threads.</p>
028     *
029     * <p>Please note that this interface is marked with {@link Beta} annotation, so it can be subject of incompatible
030     * changes or removal in later releases.</p>
031     *
032     * @author Gabor Imre
033     */
034    @Beta
035    public interface StructureRecord {
036    
037        /**
038         * Represented structure/record index.
039         *
040         * <p>0-based index of the structure in the structure file.</p>
041         *
042         * @return 0-based represented record index
043         */
044        int getReadIndex();
045    
046        /**
047         * Structure source if applicable.
048         *
049         * <p>Structure source when returned by {@link MRecord#getMolString()} or otherwise applicable.</p>
050         *
051         * @return Structure source if available
052         */
053        Optional<String> getStructureSource();
054    
055        /**
056         * Parse molecule if not parsed successfully already.
057         *
058         * @return  Parsed molecule
059         *
060         * @throws MolFormatException re-thrown parse exception
061         */
062        Molecule parseMolecule() throws MolFormatException;
063    
064    }