SyncStrategy


1   /**
2    * Copyright (C) 2003-2005 Funambol
3    *
4    * This program is free software; you can redistribute it and/or modify
5    * it under the terms of the GNU General Public License as published by
6    * the Free Software Foundation; either version 2 of the License, or
7    * (at your option) any later version.
8    *
9    * This program is distributed in the hope that it will be useful,
10   * but WITHOUT ANY WARRANTY; without even the implied warranty of
11   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12   * GNU General Public License for more details.
13   *
14   * You should have received a copy of the GNU General Public License
15   * along with this program; if not, write to the Free Software
16   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
17   */
18  package sync4j.framework.engine;
19  
20  import java.security.Principal  ;
21  import java.sql.Timestamp  ;
22  
23  import sync4j.framework.engine.source.SyncSource;
24  import sync4j.framework.engine.SyncException;
25  import sync4j.framework.engine.SyncOperationStatus;
26  
27  /**
28   * It defines the interface of a Synchronization Strategy object. <br>
29   * It implements the <i>Strategy</i> partecipant of the Strategy Pattern.
30   * <p>
31   * It is usually called by the synchronization engine when a syncronization 
32   * action has to be performed.
33   * </p>
34   * There are two types of synchronization process: slow and fast.
35   * <h2>Slow synchronization</h2>
36   * A slow synchronization is when the sources to be synchronized must be fully 
37   * compared in order to reconstruct the right images of the data on both
38   * sources. The way the sets of items are compared is implementation specific
39   * and can vary from comparing just the key or the entire content of a SyncItem.
40   * In fact, in order to decide if two sync items are exactly the same or some
41   * filed has changed, all fields might riquire a comparison.<br>
42   * A slow sync is prepared calling <i>prepareSlowSync(...)</i>
43   *
44   * <h2>Fast synchronization</h2>
45   * In the case of fast synchronization, the sources are queried only for new,
46   * deleted or updated items since a given point in time. In this case the status
47   * of the items can be checked in order to decide when a deeper comparison is
48   * required.<br>
49   * A fast sync is prepared calling <i>prepareFastSync(...)</i>
50   *
51   * <h2>Synchronization principal</h2>
52   * <i>prepareXXXSync()</i> requires an additional <i>java.security.Principal</i> 
53   * parameter in input. The meaning of this parameter is implementation specific, 
54   * but as general rule, it is used to operate on the data specific for a given 
55   * entity such as a user, an application, a device, ecc.
56   *
57   * @see sync4j.framework.engine.source.SyncSource
58   * @see sync4j.framework.engine.SyncEngine
59   *
60   * @author Stefano Fornari @ Funambol
61   *
62   * @version $Id: SyncStrategy.java,v 1.9 2005/04/04 10:53:44 nichele Exp $
63   */
64  public interface SyncStrategy {
65      /**
66       * Fired when a synchornization action must be performed
67       *
68       * @param syncOperations the synchronization operations
69       */
70      SyncOperationStatus[] sync(SyncOperation[] syncOperations) throws SyncException ;
71  
72      /**
73       * Fired when a slow synchronization action must be prepared.
74       *
75       * @param sources the sources to be synchronized
76       * @param nextSync timestamp of the beginning of the current synchronization
77       * @param principal the entity for which the synchronization is required
78       * @param last is this the last call to prepareSlowSync ?
79       *
80       * @return an array of SyncOperation, one for each SyncItem that must be
81       *         created/updated/deleted or in conflict.
82       */
83      SyncOperation[] prepareSlowSync(SyncSource[] sources  ,
84                                      Principal      principal,
85                                      Timestamp      nextSync ,
86                                      boolean      last     ) 
87      throws SyncException;
88      
89      /**
90       * Fired when a fast synchronization action must be prepared.
91       *
92       * @param sources the sources to be synchronized
93       * @param lastSync timestamp of the last synchronization
94       * @param nextSync timestamp of the current synchronization
95       * @param principal the entity for which the synchronization is required
96       * @param since look for data earlier than this timestamp
97       * @param last is this the last call to prepareFastSync ?
98       *
99       * @return an array of SyncOperation, one for each SyncItem that must be
100      *         created/updated/deleted or in conflict.
101      */
102     SyncOperation[] prepareFastSync(SyncSource[] sources  ,
103                                     Principal      principal,
104                                     Timestamp      lastSync ,
105                                     Timestamp      nextSync ,
106                                     boolean      last     ) 
107     throws SyncException;
108     
109     /**
110      * Fired when a synchronization action must be finished.
111      */
112     void endSync() throws SyncException ;
113 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags