org.jmol.api
Class JmolAdapter

java.lang.Object
  extended by 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

Nested Class Summary
 class JmolAdapter.AtomIterator
          AtomIterator is used to enumerate all the clientAtom objects in a specified frame.
 class JmolAdapter.BondIterator
          BondIterator is used to enumerate all the bonds
 class JmolAdapter.StructureIterator
          StructureIterator is used to enumerate Structures Helix, Sheet, Turn
 
Field Summary
(package private)  java.lang.String adapterName
           
static short ORDER_AROMATIC
           
static short ORDER_AROMATIC_DOUBLE
           
static short ORDER_AROMATIC_SINGLE
           
static short ORDER_COVALENT_DOUBLE
           
static short ORDER_COVALENT_SINGLE
           
static short ORDER_COVALENT_TRIPLE
           
static short ORDER_HBOND
           
static short ORDER_PARTIAL01
           
static short ORDER_PARTIAL12
           
static short ORDER_PARTIAL23
           
static short ORDER_PARTIAL32
           
static short ORDER_STEREO_FAR
           
static short ORDER_STEREO_NEAR
           
static short ORDER_UNSPECIFIED
           
static int SHELL_D_CARTESIAN
           
static int SHELL_D_SPHERICAL
           
static int SHELL_F_CARTESIAN
           
static int SHELL_F_SPHERICAL
           
static int SHELL_L
           
static int SHELL_P
           
static int SHELL_S
           
static int SHELL_SP
           
 
Constructor Summary
JmolAdapter(java.lang.String adapterName)
           
 
Method Summary
static java.lang.String canonicalizeQuantumSubshellTag(java.lang.String tag)
           
static char canonizeAlphaDigit(char ch)
           
static char canonizeAlternateLocationID(char altLoc)
           
static char canonizeChainID(char chainID)
           
static char canonizeInsertionCode(char insertionCode)
           
abstract  boolean coordinatesAreFractional(java.lang.Object atomSetCollection)
          Get the boolean whether coordinates are fractional.
 void finish(java.lang.Object atomSetCollection)
           
 java.lang.String getAdapterName()
           
abstract  JmolAdapter.AtomIterator getAtomIterator(java.lang.Object atomSetCollection)
          Get an AtomIterator for retrieval of all atoms in the file.
abstract  java.util.Hashtable getAtomSetAuxiliaryInfo(java.lang.Object atomSetCollection, int atomSetIndex)
          Get the auxiliary information for a particular atomSet.
abstract  java.util.Hashtable getAtomSetCollectionAuxiliaryInfo(java.lang.Object atomSetCollection)
          Get the auxiliary information for this atomSetCollection.
abstract  java.lang.Object getAtomSetCollectionFromDOM(java.lang.Object DOMNode)
           
abstract  java.lang.Object getAtomSetCollectionFromReader(java.lang.String name, java.lang.String type, java.io.BufferedReader bufferedReader, java.util.Hashtable htParams)
          Read an atomSetCollection object from a bufferedReader and close the reader.
abstract  java.lang.Object getAtomSetCollectionFromReaders(JmolFileReaderInterface fileReader, java.lang.String[] names, java.lang.String[] types, java.util.Hashtable[] htParams)
          Associate a atomSetCollection object with an array of BufferedReader.
abstract  java.lang.String getAtomSetCollectionName(java.lang.Object atomSetCollection)
          Get the name of the atom set collection, if known.
abstract  java.lang.Object getAtomSetCollectionOrBufferedReaderFromZip(java.io.InputStream is, java.lang.String fileName, java.lang.String[] zipDirectory, java.util.Hashtable htParams, boolean asBufferedReader)
           
abstract  java.util.Properties getAtomSetCollectionProperties(java.lang.Object atomSetCollection)
          Get the properties for this atomSetCollection.
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.
abstract  java.util.Properties getAtomSetProperties(java.lang.Object atomSetCollection, int atomSetIndex)
          Get the properties for an atomSet.
abstract  JmolAdapter.BondIterator getBondIterator(java.lang.Object atomSetCollection)
          Get a BondIterator for retrieval of all bonds in the file.
abstract  java.lang.String getClientAtomStringProperty(java.lang.Object clientAtom, java.lang.String propertyName)
          Get a property from a clientAtom.
