chemaxon.util.iterator
Class IteratorFactory

java.lang.Object
  chemaxon.util.iterator.IteratorFactory

public class IteratorFactory
extends java.lang.Object

The IteratorFactory class provides implementations of Iterator to ease the handling of atoms and bonds used in Molecule objects and its descendants. The following iterators are included in this class:

• AtomIterator
• BondIterator
• AtomNeighbourIterator
• BondNeighbourIterator
• RxnComponentIterator
• RgComponentIterator

API usage example:

      //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.next();
          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.next();
              //process the atom
              ...
          }
          //iteration on the bonds of a component
          BondIterator bondIterator = ifc.createBondIterator();
          while (bondIterator.hasNext()){
              MolBond bond = bondIterator.next();
              //process the bond
              ...
          }
      }       
      
      //the inclusion pattern of IteratorFactory can be rewritten to exclude
      //more atoms and/or bonds, for example:
      IteratorFactory factory2 = new IteratorFactory(mol, 
        IteratorFactory.INCLUDE_CHEMICAL_ATOMS_ONLY, IteratorFactory.INCLUDE_ALL_BONDS) {
          //this ensures that only chemical atoms with properties are iterated
          public boolean isExcludedAtom(MolAtom atom) {
        return (atom.propertyCount() == 0);
          }
          //the same can be done for bonds with isExcludedBond(MolBond bond)
      };
 

Since:

Marvin 5.1

Version:

5.1, 01/18/2008

Author:

Erika Biro, Peter Kovacs (pkovacs84)

See Also:

MolAtom, MolBond, Molecule, RxnMolecule, RgMolecule

Nested Class Summary

class	IteratorFactory.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.
class	IteratorFactory.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 this factory.
class	IteratorFactory.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.
class	IteratorFactory.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.
class	IteratorFactory.NeighbourIterator<E> The NeighbourIterator class provides an iterator to process the bonds connecting to the specified atom according to the atom and bond related behavior of this factory.
class	IteratorFactory.RgComponentIterator The RgComponentIterator class provides an iterator to process the rgroup definition components in the specified molecule of the factory.
class	IteratorFactory.RxnComponentIterator The RxnComponentIterator class provides an iterator to process the components (reactant, product and agent components) in the reaction molecule of the factory.

Field Summary

static int	INCLUDE_ALL_ATOMS Include all atoms: chemical atoms, explicit hydrogen, multicenter, lone pair and pseudo atoms in atom iterations.
static int	INCLUDE_ALL_BONDS Include all bonds: covalent and coordinate bonds in bond iteration.
static int	INCLUDE_CHEMICAL_ATOMS Deprecated. Replaced by INCLUDE_CHEMICAL_ATOMS_ONLY.
static int	INCLUDE_CHEMICAL_ATOMS_ONLY Include only chemical atoms in iteration, skip multicenters, lone pairs and pseudo atoms.
static int	REPLACE_COORDINATE_BONDS Replace coordinate bonds to multicenter atoms with coordinate bonds from the metal to the represented atoms (in the MulticenterSgroup of the multicenter).
static int	SKIP_COORDINATE_BONDS Exclude coordinate bonds from bond iteration.
static int	SKIP_COVALENT_BONDS Exclude covalent bonds from bond iteration.
static int	SKIP_EXPLICIT_H Exclude explicit hydrogens from atom iteration.
static int	SKIP_LONE_PAIR Exclude lone pairs from atom iteration.
static int	SKIP_MULTICENTER Exclude multicenters from atom iteration.
static int	SKIP_PSEUDO_ATOM Exclude pseudo atoms from atom iteration.

Constructor Summary

IteratorFactory(Molecule mol)
Constructs an iterator factory for the specified molecule with default atom and bond related behavior to include all atoms and bonds.

IteratorFactory(Molecule mol, int atomRelatedBehavior, int bondRelatedBehavior)
Constructs an iterator factory for the specified molecule with a specified atom and bond related behavior.

Method Summary

