Application: gvSIG desktop » gvSIG tools: Vector editing

/**

 * gvSIG. Desktop Geographic Information System.

 *

 * Copyright ? 2007-2014 gvSIG Association

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or (at your option) any later version.

 *

 * This program 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 General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,

 * MA  02110-1301, USA.

 *

 * For any additional information, do not hesitate to contact us

 * at info AT gvsig.com, or visit our website www.gvsig.com.

 */

package org.gvsig.vectorediting.lib.api;

import java.util.List;

import org.gvsig.fmap.dal.feature.FeatureStore;

import org.gvsig.fmap.geom.Geometry;

import org.gvsig.fmap.geom.primitive.Point;

import org.gvsig.tools.service.Service;

import org.gvsig.vectorediting.lib.api.exceptions.DrawServiceException;

import org.gvsig.vectorediting.lib.api.exceptions.FinishServiceException;

import org.gvsig.vectorediting.lib.api.exceptions.InvalidEntryException;

import org.gvsig.vectorediting.lib.api.exceptions.StartServiceException;

import org.gvsig.vectorediting.lib.api.exceptions.StopServiceException;

/**

 * <p>

 * This service is used to interact with Editing providers. Each instance of

 * this has linked an Editing provider. At this moment services delegate all

 * functionality to providers. To get an instance of this use

 * {@link EditingManager#getEditingService(String, org.gvsig.fmap.dal.feature.FeatureStore)}

 * </p>

 * 

 * @author gvSIG team.

 * @version $Id$

 */

public interface EditingService extends Service {

    /**

     * Gets state of drawing. If this service has sufficient values with mouse

     * position to create geometries returns a {@link DrawingStatus}. List of

     * geometries of drawing status object can be different from final

     * geometries. Use this method to get a draft status information while user

     * is drawing.

     *

     * @param mousePosition

     *            Mouse position to draw geometries.

     * @return A {@link DrawingStatus} object with a list of geometries and

     *         information.

     * @throws DrawServiceException

     *             if there are some error creating geometries.

     */

    public DrawingStatus getDrawingStatus(Point mousePosition)

        throws DrawServiceException;

    /**

     * Gets a <code>List</code> with all parameters of service. Each parameter

     * has name, description and types. See {@link EditingServiceParameter}.

     *

     * @return A list of {@link EditingServiceParameter} objects.

     */

    public List<EditingServiceParameter> getParameters();

    /**

     * Gets next parameter needed by service. The parameter has information

     * about its name, description and types. Returns <code>null</code> if all

     * parameters have values.

     *

     * @return An {@link EditingServiceParameter} object that represents the

     *         next parameter.

     */

    public EditingServiceParameter next();

    /**

     * Sets value to service. The value will be put in the next parameter need

     * by this service.

     *

     * @param value

     *            Object to be set to next {@link EditingServiceParameter}

     * @throws InvalidEntryException

     *             If the next parameter needed does not accept this value.

     */

    public void setValue(Object value) throws InvalidEntryException;

    /**

     * Sets value into a paremeter of the service.The value will be put in the parameter of this service.

     *

     * @param parameter {@link EditingServiceParameter}

     * @param value

     *            Object to be set to {@link EditingServiceParameter}

     * @throws InvalidEntryException

     *             If the next parameter needed does not accept this value.

     */

    public void setValue(EditingServiceParameter parameter, Object value) throws InvalidEntryException;

    /**

     * Return true if the parameter is enabled

     * 

     * @param parameter

     * @return

     */

    public boolean isEnabled(EditingServiceParameter parameter);

    /**

     * Stops service. Use this method to stop and clean values of service.

     *

     * @throws StopServiceException

     *             Stops service initializing necessary parameters of service.

     *             This method is called when user cancels service.

     */

    public void stop() throws StopServiceException;

    /**

     * Finalizes service. Use this method to get the result of service without

     * store it to {@link FeatureStore}. Make sure that service has all required

     * values.

     *

     * @return Geometry created or modified from added values.

     * @throws FinishServiceException

     *             if there are some error getting values,

     *             creating geometries.

     */

    public Geometry finish() throws FinishServiceException;

    /**

     * Finalizes service and stores the result to {@link FeatureStore} of this

     * service. Use this method to store the result of this service. Make sure

     * that service has all required values.

     *

     * @throws FinishServiceException

     *             if there are some error getting values,

     *             creating geometries or inserting/updating/removing geometries

     *             from feature store.

     */

    public void finishAndStore() throws FinishServiceException;

    /**

     * Starts service. Use this method before add values.

     *

     * @throws StartServiceException

     *             if there are some error starting service.

     * @throws InvalidEntryException

     *             if the entry of provider is not valid

     */

    public void start() throws StartServiceException, InvalidEntryException;

    /**

     * Gets service name. The name of service is the same name of linked

     * provider.

     *

     * @return Name of service.

     */

    public String getName();

    /**

     * Activate service

     */

    public void activate();

    /**

     * Return the parameter's value

     * 

     * @param parameter

     * @return

     */

    public Object getValue(EditingServiceParameter parameter);

}