static int getElementNumber(java.lang.String elementSymbol)
           
static java.lang.String getElementSymbol(int elementNumber)
           
abstract  int getEstimatedAtomCount(java.lang.Object atomSetCollection)
          Get the estimated number of atoms contained in the file.
abstract  java.lang.String getFileTypeName(java.lang.Object atomSetCollection)
          Get the type of this file or molecular model, if known.
abstract  float[] getNotionalUnitcell(java.lang.Object atomSetCollection)
          Get the notional unit cell.
abstract  float[] getPdbScaleMatrix(java.lang.Object atomSetCollection)
          Get the PDB scale matrix.
abstract  float[] getPdbScaleTranslate(java.lang.Object atomSetCollection)
          Get the PDB scale translation vector.
static int getQuantumShellTagID(java.lang.String tag)
           
static int getQuantumShellTagIDSpherical(java.lang.String tag)
           
static java.lang.String getQuantumSubshellTag(int shell, int subshell)
           
static int getQuantumSubshellTagID(int shell, java.lang.String tag)
           
abstract  JmolAdapter.StructureIterator getStructureIterator(java.lang.Object atomSetCollection)
          Get a StructureIterator.
static boolean isHetero(java.lang.String group3)
           
static short lookupGroupID(java.lang.String group3)
           
 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.Hashtable htParams)
           
 java.lang.Object openBufferedReader(java.lang.String name, java.lang.String type, java.io.BufferedReader bufferedReader)
           
 java.lang.String[] specialLoad(java.lang.String name, java.lang.String type)
           
 
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 short ORDER_COVALENT_SINGLE
See Also:
Constant Field Values

ORDER_COVALENT_DOUBLE

public static final short ORDER_COVALENT_DOUBLE
See Also:
Constant Field Values

ORDER_COVALENT_TRIPLE

public static final short ORDER_COVALENT_TRIPLE
See Also:
Constant Field Values

ORDER_AROMATIC

public static final short ORDER_AROMATIC
See Also:
Constant Field Values

ORDER_AROMATIC_SINGLE

public static final short ORDER_AROMATIC_SINGLE
See Also:
Constant Field Values

ORDER_AROMATIC_DOUBLE

public static final short ORDER_AROMATIC_DOUBLE
See Also:
Constant Field Values

ORDER_HBOND

public static final short ORDER_HBOND
See Also:
Constant Field Values

ORDER_STEREO_NEAR

public static final short ORDER_STEREO_NEAR
See Also:
Constant Field Values

ORDER_STEREO_FAR

public static final short ORDER_STEREO_FAR
See Also:
Constant Field Values

ORDER_PARTIAL01

public static final short ORDER_PARTIAL01
See Also:
Constant Field Values

ORDER_PARTIAL12

public static final short ORDER_PARTIAL12
See Also:
Constant Field Values

ORDER_PARTIAL23

public static final short ORDER_PARTIAL23
See Also:
Constant Field Values

ORDER_PARTIAL32

public static final short ORDER_PARTIAL32
See Also:
Constant Field Values

ORDER_UNSPECIFIED

public static final short ORDER_UNSPECIFIED
See Also:
Constant Field Values

SHELL_S

public static final int SHELL_S
See Also:
Constant Field Values

SHELL_P

public static final int SHELL_P
See Also:
Constant Field Values

SHELL_SP

public static final int SHELL_SP
See Also:
Constant Field Values

SHELL_L

public static final int SHELL_L
See Also:
Constant Field Values

SHELL_D_CARTESIAN

public static final int SHELL_D_CARTESIAN
See Also:
Constant Field Values

SHELL_D_SPHERICAL

public static final int SHELL_D_SPHERICAL
See Also:
Constant Field Values

SHELL_F_CARTESIAN

public static final int SHELL_F_CARTESIAN
See Also:
Constant Field Values

SHELL_F_SPHERICAL

public static final int SHELL_F_SPHERICAL
See Also:
Constant Field Values

adapterName

java.lang.String adapterName
Constructor Detail

JmolAdapter

public JmolAdapter(java.lang.String adapterName)
Method Detail

getElementSymbol

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

getElementNumber

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

isHetero

public static boolean isHetero(java.lang.String group3)

getQuantumShellTagID

public static int getQuantumShellTagID(java.lang.String tag)

