syncstrategy.java

实现了SyncML无线同步协议

/**
 * Copyright (C) 2003-2004 Funambol
 *
 *  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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 */
package sync4j.framework.engine;

import java.security.Principal;
import java.sql.Timestamp;

import sync4j.framework.engine.source.SyncSource;
import sync4j.framework.engine.SyncException;
import sync4j.framework.engine.SyncOperationStatus;

/**
 * It defines the interface of a Synchronization Strategy object. <br>
 * It implements the <i>Strategy</i> partecipant of the Strategy Pattern.
 * <p>
 * It is usually called by the synchronization engine when a syncronization 
 * action has to be performed.
 * </p>
 * There are two types of synchronization process: slow and fast.
 * <h2>Slow synchronization</h2>
 * A slow synchronization is when the sources to be synchronized must be fully 
 * compared in order to reconstruct the right images of the data on both
 * sources. The way the sets of items are compared is implementation specific
 * and can vary from comparing just the key or the entire content of a SyncItem.
 * In fact, in order to decide if two sync items are exactly the same or some
 * filed has changed, all fields might riquire a comparison.<br>
 * A slow sync is prepared calling <i>prepareSlowSync(...)</i>
 *
 * <h2>Fast synchronization</h2>
 * In the case of fast synchronization, the sources are queried only for new,
 * deleted or updated items since a given point in time. In this case the status
 * of the items can be checked in order to decide when a deeper comparison is
 * required.<br>
 * A fast sync is prepared calling <i>prepareFastSync(...)</i>
 *
 * <h2>Synchronization principal</h2>
 * <i>prepareXXXSync()</i> requires an additional <i>java.security.Principal</i> 
 * parameter in input. The meaning of this parameter is implementation specific, 
 * but as general rule, it is used to operate on the data specific for a given 
 * entity such as a user, an application, a device, ecc.
 *
 * @see sync4j.framework.engine.source.SyncSource
 * @see sync4j.framework.engine.SyncEngine
 *
 * @author Stefano Fornari @ Funambol
 *
 * @version $Id: SyncStrategy.java,v 1.6 2004/04/13 09:37:32 luigia Exp $
 */
public interface SyncStrategy {
    /**
     * Fired when a synchornization action must be performed
     *
     * @param syncOperations the synchronization operations
     */
    SyncOperationStatus[] sync(SyncOperation[] syncOperations) throws SyncException ;

    /**
     * Fired when a slow synchronization action must be prepared.
     *
     * @param sources the sources to be synchronized
     * @param principal the entity for which the synchronization is required
     *
     * @return an array of SyncOperation, one for each SyncItem that must be
     *         created/updated/deleted or in conflict.
     */
    SyncOperation[] prepareSlowSync(SyncSource[] sources, Principal principal) 
    throws SyncException;
    
    /**
     * Fired when a fast synchronization action must be prepared.
     *
     * @param sources the sources to be synchronized
     * @param principal the entity for which the synchronization is required
     * @param since look for data earlier than this timestamp
     *
     * @return an array of SyncOperation, one for each SyncItem that must be
     *         created/updated/deleted or in conflict.
     */
    SyncOperation[] prepareFastSync(SyncSource[] sources  , 
                                    Principal    principal,
                                    Timestamp    since    ) 
    throws SyncException;
    
    /**
     * Fired when a synchronization action must be finished.
     */
    void endSync() throws SyncException ;
}