org.osid.authentication

Interface AgentSearchSession

All Superinterfaces:

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

public interface AgentSearchSession
extends AgentQuerySession

This session provides methods for searching Agents. The search query is constructed using the AgentQuery. The agent record Type also specifies the record for the agent query.

getAgentsByQuery() is the basic search method and returns a list of Agents. A more advanced search may be performed with getAgentsBySearch(). It accepts an AgentSearch in addition to the query for the purpose of specifying additional options affecting the entire search, such as ordering. getAgentsBySearch() returns an AgentSearchResults that can be used to access the resulting AgentList or be used to perform a search within the result set through AgentSearch.

This session defines views that offer differing behaviors for searching.

• federated agency view: searches include agents in agencies of which this agency is a ancestor in the agency hierarchy
• isolated agency view: searches are restricted to agents in this agency

Agents may have an agent query record indicated by their respective record types. The agent query record is accessed via the AgentQuery.

Method Summary

Methods

Modifier and Type	Method and Description
AgentQuery	getAgentQueryFromInspector(AgentQueryInspector agentQueryInspector) Gets an agent query from an inspector.
AgentSearchResults	getAgentsBySearch(AgentQuery agentQuery, AgentSearch agentSearch) Gets the search results matching the given search query using the given search.
AgentSearch	getAgentSearch() Gets an agent search.
AgentSearchOrder	getAgentSearchOrder() Gets an agent search order.

Methods inherited from interface org.osid.authentication.AgentQuerySession

canSearchAgents, getAgency, getAgencyId, getAgentQuery, getAgentsByQuery, useFederatedAgencyView, useIsolatedAgencyView

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

getAgentSearch

AgentSearch getAgentSearch()

Gets an agent search.

Returns:

the agent search

Compliance:

mandatory - This method must be implemented.

getAgentSearchOrder

AgentSearchOrder getAgentSearchOrder()

Gets an agent search order. The AgentSearchOrder is supplied to an AgentSearch to specify the ordering of results.

Returns:

the agent search order

Compliance:

mandatory - This method must be implemented.

getAgentsBySearch

AgentSearchResults getAgentsBySearch(AgentQuery agentQuery,
                                   AgentSearch agentSearch)
                                     throws OperationFailedException,
                                            PermissionDeniedException

Gets the search results matching the given search query using the given search.

Parameters:

agentQuery - the agent query

agentSearch - the agent search

Returns:

the returned search results

Throws:

NullArgumentException - agentQuery or agentSearch is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - agentSearch or agentQuery is not of this service

Compliance:

mandatory - This method must be implemented.

getAgentQueryFromInspector

AgentQuery getAgentQueryFromInspector(AgentQueryInspector agentQueryInspector)

Gets an agent query from an inspector. The inspector is available from an AgentSearchResults.

Parameters:

agentQueryInspector - an agent query inspector

Returns:

the agent query

Throws:

NullArgumentException - agentQueryInspector is null

UnsupportedException - agentQueryInspector is not of thiss ervice

Compliance:

mandatory - This method must be implemented.