Package org.jmol.api

Class 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

    • 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)