001: // The contents of this file are subject to the Mozilla Public License Version
002: // 1.1
003: //(the "License"); you may not use this file except in compliance with the
004: //License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
005: //
006: //Software distributed under the License is distributed on an "AS IS" basis,
007: //WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
008: //for the specific language governing rights and
009: //limitations under the License.
010: //
011: //The Original Code is "The Columba Project"
012: //
013: //The Initial Developers of the Original Code are Frederik Dietz and Timo
014: // Stich.
015: //Portions created by Frederik Dietz and Timo Stich are Copyright (C) 2003.
016: //
017: //All Rights Reserved.
018: package org.columba.addressbook.facade;
019:
020: import java.util.List;
021:
022: import org.columba.api.exception.StoreException;
023:
024: /**
025: * Provides high-level contact management methods. This Facade API is the only
026: * way to access functionality of this component.
027: * <p>
028: * In case the facade implementation doesn't support specific functionality, an
029: * <code>java.lang.IllegalArgumentException</code> should be thrown.
030: * Components making use of this facade, should try to handle missing method
031: * implementations gracefully, if possible.
032: * <p>
033: * Unchecked exceptions based on <code>java.lang.RuntimeException</code> are
034: * used only. A <code>StoreException</code> is thrown in case of an internal
035: * store backend error or failure a client usually can't resolve gracefully. A
036: * <code>IllegalArgumentException</code> is used in case the client didn't
037: * make use of the method correctly.
038: * <p>
039: * Following an example on how to register a new facade implementation:
040: *
041: * <pre>
042: * ServiceRegistry.register(MyFacadeImpl.class, IContactFacade)
043: * </pre>
044: *
045: * @author fdietz
046: */
047: public interface IContactFacade {
048:
049: /**
050: * Add new contact to contact folder with specified id.
051: *
052: * @param id
053: * contact folder unique id
054: * @param contactItem The IContactItem to add to the specified folder
055: * @throws StoreException
056: * in case of an internal storage backend failure
057: * @throws IllegalArgumentException
058: * in case of invalid arguments, in case this method is not
059: * supported by a facade implementation
060: */
061: void addContact(String id, IContactItem contactItem)
062: throws StoreException, IllegalArgumentException;
063:
064: /**
065: * Add an array of contacts to the contact folder with specified id.
066: *
067: * @param id
068: * contact folder unique id
069: * @param contactItems Array of IContactItemS to add to the specified folder
070: * @throws StoreException
071: * in case of an internal storage backend failure
072: * @throws IllegalArgumentException
073: * in case of invalid arguments, in case this method is not
074: * supported by a facade implementation
075: */
076: void addContacts(String id, IContactItem[] contactItem)
077: throws StoreException, IllegalArgumentException;
078:
079: /**
080: * Add new contact to a contact folder. Implementation
081: * should prompt user for a destination contact folder.
082: * @param contactItem The IContactItem to add to the specified folder
083: *
084: * @throws StoreException
085: * in case of an internal storage backend failure
086: * @throws IllegalArgumentException
087: * in case of invalid arguments, in case this method is not
088: * supported by a facade implementation
089: */
090: void addContact(IContactItem contactItem) throws StoreException,
091: IllegalArgumentException;
092:
093: /**
094: * Add an array of contacts to a contact folder. Implementation
095: * should prompt user for a destination contact folder.
096: * @param contactItems Array of IContactItemS to add to the specified folder
097: *
098: * @throws StoreException
099: * 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)
105: throws StoreException, 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,
198: String emailAddress) throws StoreException,
199: IllegalArgumentException;
200:
201: /**
202: * Find a contact by name in specified contact folder.
203: * <p>
204: * First tries to find a vCard "SORT_AS", then vCard "LASTNAME" and last
205: * vCard "FIRSTNAME", until a match is found. If several contacts match the
206: * first one is used and all other results are ignored.
207: *
208: * @param folderId
209: * contact folder unique id
210: * @param name
211: * name to search for
212: * @return contact id, in case a matching contact was found.
213: * <code>null</code>otherwise.
214: * @throws StoreException
215: * in case of an internal storage backend failure
216: * @throws IllegalArgumentException
217: * in case of invalid arguments, in case this method is not
218: * supported by a facade implementation
219: */
220: public String findByName(String folderId, String name)
221: throws StoreException, IllegalArgumentException;
222:
223: }
|