com.zion.jbuddy.lcs
Interface IAddressBook

public interface IAddressBook

Represents an address book, which contains contact information for various LCS/OCS users. This is used along with IAddressBookProvider to provide a custom, locally-cached address book implementation.

Since:

6.3

Method Summary

void	commitChanges() Commits changes after contacts have been created, updated, or deleted.
boolean	containsContact(String id) Returns true if the specified contact exists.
void	createContact(IAddressBookContact contact) Adds a new contact to this Address Book.
void	deleteContact(String id) Attempts to delete an existing contact's information.
IAddressBookContact	findContact(String partialName) Searches for the specified contact's information.
IAddressBookContact[]	findContacts(String partialName, int maxResults) Searches for the specified contacts' information.
IAddressBookContact	getContact(String id) Looks up an existing contact's information.
Date	getLastModifiedDate() Returns the date when this Address Book was last modified.
String	getName() Returns this Address Book's name.
IAddressBookProvider	getProvider() Returns the associated Address Book Provider.
void	setLastModifiedDate(Date date) Sets the date when this Address Book was last modified.
void	updateContact(IAddressBookContact contact) Attempts to update an existing contact's information.

Method Detail

getName

String getName()

Returns this Address Book's name.

getProvider

IAddressBookProvider getProvider()

Returns the associated Address Book Provider.

getLastModifiedDate

Date getLastModifiedDate()
                         throws Exception

Returns the date when this Address Book was last modified.

Returns:

the date, or null

Throws:

Exception - if some error occurred

setLastModifiedDate

void setLastModifiedDate(Date date)
                         throws Exception

Sets the date when this Address Book was last modified.

Parameters:

date - the date

Throws:

Exception - if some error occurred

createContact

void createContact(IAddressBookContact contact)
                   throws Exception

Adds a new contact to this Address Book.

Parameters:

contact - the contact's information

Throws:

Exception - if some error occurred

getContact

IAddressBookContact getContact(String id)
                               throws Exception

Looks up an existing contact's information.

Parameters:

id - the contact's ID

Returns:

the contact's information, or null if the contact does not exist

Throws:

Exception - if some error occurred

containsContact

boolean containsContact(String id)
                        throws Exception

Returns true if the specified contact exists.

This has the same effect as checking whether getContact(java.lang.String) returns null, but no data is copied (therefore, this method is faster).

Parameters:

id - the contact's ID

Returns:

true if the specified contact exists

Throws:

Exception - if some error occurred

findContact

IAddressBookContact findContact(String partialName)
                                throws Exception

Searches for the specified contact's information.

Parameters:

partialName - a partial name. This can be a given name, surname, display name, or any portion of those.

Returns:

the first matched result, or null if a matching contact was not found

Throws:

Exception - if some error occurred

See Also:

findContacts(String, int)

findContacts

IAddressBookContact[] findContacts(String partialName,
                                   int maxResults)
                                   throws Exception

Searches for the specified contacts' information.

Parameters:

partialName - a partial name. This can be a given name, surname, display name, or any portion of those.

maxResults - the maximum number of results to return. If not specified (maxResults < 0), any number of results can be returned.

Returns:

the results, or an empty array if no matching contacts were found

Throws:

Exception - if some error occurred

updateContact

void updateContact(IAddressBookContact contact)
                   throws Exception

Attempts to update an existing contact's information.

Parameters:

contact - the contact's information

Throws:

Exception - if some error occurred

deleteContact

void deleteContact(String id)
                   throws Exception

Attempts to delete an existing contact's information.

Parameters:

id - the contact's ID

Throws:

Exception - if some error occurred

commitChanges

void commitChanges()
                   throws Exception

Commits changes after contacts have been created, updated, or deleted.

This method is guaranteed to be called some time after any of the various modification methods have been called (createContact(com.zion.jbuddy.lcs.IAddressBookContact), updateContact(com.zion.jbuddy.lcs.IAddressBookContact), or deleteContact(java.lang.String)). This can be used to cache and reuse database connections until all modifications have been made, for example.

Throws:

Exception - if some error occurred