oracle.collabsuite.addressbook
Class UserAddressBook

java.lang.Object
  |
  +--oracle.collabsuite.addressbook.UserAddressBook

public final class UserAddressBook

extends java.lang.Object

This class manages user private address book in 9.0.5. Callers must get a handle to UserAddressBook using OCSUser.getAddressBook(). Using methods in this class various operations like addition, deletion, query address book entries (contacts, private lists) can be performed. Before any of there operations can be performed, authentication to directory must be done. These APIs support the following -
An option to use connections from the common OCS pool of ldap connection for all addressbook operations. For setting up the connection pool properties, refer to OCSUser.
Other applications might already have ldap connections set up and might wish not to create additional ldap connections for using these APIs. For these cases, callers can pass their DirContext to be used using setDirContext(DirContext dirCtx) method.

Constructor Summary

UserAddressBook(javax.naming.directory.DirContext dirCtx, java.lang.String subScriberLocation, java.lang.String userDN)
This constructor can be invoked when caller application already have a pool of LDAP connections set up through some other means and wants to reuse connections from that pool.

UserAddressBook(java.lang.String subScriberLocation, java.lang.String userDN)
This constructor makes use of the common OCS ldap pool.

Method Summary

void	clearPiecewiseContactsFlag() This method clears the ldap handle and flags etc.
void	clearPiecewiseListsFlag() This method clears the ldap handle and flags etc.
AddressBookContact	createContact(AddressBookAttribute[] attrs) This method adds a contact to the given user's addressbook.
AddressBookContact	createContactInSharedAddressBook(java.lang.String ownerUserGUID, AddressBookAttribute[] attrs) This method adds a contact in another given user's addressbook.
AddressBookList	createList(AddressBookAttribute[] attrs, AddressBookContact[] contacts, AddressBookList[] lists) This method adds a list to the given user's addressbook.
AddressBookList	createListInSharedAddressBook(java.lang.String ownerUserGUID, AddressBookAttribute[] attrs, AddressBookContact[] contacts, AddressBookList[] lists) This method adds a list in another given user's addressbook.
java.lang.String[]	deleteContactByFilter(java.lang.String filter) This method deletes contacts from user's address book matching the given criteria.
java.lang.String[]	deleteListByFilter(java.lang.String filter) This method deletes lists from user's address book matching the given criteria.
java.lang.String	getAddressBookDN()
AddressBookContact[]	getAllContacts(java.lang.String[] attrsToFetch, int batchSize, int sizeLimit, java.lang.String sortingAttr) This method retrieves All Contacts for the given user.For large number of contacts, the callers can retrieve them piecewise in batches.
AddressBookList[]	getAllLists(java.lang.String[] attrsToFetch, int batchSize, int sizeLimit, java.lang.String sortingAttr) This method retrieves all Lists for the given user.
java.lang.String[]	getCategories(int category_type) This method retrieves the possible address book categories.
java.lang.String[]	getCategoriesFromSharedAddressbook(java.lang.String ownerUserGUID) This method retrieves the possible address book categories from for a shared addressbook.
AddressBookContact[]	getContacts(java.lang.String searchCriteria, java.lang.String[] attrsToFetch, int batchSize, int sizeLimit, java.lang.String sortingAttr) This method retrieves Contacts for the given user for the matching search criteria.
SchemaObject	getContactSchema() This method will return the representation of a contact in LDAP, ie.
AddressBookList[]	getLists(java.lang.String searchCriteria, java.lang.String[] attrsToFetch, int batchSize, int sizeLimit, java.lang.String sortingAttr) This method retrieves Lists for the given user for the matching search criteria.
SchemaObject	getListSchema() This method will return the representation of a list in LDAP, ie.
java.util.Hashtable	getReadersAndWritersList() This API gets the list of users having read only and read/write permission on user's address book.
java.lang.String[]	getReadersList() This API gets the list of users having read permission on user's address book.
java.util.Hashtable	getSharedAddressBookOwnerGUIDs() This API gets the list of user GUIDs who have shared their address book with this user.
AddressBookContact[]	getSharedContacts(java.lang.String[] usersGUIDs, java.lang.String searchCriteria, java.lang.String[] attrsToFetch, int batchSize, int sizeLimit, java.lang.String sortingAttr) This method retrieves Contacts other users have shared with this user for the matching search criteria.
AddressBookList[]	getSharedLists(java.lang.String[] usersGUIDs, java.lang.String searchCriteria, java.lang.String[] attrsToFetch, int batchSize, int sizeLimit, java.lang.String sortingAttr) This method retrieves lists other users have shared with this user for the matching search criteria.
java.lang.String[]	getUserGUIDsSharingAddressBook() This API gets the list of user GUIDs who have shared their address book with this user.
java.lang.String[]	getWritersList() This API gets the list of users having read and write permission on user's address book.
boolean	ifNextBatchContacts() This method tells whether more data is to be fetched from server side for the prior piecewise fetch of user contacts.
boolean	ifNextBatchLists() This method tells whether more data is to be fetched from server side for the prior piecewise fetch of user lists.
void	setDirContext(javax.naming.directory.DirContext dirCtx) This method can be invoked to set the DirContext for the user addressbook operations.
java.lang.String[]	share(java.lang.String[] readAccessGUIDs, java.lang.String[] writeAccessGUIDs) This API lets the user share his/her addressbook with other users.
java.lang.String[]	unshare(java.lang.String[] userGUIDs) This API lets the user unshare his/her addressbook from the given list of users.

Methods inherited from class java.lang.Object

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

Constructor Detail

UserAddressBook

public UserAddressBook(java.lang.String subScriberLocation,
                       java.lang.String userDN)
                throws AddressBookException

This constructor makes use of the common OCS ldap pool.

Parameters:

subScriberLocation - DN of the subscriber for the given user - can be null in case applications are not aware of it

userDN - DN of the given User in the subscriber tree

Throws:

AddressBookException - Throws AddressBookException in case of errors

UserAddressBook

public UserAddressBook(javax.naming.directory.DirContext dirCtx,
                       java.lang.String subScriberLocation,
                       java.lang.String userDN)
                throws AddressBookException

This constructor can be invoked when caller application already have a pool of LDAP connections set up through some other means and wants to reuse connections from that pool. In this case, it's caller's responsibility to pass a connection having all required permissions for accessing address book.

Parameters:

dirCtx - The JNDI DirContext

subScriberLocation - DN of the subscriber for the given user - can be null in case applications are not aware of it

userDN - DN of the given user in the subscriber tree

Throws:

AddressBookException - Throws AddressBookException in case of errors

Method Detail

setDirContext

public void setDirContext(javax.naming.directory.DirContext dirCtx)
                   throws AddressBookException

This method can be invoked to set the DirContext for the user addressbook operations.

Parameters:

dirCtx - The JNDI DirContext

Throws:

AddressBookException - Throws AddressBookException in case of errors

getCategories

public java.lang.String[] getCategories(int category_type)
                                 throws AddressBookException

This method retrieves the possible address book categories. This API can be used to retrieve user/system categories.

Parameters:

category_type - the types of categories to be fetched. AddressBookConstants.USER_CATEGORY - this will return only user defined categories AddressBookConstants.SYSTEM_CATEGORY - this will return only system level categories

Returns:

An array of Strings containing address book categories, null if there is no category defined

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

getContactSchema

public SchemaObject getContactSchema()
                              throws AddressBookException

This method will return the representation of a contact in LDAP, ie. the ldap schema information for a contact object. From the schema object, various information like the list of mandatory and optional attributes for the contact entry can be obtained. It also contains information about all these attributes, for example the syntax, multiplicity of the attributes etc.

Parameters:

void -

Returns:

schema info for contacts

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

createContact

public AddressBookContact createContact(AddressBookAttribute[] attrs)
                                 throws AddressBookException

This method adds a contact to the given user's addressbook.

Parameters:

attrs - The contact attributes. The following example shows how to set a value for mail id of a contact. ...mailAttr = new AddressBookAttribute(AddressBookContactConstants.MAILID); mailAttr.setValue("testuser@oracle.com");

Returns:

a reference to the contact that got created

Throws:

AddressBookException - Throws AddressBookException if any error is encountered. When contact already exists, this exception is an instance of AddressBookEntryExistsException

deleteContactByFilter

public java.lang.String[] deleteContactByFilter(java.lang.String filter)
                                         throws AddressBookException

