corny.addressbook
Class NativeAddressBook

java.lang.Object
  corny.addressbook.NativeAddressBook

All Implemented Interfaces:

AddressBookChangeListener

public final class NativeAddressBook
extends java.lang.Object
implements AddressBookChangeListener

Central class of the Java Address Book API. Fetches all Groups and Contacts from the Apple Address Book and provides access. Implements all the functionality to access, search or edit the Address Book and to monitor the Address Book for changes.

Author:

Corny

Field Summary

static Filter	contactsWithAddressFilter Filters Contacts which have Addresses.
static Filter	contactsWithBirthdayFilter Filters Contacts which have a birthday set.
static Filter	contactsWithEmailFilter Filters Contacts which have Email addresses.
static Filter	contactsWithNameFilter Filters Contacts which have a displayed name (full name or organization name).
static Filter	contactsWithPhoneFilter Filters Contacts which have phone numbers.
static Filter	contactsWithPictureFilter Filters Contacts which have an attached picture.
static Filter	organizationsFilter Filters Contacts which are organizations, not persons.
static Filter	personsFilter Filters Contacts which are persons, not organizations.

Method Summary

void	addAddressBookChangeListener(AddressBookChangeListener listener) Adds the specified listener to receive notifications when the Address Book data changes.
Contact	addContact(Group parentGroup) Adds a new, empty Contact (a person) to the Address Book.
Contact	addContact(java.lang.String fName, java.lang.String mName, java.lang.String lName, java.lang.String title, java.lang.String org, java.util.List<MultiValue.KeyValuePair<java.lang.String>> email, java.util.List<MultiValue.KeyValuePair<java.lang.String>> phone, java.util.List<MultiValue.KeyValuePair<Address>> address, java.util.List<MultiValue.KeyValuePair<java.lang.String>> chat, java.util.Date birthday, boolean isPerson, Group group) Adds a new Contact.
Contact	addContact(java.lang.String fName, java.lang.String mName, java.lang.String lName, java.lang.String title, java.lang.String org, MultiValue.KeyValuePair<java.lang.String> email, MultiValue.KeyValuePair<java.lang.String> phone, MultiValue.KeyValuePair<Address> address, MultiValue.KeyValuePair<java.lang.String> chat, java.util.Date birthday, boolean isPerson, Group group) Adds a new Contact.
Group	addGroup(java.lang.String name, Group parentGroup) Adds a new Group to the Address Book
void	addressBookChanged(AddressBookNotification noti) Called when the Address Book data has changed externally, for example when editing the Address Book by using Apple's Address Book interface.
void	addressBookChangedInternally(AddressBookNotification noti) Called when the Address Book data has changed by calling methods of this Java API.
static java.util.List<java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.String>>>	addressListToMapList(java.util.List<MultiValue.KeyValuePair<Address>> address) Converts a List of KeyValuePairs containing Addresses into native code comparible format
void	beginModification() Call this method if you want to apply multiple modifications to the Address Book.
void	endModification() Call this method if a series of modifications initiated by beginModification() has ended.
java.util.List<Contact>	findContacts(Filter search) Searches for Contacts in the whole Address Book
java.util.List<Contact>	findContactsInGroup(Filter search, Group g) Searches for Contacts in a given Group
java.util.List<Contact>	getContactsWithAddress(java.lang.String address) Searches the whole Address Book for Contacts whose addresses contain the given String.
java.util.List<Contact>	getContactsWithEmail(java.lang.String email) Searches the whole Address Book for Contacts whose Email Addresses contain the given String.
java.util.List<Contact>	getContactsWithFirstName(java.lang.String firstName) Searches the whole Address Book for Contacts whose first name contains the given String.
java.util.List<Contact>	getContactsWithLastName(java.lang.String lastName) Searches the whole Address Book for Contacts whose last name contains the given String.
java.util.List<Contact>	getContactsWithNameElement(java.lang.String nameElement) Searches the whole Address Book for Contacts whose full name contains the given String.
java.util.List<Contact>	getContactsWithPhone(java.lang.String phone) Searches the whole Address Book for Contacts whose phone numbers contain the given String.
java.util.List<Contact>	getContactsWithSomeAttribute(java.lang.String attribute) Searches the whole Address Book for Contacts which have any attribute which contains the given String.
java.util.List<Contact>	getEveryone()
Group	getEveryoneGroup()
java.util.List<Group>	getGroups()
Contact	getMe() Returns the Contact which represents the user
Record	getRecord(java.lang.String uid) Returns the Record with the given UID or null if the the Record doesn't exist.
void	init() Initializes the native address book to be able to send change notifications
static NativeAddressBook	instance() Returns the singleton instance of the NativeAddressBook class.
boolean	isModificationSessionActive()
static java.util.List<java.util.Map<java.lang.String,java.lang.String>>	keyValueListToMapList(java.util.List<MultiValue.KeyValuePair<java.lang.String>> list) Converts a List of KeyValuePairs containing Strings into native code comparible format
boolean	modifyContact(Contact contact, java.lang.String fName, java.lang.String mName, java.lang.String lName, java.lang.String title, java.lang.String org, java.util.List<MultiValue.KeyValuePair<java.lang.String>> email, java.util.List<MultiValue.KeyValuePair<java.lang.String>> phone, java.util.List<MultiValue.KeyValuePair<Address>> address, java.util.List<MultiValue.KeyValuePair<java.lang.String>> chat, java.util.Date birthday, java.lang.Boolean isPerson) Modifies an existing Contact.
boolean	modifyContact(Contact contact, java.lang.String fName, java.lang.String mName, java.lang.String lName, java.lang.String title, java.lang.String org, MultiValue.KeyValuePair<java.lang.String> email, MultiValue.KeyValuePair<java.lang.String> phone, MultiValue.KeyValuePair<Address> address, MultiValue.KeyValuePair<java.lang.String> chat, java.util.Date birthday, java.lang.Boolean isPerson) Modifies an existing Contact.
boolean	removeContact(Contact c) Permamently removes a Contact from the Address Book.
boolean	removeGroup(Group g) Removes a Group from the Address Book.
boolean	removeRecord(Record r) Permamently removes a Record from the Address book.
void	revealInAddressBook(Contact c, boolean edit) Opens the Address Book and selects the given Contact.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

personsFilter

public static final Filter personsFilter

Filters Contacts which are persons, not organizations.

organizationsFilter

public static final Filter organizationsFilter

Filters Contacts which are organizations, not persons.

contactsWithNameFilter

public static final Filter contactsWithNameFilter

Filters Contacts which have a displayed name (full name or organization name).

contactsWithEmailFilter

public static final Filter contactsWithEmailFilter

Filters Contacts which have Email addresses.

contactsWithPhoneFilter

public static final Filter contactsWithPhoneFilter

Filters Contacts which have phone numbers.

contactsWithBirthdayFilter

public static final Filter contactsWithBirthdayFilter

Filters Contacts which have a birthday set.

contactsWithAddressFilter

public static final Filter contactsWithAddressFilter

Filters Contacts which have Addresses.

contactsWithPictureFilter

public static final Filter contactsWithPictureFilter

Filters Contacts which have an attached picture.

Method Detail

instance

public static NativeAddressBook instance()

Returns the singleton instance of the NativeAddressBook class. On the first call, a new instance will be created and the Address Book data will be loaded.

Returns:

Singleton instance

keyValueListToMapList

public static java.util.List<java.util.Map<java.lang.String,java.lang.String>> keyValueListToMapList(java.util.List<MultiValue.KeyValuePair<java.lang.String>> list)

Converts a List of KeyValuePairs containing Strings into native code comparible format

Parameters:

list - List of KeyValuePairs

Returns:

Native code compatible representation

addressListToMapList

public static java.util.List<java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.String>>> addressListToMapList(java.util.List<MultiValue.KeyValuePair<Address>> address)

Converts a List of KeyValuePairs containing Addresses into native code comparible format

Parameters:

address - List of KeyValuePairs

Returns:

Native code compatible representation

init

public void init()

Initializes the native address book to be able to send change notifications

getRecord

public Record getRecord(java.lang.String uid)

Returns the Record with the given UID or null if the the Record doesn't exist.

Parameters:

uid - UID to search for

Returns:

Found record or null

getMe

public Contact getMe()

Returns the Contact which represents the user

Returns:

The "Me" Contact or null if it isn't set

getEveryone

public java.util.List<Contact> getEveryone()

Returns:

A List containing every Contact of the Address Book

getEveryoneGroup

public Group getEveryoneGroup()

Returns:

The Group containing every Contact

getGroups

public java.util.List<Group> getGroups()

Returns:

A List containing all Groups of the Address Book

revealInAddressBook

