package org.trinet.jasi;

/**
 * Solution
 *
 *
 * Created: Wed Oct 27 10:35:35 1999
 *
 * @author Doug Given
 * @version
 */

import java.util.ArrayList;
import java.util.Collection;

import java.sql.Connection;
import org.trinet.jasi.coda.*;
//import org.trinet.jasi.concrete.*;

import org.trinet.util.gazetteer.LatLonZ;
import org.trinet.util.DateTime;
import org.trinet.util.EpochTime;
import org.trinet.jdbc.datatypes.*;
import org.trinet.util.Format;		// CoreJava printf-like Format class
import org.trinet.jasi.JasiObject;

/**
 * Defines data members and methods that are exposed by all jasi Solution
 * objects.  All data members are DataObjects rather than primative types so
 * they can handle the concepts of "nullness", "mutability", and
 * "change-state".<p>
 *
 * NULLNESS = a field can be null, i.e. unknown or no value. The traditional
 *  approach has been to insert zero or some bogus value. In ASCII
 *  representations sometimes a field was just left blank. For example: RMS
 *  'distance' might*simply be unknown. To give it a value of 0.0km could foul
 *  up other calculations. When you write data out to a database you want to
 *  leave * null fields null and not write a bunch of zeros that were used as
 *  an expedient *inside of an application.<p>
 *
 * MUTABLITY = some fields should NEVER be explicity manipulated by an
 * application.  These are usually "key" fields that would break the database or
 * cause constraint errors. They would be set immutable. Think of these as
 * "read-only".<p>
 *
 * CHANGE-STATE = this is primarily an efficiency issue. If you read in 1000
 * records, change 10 of them, then save your work, you only want to write
 * ('update') the changed records to the database.<p>
 *
 * The database can contain null values for
 * certain fields. Also applications may not want to write a "bogus" value like 0
 * into the database when when the real value is not known. Data primatives can't
 * be null and are initiallize to zero. */

public abstract class Solution extends JasiObject implements Lockable {

    /*
      Here's the list of public data members for a solution. These need to be
      supported by any port of this abstract layer
     */

    /** Unique integer ID number of the Solution */
    public DataLong    id		= new DataLong();
    /** Unique integer ID number of the Solution that was assigned by an
     * external source. Imported data must be given a "safe" (guaranteed unique)
     * local ID when it is imported. This data member remembers the original,
     * external ID. May be null. THis is a string because some networks (e.g. NEIC)
     * use letters and numbers in their ID codes. */
    public DataString  externalId	= new DataString();

    /** In some cases a Solution is "descended" or "cloned" from an original Solution.
    * This is the number of the "parent" Solution. May be null.*/
    public DataLong parentId       = new DataLong();

    /** Origin time in seconds since epoch start. (00:00 Jan. 1, 1970) */
    public DataDouble  datetime	   = new DataDouble();

    /** Latitude of the hypocenter, decimal degrees, N positive */
    public DataDouble  lat		= new DataDouble();
    /** Longitude of the hypocenter, decimal degrees, E positive */
    public DataDouble  lon		= new DataDouble();
    /** Depth of hypocenter in km below vertDatum. Negative is below datum */
    public DataDouble  depth		= new DataDouble();

    /** Datum for lat and long */
    public DataString  horizDatum	= new DataString();
    /** Datum for depth */
    public DataString  vertDatum	= new DataString();

    /** A string describing the solution type:
  "H"=hypocenter, "C"=centroid, "A"=amplitude */
    public DataString  type		= new DataString("H");

    /** String describing the location method */
    public DataString  method		= new DataString();
    /** String describing the crustal model used. */
    public DataString    crustModel = new DataString();
    /** String describing the velocity model used */
    public DataString    velModel	 = new DataString();

    /** Solution's origin authority. The 2-character FDSN network code from which this
        origin came. Default to network code set in EnvironmentInfo.
        @See: EnvironmentInfo.getNetworkCode */
    public DataString  authority  = new DataString(EnvironmentInfo.getNetworkCode());

    /** Authority of the initial declaration of the event. An event declared or created
    * by one authority may be relocated by another. Thus, the 'authority' and 'eventauthority'
    * would be different.*/
    public DataString  eventAuthority  = new DataString(EnvironmentInfo.getNetworkCode());

