KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > sync4j > syncclient > spds > engine > 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 JavaDoc;
23 import java.security.Principal JavaDoc;
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 JavaDoc getName();
69
70     /**
71      * Returns the source URI
72      *
73      * @return the absolute URI of the source
74      */

75     public String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc principal, Date JavaDoc 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 JavaDoc principal, Date JavaDoc 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 JavaDoc principal, Date JavaDoc 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 JavaDoc 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 JavaDoc 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
Popular Tags