/*
 *                    BioJava development code
 *
 * This code may be freely distributed and modified under the
 * terms of the GNU Lesser General Public Licence.  This should
 * be distributed with the code.  If you do not have a copy,
 * see:
 *
 *      http://www.gnu.org/copyleft/lesser.html
 *
 * Copyright for this code is held jointly by the individual
 * authors.  These should be listed in @author doc comments.
 *
 * For more information on the BioJava project and its aims,
 * or to join the biojava-l mailing list, visit the home page
 * at:
 *
 *      http://www.biojava.org/
 *
 */

package org.biojava.bio.program.xff;

import org.biojava.bio.Annotation;
import org.biojava.bio.MergeAnnotation;
import org.biojava.bio.OverlayAnnotation;
import org.biojava.bio.SmallAnnotation;
import org.biojava.bio.seq.Feature;
import org.biojava.bio.seq.io.ParseException;
import org.biojava.bio.symbol.Location;
import org.biojava.utils.AssertionFailure;
import org.biojava.utils.ChangeVetoException;
import org.biojava.utils.stax.DelegationManager;
import org.biojava.utils.stax.StAXContentHandler;
import org.biojava.utils.stax.StAXContentHandlerBase;
import org.biojava.utils.stax.StringElementHandlerBase;
import org.xml.sax.Attributes;
import org.xml.sax.SAXException;

/**
 * StAX handler for the basic <code>feature</code> type of XFF.
 * This class can also be subclassed to handle other XFF types.
 *
 * <p>
 * In general, to handle a <code>feature</code> subclass, you will
 * with to:
 * </p>
 *
 * <ul>
 * <li>If necessary, override createFeatureTemplate to build the appropriate BioJava
 *     Feature.Template</li>
 * <li>Add your own <code>startElement</code> and <code>endElement</code>
 *     methods which handle extra extra elements in your feature type.  These
 *     should normally pass on all the standard elements to
 *     <code>super.startElement</code> and <code>super.endElement</code>.</li>
 * </ul>
 *
 * <p>
 * Note that, since <code>FeatureHandler</code> does some basic housekeeping,
 * if you `consume' a startElement notification (i.e. don't pass it on to the
 * superclass) you must also consume the matching endElement.  Since FeatureHandler
 * silently ignores all unrecognized elements, it is usually safe to pass on
 * all startElement and endElement notifications -- even those which are specific
 * to your feature type.
 * </p>
 *
 * @author Thomas Down
 * @since 1.2
 */

public class FeatureHandler extends StAXContentHandlerBase {
    public static final XFFPartHandlerFactory FEATURE_HANDLER_FACTORY = new XFFPartHandlerFactory() {
            public StAXContentHandler getPartHandler(XFFFeatureSetHandler xffenv) {
                return new FeatureHandler(xffenv);
            }
        } ;

    private XFFFeatureSetHandler xffenv;
    private Feature.Template template = null;
    private boolean startFired = false;
    private boolean endFired = false;
    private int level = 0;

    /**
     * Construct a new Feature handler, passing in an XFF-parsing environment.
     */

    public FeatureHandler(XFFFeatureSetHandler xffenv) {
        this.xffenv = xffenv;
    }

    /**
     * Return the XFF processing environment passed in when this handler was
     * created.
     */

    public XFFFeatureSetHandler getXFFEnvironment() {
        return xffenv;
    }

    /**
     * Get the template for the feature being constructed.  This should
     * usually not be overridden.  Delegates to <code>createFeatureTemplate</code>
     * for template construction.
     */

    protected Feature.Template getFeatureTemplate() {
        if (template == null) {
            template = createFeatureTemplate();
        }
        return template;
    }

    /**
     * Create a new template of the appropriate type.  Override this method
     * if you wish to use a template type other than Feature.Template.
     */

    protected Feature.Template createFeatureTemplate() {
        return new Feature.Template();
    }

  /**
   * Fire the startFeature event.  You should wrap this method if you want
   * to perform any validation on the Feature.Template before the
   * startFeature is fired.
   *
   * @throws ParseException if the startFeature notification fails, or if
   *                        it has already been made.
   */

  protected void fireStartFeature()
          throws ParseException
  {
    if (startFired) {
      throw new ParseException("startFeature event has already been fired for this feature");
    }

    Feature.Template templ = getFeatureTemplate();
    Annotation ann = getXFFEnvironment().getMergeAnnotation();
    Annotation orig = templ.annotation;
    Annotation res = null;

    if(ann != null && orig != null) {
      try {
        MergeAnnotation ma = new MergeAnnotation();
        ma.addAnnotation(templ.annotation);
        ma.addAnnotation(ann);
        res = ma;
      } catch (ChangeVetoException cve) {
        throw new AssertionFailure(cve);
      }
    } else if(ann != null) {
      res = ann;
    } else if(orig != null) {
      res = orig;
    }

    if(res == null) {
      res = new SmallAnnotation();
    } else {
      res = new OverlayAnnotation(res);
    }

    templ.annotation = res;

    getXFFEnvironment().getFeatureListener().startFeature(templ);
    startFired = true;
  }