IteratorFactory.AtomIterator	createAtomIterator() Constructs an atom iterator for the specified molecule of the factory according to the atom related behavior set in the factory.
IteratorFactory.AtomNeighbourIterator	createAtomNeighbourIterator(MolAtom atom) Constructs an iterator to get the atom neighbours of the specified atom.
IteratorFactory.BondIterator	createBondIterator() Constructs a bond iterator for the specified molecule of the factory according to bond related behavior set in the factory.
IteratorFactory.BondNeighbourIterator	createBondNeighbourIterator(MolAtom atom) Constructs an iterator to get the bonds connecting to the specified atom.
IteratorFactory.RgComponentIterator	createRgComponentIterator() Constructs an rgroup definition component iterator for the specified molecule of the factory if the molecule is an RgMolecule, an empty iterator otherwise.
IteratorFactory.RxnComponentIterator	createRxnComponentIterator() Constructs a reaction component iterator for the specified molecule of the factory if the molecule is an RxnMolecule, an empty iterator otherwise.
boolean	isExcludedAtom(MolAtom atom) By overriding this method, the inclusion pattern of IteratorFactory can be rewritten to exclude more atoms, than it would normally.
boolean	isExcludedBond(MolBond bond) By overriding this method, the inclusion pattern of IteratorFactory can be rewritten to exclude more bonds, than it would normally.
int	numberOfAtoms() Returns the number of atoms iterated by AtomIterator.
int	numberOfBonds() Returns the number of bonds iterated by BondIterator.
int	numberOfNeighbours(MolAtom atom) Returns the number of atoms/bonds iterated by (Atom/Bond)NeighbourIterator (the two values are the same).

Methods inherited from class java.lang.Object

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

Field Detail

INCLUDE_ALL_BONDS

public static final int INCLUDE_ALL_BONDS

Include all bonds: covalent and coordinate bonds in bond iteration.

See Also:

Constant Field Values

SKIP_COORDINATE_BONDS

public static final int SKIP_COORDINATE_BONDS

Exclude coordinate bonds from bond iteration.

See Also:

Constant Field Values

SKIP_COVALENT_BONDS

public static final int SKIP_COVALENT_BONDS

Exclude covalent bonds from bond iteration.

See Also:

Constant Field Values

REPLACE_COORDINATE_BONDS

public static final int REPLACE_COORDINATE_BONDS

Replace coordinate bonds to multicenter atoms with coordinate bonds from the metal to the represented atoms (in the MulticenterSgroup of the multicenter). These secondary bonds are not added to the molecule of the factory, so do not use Molecule.indexOf for the secondary bonds!

See Also:

Constant Field Values

INCLUDE_ALL_ATOMS

public static final int INCLUDE_ALL_ATOMS

Include all atoms: chemical atoms, explicit hydrogen, multicenter, lone pair and pseudo atoms in atom iterations.

See Also:

Constant Field Values

SKIP_EXPLICIT_H

public static final int SKIP_EXPLICIT_H

Exclude explicit hydrogens from atom iteration.

See Also:

Constant Field Values

SKIP_MULTICENTER

public static final int SKIP_MULTICENTER

Exclude multicenters from atom iteration.

See Also:

Constant Field Values

SKIP_LONE_PAIR

public static final int SKIP_LONE_PAIR

Exclude lone pairs from atom iteration.

See Also:

Constant Field Values

SKIP_PSEUDO_ATOM

public static final int SKIP_PSEUDO_ATOM

Exclude pseudo atoms from atom iteration.

See Also:

Constant Field Values

INCLUDE_CHEMICAL_ATOMS

public static final int INCLUDE_CHEMICAL_ATOMS

Deprecated. Replaced by INCLUDE_CHEMICAL_ATOMS_ONLY.

Include only chemical atoms in iteration, skip multicenters, lone pairs and pseudo atoms.

See Also:

Constant Field Values

INCLUDE_CHEMICAL_ATOMS_ONLY

public static final int INCLUDE_CHEMICAL_ATOMS_ONLY

Include only chemical atoms in iteration, skip multicenters, lone pairs and pseudo atoms.

See Also:

Constant Field Values

Constructor Detail

IteratorFactory

public IteratorFactory(Molecule mol,
                       int atomRelatedBehavior,
                       int bondRelatedBehavior)

Constructs an iterator factory for the specified molecule with a specified atom and bond related behavior. Atom and bond related behavior can be set with the constants below, using the bitwise | operator (which means AND here) to combine them.

