Iterator Factory

    The IteratorFactory class provides implementations of java.util.Iterator to ease the handling of atoms and bonds used in Molecule objects and its descendants. The IteratorFactory object always belongs to one particular Molecule object (or descendant). The following iterators are included in this class:

    • AtomIterator: The AtomIterator class provides an iterator for the atoms of the specified molecule of the factory according to the atom related behavior set in the factory.

    • BondIterator: The BondIterator class provides an iterator to process the bonds of the specified molecule in this factory according to the bond related behavior of this factory.

    • AtomNeighbourIterator: The AtomNeighbourIterator class provides an iterator to process the atoms connecting to a specified atom according to the atom and bond related behavior of the factory

    • BondNeighbourIterator: The BondNeighbourIterator class provides an iterator to process the bonds connecting to the specified atom according to the atom and bond related behavior of this factory.

    • RxnComponentIterator: The RxnComponentIterator class provides an iterator to process the reaction components (reactant, product and agent components) in the reaction molecule of the factory.

    • RgComponentIterator: The RgComponentIterator class provides an iterator to process the R-group definition components in the specified molecule of the factory.

    The above mentioned iterators are constructed by the appropriate IteratorFactory.createXXX() methods. For example an atom iterator can be constructed with the createAtomIterator() method of the iterator factory. The behavior of the iterator is determined by the parameters given in the constructor of the iterator factory. The behavior can be bond or atom related: the factory constructs consistent iterators for the specified molecule with the specified behavior.

    • atom related behavior: specifies how to iterate on atoms. The following constant values are available or their combination by the bitwise or (|) operator:

      • INCLUDE_ALL_ATOMS

      • INCLUDE_CHEMICAL_ATOMS

      • SKIP_EXPLICIT_H

      • SKIP_MULTICENTER

      • SKIP_LONE_PAIR

      • SKIP_PSEUDO_ATOM

    • bondRelatedBehavior: specifies how to iterate on bonds. The following constant values are available or their combination by the bitwise or (|) operator:

      • INCLUDE_ALL_BONDS

      • SKIP_COORDINATE_BONDS

      • SKIP_COVALENT_BONDS

    Examples

    Simple usage of an atom iterator

    
    //initialize a Molecule;
    Molecule molecule = ...;
    //create an iterator factory where the iterators skip the pseudo atom and coordinate bonds.
    IteratorFactory ifc = new IteratorFactory(molecule, IteratorFactory.SKIP_PSEUDO_ATOM | IteratorFactory.SKIP_EXPLICIT_H,
            IteratorFactory.SKIP_COORDINATE_BONDS);
    AtomIterator atomIterator = ifc.createAtomIterator();
    //iteration on the atoms of a component except the pseudo atoms.
    while (atomIterator.hasNext()){
        MolAtom atom = atomIterator.nextAtom();
        //process the atom
        ...
    }

    Complex usage of iterators

    
    //initialize an RgMolecule; 
    RgMolecule mol = ... ;
    //create the iterator factory with the specified molecule and parameters related to atoms and bonds.
    IteratorFactory factory = new IteratorFactory(mol, IteratorFactory.INCLUDE_ALL_ATOMS, IteratorFactory.INCLUDE_ALL_BONDS);
    RgComponentIterator rgIterator = factory.createRgComponentIterator();
    //iteration on the components of the RgMolecule.
    while (rgIterator.hasNext()) {
        Molecule component = rgIterator.nextComponent();
        IteratorFactory ifc = new IteratorFactory(component, IteratorFactory.SKIP_PSEUDO_ATOM | IteratorFactory.SKIP_EXPLICIT_H, 
            IteratorFactory.SKIP_COORDINATE_BONDS);
        AtomIterator atomIterator = ifc.createAtomIterator();
        //iteration on the atoms of a component
        while (atomIterator.hasNext()){
            MolAtom atom = atomIterator.nextAtom();
            //process the atom
            ...
        }
        //iteration on the bonds of a component
        BondIterator bondIterator = ifc.createBondIterator();
        while (bondIterator.hasNext()){
            MolBond bond = bondIterator.nextBond();
            //process the bond
            ...
        }
    } 

    Working code example

    Print information about atoms and bonds of molecule

    
    /* 
     * Copyright (c) 1998-2022 Chemaxon. All Rights Reserved. 
     */ 
    import java.io.IOException; 
    import chemaxon.formats.MolFormatException; 
    import chemaxon.formats.MolImporter; 
    import chemaxon.struc.Molecule; 
    import chemaxon.struc.MolAtom; 
    import chemaxon.struc.MolBond; 
    import chemaxon.util.iterator.IteratorFactory; 
    import chemaxon.util.iterator.IteratorFactory.AtomIterator; 
    import chemaxon.util.iterator.IteratorFactory.BondIterator; 
    /** 
     * Example class to demonstrate how to access atoms and bonds  
     * of the molecule using Iterators. 
     * 
     * @author Andras Volford, Miklos Vargyas 
     * 
     */  
    public class MoleculeIterators { 
    
        public static void main(String[] args) { 
    
            String filename = args[0]; 
    
            try { 
                // create a molecule importer for the given file 
                MolImporter mi = new MolImporter(filename);          
    
                // read the first molecule from the file 
                Molecule m = mi.read();              
                while (m != null) {
                     IteratorFactory itFac = new IteratorFactory(m,
                            IteratorFactory.INCLUDE_CHEMICAL_ATOMS_ONLY, 
                            IteratorFactory.REPLACE_COORDINATE_BONDS ); 
                    printAtoms(itFac,m);
                    printBonds(itFac,m);                  
    
                    // read the next molecule from the input file 
                    m = mi.read();
                 } 
                mi.close(); 
            } 
            catch (MolFormatException e) {
                 System.err.println("Molecule format not recognised.");
             } 
            catch (IOException e) { 
                System.err.println("I/O error:" + e);
             } 
        } 
    
        private static void printAtoms( IteratorFactory itFac, Molecule m ) {
             AtomIterator ai = itFac.createAtomIterator();
    
             System.out.println("Atoms in the molecule\natomic number   charge");
             while (ai.hasNext()) {
                 MolAtom a = ai.next();
                 System.out.println( a.getAtno() + "        " + a.getCharge() );
             } 
        } 
    
        private static void printBonds( IteratorFactory itFac, Molecule m ) {
             BondIterator bi = itFac.createBondIterator();
    
             System.out.println("Bonds in the molecule\nbond order  coodinate");
    
            while (bi.hasNext()) {
                 MolBond b = bi.next();
                 System.out.println( b.getType() + "        " + b.isCoordinate()
                          + " " + m.indexOf(b.getAtom1()) + "-"  
                          + m.indexOf(b.getAtom2())); 
            }       
        } 
    
    }