org.osid.contact

Interface ContactLookupSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

public interface ContactLookupSession
extends OsidSession

This session defines methods for retrieving contacts.

This lookup session defines several views:

• comparative view: elements may be silently omitted or re-ordered
• plenary view: provides a complete result set or is an error condition
• isolated address book view: All contact methods in this session operate, retrieve and pertain to contacts defined explicitly in the current address book. Using an isolated view is useful for managing contacts with the ContactAdminSession.
• federated address book view: All contact lookup methods in this session operate, retrieve and pertain to all contacts defined in this address book and any other address books implicitly available in this address book through address book inheritence.
• effective contact view: All contact lookup methods return contacts where the current dates falls in between the effective dates inclusive.
• any effective contact view: Contacts of any effective date are returned.

The methods useFederatedAddressBookView() and useIsolatedAddressBookView() behave as a radio group and one should be selected before invoking any lookup methods.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupContacts() Tests if this user can lookup contacts.
AddressBook	getAddressBook() Gets the AddressBook associated with this session.
Id	getAddressBookId() Gets the AddressBook Id associated with this session.
Contact	getContact(Id contactId) Gets the Contact specified by its Id.
ContactList	getContacts() Gets all contacts.
ContactList	getContactsByGenusType(Type contactGenusType) Gets a ContactList corresponding to the given contact genus Type which does not include contacts of genus types derived from the specified Type.
ContactList	getContactsByGenusTypeForAddress(Id addressId, Type contactGenusType) Gets a list of all contacts of the given genus type corresponding to an address Id.
ContactList	getContactsByGenusTypeForAddressOnDate(Id addressId, Type contactGenusType, DateTime from, DateTime to) Gets a list of all contacts of the given genus type corresponding to an address Id and effective during the entire given date range inclusive but not confined to the date range.
ContactList	getContactsByGenusTypeForReference(Id referenceId, Type contactGenusType) Gets a list of contacts of the given genus type corresponding to a reference Id.
ContactList	getContactsByGenusTypeForReferenceAndAddress(Id referenceId, Id addressId, Type contactGenusType) Gets a list of all contacts with the given genus type corresponding to a reference and address Id.
ContactList	getContactsByGenusTypeForReferenceAndAddressOnDate(Id referenceId, Id addressId, Type contactGenusType, DateTime from, DateTime to) Gets a list of all contacts with the given genus type corresponding to a reference and address Id and during the entire given date range inclusive but not confined to the date range.
ContactList	getContactsByGenusTypeForReferenceOnDate(Id referenceId, Type contactGenusType, DateTime from, DateTime to) Gets a list of all contacts of the given genus type corresponding to a reference Id and effective during the entire given date range inclusive but not confined to the date range.
ContactList	getContactsByGenusTypeOnDate(Type contactGenusType, DateTime from, DateTime to) Gets a list of contacts of a genus type and with an effective during the entire given date range inclusive but not confined to the date range.
ContactList	getContactsByIds(IdList contactIds) Gets a ContactList corresponding to the given IdList.
ContactList	getContactsByParentGenusType(Type contactGenusType) Gets a ContactList corresponding to the given contact genus Type and include any additional contacts with genus types derived from the specified Type.
ContactList	getContactsByRecordType(Type contactRecordType) Gets a ContactList containing the given contact record Type.
ContactList	getContactsForAddress(Id addressId) Gets a list of all contacts corresponding to an address Id.
ContactList	getContactsForAddressOnDate(Id addressId, DateTime from, DateTime to) Gets a list of all contacts corresponding to an address Id and effective during the entire given date range inclusive but not confined to the date range.
ContactList	getContactsForReference(Id referenceId) Gets a list of contacts corresponding to a reference Id.
ContactList	getContactsForReferenceAndAddress(Id referenceId, Id addressId) Gets a list of all contacts corresponding to a reference and address Id.
ContactList	getContactsForReferenceAndAddressOnDate(Id referenceId, Id addressId, DateTime from, DateTime to) Gets a list of all contacts corresponding to a reference and address Id and effectiveduring the entire given date range inclusive but not confined to the date range.
ContactList	getContactsForReferenceOnDate(Id referenceId, DateTime from, DateTime to) Gets a list of all contacts corresponding to a reference Id and effective during the entire given date range inclusive but not confined to the date range.
ContactList	getContactsOnDate(DateTime from, DateTime to) Gets a list of contacts with an effective during the entire given date range inclusive but not confined to the date range.
void	useAnyEffectiveContactView() All contacts of any effective dates are returned by all methods in this session.
void	useComparativeContactView() The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	useEffectiveContactView() Only contacts whose effective dates are current are returned by methods in this session.
void	useFederatedAddressBookView() Federates the view for methods in this session.
void	useIsolatedAddressBookView() Isolates the view for methods in this session.
void	usePlenaryContactView() A complete view of the Contact returns is desired.

Methods inherited from interface org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

getAddressBookId

Id getAddressBookId()

Gets the AddressBook Id associated with this session.

Returns:

the AddressBook Id associated with this session

Compliance:

mandatory - This method must be implemented.

getAddressBook

AddressBook getAddressBook()
                           throws OperationFailedException,
                                  PermissionDeniedException

Gets the AddressBook associated with this session.

Returns:

the address book

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupContacts

boolean canLookupContacts()

Tests if this user can lookup contacts. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer these operations.

Returns:

false if contact lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeContactView

void useComparativeContactView()

The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error. This view is used when greater interoperability is desired at the expense of precision.

Compliance:

mandatory - This method is must be implemented.

usePlenaryContactView

void usePlenaryContactView()

A complete view of the Contact returns is desired. Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.

Compliance:

mandatory - This method is must be implemented.

useFederatedAddressBookView

void useFederatedAddressBookView()

Federates the view for methods in this session. A federated view will include contacts in address books which are children of this address book in the address book hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedAddressBookView

void useIsolatedAddressBookView()

Isolates the view for methods in this session. An isolated view restricts retrievals to this address book only.

Compliance:

mandatory - This method is must be implemented.

useEffectiveContactView

void useEffectiveContactView()

Only contacts whose effective dates are current are returned by methods in this session.

Compliance:

mandatory - This method is must be implemented.

useAnyEffectiveContactView

void useAnyEffectiveContactView()

All contacts of any effective dates are returned by all methods in this session.

Compliance:

mandatory - This method is must be implemented.

getContact

Contact getContact(Id contactId)
                   throws NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

Gets the Contact specified by its Id. In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Contact may have a different Id than requested, such as the case where a duplicate Id was assigned to a Contact and retained for compatibility. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

contactId - the Id of the Contact to retrieve

Returns:

the returned Contact

Throws:

NotFoundException - no Contact found with the given Id

NullArgumentException - contactId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsByIds

ContactList getContactsByIds(IdList contactIds)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Gets a ContactList corresponding to the given IdList. In plenary mode, the returned list contains all of the contacts specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible contacts may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

contactIds - the list of Ids to retrieve

Returns:

the returned Contact list

Throws:

NotFoundException - an Id was not found

NullArgumentException - contactIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsByGenusType

ContactList getContactsByGenusType(Type contactGenusType)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Gets a ContactList corresponding to the given contact genus Type which does not include contacts of genus types derived from the specified Type. In plenary mode, the returned list contains all of the contacts specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible contacts may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

contactGenusType - a contact genus type

Returns:

the returned Contact list

Throws:

NullArgumentException - contactGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsByParentGenusType

ContactList getContactsByParentGenusType(Type contactGenusType)
                                         throws OperationFailedException,
                                                PermissionDeniedException

Gets a ContactList corresponding to the given contact genus Type and include any additional contacts with genus types derived from the specified Type. In plenary mode, the returned list contains all of the contacts specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible contacts may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

contactGenusType - a contact genus type

Returns:

the returned Contact list

Throws:

NullArgumentException - contactGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsByRecordType

ContactList getContactsByRecordType(Type contactRecordType)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Gets a ContactList containing the given contact record Type. In plenary mode, the returned list contains all of the contacts specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible contacts may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

contactRecordType - a contact record type

Returns:

the returned Contact list

Throws:

NullArgumentException - contactRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsOnDate

ContactList getContactsOnDate(DateTime from,
                            DateTime to)
                              throws OperationFailedException,
                                     PermissionDeniedException

Gets a list of contacts with an effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

from - the starting date

to - the ending date

Returns:

the returned ContactList

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsByGenusTypeOnDate

ContactList getContactsByGenusTypeOnDate(Type contactGenusType,
                                       DateTime from,
                                       DateTime to)
                                         throws OperationFailedException,
                                                PermissionDeniedException

Gets a list of contacts of a genus type and with an effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

contactGenusType - a contact genus type

from - the starting date

to - the ending date

Returns:

the returned ContactList

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - contactGenusType, from, or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsForReference

ContactList getContactsForReference(Id referenceId)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Gets a list of contacts corresponding to a reference Id. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

referenceId - the Id of the reference

Returns:

the returned ContactList

Throws:

NullArgumentException - referenceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsForReferenceOnDate

ContactList getContactsForReferenceOnDate(Id referenceId,
                                        DateTime from,
                                        DateTime to)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Gets a list of all contacts corresponding to a reference Id and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

referenceId - a reference Id

from - from date

to - to date

Returns:

the returned ContactList

Throws:

InvalidArgumentException - to is less than from

NullArgumentException - referenceId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsByGenusTypeForReference

ContactList getContactsByGenusTypeForReference(Id referenceId,
                                             Type contactGenusType)
                                               throws OperationFailedException,
                                                      PermissionDeniedException

Gets a list of contacts of the given genus type corresponding to a reference Id. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

referenceId - the Id of the reference

contactGenusType - the genus type of the contact

Returns:

