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  
19  package sync4j.syncclient.spds.engine;
20  
21  import java.io.*;
22  import java.util.Date  ;
23  import java.security.Principal  ;
24  
25  import sync4j.syncclient.spds.SyncException;
26  
27  /**
28   * A <i>SyncSource</i> is responsible for storing and retrieving <i>SyncItem</i>
29   * objects from/to an external data source.
30   * Note that the <i>SyncSource</i> interface makes no assumptions about the
31   * underlying data source or about how data are formatted: each concrete
32   * implementation will use its specific storage and formae.
33   * <p>
34   * A <i>SyncSource</i> is not used directly by the host application, instead its
35   * methods are called by the synchronization engine during modifications analysis.
36   * <p>
37   * The SyncSource methods are designed to perform an efficient synchronization
38   * process, letting the source selecting the changed items instead of doing more
39   * complex field by field comparison. It is responsibility of the source
40   * developer to make sure that the <i>getNew/Updated/DeletedSyncItems()</i>
41   * methods return the correct values.
42   * <p>
43   * The configuration information required to set up a SyncSource is stored in
44   * the device management store under the context ./syncml/sources with the
45   * structure below:
46   * <pre>
47   *    .../<i>{source name}</i>
48   *        + class
49   *        + uri
50   *        + type
51   *        + ... other properties ...
52   * </pre>
53   *
54   * Where <i>other properties</i> are implementation specific and are set by the
55   * engine when the source is instantiated.
56   *
57   *  @author Fabio Maggi
58   *  @version $Id: SyncSource.java,v 1.3 2005/07/14 10:18:02 harrie Exp $
59   **/
60  
61  public interface SyncSource {
62  
63      /**
64       * Returns the name of the source
65       *
66       * @return the name of the source
67       */
68      public String   getName();
69  
70      /**
71       * Returns the source URI
72       *
73       * @return the absolute URI of the source
74       */
75      public String   getSourceURI();
76  
77      /**
78       * Returns the type of the source.
79       * The types are defined as mime-types, for instance * text/x-vcard).
80       * @return the type of the source
81       */
82      public String   getType();
83  
84      /**
85       * Returns all items in the data store belonging to the given principal.
86       *
87       * @param principal not used, always null
88       *
89       * @return an array of all <i>SyncItem</i>s stored in this source. If there
90       *         are no items an empty array is returned.
91       *
92       * @throws SyncException in case of error (for instance if the
93       *         underlying data store runs into problems)
94       */
95      public SyncItem[] getAllSyncItems(Principal   principal)
96      throws SyncException;
97  
98  
99      /**
100      * Returns all deleted items belonging to the given principal and deleted
101      * after the given point in time.
102      *
103      * @param principal the principal for which the data has to be considered
104      *                  Null means all principals
105      * @param since consider the changes since this point in time. Null means
106      *              all items regardless when they were changed.
107      *
108      * @return an array of keys containing the <i>SyncItem</i>'s key of the deleted
109      *         items after the last synchronizazion. If there are no deleted
110      *         items an empty array is returned.
111      *
112      * @throws SyncException in case of error (for instance if the
113      *         underlying data store runs into problems)
114      */
115     public SyncItem[] getDeletedSyncItems(Principal   principal, Date   since)
116     throws SyncException;
117 
118 
119     /**
120      * Returns all new items belonging to the given principal and created
121      * after the given point in time.
122      *
123      * @param principal not used, always null
124      * @param since consider the changes since this point in . Null means
125      *              all items regardless when they were changed.
126      *
127      * @return an array of items containing representing the newly created items.
128      *         If there are no new items an empty array MUST BE returned.
129      *
130      * @throws SyncException in case of error (for instance if the
131      *         underlying data store runs into problems)
132      */
133     public SyncItem[] getNewSyncItems(Principal   principal, Date   since)
134     throws SyncException;
135 
136     /**
137      * Returns all updated items belonging to the given principal and modified
138      * after the given point in time.
139      *
140      * @param principal not used, always null
141      * @param since consider the changes since this point in time. Null means
142      *              all items regardless when they were changed.
143      *
144      * @return an array of keys containing the <i>SyncItem</I>'s key of the updated
145      *         items after the last synchronizazion. It MUST NOT return null for
146      *         no keys, but instad an empty array.
147      */
148     public SyncItem[] getUpdatedSyncItems(Principal   principal, Date   since)
149     throws SyncException;
150 
151 
152     /**
153      * Removes a SyncItem given its key.
154      *
155      * @param principal not used, always null
156      * @param syncItem  the item to remove
157      *
158      * @throws SyncException in case of error (for instance if the
159      *         underlying data store runs into problems)
160      */
161     public void removeSyncItem(Principal   principal, SyncItem syncItem)
162     throws SyncException;
163 
164     /**
165      * Replaces an existing <i>SyncItem</i> or adds a new <i>SyncItem</i> if it
166      * does not exist. The item is also returned giving the opportunity to the
167      * source to modify its content and return the updated item (i.e. updating
168      * the id to the GUID).
169      *
170      * @param principal not used, always null
171      * @param syncItem  the item to replace/add
172      *
173      * @return the inserted/updated item
174      *
175      * @throws SyncException in case of error (for instance if the
176      *         underlying data store runs into problems)
177      */
178     public SyncItem setSyncItem(Principal   principal, SyncItem syncItem)
179     throws SyncException;
180 
181 
182     /**
183      * Called after SyncManager preparation and initialization just before start
184      * the synchronization of the SyncSource.
185      *
186      * @param syncMode the synchronization type: one of the values in
187      *                 sync4j.framework.core.AlertCode
188      *
189      * @throws SyncException in case of error. This will stop the sync process
190      */
191     public void beginSync(int syncMode) throws SyncException;
192 
193     /**
194      * Called just before committing the synchronization process by the
195      * SyncManager. If an error is detected and
196      *
197      * @throws SyncException
198      */
199     public void commitSync() throws SyncException;
200 
201 
202 }
203
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags