IContactFacade


1   // The contents of this file are subject to the Mozilla Public License Version
2   // 1.1
3   //(the "License"); you may not use this file except in compliance with the
4   //License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
5   //
6   //Software distributed under the License is distributed on an "AS IS" basis,
7   //WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
8   //for the specific language governing rights and
9   //limitations under the License.
10  //
11  //The Original Code is "The Columba Project"
12  //
13  //The Initial Developers of the Original Code are Frederik Dietz and Timo
14  // Stich.
15  //Portions created by Frederik Dietz and Timo Stich are Copyright (C) 2003.
16  //
17  //All Rights Reserved.
18  package org.columba.addressbook.facade;
19  
20  import java.util.List  ;
21  
22  import org.columba.api.exception.StoreException;
23  
24  /**
25   * Provides high-level contact management methods. This Facade API is the only
26   * way to access functionality of this component.
27   * <p>
28   * In case the facade implementation doesn't support specific functionality, an
29   * <code>java.lang.IllegalArgumentException</code> should be thrown.
30   * Components making use of this facade, should try to handle missing method
31   * implementations gracefully, if possible.
32   * <p>
33   * Unchecked exceptions based on <code>java.lang.RuntimeException</code> are
34   * used only. A <code>StoreException</code> is thrown in case of an internal
35   * store backend error or failure a client usually can't resolve gracefully. A
36   * <code>IllegalArgumentException</code> is used in case the client didn't
37   * make use of the method correctly.
38   * <p>
39   * Following an example on how to register a new facade implementation:
40   * 
41   * <pre>
42   * ServiceRegistry.register(MyFacadeImpl.class, IContactFacade)
43   * </pre>
44   * 
45   * @author fdietz
46   */
47  public interface IContactFacade {
48  
49      /**
50       * Add new contact to contact folder with specified id.
51       * 
52       * @param id
53       *            contact folder unique id
54       * @param contactItem The IContactItem to add to the specified folder
55       * @throws StoreException
56       *             in case of an internal storage backend failure
57       * @throws IllegalArgumentException
58       *             in case of invalid arguments, in case this method is not
59       *             supported by a facade implementation
60       */
61      void addContact(String   id, IContactItem contactItem) throws StoreException,
62              IllegalArgumentException  ;
63  
64      /**
65       * Add an array of contacts to the contact folder with specified id.
66       * 
67       * @param id
68       *            contact folder unique id
69       * @param contactItems Array of IContactItemS to add to the specified folder
70       * @throws StoreException
71       *             in case of an internal storage backend failure
72       * @throws IllegalArgumentException
73       *             in case of invalid arguments, in case this method is not
74       *             supported by a facade implementation
75       */
76      void addContacts(String   id, IContactItem[] contactItem) throws StoreException,
77              IllegalArgumentException  ;
78  
79      /**
80       * Add new contact to a contact folder. Implementation
81       * should prompt user for a destination contact folder.
82       * @param contactItem The IContactItem to add to the specified folder
83       * 
84       * @throws StoreException
85       *             in case of an internal storage backend failure
86       * @throws IllegalArgumentException
87       *             in case of invalid arguments, in case this method is not
88       *             supported by a facade implementation
89       */
90      void addContact(IContactItem contactItem) throws StoreException,
91              IllegalArgumentException  ;
92  
93      /**
94       * Add an array of contacts to a contact folder. Implementation
95       * should prompt user for a destination contact folder.
96       * @param contactItems Array of IContactItemS to add to the specified folder
97       * 
98       * @throws StoreException
99       *             in case of an internal storage backend failure
100      * @throws IllegalArgumentException
101      *             in case of invalid arguments, in case this method is not
102      *             supported by a facade implementation
103      */
104     void addContacts(IContactItem[] contactItems) throws StoreException,
105             IllegalArgumentException  ;
106 
107     /**
108      * Retrieve contact item with given id from specified contact folder.
109      * 
110      * @param folderId
111      *            unique contact folder id
112      * @param contactId
113      *            unique contact id
114      * @return contact item instance if available, <code>null</code>otherwise.
115      * @throws StoreException
116      *             in case of an internal storage backend failure
117      * @throws IllegalArgumentException
118      *             in case of invalid arguments, in case this method is not
119      *             supported by the facade implementation
120      */
121     public IContactItem getContactItem(String   folderId, String   contactId)
122             throws StoreException, IllegalArgumentException  ;
123 
124     /**
125      * Retrieve all <code>IHeaderItem</code> instances from contact folder
126      * with selected unique id.
127      * 
128      * @param folderId
129      *            contact folder unique id
130      * @param flattenGroupItems
131      *            If true, convert <code>IGroupItem</code> to
132      *            <code>List<IContactItem></code>. The result will be a list
133      *            containing only <code>IContactItem</code> instances.
134      *            Otherwise, the list will contain <code>IContactItem</code>
135      *            and <code>IGroupItem</code> instances.
136      * @return list of <code>IHeaderItem</code> instances, never
137      *         <code>null</code>
138      * @throws StoreException
139      *             in case of an internal storage backend failure
140      * @throws IllegalArgumentException
141      *             in case of invalid arguments, in case this method is not
142      *             supported by a facade implementation
143      */
144     public List  <IHeaderItem> getAllHeaderItems(String   folderId,
145             boolean flattenGroupItems) throws StoreException,
146             IllegalArgumentException  ;
147 
148     /**
149      * Retrieve all <code>IContactItem</code> instances from a contact folder
150      * with selected unique id.
151      * 
152      * @param folderId
153      *            contact folder unique id
154      * @return list of <code>IContactItem</code> instances, never
155      *         <code>null</code>
156      * @throws StoreException
157      *             in case of an internal storage backend failure
158      * @throws IllegalArgumentException
159      *             in case of invalid arguments, in case this method is not
160      *             supported by a facade implementation
161      */
162     public List  <IContactItem> getAllContacts(String   folderId)
163             throws StoreException, IllegalArgumentException  ;
164 
165     /**
166      * Retrieve all <code>IGroupItem</code> instances from a contact folder
167      * with selected unique id.
168      * 
169      * @param folderId
170      *            contact folder unique id
171      * @return list of <code>IGroupItem</code> instances, never
172      *         <code>null</code>
173      * @throws StoreException
174      *             in case of an internal storage backend failure
175      * @throws IllegalArgumentException
176      *             in case of invalid arguments, in case this method is not
177      *             supported by a facade implementation
178      */
179     public List  <IGroupItem> getAllGroups(String   folderId)
180             throws StoreException, IllegalArgumentException  ;
181 
182     /**
183      * Find a contact by email address in specified contact folder.
184      * 
185      * @param folderId
186      *            contact folder unique id
187      * @param emailAddress
188      *            email address to search for
189      * @return contact id, in case a matching contact was found.
190      *         <code>null</code>otherwise.
191      * @throws StoreException
192      *             in case of an internal storage backend failure
193      * @throws IllegalArgumentException
194      *             in case of invalid arguments, in case this method is not
195      *             supported by a facade implementation
196      */
197     public String   findByEmailAddress(String   folderId, String   emailAddress)
198             throws StoreException, IllegalArgumentException  ;
199 
200     /**
201      * Find a contact by name in specified contact folder.
202      * <p>
203      * First tries to find a vCard "SORT_AS", then vCard "LASTNAME" and last
204      * vCard "FIRSTNAME", until a match is found. If several contacts match the
205      * first one is used and all other results are ignored.
206      * 
207      * @param folderId
208      *            contact folder unique id
209      * @param name
210      *            name to search for
211      * @return contact id, in case a matching contact was found.
212      *         <code>null</code>otherwise.
213      * @throws StoreException
214      *             in case of an internal storage backend failure
215      * @throws IllegalArgumentException
216      *             in case of invalid arguments, in case this method is not
217      *             supported by a facade implementation
218      */
219     public String   findByName(String   folderId, String   name)
220             throws StoreException, IllegalArgumentException  ;
221 
222 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags