SyncSource


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.source;
19  
20  import sync4j.framework.engine.SyncItem;
21  import sync4j.framework.engine.SyncItemKey;
22  
23  import java.security.Principal  ;
24  import java.sql.Timestamp  ;
25  
26  /**
27   * A <i>SyncSource</i> is responsible for the storing and retrieving of 
28   * <i>SyncItem</i> objects. It is used also for getting newly created or removed
29   * <i>SyncItem</i>s.<br>
30   * Note that the <i>SyncSource</i> inteface doesn't make any assumption about the
31   * underlying data source. Each concrete implementation will use the storage its
32   * specific database.
33   *
34   * @author Stefano Fornari @ Funambol
35   *
36   * @version $Id: SyncSource.java,v 1.20 2005/03/02 20:57:37 harrie Exp $
37   */
38  public interface SyncSource {
39      
40      // ---------------------------------------------------------- Public Methods
41      
42      /**
43       * Returns the name of the source
44       *
45       * @return the name of the source
46       */
47      public String   getName();
48      
49      /**
50       * Returns the query.
51       *
52       * @return Value of query.
53       */
54      public String   getSourceQuery();
55  
56      /**
57       * Returns the source URI
58       *
59       * @return the absolute URI of the source
60       */
61      public String   getSourceURI();
62      
63      /**
64       * Returns the type of the source, for instance, text/x-vcard)
65       *
66       * @return the type of the source
67       */
68      public String   getType();
69  
70      /**
71       * Returns the type info of the content handled by this source
72       *
73       * @return the type info of the content handled by this source
74       */
75      public SyncSourceInfo getInfo();
76      
77      /**
78       * Called before any other synchronization method. To interrupt the sync
79       * process, throw a SyncSourceException. 
80       *
81       * @param principal the principal for which the data has to be considered. 
82       *                  Null means all principals
83       * @param syncMode the synchronization mode being performed
84       *
85       * @throws SyncSourceException to interrupt the process with an error
86       */
87      void beginSync(Principal   principal, int syncMode) throws SyncSourceException;
88      
89      /**
90       * Called after the modifications have been applied and just before commit
91       * the source synchronization. To interrupt the committing, throw a 
92       * SyncSourceException.
93       *     
94       * @param principal the principal for which the data has to be considered. 
95       *                  Null means all principals
96       *
97       * @throws SyncSourceException to interrupt the process with an error
98       */
99      void endSync(Principal   principal) throws SyncSourceException;
100 
101     /**
102      * @param principal the principal for which the data has to be considered. 
103      *                  Null means all principals
104      * @param since consider the changes since this point in time. Null means 
105      *              all items regardless when they was changed.
106      *
107      * @return an array of keys containing the <i>SyncItem</i>'s key of the updated
108      *         items after the last synchronizazion. It MUST NOT return null for
109      *         no keys, but instad an empty array.
110      */
111     public SyncItemKey[] getUpdatedSyncItemKeys(Principal   principal,
112                                                 Timestamp   since    )
113     throws SyncSourceException ;
114 
115     /**
116      * @param principal the principal for which the data has to be considered
117      *                  Null means all principals
118      * @param since consider the changes since this point in time. Null means 
119      *              all items regardless when they was changed.
120      *
121      * @return an array of keys containing the <i>SyncItem</I>'s key of the updated
122      *         items after the last synchronizazion. It MUST NOT return null for
123      *         no keys, but instad an empty array.
124      */
125     public SyncItem[] getUpdatedSyncItems(Principal   principal,
126                                           Timestamp   since    ) 
127     throws SyncSourceException ;
128 
129     /**
130      * Replaces an existing <i>SyncItem</i> or adds a new <i>SyncItem</i> if it 
131      * does not exist. The item is also returned giving the opportunity to the
132      * source to modify its content and return the updated item (i.e. updating
133      * the id to the GUID).
134      *
135      * @param principal the entity that wants to do the operation
136      * @param syncInstance  the bean to replace/add
137      *
138      * @return the inserted/updated item
139      *
140      * @throws SyncSourceException in case of error (for instance if the
141      *         underlying data store runs into problems)
142      */
143     public SyncItem setSyncItem(Principal   principal, SyncItem syncInstance) 
144     throws SyncSourceException ;
145 
146     /**
147      * Replaces existing SyncItems or adds new SyncItems if they do not 
148      * exist.
149      *
150      * @param principal the entity that wants to do the operation
151      * @param syncItems  the beans to be replaced/added
152      *
153      * @return the inserted/updated 
154      *
155      * @throws SyncSourceException in case of error (for instance if the
156      *         underlying data store runs into problems)
157      */
158     public SyncItem[] setSyncItems(Principal   principal, SyncItem[] syncItems) 
159     throws SyncSourceException ;
160 
161     /**
162      * Removes a SyncItem given its key.
163      *
164      * @param principal the entity that wants to do the operation
165      * @param syncItem  the item to remove
166      *
167      * @throws SyncSourceException in case of error (for instance if the
168      *         underlying data store runs into problems)
169      */
170     public void removeSyncItem(Principal   principal, SyncItem syncItem) 
171     throws SyncSourceException ;
172 
173     /**
174      * Removes the given <i>SyncItem</i>s.
175      *
176      * @param principal the entity that wants to do the operation
177      * @param syncItems  the items to remove
178      *
179      * @throws SyncSourceException in case of error (for instance if the
180      *         underlying data store runs into problems)
181      */
182     public void removeSyncItems(Principal   principal, SyncItem[] syncItems) 
183     throws SyncSourceException;
184     
185     /**
186      * @param principal the principal for which the data has to be considered
187      *                  Null means all principals
188      * @param since consider the changes since this point in . Null means 
189      *              all items regardless when they was changed.
190      *
191      * @return an array of keys containing the <i>SyncItem</i>'s key of the newly 
192      *         created items after the last synchronizazion. If there are no new
193      *         items an empty array MUST BE returned. 
194      *
195      * @throws SyncSourceException in case of error (for instance if the
196      *         underlying data store runs into problems)
197      */
198     public SyncItemKey[] getNewSyncItemKeys(Principal   principal,
199                                             Timestamp   since    ) 
200     throws SyncSourceException ;
201 
202     /**
203      * @param principal the principal for which the data has to be considered
204      *                  Null means all principals
205      * @param since consider the changes since this point in time. Null means 
206      *              all items regardless when they was changed.
207      *
208      * @return an array of keys containing the <i>SyncItem</i>'s key of the newly 
209      *         created items after the last synchronizazion. If there are no new
210      *         items an empty array is returned.
211      *
212      * @throws SyncSourceException in case of error (for instance if the
213      *         underlying data store runs into problems)
214      */
215     public SyncItem[] getNewSyncItems(Principal   principal,
216                                       Timestamp   since    ) 
217     throws SyncSourceException ;
218 
219     /**
220      * @param principal the principal for which the data has to be considered
221      *                  Null means all principals
222      * @param since consider the changes since this point in time. Null means 
223      *              all items regardless when they was changed.
224      *
225      * @return an array of keys containing the <i>SyncItem</i>'s key of the deleted
226      *         items after the last synchronizazion. If there are no deleted
227      *         items an empty array is returned.
228      *
229      * @throws SyncSourceException in case of error (for instance if the
230      *         underlying data store runs into problems)
231      */
232     public SyncItemKey[] getDeletedSyncItemKeys(Principal   principal,
233                                                 Timestamp   since    ) 
234     throws SyncSourceException ;
235 
236     /**
237      * @param principal the principal for which the data has to be considered
238      *                  Null means all principals
239      * @param since consider the changes since this point in time. Null means 
240      *              all items regardless when they was changed.
241      *
242      * @return an array of keys containing the <i>SyncItem</i>'s key of the deleted
243      *         items after the last synchronizazion. If there are no deleted
244      *         items an empty array is returned.
245      *
246      * @throws SyncSourceException in case of error (for instance if the
247      *         underlying data store runs into problems)
248      */
249     public SyncItem[] getDeletedSyncItems(Principal   principal,
250                                           Timestamp   since    )
251     throws SyncSourceException ;
252 
253     /**
254      * @param principal the principal for which the data has to be considered
255      *                  Null means all principals
256      *
257      * @return an array of all <i>SyncItem</i>s stored in this source. If there 
258      *         are no items an empty array is returned.
259      *
260      * @throws SyncSourceException in case of error (for instance if the
261      *         underlying data store runs into problems)
262      */
263     public SyncItem[] getAllSyncItems(Principal   principal)
264     throws SyncSourceException;
265 
266     /**
267      * @return an array containing the <i>SyncItem</i>s corresponding to the given
268      *         array of keys. Unexisting keys must be silently ignored.
269      *
270      * @param principal look for data belonging to this principal, or null for 
271      *        not user-related searching
272      * @param syncItemKeys  the keys of the SyncItems to return
273      *
274      * @throws SyncSourceException in case of error (for instance if the
275      *         underlying data store runs into problems)
276      */
277     public SyncItem[] getSyncItemsFromIds(Principal   principal, SyncItemKey[] syncItemKeys) throws SyncSourceException;
278     
279     /**
280      * @return return the <i>SyncItem</i>s corresponding to the given
281      *         key. If no item is found, null is returned
282      *
283      * @param principal look for data belonging to this principal, or null for 
284      *        not user-related searching
285      * @param syncItemKey  the key of the SyncItem to return
286      *
287      * @throws SyncSourceException in case of errors (for instance if the
288      *         underlying data store runs into problems)
289      */
290     public SyncItem getSyncItemFromId(Principal   principal, SyncItemKey syncItemKey) throws SyncSourceException;
291     
292     /**
293      * @return an item from a twin item. Each source implementation is free to 
294      *         interpret this as it likes (i.e.: comparing all fields).
295      *
296      * @param principal look for data belonging to this principal, or null for 
297      *        not user-related searching
298      * @param syncItem the twin item
299      *
300      * @throws SyncSourceException in case of errors (for instance if the
301      *         underlying data store runs into problems)
302      */
303     public SyncItem getSyncItemFromTwin(Principal   principal, SyncItem syncItem) throws SyncSourceException;
304     
305     /**
306      * @return an array of items from corresponding twin items. Each source 
307      *         implementation is free to interpret this as it likes (i.e.: 
308      *         comparing all fields).
309      * @param principal look for data belonging to this principal, or null for 
310      *        not user-related searching 
311      * @param syncItems the twin items
312      *
313      * @throws SyncSourceException in case of errors (for instance if the
314      *         underlying data store runs into problems)
315      */
316     public SyncItem[] getSyncItemsFromTwins(Principal   principal, SyncItem[] syncItems) throws SyncSourceException;
317 }
318
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags