OSID - osid.OsidObjectQuery Service Interface Definition

Interface	osid.OsidObjectQuery
Implements	`osid.OsidIdentifiableQuery`
	`osid.OsidExtensibleQuery`
	`osid.OsidBrowsableQuery`
Description	The `OsidObjectQuery` is used to assemble search queries. An `OsidObjectQuery` is available from an `OsidSession` and defines methods to query for an `OsidObject` that includes setting a display name and a description. Once the desired parameters are set, the `OsidQuery` is given to the designated search method. The same `OsidQuery` returned from the session must be used in the search as the provider may utilize implementation-specific data wiithin the object. If multiple data elements are set in this interface, the results matching all the given data (eg: AND) are returned. Any match method inside an `OsidObjectQuery` may be invoked multiple times. In the case of a match method, each invocation adds an element to an `OR` expression. Any of these terms may also be negated through the `match` flag. OsidObjectQuery { OsidQuery.matchDisplayName AND (OsidQuery.matchDescription OR OsidObjectQuery.matchDescription)} `OsidObjects` allow for the definition of an additonal records and the `OsidQuery` parallels this mechanism. An interface type of an `OsidObject` record must also define the corresponding `OsidQuery` record which is available through query interfaces. Multiple requests of these typed interfaces may return the same underlying object and thus it is only useful to request once. String searches are described using a string search `Type` that indicates the type of regular expression or wildcarding encoding. Compatibility with a strings search `Type` can be tested within this interface. As with all aspects of OSIDs, nulls cannot be used. Separate tests are available for querying for unset values except for required fields. An example to find all objects whose name starts with "Fred" or whose name starts with "Barney", but the word "dinosaur" does not appear in the description and not the color is not purple. `ColorQuery` is a record of the object that defines a color. ObjectObjectQuery query; query = session.getObjectQuery(); query.matchDisplayName("Fred", wildcardStringMatchType, true); query.matchDisplayName("Barney", wildcardStringMatchType, true); query.matchDescriptionMatch("dinosaur", wordStringMatchType, false); ColorQuery recordQuery; recordQuery = query.getObjectRecord(colorRecordType); recordQuery.matchColor("purple", false); ObjectList list = session.getObjectsByQuery(query);
Method	matchDisplayName
Description	Adds a display name to match. Multiple display name matches can be added to perform a boolean `OR` among them.
Parameters	`string`	`displayName`	display name to match
	`osid.type.Type`	`stringMatchType`	the string match type
	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	INVALID_ARGUMENT		`displayName` is not of `stringMatchType`
	NULL_ARGUMENT		`displayName` or `stringMatchType` is `null`
	UNSUPPORTED		`supportsStringMatchType(stringMatchType)` is `false`
Compliance	`mandatory`		This method must be implemented.
Method	matchAnyDisplayName
Description	Matches any object with a display name.
Parameters	`boolean`	`match`	`true` to match any display name, `false` to match objects with no display name
Compliance	`mandatory`		This method must be implemented.
Method	clearDisplayNameTerms
Description	Clears all display name terms.
Compliance	`mandatory`		This method must be implemented.
Method	matchDescription
Description	Adds a description name to match. Multiple description matches can be added to perform a boolean `OR` among them.
Parameters	`string`	`description`	description to match
	`osid.type.Type`	`stringMatchType`	the string match type
	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	INVALID_ARGUMENT		`description` is not of `stringMatchType`
	NULL_ARGUMENT		`description` or `stringMatchType` is `null`
	UNSUPPORTED		`supportsStringMatchType(stringMatchType)` is `false`