This method deletes contacts from user's address book matching the given criteria. This also deletes all the references to deleted contacts in the user's address book.

Parameters:

filter - Filter for searching contacts, must be a valid LDAP filter (Note: it's caller's responsibility to pass a valid filter)

Returns:

String[] containing DNs of the deleted items

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

getAllContacts

public AddressBookContact[] getAllContacts(java.lang.String[] attrsToFetch,
                                           int batchSize,
                                           int sizeLimit,
                                           java.lang.String sortingAttr)
                                    throws AddressBookException

This method retrieves All Contacts for the given user.For large number of contacts, the callers can retrieve them piecewise in batches. The piecewise fetch should be used for large no of contacts as it blocks the particular ldap connection to retain the same search.
Note: While doing piecewise fetch, we will have to hold on to the same ldap handle.
Case 1 => When OCS connection pool is used by address book layer - In this case, if the caller does not fetch all entries or does not clear the search to release the handle, we will be blocking that ldap handle. In a JVM, if there are multiple operations in such state, then we might run out of connections or requests might have to wait longer. The timeout mechanism helps under these circumstances. In case of web client or other application, let's say user does a search and is in the first page, however without going to other pages users clicks elsewhere, in this case application MUST invoke "clearPiecewiseContactsFlag" method. To find out if more data exists at the server side or not, "ifNextBatchContacts" method can be used.
Case 2 => When connection pool is managed by caller and a piecewise fetch is done, in case, more data is to be recieved from server side, this layer will store a reference to the DirContext passed by the caller. So callers must use another DirContext for other operations.

Parameters:

attrsToFetch - The list of contact attributes to be returned. null means fetch all attributes

batchSize - The no of contacts to fetch in one batch. 0 or -1 means fetch all contacts matching the search criteria

sizeLimit - The maximum no of contacts to fetch. 0 or -1 means fetch all contacts matching the search criteria

sortingAttr - The name of the attribute for which results are to be sorted, this will be using server side sorting feature (provided server side ldap sorting is supported by OID). null implies no sorting

Returns:

An array of Contact objects, null if there is no match

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

getContacts

public AddressBookContact[] getContacts(java.lang.String searchCriteria,
                                        java.lang.String[] attrsToFetch,
                                        int batchSize,
                                        int sizeLimit,
                                        java.lang.String sortingAttr)
                                 throws AddressBookException

This method retrieves Contacts for the given user for the matching search criteria. The search criteria must be a valid ldap filter. For ex., criteria "givenname=t*" returns all the contacts with firstname starting with "t". For large number of contacts, callers can retrieve them piecewise in batches. The piecewise fetch should be used for large no of contacts as it blocks the particular ldap connection to retain the same search.
Note: While doing piecewise fetch, we will have to hold on to the same ldap handle.
Case 1 => When OCS connection pool is used by address book layer - In this case, if the caller does not fetch all entries or does not clear the search to release the handle, we will be blocking that ldap handle. In a JVM, if there are multiple operations in such state, then we might run out of connections or requests might have to wait longer. The timeout mechanism helps under these circumstances. In case of web client or other application, let's say user does a search and is in the first page, however without going to other pages users clicks elsewhere, in this case application MUST invoke "clearPiecewiseContactsFlag" method. To find out if more data exists at the server side or not, "ifNextBatchContacts" method can be used.
Case 2 => When connection pool is managed by caller and a piecewise fetch is done, in case, more data is to be recieved from server side, this layer will store a reference to the DirContext passed by the caller. So callers must use another DirContext for other operations.

Parameters:

searchCriteria - The search criteria in the ldap filter format

attrsToFetch - The list of contact attributes to be returned. null means fetch all attributes

batchSize - The no of contacts to fetch in one batch. 0 or -1 means fetch all contacts matching the search criteria

sizeLimit - The maximum no of contacts to fetch. 0 or -1 means fetch all contacts matching the search criteria

sortingAttr - The name of the attribute for which results are to be sorted, this will be using server side sorting feature (provided server side ldap sorting is supported by OID). null implies no sorting

Returns:

An array of Contact objects, null if there is no match

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

clearPiecewiseContactsFlag

public void clearPiecewiseContactsFlag()
                                throws AddressBookException

