//  $Id: Structure.java,v 1.1 2006/05/20 17:02:06 Sasha Buzko Exp $
//
//  Copyright (c) 2000-2002  San Diego Supercomputer Center (SDSC),
//  a facility operated jointly by the University of California,
//  San Diego (UCSD) and General Atomics, San Diego, California, USA.
//
//  Users and possessors of this source code are hereby granted a
//  nonexclusive, royalty-free copyright and design patent license to
//  use this code in individual software.  License is not granted for
//  commercial resale, in whole or in part, without prior written
//  permission from SDSC.  This source is provided "AS IS" without express
//  or implied warranty of any kind.
//
//  For further information, please see:  http://mbt.sdsc.edu
//
//  History:
//  $Log: Structure.java,v $
//  Revision 1.1  2006/05/20 17:02:06  Sasha Buzko
//  Updated version
//
//  Revision 1.1  2006/04/30 20:14:05  Sasha Buzko
//  New version of the app
//
//  Revision 1.1  2006/04/15 19:42:27  Sasha Buzko
//  Initial commit
//
//  Revision 1.1  2005/11/13 04:35:25  Administrator
//  *** empty log message ***
//
//  Revision 1.7  2003/04/23 17:33:12  moreland
//  Removed StructureComponentID/scid and replaced it with a "structure" field
//  in the StructureComponent base class.
//  Changed "getType" method to "getStructureComponentType" to return dynamic
//  SC type (ie: class name).
//  Changed getStructureComponentById method to return an object instance
//  rather than filling in a user-supplied object. The hashCode for a
//  StructureComponent subclass instance should be the the same for a
//  given StructureComponent type index.
//
//  Revision 1.6  2002/12/16 17:47:58  moreland
//  Added the getStructureMap factory method to produce a StructureMap object.
//
//  Revision 1.5  2002/12/16 06:27:53  moreland
//  Changed code to support differentiation of Conformation into Coil, Helix,
//  Strand, and Turn sub-class types (at Eliot Clingman's suggestion).
//  Also, Structure is no longer a StructureComponent sub-class (made no sense).
//
//  Revision 1.4  2002/11/14 18:14:13  moreland
//  Made minor correction to the comments.
//
//  Revision 1.3  2002/11/06 23:20:57  moreland
//  Removed references to the old selection event mechanism since raw data
//  is not selected (Viewable objects are).
//
//  Revision 1.2  2002/10/24 17:54:01  moreland
//  Provides implementation for the improved Structure API/implementation.
//
//  Revision 1.1.1.1  2002/07/16 18:00:18  moreland
//  Imported sources
//
//  Revision 1.0  2002/06/10 23:38:39  moreland
//


package edu.sdsc.mbt;

import edu.sdsc.mbt.filters.StructureComponentFilter;
import edu.sdsc.mbt.filters.RelationFilter;

/**
 *  This class provides the primary interface for a molecular structure object.
 *  <P>
 *  Note that since there are currently no "set" methods in this class,
 *  there are also currently no StructureComponentEvent handling methods.
 *  <P>
 *  @see edu.sdsc.mbt.StructureComponentEvent
 *  @see edu.sdsc.mbt.StructureComponentEventListener
 *  <P>
 *  @author John L. Moreland
 */
public abstract class Structure implements java.io.Serializable 
{
	/**
	 * This method returns a string which represents the URL
	 * from which the structure instance was produced.
	 *
	 * Examples:
	 *
	 *    file://c:/myFiles/5ebx.pdb     // a local PDB file
	 *    file://c:/myFiles/5ebx.mmCIF   // a local mmCIF file
	 *    ftp://ftp.rcsb.org/2cpk.pdb    // a remote pdb file
	 *    ftp://ftp.rcsb.org/4hhb.mmCIF  // a remote mmCIF file
	 *    iiop://corba.sdsc.edu/2cpk     // an openMMS reference
	 *
	 * This URL can be handed back to the StructureFactory in order
	 * to re-load the structure.
	 */
	abstract public String getUrlString( );

