org.osid.contact

Interface AddressSmartAddressBookSession

All Superinterfaces:

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

public interface AddressSmartAddressBookSession
extends OsidSession

This session manages queries and sequencing to create "smart" dynamic catalogs. An AddressQuery can be retrieved from this session and mapped to this AddressBook to create a virtual collection of Addresses. The addresses may be sequenced using the AddressSearchOrder from this session.

This AddressBook has a default query that matches any address and a default search order that specifies no sequencing. The queries may be examined using an AddressQueryInspector. The query may be modified by converting the inspector back to an AddressQuery.

Method Summary

Methods

Modifier and Type	Method and Description
void	applyAddressQuery(AddressQuery addressQuery) Applies an address query to this address book.
void	applyAddressSequencing(AddressSearchOrder addressSearchOrder) Applies an address search order to this address book.
boolean	canManageSmartAddressBooks() Tests if this user can manage smart address books.
AddressBook	getAddressBook() Gets the AddressBook associated with this session.
Id	getAddressBookId() Gets the AddressBook Id associated with this session.
AddressQuery	getAddressQuery() Gets an address query.
AddressQuery	getAddressQueryFromInspector(AddressQueryInspector addressQueryInspector) Gets an address query from an inspector.
AddressSearchOrder	getAddressSearchOrder() Gets an address search order.
AddressQueryInspector	inspectAddressQuery() Gets an address query inspector for this address book.

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 AddressBook associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageSmartAddressBooks

boolean canManageSmartAddressBooks()

Tests if this user can manage smart address books. A return of true does not guarantee successful authorization. A return of false indicates that it is known 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 operations to unauthorized users.

Returns:

false if smart address book management is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getAddressQuery

AddressQuery getAddressQuery()

Gets an address query.

Returns:

the address query

Compliance:

mandatory - This method must be implemented.

getAddressSearchOrder

AddressSearchOrder getAddressSearchOrder()

Gets an address search order.

Returns:

the address search order

Compliance:

mandatory - This method must be implemented.

applyAddressQuery

void applyAddressQuery(AddressQuery addressQuery)
                       throws OperationFailedException,
                              PermissionDeniedException

Applies an address query to this address book.

Parameters:

addressQuery - the address query

Throws:

NullArgumentException - addressQuery is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

UnsupportedException - addressQuery not of this service

Compliance:

mandatory - This method must be implemented.

inspectAddressQuery

AddressQueryInspector inspectAddressQuery()
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Gets an address query inspector for this address book.

Returns:

the address query inspector

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

applyAddressSequencing

void applyAddressSequencing(AddressSearchOrder addressSearchOrder)
                            throws OperationFailedException,
                                   PermissionDeniedException

Applies an address search order to this address book.

Parameters:

addressSearchOrder - the address search order

Throws:

NullArgumentException - addressSearchOrder is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

UnsupportedException - addressSearchOrder not of this service

Compliance:

mandatory - This method must be implemented.

getAddressQueryFromInspector

AddressQuery getAddressQueryFromInspector(AddressQueryInspector addressQueryInspector)

Gets an address query from an inspector.

Parameters:

addressQueryInspector - a query inspector

Returns:

the address query

Throws:

NullArgumentException - addressQueryInspector is null

UnsupportedException - addressQueryInspector is not of this service

Compliance:

mandatory - This method must be implemented.