/android/import-contacts

To get this branch, use:
bzr branch http://bzr.ed.am/android/import-contacts
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
1
/*
2
 * Backend.java
3
 *
4
 * Copyright (C) 2012 Tim Marston <tim@ed.am>
5
 *
6
 * This file is part of the Import Contacts program (hereafter referred
93 by Tim Marston
minor style tweaks
7
 * to as "this program").  For more information, see
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
8
 * http://ed.am/dev/android/import-contacts
9
 *
10
 * This program is free software: you can redistribute it and/or modify
11
 * it under the terms of the GNU General Public License as published by
12
 * the Free Software Foundation, either version 3 of the License, or
13
 * (at your option) any later version.
14
 *
15
 * This program is distributed in the hope that it will be useful,
16
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18
 * GNU General Public License for more details.
19
 *
20
 * You should have received a copy of the GNU General Public License
21
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
22
 */
23
24
package am.ed.importcontacts;
25
26
import am.ed.importcontacts.Importer.ContactData;
27
28
public interface Backend
29
{
30
	/**
31
	 * Build-up our contacts cache, using contacts on the device.
93 by Tim Marston
minor style tweaks
32
	 *
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
33
	 * @param cache the contacts cache to populate
34
	 */
35
	public void populateCache( ContactsCache cache );
36
37
	/**
57 by edam
cleanup; fixed some typos; updated TODO
38
	 * Delete a contact from the device.
93 by Tim Marston
minor style tweaks
39
	 *
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
40
	 * @param id of the contact to delete
41
	 */
42
	public void deleteContact( Long id );
43
61 by edam
made contacts backend throw exceptions when it can't create contacts on the device; specified Locale in lower/upper case conversions; stripped old Contacts types from Importer (and replaced with our own types, which are now converted in the backend; switched using Integer() constructors to Integer.valueOf(); rewrote the main importer routine a bit
44
	@SuppressWarnings("serial")
45
	public class ContactCreationException extends Exception { };
46
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
47
	/**
57 by edam
cleanup; fixed some typos; updated TODO
48
	 * Add a contact to the device.
93 by Tim Marston
minor style tweaks
49
	 *
61 by edam
made contacts backend throw exceptions when it can't create contacts on the device; specified Locale in lower/upper case conversions; stripped old Contacts types from Importer (and replaced with our own types, which are now converted in the backend; switched using Integer() constructors to Integer.valueOf(); rewrote the main importer routine a bit
50
	 * @param name name of the new contact, or null if there isn't one
51
	 * @return the new contact's id
52
	 * @throws ContactCreationException
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
53
	 */
61 by edam
made contacts backend throw exceptions when it can't create contacts on the device; specified Locale in lower/upper case conversions; stripped old Contacts types from Importer (and replaced with our own types, which are now converted in the backend; switched using Integer() constructors to Integer.valueOf(); rewrote the main importer routine a bit
54
	public Long addContact( String name ) throws ContactCreationException;
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
55
56
	/**
57 by edam
cleanup; fixed some typos; updated TODO
57
	 * Add a phone number to an existing contact on the device.
93 by Tim Marston
minor style tweaks
58
	 *
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
59
	 * @param id the existing contact's id
60
	 * @param number the phone number
61
	 * @param data data about the number
61 by edam
made contacts backend throw exceptions when it can't create contacts on the device; specified Locale in lower/upper case conversions; stripped old Contacts types from Importer (and replaced with our own types, which are now converted in the backend; switched using Integer() constructors to Integer.valueOf(); rewrote the main importer routine a bit
62
	 * @throws ContactCreationException
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
63
	 */
64
	public void addContactPhone( Long id, String number,
61 by edam
made contacts backend throw exceptions when it can't create contacts on the device; specified Locale in lower/upper case conversions; stripped old Contacts types from Importer (and replaced with our own types, which are now converted in the backend; switched using Integer() constructors to Integer.valueOf(); rewrote the main importer routine a bit
65
		ContactData.PreferredDetail data ) throws ContactCreationException;
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
66
67
	/**
57 by edam
cleanup; fixed some typos; updated TODO
68
	 * Add an email address to an existing contact on the device.
93 by Tim Marston
minor style tweaks
69
	 *
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
70
	 * @param id the existing contact's id
71
	 * @param email the email address
72
	 * @param data data about the email address
61 by edam
made contacts backend throw exceptions when it can't create contacts on the device; specified Locale in lower/upper case conversions; stripped old Contacts types from Importer (and replaced with our own types, which are now converted in the backend; switched using Integer() constructors to Integer.valueOf(); rewrote the main importer routine a bit
73
	 * @throws ContactCreationException
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
74
	 */
75
	public void addContactEmail( Long id, String email,
61 by edam
made contacts backend throw exceptions when it can't create contacts on the device; specified Locale in lower/upper case conversions; stripped old Contacts types from Importer (and replaced with our own types, which are now converted in the backend; switched using Integer() constructors to Integer.valueOf(); rewrote the main importer routine a bit
76
		ContactData.PreferredDetail data ) throws ContactCreationException;
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
77
78
	/**
57 by edam
cleanup; fixed some typos; updated TODO
79
	 * Add an address to an existing contact on the device.
93 by Tim Marston
minor style tweaks
80
	 *
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
81
	 * @param id the existing contact's id
82
	 * @param address the address
83
	 * @param data data about the address
61 by edam
made contacts backend throw exceptions when it can't create contacts on the device; specified Locale in lower/upper case conversions; stripped old Contacts types from Importer (and replaced with our own types, which are now converted in the backend; switched using Integer() constructors to Integer.valueOf(); rewrote the main importer routine a bit
84
	 * @throws ContactCreationException
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
85
	 */
86
	public void addContactAddresses( Long id, String address,
61 by edam
made contacts backend throw exceptions when it can't create contacts on the device; specified Locale in lower/upper case conversions; stripped old Contacts types from Importer (and replaced with our own types, which are now converted in the backend; switched using Integer() constructors to Integer.valueOf(); rewrote the main importer routine a bit
87
		ContactData.TypeDetail data ) throws ContactCreationException;
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
88
89
	/**
57 by edam
cleanup; fixed some typos; updated TODO
90
	 * Add a title and organisation to an existing contact on the device.
93 by Tim Marston
minor style tweaks
91
	 *
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
92
	 * @param id the existing contact's id
93
	 * @param organisation the organisation
94
	 * @param data data about the organisation
61 by edam
made contacts backend throw exceptions when it can't create contacts on the device; specified Locale in lower/upper case conversions; stripped old Contacts types from Importer (and replaced with our own types, which are now converted in the backend; switched using Integer() constructors to Integer.valueOf(); rewrote the main importer routine a bit
95
	 * @throws ContactCreationException
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
96
	 */
97
	public void addContactOrganisation( Long id, String organisation,
61 by edam
made contacts backend throw exceptions when it can't create contacts on the device; specified Locale in lower/upper case conversions; stripped old Contacts types from Importer (and replaced with our own types, which are now converted in the backend; switched using Integer() constructors to Integer.valueOf(); rewrote the main importer routine a bit
98
		ContactData.ExtraDetail data ) throws ContactCreationException;
65 by edam
added support for notes; rewrote backends so that all normalising of data is now done within the contacts cache; made the vCard unescape routine slightly more acceptant of non-standard escaped characters
99
100
	/**
101
	 * Add a note to an existing contact on the device.
93 by Tim Marston
minor style tweaks
102
	 *
65 by edam
added support for notes; rewrote backends so that all normalising of data is now done within the contacts cache; made the vCard unescape routine slightly more acceptant of non-standard escaped characters
103
	 * @param id the existing contact's id
104
	 * @param note the note
105
	 * @throws ContactCreationException
106
	 */
107
	public void addContactNote( Long id, String note )
108
		throws ContactCreationException;
109
53 by edam
abstracted the android contacts API in to an interface, ready to be switched to
110
}