	/**
	 * Counts components of the specified type that exist in the structure.
	 * TYPE values are defined in the StructureComponentRegistry class.
	 */
	abstract public int getStructureComponentCount( String scType );

	/**
	 * Given a StructureComponentFilter, create and return an iterator
	 * which will selectively return a subset of structure components.
	 */
	public StructureComponentIterator createStructureComponentIterator(
		StructureComponentFilter filter )
	{
		try
		{
			return new StructureComponentIterator( this, filter );
		}
		catch( Exception e )
		{
	 		System.err.println( "Structure.createStructureComponentIterator: exception = " + e + " (perhaps a bad filter?)" );
			return null;
		}
	}


	/**
	 * Given a StructureComponentRelation name and a StructureComponent,
	 * create and return a StructureComponentIterator which will selectively
	 * return the related subset of StructureComponent objects. This is
	 * acheaved by creating a RelationFilter with relation name and
	 * StructureComponent parameters then simply calling the
	 * createStructureComponentIterator method with that filter.
	 * <P>
	 */
	public StructureComponentIterator getStructureComponentRelations(
		String relation_name, StructureComponent structureComponent )
			throws IllegalArgumentException
	{
		StructureComponentRelation relation =
			StructureComponentRegistry.getRelation( relation_name );
		RelationFilter relationFilter =
			new RelationFilter( relation, structureComponent );
		return createStructureComponentIterator( relationFilter );
	}

	/**
	 * Get the values for any StructureSomponent subclass by its type-specific
	 * index. For example: Atom, Residue, Conformation, etc.
	 * <P>
	 * Note that it is the caller's responsibility to cast the returned
	 * object to the corresponding StructureComponent sublcass type.
	 * For example, an application might do something like this:
	 * <P>
	 * <UL>
	 * <PRE>
	 * // First load a structure using the StructureFactory, and then...
	 * int atom_count =
	 *   structure.getStructureComponentCount( StructureComponentRegistry.TYPE_ATOM );
	 * for ( int i=0; i<atom_count; i++ )
	 * {
	 *    Atom atom = (Atom) structure.getStructureComponentByIndex(
	 *       StructureComponentRegistry.TYPE_ATOM, i );
	 *
	 *    System.err.println( "coord = " + atom.coordinate[0] + ", " +
     *      atom.coordinate[1] + ", " + atom.coordinate[2] );
     *      System.err.println( "name = " + atom.name );
     *    System.err.println( "occupancy = " + atom.occupancy );
	 * }
	 * </PRE>
	 * </UL>
	 */
	abstract public StructureComponent getStructureComponentByIndex(
		String structureComponentType, int index )
		throws IndexOutOfBoundsException, IllegalArgumentException;

	/**
	 *  Stores a reference to a StructureMap object for this Structure.
	 *  Only one StructureMap needs to be created for a given Structure,
	 *  because no inter-method-call state is kept by the object.
	 *  Once a single StructureMap is created, subsequent calls to
	 *  the getStructureMap method return the same StructureMap object.
	 */
	private StructureMap structureMap = null;

	/**
	 * Return the StructureMap object that describes the derived (implied)
	 * hierarchy of primary and secondary structure data for the Structure.
	 * This mapping provides a means to iteratate over components of the
	 * structure in an ordered and efficient manner.
	 * <P>
	 */
	public StructureMap getStructureMap( )
	{
		if ( structureMap == null )
			structureMap = new StructureMap( this );
		return structureMap;
	}
	
	
	private void writeObject(java.io.ObjectOutputStream out) throws java.io.IOException {
		out.defaultWriteObject();
	}
	private void readObject(java.io.ObjectInputStream in) throws java.io.IOException, ClassNotFoundException {
		in.defaultReadObject();
	} 

}