getQuantumShellTagIDSpherical

public static int getQuantumShellTagIDSpherical(java.lang.String tag)

getQuantumSubshellTagID

public static final int getQuantumSubshellTagID(int shell,
                                                java.lang.String tag)

getQuantumSubshellTag

public static final java.lang.String getQuantumSubshellTag(int shell,
                                                           int subshell)

canonicalizeQuantumSubshellTag

public static final java.lang.String canonicalizeQuantumSubshellTag(java.lang.String tag)

lookupGroupID

public static final short lookupGroupID(java.lang.String group3)

getAdapterName

public java.lang.String getAdapterName()

getAtomSetCollectionFromReader

public abstract java.lang.Object getAtomSetCollectionFromReader(java.lang.String name,
                                                                java.lang.String type,
                                                                java.io.BufferedReader bufferedReader,
                                                                java.util.Hashtable 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

getAtomSetCollectionFromReaders

public abstract java.lang.Object getAtomSetCollectionFromReaders(JmolFileReaderInterface fileReader,
                                                                 java.lang.String[] names,
                                                                 java.lang.String[] types,
                                                                 java.util.Hashtable[] htParams)
Associate a 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
Returns:
The atomSetCollection or String with an error message

getAtomSetCollectionOrBufferedReaderFromZip

public abstract java.lang.Object getAtomSetCollectionOrBufferedReaderFromZip(java.io.InputStream is,
                                                                             java.lang.String fileName,
                                                                             java.lang.String[] zipDirectory,
                                                                             java.util.Hashtable htParams,
                                                                             boolean asBufferedReader)

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.Hashtable 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)

finish

public void finish(java.lang.Object 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

getAtomSetCollectionProperties

public abstract java.util.Properties getAtomSetCollectionProperties(java.lang.Object atomSetCollection)
Get the properties for this atomSetCollection.

Not yet implemented everywhere, it is in the smarterJmolAdapter

Parameters:
atomSetCollection - The client file
Returns:
The properties for this atomSetCollection or null

getAtomSetCollectionAuxiliaryInfo

public abstract java.util.Hashtable 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

getAtomSetProperties

public abstract java.util.Properties getAtomSetProperties(java.lang.Object atomSetCollection,
                                                          int atomSetIndex)
Get the properties for an atomSet.

Parameters:
atomSetCollection - The client file
atomSetIndex - The atom set index
Returns:
The properties for an atom set or null

getAtomSetAuxiliaryInfo

public abstract java.util.Hashtable 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

getEstimatedAtomCount

public abstract int getEstimatedAtomCount(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

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

getNotionalUnitcell

public abstract float[] getNotionalUnitcell(java.lang.Object atomSetCollection)
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:
atomSetCollection - The client file
Returns:
The array of the values or null

getPdbScaleMatrix

public abstract float[] getPdbScaleMatrix(java.lang.Object atomSetCollection)
Get the PDB scale matrix.

Does not seem to be overriden by any descendent

Parameters:
atomSetCollection - The client file
Returns:
The array of 9 floats for the matrix or null

getPdbScaleTranslate

public abstract float[] getPdbScaleTranslate(java.lang.Object atomSetCollection)
Get the PDB scale translation vector.

Does not seem to be overriden by any descendent

Parameters:
atomSetCollection - The client file
Returns:
The x, y and z translation values or null

getClientAtomStringProperty

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

Parameters:
clientAtom - The clientAtom
propertyName - the key of the property
Returns:
The value of the property

getAtomIterator

public abstract JmolAdapter.AtomIterator 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:
JmolAdapter.AtomIterator

getBondIterator

public abstract JmolAdapter.BondIterator 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:
JmolAdapter.BondIterator

getStructureIterator

public abstract JmolAdapter.StructureIterator getStructureIterator(java.lang.Object atomSetCollection)
Get a StructureIterator.

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

canonizeAlphaDigit

public static final char canonizeAlphaDigit(char ch)

canonizeChainID

public static final char canonizeChainID(char chainID)

canonizeInsertionCode

public static final char canonizeInsertionCode(char insertionCode)

canonizeAlternateLocationID

public static final char canonizeAlternateLocationID(char altLoc)

specialLoad

public java.lang.String[] specialLoad(java.lang.String name,
                                      java.lang.String type)