Package org.jmol.api

Class JmolAdapter

java.lang.Object
org.jmol.api.JmolAdapter
Direct Known Subclasses:
SmarterJmolAdapter

public abstract class JmolAdapter extends Object
The JmolAdapter interface defines the API used by the JmolViewer to read external files and fetch atom properties necessary for rendering. A client of the JmolViewer implements this interface on top of their existing molecular model representation. The JmolViewer then requests information from the implementation using this API. Jmol will automatically calculate some atom properties if the client is not capable or does not want to supply them. Note: If you are seeing pink atoms that have lots of bonds, then your methods for getElementNumber(clientAtom) or getElementSymbol(clientAtom) are probably returning stray values. Therefore, these atoms are getting mapped to element 0 (Xx), which has color pink and a relatively large covalent bonding radius.
See Also:
  • Field Details

  • Constructor Details

    • JmolAdapter

      public JmolAdapter()
  • Method Details

    • getElementSymbol

      public static String getElementSymbol(int elementNumber)
    • getElementNumber

      public static int getElementNumber(String elementSymbol)
    • getNaturalIsotope

      public static int getNaturalIsotope(int elementNumber)
    • getBondingRadius

      public static float getBondingRadius(int atomicNumberWithIsotope, int charge)
    • getAtomSetCollectionReader

      public abstract Object getAtomSetCollectionReader(String name, String type, Object bufferedReader, Map<String,Object> htParams)
      Read an atomSetCollection object from a bufferedReader and close the reader.

      Given the BufferedReader, return an object which represents the file contents. The parameter name is assumed to be the file name or URL which is the source of reader. Note that this 'file' may have been automatically decompressed. Also note that the name may be 'String', representing a string constant. Therefore, few assumptions should be made about the name parameter. The return value is an object which represents a atomSetCollection. This atomSetCollection will be passed back in to other methods. If the return value is instanceof String then it is considered an error condition and the returned String is the error message.

      Parameters:
      name - File name, String or URL acting as the source of the reader
      type - File type, if known, or null
      bufferedReader - The BufferedReader
      htParams - a hash table containing parameter information
      Returns:
      The atomSetCollection or String with an error message
    • getAtomSetCollection

      public abstract Object getAtomSetCollection(Object atomSetCollectionReader)
    • getAtomSetCollectionReaders

      public abstract Object getAtomSetCollectionReaders(JmolFilesReaderInterface fileReader, String[] names, String[] types, Map<String,Object> htParams, boolean getReadersOnly)
      Associate an atomSetCollection object with an array of BufferedReader.

      Given the array of BufferedReader, return an object which represents the concatenation of every file contents. The parameter name is assumed to be the file names or URL which are the source of each reader. Note that each of this 'file' may have been automatically decompressed. Also note that the name may be 'String', representing a string constant. Therefore, few assumptions should be made about the name parameter. The return value is an object which represents a atomSetCollection. This atomSetCollection will be passed back in to other methods. If the return value is instanceof String then it is considered an error condition and the returned String is the error message.

      Parameters:
      fileReader - the thread requesting a set of files if bufferedReaders is null
      names - File names, String or URL acting as the source of each reader
      types - File types, if known, or null
      htParams - The input parameters for each file to load
      getReadersOnly -
      Returns:
      The atomSetCollection or String with an error message
    • getAtomSetCollectionFromSet

      public abstract Object getAtomSetCollectionFromSet(Object readers, Object atomSets, Map<String,Object> htParams)
    • getAtomSetCollectionFromReader

      public abstract Object getAtomSetCollectionFromReader(String fname, Object reader, Map<String,Object> htParams) throws Exception
      Throws:
      Exception
    • getAtomSetCollectionFromReaderType

      public Object getAtomSetCollectionFromReaderType(String name, String type, Object bufferedReader, Map<String,Object> htParams)
      all in one -- for TestSmarterJmolAdapter
      Parameters:
      name -
      type -
      bufferedReader -
      htParams -
      Returns:
      AtomSetCollection or error string
    • openBufferedReader

      public Object openBufferedReader(String name, BufferedReader bufferedReader)
    • openBufferedReader

      public Object openBufferedReader(String name, BufferedReader bufferedReader, Map<String,Object> htParams)
    • openBufferedReader

      public Object openBufferedReader(String name, String type, BufferedReader bufferedReader)
    • getAtomSetCollectionFromDOM

      public abstract Object getAtomSetCollectionFromDOM(Object DOMNode, Map<String,Object> htParams)
    • finish

      public abstract void finish(Object atomSetCollection)
      Parameters:
      atomSetCollection -
    • getFileTypeName

      public abstract String getFileTypeName(Object atomSetCollection)
      Get the type of this file or molecular model, if known.
      Parameters:
      atomSetCollection - The client file
      Returns:
      The type of this file or molecular model, default "unknown"
    • getAtomSetCollectionName

      public abstract String getAtomSetCollectionName(Object atomSetCollection)
      Get the name of the atom set collection, if known.

      Some file formats contain a formal name of the molecule in the file. If this method returns null then the JmolViewer will automatically supply the file/URL name as a default.

      Parameters:
      atomSetCollection -
      Returns:
      The atom set collection name or null
    • getAtomSetCollectionAuxiliaryInfo

      public abstract Map<String,Object> getAtomSetCollectionAuxiliaryInfo(Object atomSetCollection)
      Get the auxiliary information for this atomSetCollection.

      Via the smarterJmolAdapter

      Parameters:
      atomSetCollection - The client file
      Returns:
      The auxiliaryInfo Hashtable that may be available for particular filetypes for this atomSetCollection or null
    • getAtomSetCount

      public abstract int getAtomSetCount(Object atomSetCollection)
      Get number of atomSets in the file.

      NOTE WARNING:
      Not yet implemented everywhere, it is in the smarterJmolAdapter

      Parameters:
      atomSetCollection - The client file
      Returns:
      The number of atomSets in the file
    • getAtomSetNumber

      public abstract int getAtomSetNumber(Object atomSetCollection, int atomSetIndex)
      Get the number identifying each atomSet.

      For a PDB file, this is is the model number. For others it is a 1-based atomSet number.

      Note that this is not currently implemented in PdbReader

      Parameters:
      atomSetCollection - The client file
      atomSetIndex - The atom set's index for which to get the atom set number
      Returns:
      The number identifying each atom set.
    • getAtomSetName

      public abstract String getAtomSetName(Object atomSetCollection, int atomSetIndex)
      Get the name of an atomSet.
      Parameters:
      atomSetCollection - The client file
      atomSetIndex - The atom set index
      Returns:
      The name of the atom set, default the string representation of atomSetIndex
    • getAtomSetAuxiliaryInfo

      public abstract Map<String,Object> getAtomSetAuxiliaryInfo(Object atomSetCollection, int atomSetIndex)
      Get the auxiliary information for a particular atomSet.

      Via the smarterJmolAdapter

      Parameters:
      atomSetCollection - The client file
      atomSetIndex - The atom set index
      Returns:
      The auxiliaryInfo Hashtable that may be available for particular filetypes for this atomSet or null
    • getAtomCount

      public abstract int getAtomCount(Object atomSetCollection)
      Get the estimated number of atoms contained in the file.

      Just return -1 if you don't know (or don't want to figure it out)

      Parameters:
      atomSetCollection - The client file
      Returns:
      The estimated number of atoms in the file
    • getHydrogenAtomCount

      public abstract int getHydrogenAtomCount(Object atomSetCollection)
      Get the hydrogen atom count -- for ligand files
      Parameters:
      atomSetCollection -
      Returns:
      number of hydrogen atoms in this model
    • getBondList

      public abstract String[][] getBondList(Object atomSetCollection)
      Parameters:
      atomSetCollection -
      Returns:
      [ [atomName1 atomName2 order] ...]
    • coordinatesAreFractional

      public abstract boolean coordinatesAreFractional(Object atomSetCollection)
      Get the boolean whether coordinates are fractional.
      Parameters:
      atomSetCollection - The client file
      Returns:
      true if the coordinates are fractional, default false
    • getAtomIterator

      public abstract JmolAdapterAtomIterator getAtomIterator(Object atomSetCollection)
      Get an AtomIterator for retrieval of all atoms in the file.

      This method may not return null.

      Parameters:
      atomSetCollection - The client file
      Returns:
      An AtomIterator
      See Also:
    • getBondIterator

      public abstract JmolAdapterBondIterator getBondIterator(Object atomSetCollection)
      Get a BondIterator for retrieval of all bonds in the file.

      If this method returns null and no bonds are defined then the JmolViewer will automatically apply its rebonding code to build bonds between atoms.

      Parameters:
      atomSetCollection - The client file
      Returns:
      A BondIterator or null
      See Also:
    • getStructureIterator

      public abstract JmolAdapterStructureIterator getStructureIterator(Object atomSetCollection)
      Get a StructureIterator.
      Parameters:
      atomSetCollection - The client file
      Returns:
      A StructureIterator or null
    • canonizeAlphaDigit

      private static final char canonizeAlphaDigit(char ch)
    • canonizeInsertionCode

      public static final char canonizeInsertionCode(char insertionCode)
    • canonizeAlternateLocationID

      public static final char canonizeAlternateLocationID(char altLoc)