OSID - osid.OsidSession Service Interface Definition

Interface	osid.OsidSession
Description	The `OsidSession` is the top level interface for all OSID sessions. An `OsidSession` is created through its corresponding `OsidManager.` A new `OsidSession` should be created for each user of a service and for each processing thread. A session maintains a single authenticated user and is not required to ensure thread-protection. A typical OSID session defines a set of service methods corresponding to some compliance level as defined by the service and is generally responsible for the management and retrieval of `OsidObjects.` `OsidSession` defines a set of common methods used throughout all OSID sessions. An OSID session may optionally support transactions through the transaction interface.
Method	getLocale
Description	Gets the locale indicating the localization preferences in effect for this session.
Return	`osid.locale.Locale`	the locale
Compliance	`mandatory`	This method must be implemented.
Method	isAuthenticated
Description	Tests if an agent is authenticated to this session.
Return	`boolean`	`true` if valid authentication credentials exist, `false` otherwise
Compliance	`mandatory`	This method must be implemented.
Method	getAuthenticatedAgentId
Description	Gets the `Id` of the agent authenticated to this session. This is the agent for which credentials are used either acquired natively or via an `OsidProxyManager.`
Return	`osid.id.Id`	the authenticated agent `Id`
Errors	ILLEGAL_STATE	`isAuthenticated()` is `false`
Compliance	`mandatory`	This method must be implemented.
Method	getAuthenticatedAgent
Description	Gets the agent authenticated to this session. This is the agent for which credentials are used either acquired natively or via an `OsidProxyManager.`
Return	`osid.authentication.Agent`	the authenticated agent
Errors	ILLEGAL_STATE	`isAuthenticated()` is `false`
Errors	OPERATION_FAILED	unable to complete request
Compliance	`mandatory`	This method must be implemented.
Method	getEffectiveAgentId
Description	Gets the `Id` of the effective agent in use by this session. If `isAuthenticated()` is true, then the effective agent may be the same as the agent returned by `getAuthenticatedAgent().` If `isAuthenticated()` is `false,` then the effective agent may be a default agent used for authorization by an unknwon or anonymous user.
Return	`osid.id.Id`	the effective agent
Compliance	`mandatory`	This method must be implemented.
Method	getEffectiveAgent
Description	Gets the effective agent in use by this session. If `isAuthenticated()` is true, then the effective agent may be the same as the agent returned by `getAuthenticatedAgent().` If `isAuthenticated()` is `false,` then the effective agent may be a default agent used for authorization by an unknwon or anonymous user.
Return	`osid.authentication.Agent`	the effective agent
Errors	OPERATION_FAILED	unable to complete request
Compliance	`mandatory`	This method must be implemented.
Method	getDate
Description	Gets the service date which may be the current date or the effective date in which this session exists.
Return	`timestamp`	the service date
Compliance	`mandatory`	This method must be implemented.
Method	getClockRate
Description	Gets the rate of the service clock.
Return	`decimal`	the clock rate
Compliance	`mandatory`	This method must be implemented.
Method	getFormatType
Description	Gets the `DisplayText` format `Type` preference in effect for this session.
Return	`osid.type.Type`	the effective `DisplayText` format `Type`
Compliance	`mandatory`	This method must be implemented.
Method	supportsTransactions
Description	Tests for the availability of transactions.
Return	`boolean`	`true` if transaction methods are available, `false` otherwise
Compliance	`mandatory`	This method must be implemented.
Method	startTransaction
Description	Starts a new transaction for this sesson. Transactions are a means for an OSID to provide an all-or-nothing set of operations within a session and may be used to coordinate this service from an external transaction manager. A session supports one transaction at a time. Starting a second transaction before the previous has been committed or aborted results in an `ILLEGAL_STATE` error.
Return	`osid.transaction.Transaction`	a new transaction
Errors	ILLEGAL_STATE	a transaction is already open
	OPERATION_FAILED	unable to complete request
	UNSUPPORTED	transactions not supported
Compliance	`optional`	This method must be implemented if `supportsTransactions()` is true.
Provider Notes	Ideally, a provider that supports transactions should guarantee atomicity, consistency, isolation and durability in a 2 phase commit process. This is not always possible in distributed systems and a transaction provider may simply allow for a means of processing bulk updates. To maximize interoperability, providers should honor the one-transaction-at-a-time rule.