org.jmol.api

Class JmolAdapter

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:

Nested Class Summary
abstract classJmolAdapter.AtomIterator
AtomIterator is used to enumerate all the clientAtom objects in a specified frame.
abstract classJmolAdapter.BondIterator
BondIterator is used to enumerate all the bonds
abstract classJmolAdapter.StructureIterator
StructureIterator is used to enumerate Structures Helix, Sheet, Turn
Field Summary
StringadapterName
static shortORDER_AROMATIC
static shortORDER_AROMATIC_DOUBLE
static shortORDER_AROMATIC_SINGLE
static shortORDER_COVALENT_DOUBLE
static shortORDER_COVALENT_SINGLE
static shortORDER_COVALENT_TRIPLE
static shortORDER_HBOND
static shortORDER_PARTIAL01
static shortORDER_PARTIAL12
static shortORDER_PARTIAL23
static shortORDER_PARTIAL32
static shortORDER_STEREO_FAR
static shortORDER_STEREO_NEAR
static shortORDER_UNSPECIFIED
static intSHELL_D_CARTESIAN
static intSHELL_D_SPHERICAL
static intSHELL_F_CARTESIAN
static intSHELL_F_SPHERICAL
static intSHELL_L
static intSHELL_P
static intSHELL_S
static intSHELL_SP
Constructor Summary
JmolAdapter(String adapterName)
Method Summary
static StringcanonicalizeQuantumSubshellTag(String tag)
static charcanonizeAlphaDigit(char ch)
static charcanonizeAlternateLocationID(char altLoc)
static charcanonizeChainID(char chainID)
static charcanonizeInsertionCode(char insertionCode)
booleancoordinatesAreFractional(Object clientFile)
Get the boolean whether coordinates are fractional.
voidfinish(Object clientFile)
StringgetAdapterName()
abstract JmolAdapter.AtomIteratorgetAtomIterator(Object clientFile)
Get an AtomIterator for retrieval of all atoms in the file.
HashtablegetAtomSetAuxiliaryInfo(Object clientFile, int atomSetIndex)
Get the auxiliary information for a particular atomSet.
HashtablegetAtomSetCollectionAuxiliaryInfo(Object clientFile)
Get the auxiliary information for this atomSetCollection.
StringgetAtomSetCollectionName(Object clientFile)
Get the name of the atom set collection, if known.
PropertiesgetAtomSetCollectionProperties(Object clientFile)
Get the properties for this atomSetCollection.
intgetAtomSetCount(Object clientFile)
Get number of atomSets in the file.
StringgetAtomSetName(Object clientFile, int atomSetIndex)
Get the name of an atomSet.
intgetAtomSetNumber(Object clientFile, int atomSetIndex)
Get the number identifying each atomSet.
PropertiesgetAtomSetProperties(Object clientFile, int atomSetIndex)
Get the properties for an atomSet.
JmolAdapter.BondIteratorgetBondIterator(Object clientFile)
Get a BondIterator for retrieval of all bonds in the file.
StringgetClientAtomStringProperty(Object clientAtom, String propertyName)
Get a property from a clientAtom.
static intgetElementNumber(String elementSymbol)
static StringgetElementSymbol(int elementNumber)
abstract intgetEstimatedAtomCount(Object clientFile)
Get the estimated number of atoms contained in the file.
StringgetFileTypeName(Object clientFile)
Get the type of this file or molecular model, if known.
float[]getNotionalUnitcell(Object clientFile)
Get the notional unit cell.
float[]getPdbScaleMatrix(Object clientFile)
Get the PDB scale matrix.
float[]getPdbScaleTranslate(Object clientFile)
Get the PDB scale translation vector.
static intgetQuantumShellTagID(String tag)
static intgetQuantumShellTagIDSpherical(String tag)
static StringgetQuantumSubshellTag(int shell, int subshell)
static intgetQuantumSubshellTagID(int shell, String tag)
JmolAdapter.StructureIteratorgetStructureIterator(Object clientFile)
Get a StructureIterator.
static booleanisHetero(String group3)
static shortlookupGroupID(String group3)
ObjectopenBufferedReader(String name, String type, BufferedReader bufferedReader, Hashtable htParams)
Associate a clientFile object with a bufferedReader.
ObjectopenBufferedReader(String name, BufferedReader bufferedReader)
ObjectopenBufferedReader(String name, BufferedReader bufferedReader, Hashtable htParams)
ObjectopenBufferedReader(String name, String type, BufferedReader bufferedReader)
ObjectopenBufferedReaders(JmolFileReaderInterface fileReader, String[] names, String[] types, Hashtable[] htParams)
Associate a clientFile object with an array of BufferedReader.
ObjectopenDOMReader(Object DOMNode)
ObjectopenZipFiles(InputStream is, String fileName, String[] zipDirectory, Hashtable htParams, boolean asBufferedReader)
String[]specialLoad(String name, String type)