This method clears the ldap handle and flags etc. associated with prior piecewise fetch of user contacts. MUST be invoked if callers does not want to fetch the remaining data from the prior search and wants to perform a new search. This method is important and must be invoked by callers performing piecewise fetches as they are blocking ldap connection for piecewise fetch

Parameters:

void -

Returns:

void

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

ifNextBatchContacts

public boolean ifNextBatchContacts()

This method tells whether more data is to be fetched from server side for the prior piecewise fetch of user contacts.

Parameters:

void -

Returns:

boolean true means data exists

getListSchema

public SchemaObject getListSchema()
                           throws AddressBookException

This method will return the representation of a list in LDAP, ie. the ldap schema information for a list object. From the schema object, various information like the list of mandatory and optional attributes for the list entry can be obtained. It also contains information about all these attributes, for example the syntax, multiplicity of the attributes etc.

Parameters:

void -

Returns:

schema info for lists

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

createList

public AddressBookList createList(AddressBookAttribute[] attrs,
                                  AddressBookContact[] contacts,
                                  AddressBookList[] lists)
                           throws AddressBookException

This method adds a list to the given user's addressbook.

Parameters:

attrs - The list attributes. The following example shows how to add 2 mail ids for a new list ...mailAttr = new AddressBookAttribute(AddressBookListConstants.MAILADDRESSES); mailAttr.setValue(new String[] {"testuser1@oracle.com", "testuser2@oracle.com"}); Contact members and lists can be added to the given list using add/delete methods of AddressBookList or by passing the contacts and lists parameters

contacts - list of contacts to be added to this list [ for contacts, the AddressBookContact objects can be obtained by performing a query.]. null means no contact members

lists - other lists to be added to this list [ for these lists, the AddressBookList objects can be obtained by performing a query.] null means no list members

Returns:

a reference to the list that was created

Throws:

AddressBookException - Throws AddressBookException if any error is encountered. When list already exists, this exception is an instance of AddressBookEntryExistsException

deleteListByFilter

public java.lang.String[] deleteListByFilter(java.lang.String filter)
                                      throws AddressBookException

This method deletes lists from user's address book matching the given criteria. This also deletes all the references to deleted lists in the user's address book.

Parameters:

filter - Filter for searching lists, must be a valid LDAP filter (Note: it's caller's responsibility to pass a valid filter)

Returns:

String[] containing DNs of the deleted items

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

getAllLists

public AddressBookList[] getAllLists(java.lang.String[] attrsToFetch,
                                     int batchSize,
                                     int sizeLimit,
                                     java.lang.String sortingAttr)
                              throws AddressBookException

This method retrieves all Lists for the given user. For large number of lists, the callers can retrieve them piecewise in batches. The piecewise fetch should be used for large no of lists as it blocks the particular ldap connection to retain the same search.
Note: While doing piecewise fetch, we will have to hold on to the same ldap handle.
Case 1 => When OCS connection pool is used by address book layer - In this case, if the caller does not fetch all entries or does not clear the search to release the handle, we will be blocking that ldap handle. In a JVM, if there are multiple operations in such state, then we might run out of connections or requests might have to wait longer. The timeout mechanism helps under these circumstances. In case of web client or other application, let's say user does a search and is in the first page, however without going to other pages users clicks elsewhere, in this case application MUST invoke "clearPiecewiseListsFlag" method. To find out if more data exists at the server side or not, "ifNextBatchLists" method can be used.
Case 2 => When connection pool is managed by caller and a piecewise fetch is done, in case, more data is to be recieved from server side, this layer will store a reference to the DirContext passed by the caller. So callers must use another DirContext for other operations.

Parameters:

attrsToFetch - The list of list attributes to be returned. null means fetch all attributes

batchSize - The no of lists to fetch in one batch. 0 or -1 means fetch all lists matching the search criteria

sizeLimit - The maximum no of lists to fetch. 0 or -1 means fetch all contacts matching the search criteria

sortingAttr - The name of the attribute for which results are to be sorted, this will be using server side sorting feature (provided server side ldap sorting is supported by OID). null implies no sorting

Returns:

An array of List objects, null if there is no match

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

getLists

public AddressBookList[] getLists(java.lang.String searchCriteria,
                                  java.lang.String[] attrsToFetch,
                                  int batchSize,
                                  int sizeLimit,
                                  java.lang.String sortingAttr)
                           throws AddressBookException

