JmolAdapter
Date: 2019-10-22

org.jmol.api

## Class JmolAdapter

- java.lang.Object
- - org.jmol.api.JmolAdapter

- Direct Known Subclasses:
    SmarterJmolAdapter

      public abstract class JmolAdapter
      extends java.lang.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:
    `JmolViewer`, `SmarterJmolAdapter`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String[]` | `cellParamNames`
    `static int` | `ORDER_AROMATIC`
    `static int` | `ORDER_AROMATIC_DOUBLE`
    `static int` | `ORDER_AROMATIC_SINGLE`
    `static int` | `ORDER_COVALENT_DOUBLE`
    `static int` | `ORDER_COVALENT_HEX`
    `static int` | `ORDER_COVALENT_QUAD`
    `static int` | `ORDER_COVALENT_QUINT`
    `static int` | `ORDER_COVALENT_SINGLE`
    `static int` | `ORDER_COVALENT_TRIPLE`
    `static int` | `ORDER_HBOND`
    `static int` | `ORDER_PARTIAL01`
    `static int` | `ORDER_PARTIAL12`
    `static int` | `ORDER_PARTIAL23`
    `static int` | `ORDER_PARTIAL32`
    `static int` | `ORDER_PYMOL_MULT`
    `static int` | `ORDER_PYMOL_SINGLE`
    `static int` | `ORDER_STEREO_FAR`
    `static int` | `ORDER_STEREO_NEAR`
    `static int` | `ORDER_UNSPECIFIED`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JmolAdapter()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `private static char` | `canonizeAlphaDigit(char ch)`
    `static char` | `canonizeAlternateLocationID(char altLoc)`
    `static char` | `canonizeInsertionCode(char insertionCode)`
    `abstract boolean` | `coordinatesAreFractional(java.lang.Object atomSetCollection)` Get the boolean whether coordinates are fractional.
    `abstract void` | `finish(java.lang.Object atomSetCollection)`
    `abstract int` | `getAtomCount(java.lang.Object atomSetCollection)` Get the estimated number of atoms contained in the file.
    `abstract JmolAdapterAtomIterator` | `getAtomIterator(java.lang.Object atomSetCollection)` Get an AtomIterator for retrieval of all atoms in the file.
    `abstract java.util.Map<java.lang.String,java.lang.Object>` | `getAtomSetAuxiliaryInfo(java.lang.Object atomSetCollection, int atomSetIndex)` Get the auxiliary information for a particular atomSet.
    `abstract java.lang.Object` | `getAtomSetCollection(java.lang.Object atomSetCollectionReader)`
    `abstract java.util.Map<java.lang.String,java.lang.Object>` | `getAtomSetCollectionAuxiliaryInfo(java.lang.Object atomSetCollection)` Get the auxiliary information for this atomSetCollection.
    `abstract java.lang.Object` | `getAtomSetCollectionFromDOM(java.lang.Object DOMNode, java.util.Map<java.lang.String,java.lang.Object> htParams)`
    `abstract java.lang.Object` | `getAtomSetCollectionFromReader(java.lang.String fname, java.lang.Object reader, java.util.Map<java.lang.String,java.lang.Object> htParams)`
    `java.lang.Object` | `getAtomSetCollectionFromReaderType(java.lang.String name, java.lang.String type, java.lang.Object bufferedReader, java.util.Map<java.lang.String,java.lang.Object> htParams)` all in one -- for TestSmarterJmolAdapter
    `abstract java.lang.Object` | `getAtomSetCollectionFromSet(java.lang.Object readers, java.lang.Object atomSets, java.util.Map<java.lang.String,java.lang.Object> htParams)`
    `abstract java.lang.String` | `getAtomSetCollectionName(java.lang.Object atomSetCollection)` Get the name of the atom set collection, if known.
    `abstract java.lang.Object` | `getAtomSetCollectionReader(java.lang.String name, java.lang.String type, java.lang.Object bufferedReader, java.util.Map<java.lang.String,java.lang.Object> htParams)` Read an atomSetCollection object from a bufferedReader and close the reader.
    `abstract java.lang.Object` | `getAtomSetCollectionReaders(JmolFilesReaderInterface fileReader, java.lang.String[] names, java.lang.String[] types, java.util.Map<java.lang.String,java.lang.Object> htParams, boolean getReadersOnly)` Associate an atomSetCollection object with an array of BufferedReader.
    `abstract int` | `getAtomSetCount(java.lang.Object atomSetCollection)` Get number of atomSets in the file.
    `abstract java.lang.String` | `getAtomSetName(java.lang.Object atomSetCollection, int atomSetIndex)` Get the name of an atomSet.
    `abstract int` | `getAtomSetNumber(java.lang.Object atomSetCollection, int atomSetIndex)` Get the number identifying each atomSet.
    `static float` | `getBondingRadius(int atomicNumberWithIsotope, int charge)`
    `abstract JmolAdapterBondIterator` | `getBondIterator(java.lang.Object atomSetCollection)` Get a BondIterator for retrieval of all bonds in the file.
    `abstract java.lang.String[][]` | `getBondList(java.lang.Object atomSetCollection)`
    `static int` | `getElementNumber(java.lang.String elementSymbol)`
    `static java.lang.String` | `getElementSymbol(int elementNumber)`
    `abstract java.lang.String` | `getFileTypeName(java.lang.Object atomSetCollection)` Get the type of this file or molecular model, if known.
    `abstract int` | `getHydrogenAtomCount(java.lang.Object atomSetCollection)` Get the hydrogen atom count -- for ligand files
    `static int` | `getNaturalIsotope(int elementNumber)`
    `abstract JmolAdapterStructureIterator` | `getStructureIterator(java.lang.Object atomSetCollection)` Get a StructureIterator.
    `java.lang.Object` | `openBufferedReader(java.lang.String name, java.io.BufferedReader bufferedReader)`
    `java.lang.Object` | `openBufferedReader(java.lang.String name, java.io.BufferedReader bufferedReader, java.util.Map<java.lang.String,java.lang.Object> htParams)`
    `java.lang.Object` | `openBufferedReader(java.lang.String name, java.lang.String type, java.io.BufferedReader bufferedReader)`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### ORDER_COVALENT_SINGLE

          public static final int ORDER_COVALENT_SINGLE

      See Also:
        Constant Field Values

    - #### ORDER_COVALENT_DOUBLE

          public static final int ORDER_COVALENT_DOUBLE

      See Also:
        Constant Field Values

    - #### ORDER_COVALENT_TRIPLE

          public static final int ORDER_COVALENT_TRIPLE

      See Also:
        Constant Field Values

    - #### ORDER_COVALENT_QUAD

          public static final int ORDER_COVALENT_QUAD

      See Also:
        Constant Field Values

    - #### ORDER_COVALENT_QUINT

          public static final int ORDER_COVALENT_QUINT

      See Also:
        Constant Field Values

    - #### ORDER_COVALENT_HEX

          public static final int ORDER_COVALENT_HEX

      See Also:
        Constant Field Values

    - #### ORDER_AROMATIC

          public static final int ORDER_AROMATIC

      See Also:
        Constant Field Values

    - #### ORDER_AROMATIC_SINGLE

          public static final int ORDER_AROMATIC_SINGLE

      See Also:
        Constant Field Values

    - #### ORDER_AROMATIC_DOUBLE

          public static final int ORDER_AROMATIC_DOUBLE

      See Also:
        Constant Field Values

    - #### ORDER_HBOND

          public static final int ORDER_HBOND

      See Also:
        Constant Field Values

    - #### ORDER_STEREO_NEAR

          public static final int ORDER_STEREO_NEAR

      See Also:
        Constant Field Values

    - #### ORDER_STEREO_FAR

          public static final int ORDER_STEREO_FAR

      See Also:
        Constant Field Values

    - #### ORDER_PARTIAL01

          public static final int ORDER_PARTIAL01

      See Also:
        Constant Field Values

    - #### ORDER_PARTIAL12

          public static final int ORDER_PARTIAL12

      See Also:
        Constant Field Values

    - #### ORDER_PARTIAL23

          public static final int ORDER_PARTIAL23

      See Also:
        Constant Field Values

    - #### ORDER_PARTIAL32

          public static final int ORDER_PARTIAL32

      See Also:
        Constant Field Values

    - #### ORDER_UNSPECIFIED

          public static final int ORDER_UNSPECIFIED

      See Also:
        Constant Field Values

    - #### ORDER_PYMOL_SINGLE

          public static final int ORDER_PYMOL_SINGLE

      See Also:
        Constant Field Values

    - #### ORDER_PYMOL_MULT

          public static final int ORDER_PYMOL_MULT

      See Also:
        Constant Field Values

    - #### cellParamNames

          public static final java.lang.String[] cellParamNames

  - ### Constructor Detail

    - #### JmolAdapter

          public JmolAdapter()

  - ### Method Detail

    - #### getElementSymbol

          public static java.lang.String getElementSymbol(int elementNumber)

    - #### getElementNumber

          public static int getElementNumber(java.lang.String elementSymbol)

    - #### getNaturalIsotope

          public static int getNaturalIsotope(int elementNumber)

    - #### getBondingRadius

          public static float getBondingRadius(int atomicNumberWithIsotope,
                                               int charge)

    - #### getAtomSetCollectionReader

          public abstract java.lang.Object getAtomSetCollectionReader(java.lang.String name,
                                                                      java.lang.String type,
                                                                      java.lang.Object bufferedReader,
                                                                      java.util.Map<java.lang.String,java.lang.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 java.lang.Object getAtomSetCollection(java.lang.Object atomSetCollectionReader)

    - #### getAtomSetCollectionReaders

          public abstract java.lang.Object getAtomSetCollectionReaders(JmolFilesReaderInterface fileReader,
                                                                       java.lang.String[] names,
                                                                       java.lang.String[] types,
                                                                       java.util.Map<java.lang.String,java.lang.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 java.lang.Object getAtomSetCollectionFromSet(java.lang.Object readers,
                                                                       java.lang.Object atomSets,
                                                                       java.util.Map<java.lang.String,java.lang.Object> htParams)

    - #### getAtomSetCollectionFromReader

          public abstract java.lang.Object getAtomSetCollectionFromReader(java.lang.String fname,
                                                                          java.lang.Object reader,
                                                                          java.util.Map<java.lang.String,java.lang.Object> htParams)
                                                                   throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### getAtomSetCollectionFromReaderType

          public java.lang.Object getAtomSetCollectionFromReaderType(java.lang.String name,
                                                                     java.lang.String type,
                                                                     java.lang.Object bufferedReader,
                                                                     java.util.Map<java.lang.String,java.lang.Object> htParams)

      all in one -- for TestSmarterJmolAdapter
      Parameters:
        `name` -
        `type` -
        `bufferedReader` -
        `htParams` -
      Returns:
        AtomSetCollection or error string

    - #### openBufferedReader

          public java.lang.Object openBufferedReader(java.lang.String name,
                                                     java.io.BufferedReader bufferedReader)

    - #### openBufferedReader

          public java.lang.Object openBufferedReader(java.lang.String name,
                                                     java.io.BufferedReader bufferedReader,
                                                     java.util.Map<java.lang.String,java.lang.Object> htParams)

    - #### openBufferedReader

          public java.lang.Object openBufferedReader(java.lang.String name,
                                                     java.lang.String type,
                                                     java.io.BufferedReader bufferedReader)

    - #### getAtomSetCollectionFromDOM

          public abstract java.lang.Object getAtomSetCollectionFromDOM(java.lang.Object DOMNode,
                                                                       java.util.Map<java.lang.String,java.lang.Object> htParams)

    - #### finish

          public abstract void finish(java.lang.Object atomSetCollection)

      Parameters:
        `atomSetCollection` -

    - #### getFileTypeName

          public abstract java.lang.String getFileTypeName(java.lang.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 java.lang.String getAtomSetCollectionName(java.lang.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 java.util.Map<java.lang.String,java.lang.Object> getAtomSetCollectionAuxiliaryInfo(java.lang.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(java.lang.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(java.lang.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 java.lang.String getAtomSetName(java.lang.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 java.util.Map<java.lang.String,java.lang.Object> getAtomSetAuxiliaryInfo(java.lang.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(java.lang.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(java.lang.Object atomSetCollection)

      Get the hydrogen atom count -- for ligand files
      Parameters:
        `atomSetCollection` -
      Returns:
        number of hydrogen atoms in this model

    - #### getBondList

          public abstract java.lang.String[][] getBondList(java.lang.Object atomSetCollection)

      Parameters:
        `atomSetCollection` -
      Returns:
        [ [atomName1 atomName2 order] ...]

    - #### coordinatesAreFractional

          public abstract boolean coordinatesAreFractional(java.lang.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(java.lang.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:
        `JmolAdapterAtomIterator`

    - #### getBondIterator

          public abstract JmolAdapterBondIterator getBondIterator(java.lang.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:
        `JmolAdapterBondIterator`

    - #### getStructureIterator

          public abstract JmolAdapterStructureIterator getStructureIterator(java.lang.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)