Parameters:

mol - the molecule whose atoms and bonds to be iterated.

atomRelatedBehavior - the behavior how to iterate on atoms. Specify with the constants:

• INCLUDE_ALL_ATOMS
• INCLUDE_CHEMICAL_ATOMS_ONLY
• SKIP_EXPLICIT_H
• SKIP_MULTICENTER
• SKIP_LONE_PAIR
• SKIP_PSEUDO_ATOM

bondRelatedBehavior - the behavior how to iterate on bonds. Specify with the constants:

• INCLUDE_ALL_BONDS
• SKIP_COORDINATE_BONDS
• SKIP_COVALENT_BONDS
• REPLACE_COORDINATE_BONDS

IteratorFactory

public IteratorFactory(Molecule mol)

Constructs an iterator factory for the specified molecule with default atom and bond related behavior to include all atoms and bonds.

See Also:

INCLUDE_ALL_ATOMS, INCLUDE_ALL_BONDS

Method Detail

createAtomIterator

public IteratorFactory.AtomIterator createAtomIterator()

Constructs an atom iterator for the specified molecule of the factory according to the atom related behavior set in the factory.

Returns:

the atom iterator

createBondIterator

public IteratorFactory.BondIterator createBondIterator()

Constructs a bond iterator for the specified molecule of the factory according to bond related behavior set in the factory.

Returns:

the bond iterator

createAtomNeighbourIterator

public IteratorFactory.AtomNeighbourIterator createAtomNeighbourIterator(MolAtom atom)

Constructs an iterator to get the atom neighbours of the specified atom. The following atoms are excluded:

• atoms excluded in the atom related behavior of the factory and
• atoms connecting with bonds that are excluded in the bond related behavior of the factory.

Parameters:

atom - the atom whose neighbour atoms to be iterated

Returns:

the atom neighbour iterator of the specified atom

createBondNeighbourIterator

public IteratorFactory.BondNeighbourIterator createBondNeighbourIterator(MolAtom atom)

Constructs an iterator to get the bonds connecting to the specified atom. The following bonds are excluded:

• bonds excluded in the bond related behavior of the factory and
• bonds connecting to atoms that are excluded in the atom related behavior of the factory.

Parameters:

atom - the atom whose bonds to be iterated

Returns:

the bond neighbour iterator of the specified atom

createRxnComponentIterator

public IteratorFactory.RxnComponentIterator createRxnComponentIterator()

Constructs a reaction component iterator for the specified molecule of the factory if the molecule is an RxnMolecule, an empty iterator otherwise.

Returns:

the reaction component iterator

createRgComponentIterator

public IteratorFactory.RgComponentIterator createRgComponentIterator()

Constructs an rgroup definition component iterator for the specified molecule of the factory if the molecule is an RgMolecule, an empty iterator otherwise.

Returns:

the rgroup component iterator

isExcludedAtom

public boolean isExcludedAtom(MolAtom atom)

By overriding this method, the inclusion pattern of IteratorFactory can be rewritten to exclude more atoms, than it would normally. By default, this method returns false.

Parameters:

atom - the atom to be checked

Returns:

whether the atom should be excluded

isExcludedBond

public boolean isExcludedBond(MolBond bond)

By overriding this method, the inclusion pattern of IteratorFactory can be rewritten to exclude more bonds, than it would normally. By default, this method returns false.

Parameters:

bond - the bond to be checked

Returns:

whether the bond should be excluded

numberOfAtoms

public int numberOfAtoms()

Returns the number of atoms iterated by AtomIterator. It currently works by creating an AtomIterator, and iterating through it. This might make it unsuitable for some uses, where performance is important.

Returns:

the number of atoms

numberOfBonds

public int numberOfBonds()

Returns the number of bonds iterated by BondIterator. It currently works by creating a BondIterator, and iterating through it. This might make it unsuitable for some uses, where performance is important.

Returns:

the number of bonds

numberOfNeighbours

public int numberOfNeighbours(MolAtom atom)

Returns the number of atoms/bonds iterated by (Atom/Bond)NeighbourIterator (the two values are the same). It currently works by creating a BondNeighbourIterator, and iterating through it. This might make it unsuitable for some uses, where performance is important.

Returns:

the number of neighbours