Field Detail

adapterName

String adapterName

ORDER_AROMATIC

public static final short ORDER_AROMATIC

ORDER_AROMATIC_DOUBLE

public static final short ORDER_AROMATIC_DOUBLE

ORDER_AROMATIC_SINGLE

public static final short ORDER_AROMATIC_SINGLE

ORDER_COVALENT_DOUBLE

public static final short ORDER_COVALENT_DOUBLE

ORDER_COVALENT_SINGLE

public static final short ORDER_COVALENT_SINGLE

ORDER_COVALENT_TRIPLE

public static final short ORDER_COVALENT_TRIPLE

ORDER_HBOND

public static final short ORDER_HBOND

ORDER_PARTIAL01

public static final short ORDER_PARTIAL01

ORDER_PARTIAL12

public static final short ORDER_PARTIAL12

ORDER_PARTIAL23

public static final short ORDER_PARTIAL23

ORDER_PARTIAL32

public static final short ORDER_PARTIAL32

ORDER_STEREO_FAR

public static final short ORDER_STEREO_FAR

ORDER_STEREO_NEAR

public static final short ORDER_STEREO_NEAR

ORDER_UNSPECIFIED

public static final short ORDER_UNSPECIFIED

SHELL_D_CARTESIAN

public static final int SHELL_D_CARTESIAN

SHELL_D_SPHERICAL

public static final int SHELL_D_SPHERICAL

SHELL_F_CARTESIAN

public static final int SHELL_F_CARTESIAN

SHELL_F_SPHERICAL

public static final int SHELL_F_SPHERICAL

SHELL_L

public static final int SHELL_L

SHELL_P

public static final int SHELL_P

SHELL_S

public static final int SHELL_S

SHELL_SP

public static final int SHELL_SP

Constructor Detail

JmolAdapter

public JmolAdapter(String adapterName)

Method Detail

canonicalizeQuantumSubshellTag

public static final String canonicalizeQuantumSubshellTag(String tag)

canonizeAlphaDigit

public static final char canonizeAlphaDigit(char ch)

canonizeAlternateLocationID

public static final char canonizeAlternateLocationID(char altLoc)

canonizeChainID

public static final char canonizeChainID(char chainID)

canonizeInsertionCode

public static final char canonizeInsertionCode(char insertionCode)

coordinatesAreFractional

public boolean coordinatesAreFractional(Object clientFile)
Get the boolean whether coordinates are fractional.

Parameters: clientFile The client file

Returns: true if the coordinates are fractional, default false

finish

public void finish(Object clientFile)

getAdapterName

public String getAdapterName()

getAtomIterator

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

This method may not return null.

Parameters: clientFile The client file

Returns: An AtomIterator

See Also: AtomIterator

getAtomSetAuxiliaryInfo

public Hashtable getAtomSetAuxiliaryInfo(Object clientFile, int atomSetIndex)
Get the auxiliary information for a particular atomSet.

Via the smarterJmolAdapter

Parameters: clientFile The client file atomSetIndex The atom set index

Returns: The auxiliaryInfo Hashtable that may be available for particular filetypes for this atomSet or null

getAtomSetCollectionAuxiliaryInfo

public Hashtable getAtomSetCollectionAuxiliaryInfo(Object clientFile)
Get the auxiliary information for this atomSetCollection.

Via the smarterJmolAdapter

Parameters: clientFile The client file

Returns: The auxiliaryInfo Hashtable that may be available for particular filetypes for this atomSetCollection or null

getAtomSetCollectionName

public String getAtomSetCollectionName(Object clientFile)
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: clientFile

Returns: The atom set collection name or null

getAtomSetCollectionProperties

public Properties getAtomSetCollectionProperties(Object clientFile)
Get the properties for this atomSetCollection.

Not yet implemented everywhere, it is in the smarterJmolAdapter