    /** Data source string. Describes the source of the Solution's origin (location)
        information. Optional site defined source string.
        Default to application name set in EnvironmentInfo.
        @See: EnvironmentInfo.getApplicationName */
    public DataString  source	  = new DataString(EnvironmentInfo.getApplicationName());

    /** Source of the initial declaration of the event. An event declared or created
    * by one application may be relocated by another. Thus, the 'source' and 'eventsource'
    * would be different. */
    public DataString  eventSource	= new DataString(EnvironmentInfo.getApplicationName());

    /** DataString containing username of the analyst that created this solution. */
    private DataString  who	= new DataString(EnvironmentInfo.getApplicationName());

    /** Largest azimuthal gap of solution in degrees. */
    public DataDouble  gap		= new DataDouble();

    /** Distance in km to the nearest station that contributed to the solution */
    public DataDouble  distance		= new DataDouble();
    /** RMS error of solution */
    public DataDouble  rms		= new DataDouble();
    /** Error in origin time in seconds. */
    public DataDouble  errorTime	= new DataDouble();
    /** Horizontal error in km. */
    public DataDouble  errorHoriz	= new DataDouble();
    /** Vertical error in km. */
    public DataDouble  errorVert	= new DataDouble();
    /** Latitude error in degrees. */
    public DataDouble  errorLat		= new DataDouble();
    /** Longitude error in degress. */
    public DataDouble  errorLon		= new DataDouble();
    /** Total phase readings, of all types associated with the solutions. */
    public DataLong    totalReadings	= new DataLong();
    /**  Total phase readings, of all types used in the solution. */
    public DataLong    usedReadings	= new DataLong();
    /**  Total S-phase readings, of all types used in the solution. */
    public DataLong    sReadings	= new DataLong();
    /** Total first motion reading associated with this solution */
    public DataLong    firstMotions	= new DataLong();

    /** Solution quality expressed as a number between 0.0 and 1.0; 0.0 is the worst*/
    public DataDouble  quality		= new DataDouble();

    /** Solution priority, this is a site defined value that can be used to
    * determine the priority of events for processing tasks. */
    public DataDouble  priority		= new DataDouble();

    /** A free-format comment text string. May not be supported by
    * all data sources or may be limited in length.*/
    public DataString  comment = new DataString();

    /** Equals 0 if the solution should not be considered valid. */
    final long DefaultValidFlag = 1;
    public DataLong    validFlag	= new DataLong(DefaultValidFlag);

    /** Equals 1 if this is a dummy solution. A dummy solution is often needed
    * to hold incomplete Solution information. For example a Solution for which
    * no viable location was possible. Events with type 'trigger' will usually
    * have dummyFlag = 1. */
    final long DefaultDummyFlag = 0;
    public DataLong    dummyFlag	= new DataLong(DefaultDummyFlag);

    /** A string describing the event type. Possible types are: <p>
  <ul>
  <li> local </li>
  <li> quarry </li>
  <li> regional </li>
  <li> teleseism </li>
  <li> sonic </li>
  <li> nuclear </li>
  <li> trigger </li>
      <li> unknown </li>
  </ul>
     @see: EventTypeMap
     */
    public DataString  eventType	= new DataString(EventTypeMap.getDefaultEventType());   //"unknown"

    /** State of processing. 'A'=automatic, 'H'=human, 'F'=final */
    final String DefaultProcessingState = EnvironmentInfo.getAutoString();
    public DataString  processingState	= new DataString(DefaultProcessingState);	// rflag

    public static int STATE_NONE = 0;
    public static int STATE_AUTOMATIC = 1;
    public static int STATE_HUMAN = 2;
    public static int STATE_FINAL = 3;

    /** True if the solution's depth is fixed. */
    // Defaults to "false". If you use "new Databoolean()" it sets isUpdate = true!
    public DataBoolean  depthFixed	= new DataBoolean();
    /** True if the solution's location is fixed. */
    public DataBoolean  locationFixed	= new DataBoolean();
    /** True if the solution's origin time is fixed. */
    public DataBoolean  timeFixed	= new DataBoolean();

    /** Number of waveforms associated with this solution */
    public DataLong    waveRecords	= new DataLong();

    /** List of alternate solutions for this solution. This list does not contain
     * the preferred (this) solution. */
    public SolutionList altSolList = new SolutionList();

