# 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:
  - `JmolViewer`
  - `SmarterJmolAdapter`

## Field Summary

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

## Constructor Summary

Constructors
Constructor
Description
`JmolAdapter()`

## Method Summary

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

### Methods inherited from class Object

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

## Field Details

### 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_STEREO_EITHER

public static final int ORDER_STEREO_EITHER

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 String[] cellParamNames
///////////////////////////////////////////////////////////////

## 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`

### getAtomSetCollectionInline

public abstract Object getAtomSetCollectionInline(Object molData, Map<String,Object> htParams)

### 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 or specific model index in 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, int atomSetIndex)
Get the number of atoms contained in the file.

Parameters:
  `atomSetCollection` - The client file
  `atomSetIndex` - if -1, then count for the whole collection, else for this set
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:
  - `JmolAdapterAtomIterator`

### 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:
  - `JmolAdapterBondIterator`

### getStructureIterator

public abstract JmolAdapterStructureIterator getStructureIterator(Object atomSetCollection)
Get a StructureIterator.

Parameters:
  `atomSetCollection` - The client file
Returns:
  A StructureIterator or `null`

### canonizeInsertionCode

public static final char canonizeInsertionCode(char insertionCode)

### canonizeAlternateLocationID

public static final char canonizeAlternateLocationID(char altLoc)