This method retrieves Lists for the given user for the matching search criteria. The search criteria must be a valid ldap filter. For large number of lists, the callers can retrieve them piecewise in batches. The piecewise fetch should be used for large no of lists as it blocks the particular ldap connection to retain the same search.
Note: While doing piecewise fetch, we will have to hold on to the same ldap handle.
Case 1 => When OCS connection pool is used by address book layer - In this case, if the caller does not fetch all entries or does not clear the search to release the handle, we will be blocking that ldap handle. In a JVM, if there are multiple operations in such state, then we might run out of connections or requests might have to wait longer. The timeout mechanism helps under these circumstances. In case of web client or other application, let's say user does a search and is in the first page, however without going to other pages users clicks elsewhere, in this case application MUST invoke "clearPiecewiseListsFlag" method. To find out if more data exists at the server side or not, "ifNextBatchLists" method can be used.
Case 2 => When connection pool is managed by caller and a piecewise fetch is done, in case, more data is to be recieved from server side, this layer will store a reference to the DirContext passed by the caller. So callers must use another DirContext for other operations.

Parameters:

searchCriteria - The search criteria in the ldap filter format

attrsToFetch - The list of list attributes to be returned. null means fetch all attributes

batchSize - The no of lists to fetch in one batch. 0 or -1 means fetch all lists matching the search criteria

sizeLimit - The maximum no of lists to fetch. 0 or -1 means fetch all contacts matching the search criteria

sortingAttr - The name of the attribute for which results are to be sorted, this will be using server side sorting feature (provided server side ldap sorting is supported by OID). null implies no sorting

Returns:

An array of List objects, null if there is no match

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

clearPiecewiseListsFlag

public void clearPiecewiseListsFlag()
                             throws AddressBookException

This method clears the ldap handle and flags etc. associated with prior piecewise fetch of user lists. MUST be invoked if callers does not want to fetch the remaining data from the prior search and wants to perform a new search. This method is important and must be invoked by callers performing piecewise fetches as they are blocking ldap connection for piecewise fetch

Parameters:

void -

Returns:

void

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

ifNextBatchLists

public boolean ifNextBatchLists()

This method tells whether more data is to be fetched from server side for the prior piecewise fetch of user lists.

Parameters:

void -

Returns:

boolean true means data exists

getCategoriesFromSharedAddressbook

public java.lang.String[] getCategoriesFromSharedAddressbook(java.lang.String ownerUserGUID)
                                                      throws AddressBookException

This method retrieves the possible address book categories from for a shared addressbook. It gets only the user defined public categories.

Parameters:

ownerUserGUID - The GUID of the user in whose address book this contact is getting created

Returns:

An array of Strings containing address book categories, null if there is no category defined

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

share

public java.lang.String[] share(java.lang.String[] readAccessGUIDs,
                                java.lang.String[] writeAccessGUIDs)
                         throws AddressBookException

This API lets the user share his/her addressbook with other users.

Parameters:

readAccessGUIDs - An array of Strings containing user GUIDs for giving read permission - can be null if user is giving only write permissions

writeAccessGUIDs - An array of Strings containing user GUIDs for giving write permission - can be null if user is giving only read permissions

Returns:

an array of Strings containing the GUIDs for which sharing failed.

Throws:

AddressBookException - Throws AddressbookException if any error is encountered.

unshare

public java.lang.String[] unshare(java.lang.String[] userGUIDs)
                           throws AddressBookException

This API lets the user unshare his/her addressbook from the given list of users.

Parameters:

userGUIDs - An array of Strings containing user GUIDs for removing access. When this is null, this means remove sharing access from all users

Returns:

an array of Strings containing the GUIDs for which unsharing failed.

Throws:

AddressBookException - Throws AddressbookException if any error is encountered.

getReadersList

public java.lang.String[] getReadersList()
                                  throws AddressBookException

This API gets the list of users having read permission on user's address book. Returns null in case addressbook does not have any readers.

Parameters:

void -

Returns:

an array of Strings containing the GUIDs of users having read access

Throws:

AddressBookException - Throws AddressbookException if any error is encountered.

getWritersList

public java.lang.String[] getWritersList()
                                  throws AddressBookException