public void revealInAddressBook(Contact c,
                                boolean edit)

Opens the Address Book and selects the given Contact. If edit is set to true, Address Book will open in editing mode.

Parameters:

c - Contact to reveal

edit - If true, Address Book will open in editing mode

findContactsInGroup

public java.util.List<Contact> findContactsInGroup(Filter search,
                                                   Group g)

Searches for Contacts in a given Group

Parameters:

search - Search filter

g - Group to search for matching Contacts

Returns:

List of Contacts matching the giben Filter

findContacts

public java.util.List<Contact> findContacts(Filter search)

Searches for Contacts in the whole Address Book

Parameters:

search - Search filter

Returns:

List of Contacts matching the giben Filter

getContactsWithLastName

public java.util.List<Contact> getContactsWithLastName(java.lang.String lastName)

Searches the whole Address Book for Contacts whose last name contains the given String.

Parameters:

lastName - Pattern the last name should contain

Returns:

List of matching Contacts

getContactsWithFirstName

public java.util.List<Contact> getContactsWithFirstName(java.lang.String firstName)

Searches the whole Address Book for Contacts whose first name contains the given String.

Parameters:

firstName - Pattern the first name should contain

Returns:

List of matching Contacts

getContactsWithNameElement

public java.util.List<Contact> getContactsWithNameElement(java.lang.String nameElement)

Searches the whole Address Book for Contacts whose full name contains the given String.

Parameters:

nameElement - Pattern the full name should contain

Returns:

List of matching Contacts

getContactsWithPhone

public java.util.List<Contact> getContactsWithPhone(java.lang.String phone)

Searches the whole Address Book for Contacts whose phone numbers contain the given String.

Parameters:

phone - Pattern the phone numbers should contain

Returns:

List of matching Contacts

getContactsWithEmail

public java.util.List<Contact> getContactsWithEmail(java.lang.String email)

Searches the whole Address Book for Contacts whose Email Addresses contain the given String.

Parameters:

email - Pattern the Email Addresses should contain

Returns:

List of matching Contacts

getContactsWithAddress

public java.util.List<Contact> getContactsWithAddress(java.lang.String address)

Searches the whole Address Book for Contacts whose addresses contain the given String.

Parameters:

address - Pattern the addresses should contain

Returns:

List of matching Contacts

getContactsWithSomeAttribute

public java.util.List<Contact> getContactsWithSomeAttribute(java.lang.String attribute)

Searches the whole Address Book for Contacts which have any attribute which contains the given String.

Parameters:

attribute - Pattern the Contact's attributes should

Returns:

List of matching Contacts

beginModification

public void beginModification()

Call this method if you want to apply multiple modifications to the Address Book. Until you call endModification(), the Address Book won't be saved and no AddressBookNotification will be sent. This greatly improves performance.

See Also:

endModification(), isModificationSessionActive()

endModification

public void endModification()

Call this method if a series of modifications initiated by beginModification() has ended.

See Also:

beginModification(), isModificationSessionActive()

isModificationSessionActive

public boolean isModificationSessionActive()

Returns:

true, if a modification session is active.

See Also:

beginModification(), endModification()

addContact

public Contact addContact(java.lang.String fName,
                          java.lang.String mName,
                          java.lang.String lName,
                          java.lang.String title,
                          java.lang.String org,
                          java.util.List<MultiValue.KeyValuePair<java.lang.String>> email,
                          java.util.List<MultiValue.KeyValuePair<java.lang.String>> phone,
                          java.util.List<MultiValue.KeyValuePair<Address>> address,
                          java.util.List<MultiValue.KeyValuePair<java.lang.String>> chat,
                          java.util.Date birthday,
                          boolean isPerson,
                          Group group)

Adds a new Contact. For the fields you don't want to set, pass null or an empty String. If you pass null as parent group, the Contact will be added to the everyone group.

Parameters:

fName - first name

mName - middle name

lName - last name

title - title

org - organization

email - E-Mails

phone - Phones

address - Addresses

chat - Chats

birthday - Birthday

isPerson - Person flag

group - Parent group or null for no parent group

Returns:

The UID of the created Contact

addContact

public Contact addContact(java.lang.String fName,
                          java.lang.String mName,
                          java.lang.String lName,
                          java.lang.String title,
                          java.lang.String org,
                          MultiValue.KeyValuePair<java.lang.String> email,
                          MultiValue.KeyValuePair<java.lang.String> phone,
                          MultiValue.KeyValuePair<Address> address,
                          MultiValue.KeyValuePair<java.lang.String> chat,
                          java.util.Date birthday,
                          boolean isPerson,
                          Group group)

