OSID - osid.contact.AddressBookQuery Service Interface Definition

Interface	osid.contact.AddressBookQuery
Implements	`osid.OsidCatalogQuery`
Used By	`osid.contact.AddressBookQuery`
	`osid.contact.AddressBookQuerySession`
	`osid.contact.AddressBookSearchSession`
	`osid.contact.AddressQuery`
	`osid.contact.ContactQuery`
	`osid.contact.rules.ContactEnablerQuery`
Description	This is the query for searching for address books. Each method specifies an `AND` term while multiple invocations of the same method produce a nested `OR`.
Method	matchContactId
Description	Sets the contact `Id` for this query to match contacts assigned to address books.
Parameters	`osid.id.Id`	`contactId`	a contact `Id`
Parameters	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	NULL_ARGUMENT		`contactId` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	clearContactIdTerms
Description	Clears the contact `Id` terms.
Compliance	`mandatory`		This method must be implemented.
Method	supportsContactQuery
Description	Tests if a contact query is available.
Return	`boolean`		`true` if a contact query is available, `false` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getContactQuery
Description	Gets the query for an address book.
Return	`osid.contact.ContactQuery`		the contact query
Errors	UNIMPLEMENTED		`supportsContactQuery()` is `false`
Compliance	`optional`		This method must be implemented if `supportsContactQuery()` is `true`.
Method	matchAnyContact
Description	Matches address books with any contact.
Parameters	`boolean`	`match`	`true` to match address books with any contact, `false` to match address books with no contacts
Compliance	`mandatory`		This method must be implemented.
Method	clearContactTerms
Description	Clears the contact terms.
Compliance	`mandatory`		This method must be implemented.
Method	matchAddressId
Description	Sets the address `Id` for this query to match contacts assigned to addresses.
Parameters	`osid.id.Id`	`addressId`	an address `Id`
Parameters	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	NULL_ARGUMENT		`addressId` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	clearAddressIdTerms
Description	Clears the address `Id` terms.
Compliance	`mandatory`		This method must be implemented.
Method	supportsAddressQuery
Description	Tests if an `AddressQuery` is available.
Return	`boolean`		`true` if an address query is available, `false` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getAddressQuery
Description	Gets the query for an address query. Multiple retrievals produce a nested `OR` term.
Return	`osid.contact.AddressQuery`		the address query
Errors	UNIMPLEMENTED		`supportsAddressQuery()` is `false`
Compliance	`optional`		This method must be implemented if `supportsAddressQuery()` is `true`.
Method	matchAnyAddress
Description	Matches address books with any address.
Parameters	`boolean`	`match`	`true` to match address books with any address, `false` to match address books with no addresses
Compliance	`mandatory`		This method must be implemented.
Method	clearAddressTerms
Description	Clears the address terms.
Compliance	`mandatory`		This method must be implemented.
Method	matchAncestorAddressBookId
Description	Sets the address book `Id` for this query to match address books that have the specified address book as an ancestor.
Parameters	`osid.id.Id`	`addressBookId`	an address book `Id`
Parameters	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	NULL_ARGUMENT		`addressBookId` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	clearAncestorAddressBookIdTerms
Description	Clears the ancestor address book `Id` terms.
Compliance	`mandatory`		This method must be implemented.
Method	supportsAncestorAddressBookQuery
Description	Tests if an `AddressBookQuery` is available.
Return	`boolean`		`true` if an address book query is available, `false` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getAncestorAddressBookQuery
Description	Gets the query for an address book. Multiple retrievals produce a nested `OR` term.
Return	`osid.contact.AddressBookQuery`		the address book query
Errors	UNIMPLEMENTED		`supportsAncestorAddressBookQuery()` is `false`
Compliance	`optional`		This method must be implemented if `supportsAncestorAddressBookQuery()` is `true`.
Method	matchAnyAncestorAddressBook
Description	Matches address books with any ancestor.
Parameters	`boolean`	`match`	`true` to match address books with any ancestor, `false` to match root address books
Compliance	`mandatory`		This method must be implemented.
Method	clearAncestorAddressBookTerms
Description	Clears the ancestor address book terms.
Compliance	`mandatory`		This method must be implemented.
Method	matchDescendantAddressBookId
Description	Sets the address book `Id` for this query to match address books that have the specified address book as a descendant.
Parameters	`osid.id.Id`	`addressBookId`	an address book `Id`
Parameters	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	NULL_ARGUMENT		`addressBookId` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	clearDescendantAddressBookIdTerms
Description	Clears the descendant address book `Id` terms.
Compliance	`mandatory`		This method must be implemented.
Method	supportsDescendantAddressBookQuery
Description	Tests if an `AddressBookQuery` is available.
Return	`boolean`		`true` if an address book query is available, `false` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getDescendantAddressBookQuery
Description	Gets the query for an address book. Multiple retrievals produce a nested `OR` term.
Return	`osid.contact.AddressBookQuery`		the address book query
Errors	UNIMPLEMENTED		`supportsDescendantAddressBookQuery()` is `false`
Compliance	`optional`		This method must be implemented if `supportsDescendantAddressBookQuery()` is `true`.
Method	matchAnyDescendantAddressBook
Description	Matches address books with any descendant.
Parameters	`boolean`	`match`	`true` to match address books with any descendant, `false` to match leaf address books
Compliance	`mandatory`		This method must be implemented.
Method	clearDescendantAddressBookTerms
Description	Clears the descendant address book terms.
Compliance	`mandatory`		This method must be implemented.
Method	getAddressBookQueryRecord
Description	Gets the query record corresponding to the given `AddressBook` record `Type`. Multiple record retrievals produce a nested boolean `OR` term.
Parameters	`osid.type.Type`	`addressBookRecordType`	an address book record type
Return	`osid.contact.records.AddressBookQueryRecord`		the address book query record
Errors	NULL_ARGUMENT		`addressBookRecordType` is `null`
	OPERATION_FAILED		unable to complete request
	UNSUPPORTED		`hasRecordType(addressBookRecordType)` is `false`
Compliance	`mandatory`		This method must be implemented.