    /** The preferred Magnitude associated with this Solution */
    //    public Magnitude magnitude = Magnitude.create();
    public Magnitude magnitude = null;

    /** Collection of alternate magnitudes associated with the solution.
     * This list does NOT contain the preferred magnitude so it is a list
     * on non-preferred mags. */
    public ArrayList altMagList = new ArrayList();

    /** List of phases associated with this Solution */
    //    public ArrayList phaseList = new ArrayList();
    public PhaseList phaseList = new PhaseList();

    /** List of Waveform object associated with this Solution.  Note that not
     * all schemas make a connection between solutions and waveforms.  This is
     * provided to accommodate those that do.*/
    public ArrayList waveformList = new ArrayList();

    /**
     * List of amplitude reading associated with this solution.
     */
    public AmpList ampList = new AmpList();

    /**
     * List of codas observations associated with this solution.
     */
    public CodaList codaList = new CodaList();  // AWW added 10/11/2000

    /** A solutionLock instance to support the Lockable interface. Will be null
    * if locking is not supported by the datasource */

    SolutionLock solLock = SolutionLock.create();

    /** Set true to lookup comments for each solution in the data source.
    * Default is 'true'. */
    protected boolean includeComment = true;

    /**
     * NOTE ON COLLECTIONS Java (SWING) Collections are abstract. The caller
     * must use a concrete subclass where ever "Collection" is used as an
     * argument or return type here. Use of the abstract type "Collection" here
     * allows the user to choose ANY subclass they choose with on modification to
     * the jasi classes. */

    /** True if changes have been made to the phase list and a relocation is
     needed.  */
    boolean isStale = false;

    /** True if changes have been made OR solution has been relocated and it
     needs to be recommited to the datasource.  */
    boolean needsCommit = false;

    /** Summary string describing status of the last commit operation. */
    protected String commitStatus = "";

    /** True if phase has been virtually deleted */
    boolean deleteFlag = false;

// //////////////////////////////////////////////////////////////////////
    /**
     * constructor is 'friendly' so that you can only instantiate jasi objects
     * using the 'create()' factory method.
     */
    public Solution() { }

// -- Concrete FACTORY METHODS ---
    /*
     o Must be static so we can call with Solution.create()
     o Can't be abstract in JasiObject because this must return a Solution object
       and JasiObject can only return Object.
     o Its final so concrete children can't override.
    */


    /**
     * Instantiate an object of this type. You do
     * NOT use a constructor. This "factory" method creates various
     * concrete implementations. Creates a Solution of the DEFAULT type.
     * @See: JasiObject
     */
     public static final Solution create() {
  return create(DEFAULT);
    }

    /**
     * Instantiate an object of this type. You do
     * NOT use a constructor. This "factory" method creates various
     * concrete implementations. The argument is an integer implementation type.
     * @See: JasiObject
     */
    public static final Solution create(int schemaType) {
      return create(JasiFactory.suffix[schemaType]);
    }

    /**
     * Instantiate an object of this type. You do
     * NOT use a constructor. This "factory" method creates various
     * concrete implementations. The argument is as 2-char implementation suffix.
     * @See: JasiObject
     */
    public static final Solution create(String suffix) {
  Solution sol = (Solution) JasiObject.newInstance("org.trinet.jasi.Solution", suffix);
        sol.setDefaultValues();
        return sol;
    }

    /**  Set true to lookup comments for each solution in the data source.*/
    public void setIncludeComment(boolean tf) {
      includeComment = tf;
    }
    /**  If true comments for each solution will be extracted from the data source.*/
    public boolean getIncludeComment(){
      return includeComment;
    }

    /**
    * Set the ID of the Solution. The ID must be a unique long integer.
    */
    public void setId (long id) {
      this.id.setValue(id);
    }
    /**
    * Return the ID of the Solution.
    */
    public DataLong getId () {
       return id;
    }

    /** Set the ID of the Solution this Solution is "descended" or "cloned" from.
    */
    public void setParentId ( long parentId) {
      this.parentId.setValue(parentId);
    }
    /** Return the ID of the Solution this Solution is "descended" or "cloned" from.
    */
    public DataLong getParentId () {
       return parentId;
    }

    /** Set the default values of some fields. Concrete classes can override this