/*
 *    GeoTools - The Open Source Java GIS Toolkit
 *    http://geotools.org
 * 
 *    (C) 2008, Open Source Geospatial Foundation (OSGeo)
 *
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License as published by the Free Software Foundation;
 *    version 2.1 of the License.
 *
 *    This library is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *    Lesser General Public License for more details.
 */
package org.geotools.data;

import java.io.IOException;
import java.util.List;

import org.opengis.feature.Feature;
import org.opengis.feature.type.AttributeDescriptor;
import org.opengis.feature.type.FeatureType;
import org.opengis.feature.type.Name;
import org.opengis.filter.Filter;
import org.opengis.filter.identity.FeatureId;
import org.geotools.feature.FeatureCollection;


/**
 * This interface extends {@code FeatureSource}, adding methods to add and remove
 * features and to modify existing features.
 * <pre><code>
 * DataStore myDataStore = ...
 * FeatureSource featureSource = myDataStore.getFeatureSource("aname");
 * if (featureSource instanceof FeatureStore) {
 *     // we have write access to the feature data
 *     FeatureStore featureStore = (FeatureStore) featureSource;
 *
 *     // add some new features
 *     Transaction t = new DefaultTransaction("add");
 *     featureStore.setTransaction(t);
 *     try {
 *         featureStore.addFeatures( someFeatures );
 *         t.commit();
 *     } catch (Exception ex) {
 *         ex.printStackTrace();
 *         t.rollback();
 *     } finally {
 *         t.close();
 *     }
 * }
 * </code></pre>
 *
 * @author Jody Garnett
 * @author Ray Gallagher
 * @author Rob Hranac, TOPP
 * @author Chris Holmes, TOPP
 *
 * @source $URL: http://svn.osgeo.org/geotools/branches/2.7.x/modules/library/api/src/main/java/org/geotools/data/FeatureStore.java $
 * @version $Id: FeatureStore.java 37280 2011-05-24 07:53:02Z mbedward $
 */
public interface FeatureStore<T extends FeatureType, F extends Feature> extends FeatureSource<T, F> {
    /**
     * Adds all features from the feature collection.
     * <p>
     * A list of {@code FeatureIds} is returned, one for each feature in the order created.
     * However, these might not be assigned until after a commit has been performed.
     * 
     * @param collection the collection of features to add
     *
     * @return the {@code FeatureIds} of the newly added features
     *
     * @throws IOException if an error occurs modifying the data source
     */
    List<FeatureId> addFeatures(FeatureCollection<T, F> collection) throws IOException;

    /**
     * Removes features selected by the given filter.
     *
     * @param filter an OpenGIS filter
     *
     * @throws IOException if an error occurs modifying the data source
     */
    void removeFeatures(Filter filter) throws IOException;

    /**
     * Modifies the attributes with the supplied values in all
     * features selected by the given filter.
     *
     * @param attributeNames the attributes to modify
     *
     * @param attributeValues the new values for the attributes
     *
     * @param filter an OpenGIS filter
     *
     * @throws IOException if the attribute and object arrays are not equal
     *         in length; if the value types do not match the attribute types;
     *         if modification is not supported; or if there errors accessing the
     *         data source
     */
    void modifyFeatures( Name[] attributeNames, Object[] attributeValues, Filter filter )  throws IOException;

    /**
     * For backwards compatibility; please be careful that your descriptor is
     * actually compatible with the one declared.
     * 
     * @param type the attributes to modify
     *
     * @param value the new values for the attributes
     *
     * @param filter an OpenGIS filter
     *
     * @throws IOException
     *
     * @deprecated Please use the safer method {@link #modifyFeatures(Name[], Object[], Filter)}
     */
    void modifyFeatures(AttributeDescriptor[] type, Object[] value, Filter filter) throws IOException;
    
    /**
     * Modifies an attribute with the supplied value in all features
     * selected by the given filter.
     *
     * @param attributeName the attribute to modify
     *
     * @param attributeValue the new value for the attribute
     *
     * @param filter an OpenGIS filter
     *
     * @throws IOException if modification is not supported; if the value type does
     *         not match the attribute type; or if there errors accessing the data source
     */
    void modifyFeatures( Name attributeName, Object attributeValue, Filter filter )  throws IOException;
    
    /**
     * For backwards compatibility; please be careful that your descriptor is actually compatible
     * with the one declared.
     *
     * @param type the attribute to modify
     *
     * @param value the new value for the attribute
     *
     * @param filter an OpenGIS filter
     *
     * @throws IOException
     *
     * @deprecated Please use the safer method {@link #modifyFeatures(Name, Object, Filter)}
     */
    void modifyFeatures(AttributeDescriptor type, Object value, Filter filter)
        throws IOException;

    /**
     * Deletes any existing features in the data source and then
     * inserts new features provided by the given reader. This is primarily used
     * as a convenience method for file-based data sources.
     *
     * @param reader - the collection to be written
     *
     * @throws IOException if there are any datasource errors.
     */
    void setFeatures(FeatureReader<T, F> reader) throws IOException;

    /**
     * Provide a transaction for commit/rollback control of a modifying
     * operation on this {@code FeatureStore}.
     * <pre><code>
     * Transation t = new DefaultTransaction();
     * featureStore.setTransaction(t);
     * try {
     *     featureStore.addFeatures( someFeatures );
     *     t.commit();
     * } catch ( IOException ex ) {
     *     // something went wrong;
     *     ex.printStackTrace();
     *     t.rollback();
     * } finally {
     *     t.close();
     * }
     * </code></pre>
     *
     * @param transaction the transaction
     */
    void setTransaction(Transaction transaction);

    /**
     * Gets the {@code Transaction} that this {@code FeatureStore} is
     * currently operating against.
     * <pre><code>
     * Transaction t = featureStore.getTransaction();
     * try {
     *     featureStore.addFeatures( features );
     *     t.commit();
     * } catch( IOException erp ){
     *     // something went wrong;
     *     ex.printStackTrace();
     *     t.rollback();
     * }
     * </code></pre>
     *
     * @return Transaction in use, or {@linkplain Transaction#AUTO_COMMIT}
     */
    Transaction getTransaction();
}