the returned ContactList

Throws:

NullArgumentException - referenceId or contactGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsByGenusTypeForReferenceOnDate

ContactList getContactsByGenusTypeForReferenceOnDate(Id referenceId,
                                                   Type contactGenusType,
                                                   DateTime from,
                                                   DateTime to)
                                                     throws OperationFailedException,
                                                            PermissionDeniedException

Gets a list of all contacts of the given genus type corresponding to a reference Id and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

referenceId - a reference Id

contactGenusType - the genus type of the contact

from - from date

to - to date

Returns:

the returned ContactList

Throws:

InvalidArgumentException - to is less than from

NullArgumentException - referenceId, contactGenusType, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsForAddress

ContactList getContactsForAddress(Id addressId)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Gets a list of all contacts corresponding to an address Id. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

addressId - the Id of the address

Returns:

the returned ContactList

Throws:

NullArgumentException - addressId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsForAddressOnDate

ContactList getContactsForAddressOnDate(Id addressId,
                                      DateTime from,
                                      DateTime to)
                                        throws OperationFailedException,
                                               PermissionDeniedException

Gets a list of all contacts corresponding to an address Id and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

addressId - an address Id

from - from date

to - to date

Returns:

the returned ContactList

Throws:

InvalidArgumentException - to is less than from

NullArgumentException - addressId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsByGenusTypeForAddress

ContactList getContactsByGenusTypeForAddress(Id addressId,
                                           Type contactGenusType)
                                             throws OperationFailedException,
                                                    PermissionDeniedException

Gets a list of all contacts of the given genus type corresponding to an address Id. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

addressId - the Id of the address

contactGenusType - the genus type of the contact

Returns:

the returned ContactList

Throws:

NullArgumentException - addressId or contactGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsByGenusTypeForAddressOnDate

ContactList getContactsByGenusTypeForAddressOnDate(Id addressId,
                                                 Type contactGenusType,
                                                 DateTime from,
                                                 DateTime to)
                                                   throws OperationFailedException,
                                                          PermissionDeniedException

Gets a list of all contacts of the given genus type corresponding to an address Id and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

addressId - an address Id

contactGenusType - the genus type of the contact

from - from date

to - to date

Returns:

the returned ContactList

Throws:

InvalidArgumentException - to is less than from

NullArgumentException - addressId, contactGenusType, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsForReferenceAndAddress

ContactList getContactsForReferenceAndAddress(Id referenceId,
                                            Id addressId)
                                              throws OperationFailedException,
                                                     PermissionDeniedException

Gets a list of all contacts corresponding to a reference and address Id. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

referenceId - the Id of the reference

addressId - the Id of the address

Returns:

the returned ContactList

Throws:

NullArgumentException - referenceId or addressId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsForReferenceAndAddressOnDate

ContactList getContactsForReferenceAndAddressOnDate(Id referenceId,
                                                  Id addressId,
                                                  DateTime from,
                                                  DateTime to)
                                                    throws OperationFailedException,
                                                           PermissionDeniedException

Gets a list of all contacts corresponding to a reference and address Id and effectiveduring the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

referenceId - the Id of the reference

addressId - an address Id

from - from date

to - to date

Returns:

the returned ContactList

Throws:

InvalidArgumentException - to is less than from

NullArgumentException - referenceId, addressI, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsByGenusTypeForReferenceAndAddress

ContactList getContactsByGenusTypeForReferenceAndAddress(Id referenceId,
                                                       Id addressId,
                                                       Type contactGenusType)
                                                         throws OperationFailedException,
                                                                PermissionDeniedException

Gets a list of all contacts with the given genus type corresponding to a reference and address Id. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

referenceId - the Id of the reference

addressId - the Id of the address

contactGenusType - the genus type of the contact

Returns:

the returned ContactList

Throws:

NullArgumentException - referenceId, addressId or contactGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContactsByGenusTypeForReferenceAndAddressOnDate

ContactList getContactsByGenusTypeForReferenceAndAddressOnDate(Id referenceId,
                                                             Id addressId,
                                                             Type contactGenusType,
                                                             DateTime from,
                                                             DateTime to)
                                                               throws OperationFailedException,
                                                                      PermissionDeniedException

Gets a list of all contacts with the given genus type corresponding to a reference and address Id and during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Parameters:

referenceId - the Id of the reference

addressId - an address Id

contactGenusType - the genus type of the contact

from - from date

to - to date

Returns:

the returned ContactList

Throws:

InvalidArgumentException - to is less than from

NullArgumentException - referenceId, addressId, contactGenusType, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getContacts

ContactList getContacts()
                        throws OperationFailedException,
                               PermissionDeniedException

Gets all contacts. In plenary mode, the returned list contains all known contacts or an error results. Otherwise, the returned list may contain only those contacts that are accessible through this session. In effective mode, contacts are returned that are currently effective. In any effective mode, effective contacts and those currently expired are returned.

Returns:

a list of contacts

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.