    /**
     * Fire the endFeature event.
     */

    protected void fireEndFeature()
        throws ParseException
    {
        if (!startFired) {
            throw new ParseException("startFeature has not yet been fired for this feature.");
        }

        if (endFired) {
            throw new ParseException("endFeature event has already been fired for this feature");
        }

        getXFFEnvironment().getFeatureListener().endFeature();
        endFired = true;
    }

    /**
     * Set a property.  If the startFeature notification has not yet been fired,
     * the property is added directly to the annotation bundle in the feature
     * template, otherwise an addFeatureProperty event is generated.
     */

    protected void setFeatureProperty(Object key, Object value)
        throws ChangeVetoException, ParseException
    {
        if (startFired) {
            getXFFEnvironment().getFeatureListener().addFeatureProperty(key, value);
        } else {
            Feature.Template ft = getFeatureTemplate();
            if (ft.annotation == null) {
                ft.annotation = new SmallAnnotation();
            }
            ft.annotation.setProperty(key, value);
        }
    }

    /**
     * StAX callback for element starts.  Wrap this method to handle extra
     * elements within your own feature types.
     */

    public void startElement(String nsURI,
                             String localName,
                             String qName,
                             Attributes attrs,
                             DelegationManager dm)
         throws SAXException
    {
        level++;
        if (level == 1) {
            // This was our initial startElement.
            String id = attrs.getValue("id");
            if (id != null) {
                try {
                    setFeatureProperty(XFFFeatureSetHandler.PROPERTY_XFF_ID, id);
                } catch (Exception ex) {
                    throw new SAXException("Couldn't set property", ex);
                }
            }
        } else {
            if (localName.equals("type")) {
                dm.delegate(getTypeHandler());
            } else if (localName.equals("source")) {
                dm.delegate(getSourceHandler());
            } else if (localName.equals("location")) {
                dm.delegate(getLocationHandler());
            } else if (localName.equals("id")) {
                dm.delegate(getOldIDHandler());
            } else if (localName.equals("details")) {
                if (!startFired) {
                    try {
                        fireStartFeature();
                    } catch (ParseException ex) {
                        throw new SAXException(ex);
                    }
                }

                dm.delegate(xffenv.getDetailsHandler());

                // Need to handle details properly
            } else if (localName.equals("featureSet")) {
                if (!startFired) {
                    try {
                        fireStartFeature();
                    } catch (ParseException ex) {
                        throw new SAXException(ex);
                    }
                }

                dm.delegate(xffenv);
            } else {
                // throw new SAXException("Couldn't recognize element " + localName + " in namespace " + nsURI);
            }
        }
    }

    /**
     * StAX callback for element ends.  Wrap this method to handle extra
     * elements within your own feature types.
     */

    public void endElement(String nsURI,
                           String localName,
                           String qName,
                           StAXContentHandler handler)
        throws SAXException
    {
        level--;

        if (level == 0) {
            // Our tree is done.

            try {
                if (!startFired) {
                    fireStartFeature();
                }

                if (!endFired) {
                    fireEndFeature();
                }
            } catch (ParseException ex) {
                throw new SAXException(ex);
            }
        }
    }

    protected StAXContentHandler getTypeHandler() {
        return new StringElementHandlerBase() {
                protected void setStringValue(String s) {
                    getFeatureTemplate().type = s.trim();
                }
            } ;
    }

    protected StAXContentHandler getSourceHandler() {
        return new StringElementHandlerBase() {
                protected void setStringValue(String s) {
                    getFeatureTemplate().source = s.trim();
                }
            } ;
    }

    protected StAXContentHandler getOldIDHandler() {
        return new StringElementHandlerBase() {
                protected void setStringValue(String s)
                    throws SAXException
                {
                    try {
                        setFeatureProperty(XFFFeatureSetHandler.PROPERTY_XFF_ID, s.trim());
                    } catch (Exception ex) {
                        throw new SAXException("Couldn't set property", ex);
                    }
                }
            } ;
    }

    protected StAXContentHandler getLocationHandler() {
        return new LocationHandlerBase() {
                protected void setLocationValue(Location l) {
                    getFeatureTemplate().location = l;
                }
            } ;
    }
}