//  $Id: StructureComponent.java,v 1.2 2007/02/13 19:08:41 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: StructureComponent.java,v $
//  Revision 1.2  2007/02/13 19:08:41  Sasha Buzko
//  *** empty log message ***
//
//  Revision 1.1  2006/05/20 17:02:07  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.3  2005/11/26 04:36:10  Administrator
//  *** empty log message ***
//
//  Revision 1.2  2005/11/13 23:44:31  Administrator
//  *** empty log message ***
//
//  Revision 1.1  2005/11/13 04:35:27  Administrator
//  *** empty log message ***
//
//  Revision 1.3  2003/04/23 17:34:50  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).
//  Added getStructure method.
//
//  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;


/**
 *  Defines the abstract base class for a StructureComponent data container.
 *  Each subclass instance represents a raw "record" from its source Structure.
 *  Using the Structure class directly is useful if an application simply
 *  wishes to walk the raw records of a data set. For a more structured "map"
 *  (hierarchical view) of derived data, see the StructureMap class.
 *  <P>
 *  <B>PROGRAMMING NOTE</B>:<BR>
 *  <P>
 *  Here is an example of the Atom sub-class which demonstrates a typical
 *  use case for all StructureComponent sub-classes:
 *  <P>
 *  <PRE>
 *      int atomCount = structure.getStructureComponentCount(
 *         StructureComponentRegistry.TYPE_ATOM );
 *      for ( int i=0; i<atomCount; i++ )
 *      {   
 *         Atom atom = (Atom) getStructureComponentByIndex(
 *            StructureComponentRegistry.TYPE_ATOM, i );
 *         // do something useful here with the current Atom record
 *      }
 *  </PRE>
 *  <P>
 *  @see edu.sdsc.mbt.Structure
 *  @see edu.sdsc.mbt.StructureMap
 */
public abstract class StructureComponent
	implements java.lang.Cloneable, java.io.Serializable
{
	/**
	 *  The Structure to which a StructureComponent instance belongs.
	 */
	public Structure structure = null;

	/**
	 *  Clone this object.
	 */
	public Object clone( )
		throws CloneNotSupportedException
	{
		return super.clone( );
	}

	/**
	 *  Copy all of the field values from the parameter object into "this".
	 */
	abstract public void copy( StructureComponent structureComponent );

	/**
	 *  This method returns the fully qualified name of this class.
	 *  Sub-classes must override this method (This method should really
	 *  be declared abstract, but unfortunately Java does not allow a
	 *  method to be both static AND abstract). Instead, this base class 
	 *  implementation will through an UnsupportedOperationException.
	 *  <P>
	 *  This name is used by the StructureComponentRegistry class to enable
	 *  dynamic registration and discovery of new StructureComponent
	 *  sub-classes/types. The name is also used to create instances
	 *  of any sublcass dynamically from this name.
	 */
	public static String getClassName( )
		throws UnsupportedOperationException
	{
		throw new UnsupportedOperationException(
			"getClassName method not implemented" );
	}

	/**
	 *  This method returns the fully qualified name of this class.
	 *  Sub-classes must override this method. Unfortunately Java does not
	 *  allow a method to be both static AND abstract). Instead, this base
	 *  class implementation will through an UnsupportedOperationException.
	 *  <P>
	 *  This name is used by the StructureComponentRegistry class to enable
	 *  dynamic registration and discovery of new StructureComponent
	 *  sub-classes/types. The name is also used to create instances
	 *  of any sublcass dynamically from this name.
	 */
	public abstract String getStructureComponentType( );
	
	/**
	 *  Set the Structure to which a StructureComponent instance belongs.
	 */
	public final void setStructure( Structure structure )
	{
		//this may be a bit foolish, but is necessary for stepwise bond initialization
		//when input files have bond information: then the placeholder object is created
		// as the file is parsed, and structure is assigned by StructureMap later
//		if ( structure == null )
//			throw new NullPointerException( "Null structure" );
		this.structure = structure;
	}

	/**
	 *  Get the Structure to which a StructureComponent instance belongs.
	 */
	public final Structure getStructure( )
	{
		return structure;
	}
	
	
	public abstract boolean isVisible();

}