This API gets the list of users having read and write permission on user's address book. Returns null in case addressbook does not have any writers.

Parameters:

void -

Returns:

an array of Strings containing the GUIDs of users having read/write access

Throws:

AddressBookException - Throws AddressbookException if any error is encountered.

getReadersAndWritersList

public java.util.Hashtable getReadersAndWritersList()
                                             throws AddressBookException

This API gets the list of users having read only and read/write permission on user's address book. Returns null if no readers and writers are present. Also, if there are no readers or writers, hashtable does not contain the respective type.

Parameters:

void -

Returns:

a hashtable - key of hashtable is AddressBookConstants.READERS for reader guids and AddressBookConstants.WRITERS for writer guids. The value is an array of Strings containing the GUIDs. Returns null if user has not shared his/her address book.

Throws:

AddressBookException - Throws AddressbookException if any error is encountered.

getUserGUIDsSharingAddressBook

public java.lang.String[] getUserGUIDsSharingAddressBook()
                                                  throws AddressBookException

This API gets the list of user GUIDs who have shared their address book with this user.

Parameters:

void -

Returns:

an array of Strings containing the GUIDs of users sharing their address book with this user

Throws:

AddressBookException - Throws AddressbookException if any error is encountered.

getSharedAddressBookOwnerGUIDs

public java.util.Hashtable getSharedAddressBookOwnerGUIDs()
                                                   throws AddressBookException

This API gets the list of user GUIDs who have shared their address book with this user. Using this API, caller can figure out which user's address book the given user has read access to and to which user's address book the given user has write access to.

Parameters:

void -

Returns:

a Hashtable - key of hashtable is AddressBookConstants.READERS for reader guids and AddressBookConstants.WRITERS for writer guids. The value is an array of Strings containing the GUIDs. Returns null if user does not have access to any shared address book.

Throws:

AddressBookException - Throws AddressbookException if any error is encountered.

createContactInSharedAddressBook

public AddressBookContact createContactInSharedAddressBook(java.lang.String ownerUserGUID,
                                                           AddressBookAttribute[] attrs)
                                                    throws AddressBookException

This method adds a contact in another given user's addressbook. For this API to work, the current user must have "write" permission on the other user's address book.

Parameters:

ownerUserGUID - The GUID of the user in whose address book this contact is getting created

attrs - The contact attributes. The following example shows how to set a value for mail id of a contact. ...mailAttr = new AddressBookAttribute(AddressBookContactConstants.MAILID); mailAttr.setValue("testuser@oracle.com");

Returns:

a reference to the contact that was created

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

getSharedContacts

public AddressBookContact[] getSharedContacts(java.lang.String[] usersGUIDs,
                                              java.lang.String searchCriteria,
                                              java.lang.String[] attrsToFetch,
                                              int batchSize,
                                              int sizeLimit,
                                              java.lang.String sortingAttr)
                                       throws AddressBookException

This method retrieves Contacts other users have shared with this user for the matching search criteria. The search criteria must be a valid ldap filter. For ex., with usersGUIDs array E034080020A0ADB6 and ABCE034080020A0ADB6 and criteria "givenname=t*" returns all the contacts shared having givenname starting with t* by users E034080020A0ADB6 and ABCE034080020A0ADB with this user. For large number of contacts, the callers can retrieve them piecewise in batches. The piecewise fetch should be used for large no of contacts as it blocks the particular ldap connection to retain the same search.
Note: While doing piecewise fetch, we will have to hold on to the same ldap handle.
Case 1 => When connection pool is managed by address book layer- In this case, if the caller does not fetch all entries or does not clear the search to release the handle, we will be blocking that ldap handle. In a JVM, if there are multiple operations in such state, then we might run out of connections or requests might have to wait longer. The timeout mechanism helps under these circumstances. In case of web client or other application, let's say user does a search and is in the first page, however without going to other pages users clicks elsewhere, in this case application MUST invoke "clearPiecewiseContactsFlag" method. To find out if more data exists at the server side or not, "ifNextBatchContacts" method can be used.
Case 2 => When connection pool is managed by caller and a piecewise fetch is done, in case, more data is to be recieved from server side, this layer will store a reference to the DirContext passed by the caller. So callers must use another DirContext for other operations.

Parameters:

usersGUIDs - The list of user GUIDs whose addressbook needs to be searched. When this is null, this API gets any shared contacts from all user's address book.

searchCriteria - The search criteria in the ldap filter format

attrsToFetch - The list of contact attributes to be returned. null means fetch all attributes

batchSize - The no of contacts to fetch in one batch. 0 or -1 means fetch all contacts matching the search criteria

sizeLimit - The maximum no of contacts to fetch. 0 or -1 means fetch all contacts matching the search criteria

sortingAttr - The name of the attribute for which results are to be sorted, this will be using server side sorting feature (provided server side ldap sorting is supported by OID). null implies no sorting [this sorting is done per user]

Returns:

An array of Contact objects, null if there is no match

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

createListInSharedAddressBook

public AddressBookList createListInSharedAddressBook(java.lang.String ownerUserGUID,
                                                     AddressBookAttribute[] attrs,
                                                     AddressBookContact[] contacts,
                                                     AddressBookList[] lists)
                                              throws AddressBookException

This method adds a list in another given user's addressbook. For this API to work, the current user must have "write" permission on the other user's address book.

Parameters:

ownerUserGUID - The GUID of the user in whose address book this list is getting created

attrs - The list attributes. The following example shows how to set a value for mail id of a list. ...mailAttr = new AddressBookAttribute(AddressBookContactConstants.MAILID); mailAttr.setValue("testuser@oracle.com");

contacts - list of contacts to be added to this list [ for contacts, the AddressBookContact objects can be obtained by performing a query.]. null means no contact members. The contact members must belong to the address book of ownerUserGUID user.

lists - other lists to be added to this list [ for these lists, the AddressBookList objects can be obtained by performing a query.] null means no list members. The list members must belong to the address book of ownerUserGUID user.

Returns:

a reference to the list that was created

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

getSharedLists

public AddressBookList[] getSharedLists(java.lang.String[] usersGUIDs,
                                        java.lang.String searchCriteria,
                                        java.lang.String[] attrsToFetch,
                                        int batchSize,
                                        int sizeLimit,
                                        java.lang.String sortingAttr)
                                 throws AddressBookException

This method retrieves lists other users have shared with this user for the matching search criteria. The search criteria must be a valid ldap filter. For ex., with usersGUIDs array E034080020A0ADB6 and ABCE034080020A0ADB6 and criteria "orcladdressbookid=*" returns all the lists shared by users E034080020A0ADB6 and ABCE034080020A0ADB with this user. For large number of lists, the callers can retrieve them piecewise in batches. The piecewise fetch should be used for large no of lists as it blocks the particular ldap connection to retain the same search.
Note: While doing piecewise fetch, we will have to hold on to the same ldap handle.
Case 1 => When connection pool is managed by address book layer- In this case, if the caller does not fetch all entries or does not clear the search to release the handle, we will be blocking that ldap handle. In a JVM, if there are multiple operations in such state, then we might run out of connections or requests might have to wait longer. The timeout mechanism helps under these circumstances. In case of web client or other application, let's say user does a search and is in the first page, however without going to other pages users clicks elsewhere, in this case application MUST invoke "clearPiecewiseContactsFlag" method. To find out if more data exists at the server side or not, "ifNextBatchLists" method can be used.
Case 2 => When connection pool is managed by caller and a piecewise fetch is done, in case, more data is to be recieved from server side, this layer will store a reference to the DirContext passed by the caller. So callers must use another DirContext for other operations.

Parameters:

usersGUIDs - The list of user GUIDs whose addressbook needs to be searched. When this is null, this API gets any shared lists from all user's address book.

searchCriteria - The search criteria in the ldap filter format

attrsToFetch - The list of list attributes to be returned. null means fetch all attributes

batchSize - The no of lists to fetch in one batch. 0 or -1 means fetch all lists matching the search criteria

sizeLimit - The maximum no of lists to fetch. 0 or -1 means fetch all contacts matching the search criteria

sortingAttr - The name of the attribute for which results are to be sorted, this will be using server side sorting feature (provided server side ldap sorting is supported by OID). null implies no sorting [this sorting is done per user]

Returns:

An array of List objects, null if there is no match

Throws:

AddressBookException - Throws AddressBookException if any error is encountered.

getAddressBookDN

public java.lang.String getAddressBookDN()