Compliance	`mandatory`		This method must be implemented.
Method	matchAnyDescription
Description	Matches a description that has any value.
Parameters	`boolean`	`match`	`true` to match any description, `false` to match descriptions with no values
Compliance	`mandatory`		This method must be implemented.
Method	clearDescriptionTerms
Description	Clears all description terms.
Compliance	`mandatory`		This method must be implemented.
Method	matchGenusType
Description	Sets a `Type` for querying objects of a given genus. A genus type matches if the specified type is the same genus as the object genus type.
Parameters	`osid.type.Type`	`genusType`	the object genus type
Parameters	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	NULL_ARGUMENT		`genusType` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	matchAnyGenusType
Description	Matches an object that has any genus type.
Parameters	`boolean`	`match`	`true` to match any genus type, `false` to match objects with no genus type
Compliance	`mandatory`		This method must be implemented.
Method	clearGenusTypeTerms
Description	Clears all genus type terms.
Compliance	`mandatory`		This method must be implemented.
Method	matchParentGenusType
Description	Sets a `Type` for querying objects of a given genus. A genus type matches if the specified type is the same genus as the object or if the specified type is an ancestor of the object genus in a type hierarchy.
Parameters	`osid.type.Type`	`genusType`	the object genus type
Parameters	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	NULL_ARGUMENT		`genusType` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	clearParentGenusTypeTerms
Description	Clears all genus type terms.
Compliance	`mandatory`		This method must be implemented.
Method	matchSubjectId
Description	Matches an object with a relationship to the given subject.
Parameters	`osid.id.Id`	`subjectId`	a subject `Id`
Parameters	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	NULL_ARGUMENT		`subjectId` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	clearSubjectIdTerms
Description	Clears all subject `Id` terms.
Compliance	`mandatory`		This method must be implemented.
Method	supportsSubjectQuery
Description	Tests if a `SubjectQuery` is available.
Return	`boolean`		`true` if a subject query is available, `false` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getSubjectQuery
Description	Gets the query for a subject. Multiple retrievals produce a nested `OR` term.
Return	`osid.ontology.SubjectQuery`		the subject query
Errors	UNIMPLEMENTED		`supportsSubjectQuery()` is `false`
Compliance	`optional`		This method must be implemented if `supportsSubjectQuery()` is `true.`
Method	matchAnySubject
Description	Matches an object that has any relationship to a `Subject.`
Parameters	`boolean`	`match`	`true` to match any subject, `false` to match objects with no subjects
Compliance	`mandatory`		This method must be implemented.
Method	clearSubjectTerms
Description	Clears all subject terms.
Compliance	`mandatory`		This method must be implemented.
Method	supportsSubjectRelevancyQuery
Description	Tests if a `RelevancyQuery` is available to provide queries about the relationships to `Subjects.`
Return	`boolean`		`true` if a relevancy entry query is available, `false` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getSubjectRelevancyQuery
Description	Gets the query for a subject relevancy. Multiple retrievals produce a nested `OR` term.
Return	`osid.ontology.RelevancyQuery`		the relevancy query
Errors	UNIMPLEMENTED		`supportsSubjectRelevancyQuery()` is `false`
Compliance	`optional`		This method must be implemented if `supportsSubjectRelevancyQuery()` is `true.`
Method	clearSubjectRelevancyTerms
Description	Clears all subject relevancy terms.
Compliance	`mandatory`		This method must be implemented.
Method	matchStateId
Description	Matches an object mapped to the given state.
Parameters	`osid.id.Id`	`stateId`	a state `Id`
Parameters	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	NULL_ARGUMENT		`stateId` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	clearStateIdTerms
Description	Clears all state `Id` terms.
Compliance	`mandatory`		This method must be implemented.
Method	supportsStateQuery
Description	Tests if a `StateQuery` is available to provide queries of processed objects.
Return	`boolean`		`true` if a state query is available, `false` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getStateQuery
Description	Gets the query for a state. Multiple retrievals produce a nested `OR` term.
Return	`osid.process.StateQuery`		the journal entry query
Errors	UNIMPLEMENTED		`supportsStateQuery()` is `false`
Compliance	`optional`		This method must be implemented if `supportsStateQuery()` is `true.`
Method	matchAnyState
Description	Matches an object that has any mapping to a `State` in the given `Process.`
Parameters	`boolean`	`match`	`true` to match any state, `false` to match objects with no states
Compliance	`mandatory`		This method must be implemented.
Method	clearStateTerms
Description	Clears all state terms.
Compliance	`mandatory`		This method must be implemented.
Method	matchCommentId
Description	Matches an object that has the given comment.
Parameters	`osid.id.Id`	`commentId`	a comment `Id`
Parameters	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	NULL_ARGUMENT		`commentId` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	clearCommentIdTerms
Description	Clears all comment `Id` terms.
Compliance	`mandatory`		This method must be implemented.
Method	supportsCommentQuery
Description	Tests if a `CommentQuery` is available.
Return	`boolean`		`true` if a comment query is available, `false` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getCommentQuery
Description	Gets the query for a comment. Multiple retrievals produce a nested `OR` term.
Return	`osid.commenting.CommentQuery`		the comment query
Errors	UNIMPLEMENTED		`supportsCommentQuery()` is `false`
Compliance	`optional`		This method must be implemented if `supportsCommentQuery()` is `true.`
Method	matchAnyComment
Description	Matches an object that has any `Comment` in the given `Book.`
Parameters	`boolean`	`match`	`true` to match any comment, `false` to match objects with no comments
Compliance	`mandatory`		This method must be implemented.
Method	clearCommentTerms
Description	Clears all comment terms.
Compliance	`mandatory`		This method must be implemented.
Method	matchJournalEntryId
Description	Matches an object that has the given journal entry.
Parameters	`osid.id.Id`	`journalEntryId`	a journal entry `Id`
Parameters	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	NULL_ARGUMENT		`journalEntryId` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	clearJournalEntryIdTerms
Description	Clears all journal entry `Id` terms.
Compliance	`mandatory`		This method must be implemented.
Method	supportsJournalEntryQuery
Description	Tests if a `JournalEntry` is available to provide queries of journaled `OsidObjects.`
Return	`boolean`		`true` if a journal entry query is available, `false` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getJournalEntryQuery
Description	Gets the query for a journal entry. Multiple retrievals produce a nested `OR` term.
Return	`osid.journaling.JournalEntryQuery`		the journal entry query
Errors	UNIMPLEMENTED		`supportsJournalEntryQuery()` is `false`
Compliance	`optional`		This method must be implemented if `supportsJournalEntryQuery()` is `true.`
Method	matchAnyJournalEntry
Description	Matches an object that has any `JournalEntry` in the given `Journal.`
Parameters	`boolean`	`match`	`true` to match any journal entry, `false` to match objects with no journal entries
Compliance	`mandatory`		This method must be implemented.
Method	clearJournalEntryTerms
Description	Clears all journal entry terms.
Compliance	`mandatory`		This method must be implemented.
Method	supportsStatisticQuery
Description	Tests if a `StatisticQuery` is available to provide statistical queries.
Return	`boolean`		`true` if a statistic query is available, `false` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getStatisticQuery
Description	Gets the query for a statistic. Multiple retrievals produce a nested `OR` term.
Return	`osid.metering.StatisticQuery`		the statistic query
Errors	UNIMPLEMENTED		`supportsStatisticQuery()` is `false`
Compliance	`optional`		This method must be implemented if `supportsStatisticQuery()` is `true.`
Method	matchAnyStatistic
Description	Matches an object that has any `Statistic` .
Parameters	`boolean`	`match`	`true` to match any statistic, `false` to match objects with no statistics
Compliance	`mandatory`		This method must be implemented.
Method	clearStatisticTerms
Description	Clears all statistic terms.
Compliance	`mandatory`		This method must be implemented.
Method	matchCreditId
Description	Matches an object that has the given credit.
Parameters	`osid.id.Id`	`creditId`	a credit `Id`
Parameters	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	NULL_ARGUMENT		`creditId` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	clearCreditIdTerms
Description	Clears all credit `Id` terms.
Compliance	`mandatory`		This method must be implemented.
Method	supportsCreditQuery
Description	Tests if a `CreditQuery` is available to provide queries of related acknowledgements.
Return	`boolean`		`true` if a credit query is available, `false` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getCreditQuery
Description	Gets the query for an ackowledgement credit. Multiple retrievals produce a nested `OR` term.
Return	`osid.acknowledgement.CreditQuery`		the credit query
Errors	UNIMPLEMENTED		`supportsCreditQuery()` is `false`
Compliance	`optional`		This method must be implemented if `supportsCreditQuery()` is `true.`
Method	matchAnyCredit
Description	Matches an object that has any `Credit.`
Parameters	`boolean`	`match`	`true` to match any credit, `false` to match objects with no credits
Compliance	`mandatory`		This method must be implemented.
Method	clearCreditTerms
Description	Clears all credit terms.
Compliance	`mandatory`		This method must be implemented.
Method	matchRelationshipId
Description	Matches an object that has the given relationship.
Parameters	`osid.id.Id`	`relationshipId`	a relationship `Id`
Parameters	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	NULL_ARGUMENT		`relationshipId` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	clearRelationshipIdTerms
Description	Clears all relationship `Id` terms.
Compliance	`mandatory`		This method must be implemented.
Method	supportsRelationshipQuery
Description	Tests if a `RelationshipQuery` is available.
Return	`boolean`		`true` if a relationship query is available, `false` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getRelationshipQuery
Description	Gets the query for relationship. Multiple retrievals produce a nested `OR` term.
Return	`osid.relationship.RelationshipQuery`		the relationship query
Errors	UNIMPLEMENTED		`supportsRelationshipQuery()` is `false`
Compliance	`optional`		This method must be implemented if `supportsRelationshipQuery()` is `true.`
Method	matchAnyRelationship
Description	Matches an object that has any `Relationship.`
Parameters	`boolean`	`match`	`true` to match any relationship, `false` to match objects with no relationships
Compliance	`mandatory`		This method must be implemented.
Method	clearRelationshipTerms
Description	Clears all relationship terms.
Compliance	`mandatory`		This method must be implemented.
Method	matchRelationshipPeerId
Description	Matches an object that has a relationship to the given peer `Id.`
Parameters	`osid.id.Id`	`peerId`	a relationship peer `Id`
Parameters	`boolean`	`match`	`true` for a positive match, `false` for a negative match
Errors	NULL_ARGUMENT		`peerId` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	clearRelationshipPeerIdTerms
Description	Clears all relationship `Id` terms.
Compliance	`mandatory`		This method must be implemented.