Adds a new Contact. For the fields you don't want to set, pass null or an empty String. If you pass null as parent group, the Contact will be added to the everyone group. Use this method if you want to pass only one value for the multi value fields.

Parameters:

fName - first name

mName - middle name

lName - last name

title - title

org - organization

email - E-Mail

phone - Phone

address - Addresse

chat - Chat

birthday - Birthday

isPerson - Person flag

group - Parent group or null for no parent group

Returns:

The UID of the created Contact

addContact

public Contact addContact(Group parentGroup)

Adds a new, empty Contact (a person) to the Address Book.

Parameters:

parentGroup - The parent Group of the new Contact or null to add it to the "Everyone" group.

Returns:

The new Contact

modifyContact

public boolean modifyContact(Contact contact,
                             java.lang.String fName,
                             java.lang.String mName,
                             java.lang.String lName,
                             java.lang.String title,
                             java.lang.String org,
                             java.util.List<MultiValue.KeyValuePair<java.lang.String>> email,
                             java.util.List<MultiValue.KeyValuePair<java.lang.String>> phone,
                             java.util.List<MultiValue.KeyValuePair<Address>> address,
                             java.util.List<MultiValue.KeyValuePair<java.lang.String>> chat,
                             java.util.Date birthday,
                             java.lang.Boolean isPerson)

Modifies an existing Contact. Pass null for the fields you don't want to modify.

Parameters:

contact - Contact to modify

fName - New first name

mName - New middle name

lName - New last name

title - New title

org - New organization

email - New E-Mails

phone - New Phones

address - New Addresses

chat - New Chats

birthday - Birthday

isPerson - New Person flag

Returns:

True if the modification was successful

modifyContact

public boolean modifyContact(Contact contact,
                             java.lang.String fName,
                             java.lang.String mName,
                             java.lang.String lName,
                             java.lang.String title,
                             java.lang.String org,
                             MultiValue.KeyValuePair<java.lang.String> email,
                             MultiValue.KeyValuePair<java.lang.String> phone,
                             MultiValue.KeyValuePair<Address> address,
                             MultiValue.KeyValuePair<java.lang.String> chat,
                             java.util.Date birthday,
                             java.lang.Boolean isPerson)

Modifies an existing Contact. Pass null for the fields you don't want to modify. Use this method if you want to pass only one value for the multi value fields.

Parameters:

contact - Contact to modify

fName - New first name

mName - New middle name

lName - New last name

title - New title

org - New organization

email - New E-Mail

phone - New Phone

address - New Addresse

chat - New Chat

birthday - Birthday

isPerson - New Person flag

Returns:

True if the modification was successful

addGroup

public Group addGroup(java.lang.String name,
                      Group parentGroup)

Adds a new Group to the Address Book

Parameters:

name - Name of the new Group

parentGroup - Parent group. Usually null.

Returns:

UID of the created Group

removeGroup

public boolean removeGroup(Group g)

Removes a Group from the Address Book. The Contacts of the Group will remain.

Parameters:

g - Group to remove

Returns:

true, if the removal was successful

removeContact

public boolean removeContact(Contact c)

Permamently removes a Contact from the Address Book. It will be removed from all parent Groups. This action cannot be undone.

Parameters:

c - Contact to remove

Returns:

true, if the removal was successful

removeRecord

public boolean removeRecord(Record r)

Permamently removes a Record from the Address book.

Parameters:

r - Record to remove

Returns:

true, if the removal was successful

addAddressBookChangeListener

public void addAddressBookChangeListener(AddressBookChangeListener listener)

Adds the specified listener to receive notifications when the Address Book data changes.

Parameters:

listener - New listener

addressBookChangedInternally

public void addressBookChangedInternally(AddressBookNotification noti)

Called when the Address Book data has changed by calling methods of this Java API. Fires the AddressBookChangeListeners.

Parameters:

noti - Notification containing the information about what has changed

addressBookChanged

public void addressBookChanged(AddressBookNotification noti)

Called when the Address Book data has changed externally, for example when editing the Address Book by using Apple's Address Book interface. Invoked by the JNIInvocationHandler.

Specified by:

addressBookChanged in interface AddressBookChangeListener

Parameters:

noti - Notification containing the information about what has changed