/*
 *    Geotoolkit - An Open Source Java GIS Toolkit
 *    http://www.geotoolkit.org
 *
 *    (C) 2009, Geomatys
 *
 *    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.geotoolkit.data.session;

import java.util.Collection;
import java.util.Map;
import org.apache.sis.storage.DataStoreException;
import org.geotoolkit.data.FeatureCollection;
import org.geotoolkit.data.FeatureIterator;
import org.geotoolkit.data.FeatureStore;
import org.geotoolkit.data.query.Query;
import org.geotoolkit.storage.StorageListener;
import org.geotoolkit.version.Version;
import org.opengis.feature.Feature;
import org.opengis.util.GenericName;
import org.opengis.filter.Filter;
import org.opengis.geometry.Envelope;

/**
 * This object holds a serie of alteration made against the feature store
 * but thoses are not pushed on the feature store until the commit() method has been called.
 *
 * If we had follow the WFS specification this class would have been named transaction
 * but we choose to use the name Session given by JSR-170 and JSR-283 (Java Content Repository).
 * 
 * @author Johann Sorel (Geomatys)
 * @module
 */
public interface Session {

    /**
     * Get the feature store attached to this session.
     * @return FeatureStore, never null
     */
    FeatureStore getFeatureStore();

    /**
     * Check if the session is asynchrone.
     * If it is asynchrone then a call to commit is necessary to push all
     * changes to the feature store.
     * 
     * @return true if this session is asynchrone
     */
    boolean isAsynchrone();

    /**
     * Get session version. 
     * This version will be used on all queries passing through this session.
     * If a session is set, writing operations will systematicaly raise an exception.
     * 
     * @return Version, can be null
     */
    Version getVersion();
    
    /**
     * Request a collection of features that match the given query.
     *
     * @param query collections query
     * @return FeatureCollection , never null
     */
    FeatureCollection getFeatureCollection(Query query);

    /**
     * Get a feature iterator that can be used only for reading.
     * Use add, update and remove methods for other purposes.
     *
     * @param query
     * @return FeatureIterator
     * @throws DataStoreException
     */
    FeatureIterator getFeatureIterator(Query query) throws DataStoreException;

    /**
     * Same behavior as @see FeatureStore#updateFeatures(org.opengis.feature.type.Name, java.util.Collection)
     * but makes modification in the session diff if this one is asynchrone.
     * @param groupName
     * @param newFeatures
     * @throws org.apache.sis.storage.DataStoreException
     */
    void addFeatures(String groupName, Collection<? extends Feature> newFeatures) throws DataStoreException;

    /**
     * Same behavior as @see FeatureStore#updateFeatures(org.opengis.feature.type.Name, org.opengis.filter.Filter, java.util.Map)
     * but makes modification in the session diff if this one is asynchrone.
     * @param groupName
     * @param filter
     * @param values
     * @throws org.apache.sis.storage.DataStoreException
     */
    void updateFeatures(String groupName, Filter filter, Map<String, ?> values) throws DataStoreException;

    /**
     * Same behavior as @see FeatureStore#removeFeatures(org.opengis.feature.type.Name, org.opengis.filter.Filter)
     * but makes modification in the session diff if this one is asynchrone.
     * @param groupName
     * @param filter
     * @throws org.apache.sis.storage.DataStoreException
     */
    void removeFeatures(String groupName, Filter filter) throws DataStoreException;

    /**
     * Returns true if this session holds pending (that is, unsaved) changes; otherwise returns false. 
     * @return
     */
    boolean hasPendingChanges();

    /**
     * Apply all the changes made in this session on the featurestore.
     *
     * @throws DataStoreException
     */
    void commit() throws DataStoreException;

    /**
     * Revert all changes made in this session.
     */
    void rollback();

    /**
     * Same behavior as @see FeatureStore#getCount(org.geotoolkit.data.query.Query)
     * but take in consideration the session modifications.
     * @param query
     * @return
     * @throws org.apache.sis.storage.DataStoreException
     */
    long getCount(Query query) throws DataStoreException;

    /**
     * Same behavior as @see FeatureStore#getEnvelope(org.geotoolkit.data.query.Query)
     * but take in consideration the session modifications.
     * @param query
     * @return
     * @throws org.apache.sis.storage.DataStoreException
     */
    Envelope getEnvelope(Query query) throws DataStoreException;

    /**
     * Add a storage listener which will be notified when schema are added, modified or deleted
     * and when features are added, modified or deleted.
     *
     * This includes events from the feature store and events from the session.
     *
     * @param listener to add
     */
    void addStorageListener(StorageListener listener);

    /**
     * Remove a storage listener
     * @param listener to remove
     */
    void removeStorageListener(StorageListener listener);

}