Parameters: clientFile The client file

Returns: The properties for this atomSetCollection or null

getAtomSetCount

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

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

Parameters: clientFile The client file

Returns: The number of atomSets in the file, default 1

getAtomSetName

public String getAtomSetName(Object clientFile, int atomSetIndex)
Get the name of an atomSet.

Parameters: clientFile The client file atomSetIndex The atom set index

Returns: The name of the atom set, default the string representation of atomSetIndex

getAtomSetNumber

public int getAtomSetNumber(Object clientFile, 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: clientFile The client file atomSetIndex The atom set's index for which to get the atom set number

Returns: The number identifying each atom set, default atomSetIndex+1.

getAtomSetProperties

public Properties getAtomSetProperties(Object clientFile, int atomSetIndex)
Get the properties for an atomSet.

Parameters: clientFile The client file atomSetIndex The atom set index

Returns: The properties for an atom set or null

getBondIterator

public JmolAdapter.BondIterator getBondIterator(Object clientFile)
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: clientFile The client file

Returns: A BondIterator or null

See Also: BondIterator

getClientAtomStringProperty

public String getClientAtomStringProperty(Object clientAtom, String propertyName)
Get a property from a clientAtom.

Parameters: clientAtom The clientAtom propertyName the key of the property

Returns: The value of the property

getElementNumber

public static int getElementNumber(String elementSymbol)

getElementSymbol

public static String getElementSymbol(int elementNumber)

getEstimatedAtomCount

public abstract int getEstimatedAtomCount(Object clientFile)
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: clientFile The client file

Returns: The estimated number of atoms in the file

getFileTypeName

public String getFileTypeName(Object clientFile)
Get the type of this file or molecular model, if known.

Parameters: clientFile The client file

Returns: The type of this file or molecular model, default "unknown"

getNotionalUnitcell

public float[] getNotionalUnitcell(Object clientFile)
Get the notional unit cell.

This method returns the parameters that define a crystal unitcell the parameters are returned in a float[] in the following order a, b, c, alpha, beta, gamma
a, b, c : angstroms
alpha, beta, gamma : degrees
if there is no unit cell data then return null

Parameters: clientFile The client file

Returns: The array of the values or null

getPdbScaleMatrix

public float[] getPdbScaleMatrix(Object clientFile)
Get the PDB scale matrix.

Does not seem to be overriden by any descendent

Parameters: clientFile The client file

Returns: The array of 9 floats for the matrix or null

getPdbScaleTranslate

public float[] getPdbScaleTranslate(Object clientFile)
Get the PDB scale translation vector.

Does not seem to be overriden by any descendent

Parameters: clientFile The client file

Returns: The x, y and z translation values or null

getQuantumShellTagID

public static int getQuantumShellTagID(String tag)

getQuantumShellTagIDSpherical

public static int getQuantumShellTagIDSpherical(String tag)

getQuantumSubshellTag

public static final String getQuantumSubshellTag(int shell, int subshell)

getQuantumSubshellTagID

public static final int getQuantumSubshellTagID(int shell, String tag)

getStructureIterator

public JmolAdapter.StructureIterator getStructureIterator(Object clientFile)
Get a StructureIterator.

Parameters: clientFile The client file

Returns: A StructureIterator or null

isHetero

public static boolean isHetero(String group3)

lookupGroupID

public static final short lookupGroupID(String group3)

openBufferedReader

public Object openBufferedReader(String name, String type, BufferedReader bufferedReader, Hashtable htParams)
Associate a clientFile object with a bufferedReader.

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 clientFile. This clientFile 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 clientFile or String with an error message

openBufferedReader

public Object openBufferedReader(String name, BufferedReader bufferedReader)

openBufferedReader

public Object openBufferedReader(String name, BufferedReader bufferedReader, Hashtable htParams)

openBufferedReader

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

openBufferedReaders

public Object openBufferedReaders(JmolFileReaderInterface fileReader, String[] names, String[] types, Hashtable[] htParams)
Associate a clientFile 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 clientFile. This clientFile 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

Returns: The clientFile or String with an error message

openDOMReader

public Object openDOMReader(Object DOMNode)

openZipFiles

public Object openZipFiles(InputStream is, String fileName, String[] zipDirectory, Hashtable htParams, boolean asBufferedReader)

specialLoad

public String[] specialLoad(String name, String type)