org.osid.bidding

Interface BidLookupSession

All Superinterfaces:

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

public interface BidLookupSession
extends OsidSession

This session provides methods for retrieving Bid relationships.

This session defines views that offer differing behaviors when retrieving multiple objects.

• comparative view: elements may be silently omitted or re-ordered
• plenary view: provides a complete set or is an error condition
• isolated auction house view: All bid methods in this session operate, retrieve and pertain to bids defined explicitly in the current auction house. Using an isolated view is useful for managing Bids with the BidAdminSession.
• federated auction house view: All bid methods in this session operate, retrieve and pertain to all bids defined in this auction house and any other bids implicitly available in this auction house through auction house inheritence.
• effective bid view: All bid lookup methods return bids where the current date falls in between the effective dates inclusive.
• any effective bid view: Bids of any effective date are returned from methods.

Generally, the comparative view should be used for most applications as it permits operation even if there is data that cannot be accessed. The methods useFederatedAuctionHouseView() and useIsolatedAuctionHouseView() behave as a radio group and one should be selected before invoking any lookup methods.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupBids() Tests if this user can perform Bid lookups.
AuctionHouse	getAuctionHouse() Gets the AuctionHouse associated with this session.
Id	getAuctionHouseId() Gets the AuctionHouse Id associated with this session.
Bid	getBid(Id bidId) Gets the Bid specified by its Id.
BidList	getBids() Gets all Bids.
BidList	getBidsByGenusType(Type bidGenusType) Gets a BidList corresponding to the given bid genus Type which does not include bids of genus types derived from the specified Type.
BidList	getBidsByIds(IdList bidIds) Gets a BidList corresponding to the given IdList.
BidList	getBidsByParentGenusType(Type bidGenusType) Gets a BidList corresponding to the given bid genus Type and include any additional bids with genus types derived from the specified Type.
BidList	getBidsByRecordType(Type bidRecordType) Gets a BidList containing the given bid record Type.
BidList	getBidsForAuction(Id auctionId) Gets a list of bids for an auction.
BidList	getBidsForAuctionAndBidder(Id auctionId, Id resourceId) Gets a list of bids for an auction and bidder.
BidList	getBidsForAuctionAndBidderOnDate(Id auctionId, Id resourceId, DateTime from, DateTime to) Gets a list of bids for an auction and bidder and effective during the entire given date range inclusive but not confined to the date range.
BidList	getBidsForAuctionOnDate(Id auctionId, DateTime from, DateTime to) Gets a list of bids for an auction and effective during the entire given date range inclusive but not confined to the date range.
BidList	getBidsForBidder(Id resourceId) Gets a list of bids for a bidder.
BidList	getBidsForBidderOnDate(Id resourceId, DateTime from, DateTime to) Gets a list of bids for a bidder and effective during the entire given date range inclusive but not confined to the date range.
BidList	getBidsOnDate(DateTime from, DateTime to) Gets a BidList effective during the entire given date range inclusive but not confined to the date range.
BidList	getWinningBids() Gets all winning Bids.
BidList	getWinningBidsForAuction(Id auctionId) Gets a list of all winning bids for an auction.
BidList	getWinningBidsForAuctionOnDate(Id auctionId, DateTime from, DateTime to) Gets a list of winning bids for an auction and effectiveduring the entire given date range inclusive but not confined to the date range.
BidList	getWinningBidsForBidder(Id resourceId) Gets a list of all winning bids for a bidder.
BidList	getWinningBidsForBidderOnDate(Id resourceId, DateTime from, DateTime to) Gets a list of winning bids for a bidder and effective during the entire given date range inclusive but not confined to the date range.
BidList	getWinningBidsOnDate(DateTime from, DateTime to) Gets a list of all winning bids effective during the entire given date range inclusive but not confined to the date range.
void	useAnyEffectiveBidView() All bids of any effective dates are returned by methods in this session.
void	useComparativeBidView() The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	useEffectiveBidView() Only bids whose effective dates are current are returned by methods in this session.
void	useFederatedAuctionHouseView() Federates the view for methods in this session.
void	useIsolatedAuctionHouseView() Isolates the view for methods in this session.
void	usePlenaryBidView() A complete view of the Bid returns is desired.

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

getAuctionHouseId

Id getAuctionHouseId()

Gets the AuctionHouse Id associated with this session.

Returns:

the AuctionHouse Id associated with this session

Compliance:

mandatory - This method must be implemented.

getAuctionHouse

AuctionHouse getAuctionHouse()
                             throws OperationFailedException,
                                    PermissionDeniedException

Gets the AuctionHouse associated with this session.

Returns:

the auction house

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupBids

boolean canLookupBids()

Tests if this user can perform Bid lookups. A return of true does not guarantee successful authorization. A return of false indicates that it is known all 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 lookup operations to unauthorized users.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeBidView

void useComparativeBidView()

The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error. This view is used when greater interoperability is desired at the expense of precision.

Compliance:

mandatory - This method is must be implemented.

usePlenaryBidView

void usePlenaryBidView()

A complete view of the Bid returns is desired. Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.

Compliance:

mandatory - This method is must be implemented.

useFederatedAuctionHouseView

void useFederatedAuctionHouseView()

Federates the view for methods in this session. A federated view will include bids in auction houses which are children of this auction house in the auction house hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedAuctionHouseView

void useIsolatedAuctionHouseView()

Isolates the view for methods in this session. An isolated view restricts lookups to this auction house only.

Compliance:

mandatory - This method is must be implemented.

useEffectiveBidView

void useEffectiveBidView()

Only bids whose effective dates are current are returned by methods in this session.

Compliance:

mandatory - This method is must be implemented.

useAnyEffectiveBidView

void useAnyEffectiveBidView()

All bids of any effective dates are returned by methods in this session.

Compliance:

mandatory - This method is must be implemented.

getBid

Bid getBid(Id bidId)
           throws NotFoundException,
                  OperationFailedException,
                  PermissionDeniedException

Gets the Bid specified by its Id. In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Bid may have a different Id than requested, such as the case where a duplicate Id was assigned to a Bid and retained for compatibility. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

bidId - Id of the Bid

Returns:

the bid

Throws:

NotFoundException - bidId not found

NullArgumentException - bidId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

getBidsByIds

BidList getBidsByIds(IdList bidIds)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Gets a BidList corresponding to the given IdList. In plenary mode, the returned list contains all of the bids specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible Bids may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

bidIds - the list of Ids to retrieve

Returns:

the returned Bid list

Throws:

NotFoundException - an Id was not found

NullArgumentException - bidIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBidsByGenusType

BidList getBidsByGenusType(Type bidGenusType)
                           throws OperationFailedException,
                                  PermissionDeniedException

Gets a BidList corresponding to the given bid genus Type which does not include bids of genus types derived from the specified Type. In plenary mode, the returned list contains all known bids or an error results. Otherwise, the returned list may contain only those bids that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

bidGenusType - a bid genus type

Returns:

the returned Bid list

Throws:

NullArgumentException - bidGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBidsByParentGenusType

BidList getBidsByParentGenusType(Type bidGenusType)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Gets a BidList corresponding to the given bid genus Type and include any additional bids with genus types derived from the specified Type. In plenary mode, the returned list contains all known bids or an error results. Otherwise, the returned list may contain only those bids that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

bidGenusType - a bid genus type

Returns:

the returned Bid list

Throws:

NullArgumentException - bidGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBidsByRecordType

BidList getBidsByRecordType(Type bidRecordType)
                            throws OperationFailedException,
                                   PermissionDeniedException

Gets a BidList containing the given bid record Type. In plenary mode, the returned list contains all known bids or an error results. Otherwise, the returned list may contain only those bids that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

bidRecordType - a bid record type

Returns:

the returned Bid list

Throws:

NullArgumentException - bidRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBidsOnDate

BidList getBidsOnDate(DateTime from,
                    DateTime to)
                      throws OperationFailedException,
                             PermissionDeniedException

Gets a BidList effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known bids or an error results. Otherwise, the returned list may contain only those bids that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

from - start of date range

to - end of date range

Returns:

the returned Bid list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBidsForAuction

BidList getBidsForAuction(Id auctionId)
                          throws OperationFailedException,
                                 PermissionDeniedException

Gets a list of bids for an auction. In plenary mode, the returned list contains all known auctions or an error results. Otherwise, the returned list may contain only those auctions that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

auctionId - an auction Id

Returns:

the returned Bid list

Throws:

NullArgumentException - auctionId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBidsForAuctionOnDate

BidList getBidsForAuctionOnDate(Id auctionId,
                              DateTime from,
                              DateTime to)
                                throws OperationFailedException,
                                       PermissionDeniedException

Gets a list of bids for an auction and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known bids or an error results. Otherwise, the returned list may contain only those bids that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

auctionId - an auction Id

from - start of date range

to - end of date range

Returns:

the returned Bid list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - auctionId, from, or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBidsForBidder

BidList getBidsForBidder(Id resourceId)
                         throws OperationFailedException,
                                PermissionDeniedException

Gets a list of bids for a bidder. In plenary mode, the returned list contains all known bids or an error results. Otherwise, the returned list may contain only those bids that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

resourceId - a resource Id

Returns:

the returned C ommission list

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBidsForBidderOnDate

BidList getBidsForBidderOnDate(Id resourceId,
                             DateTime from,
                             DateTime to)
                               throws OperationFailedException,
                                      PermissionDeniedException

Gets a list of bids for a bidder and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known bids or an error results. Otherwise, the returned list may contain only those bids that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

resourceId - a resource Id

from - start of date range

to - end of date range

Returns:

the returned C ommission list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - resourceId, from, or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBidsForAuctionAndBidder

BidList getBidsForAuctionAndBidder(Id auctionId,
                                 Id resourceId)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Gets a list of bids for an auction and bidder. In plenary mode, the returned list contains all known bids or an error results. Otherwise, the returned list may contain only those bids that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

auctionId - an auction Id

resourceId - a resource Id

Returns:

the returned C ommission list

Throws:

NullArgumentException - auctionId or resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBidsForAuctionAndBidderOnDate

BidList getBidsForAuctionAndBidderOnDate(Id auctionId,
                                       Id resourceId,
                                       DateTime from,
                                       DateTime to)
                                         throws OperationFailedException,
                                                PermissionDeniedException

Gets a list of bids for an auction and bidder and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known bids or an error results. Otherwise, the returned list may contain only those bids that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

auctionId - an auction Id

resourceId - a resource Id

from - start of date range

to - end of date range

Returns:

the returned C ommission list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - auctionId, resourceId, from, or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getWinningBids

BidList getWinningBids()
                       throws OperationFailedException,
                              PermissionDeniedException

Gets all winning Bids. In plenary mode, the returned list contains all known bids or an error results. Otherwise, the returned list may contain only those bids that are accessible through this session. In both cases, the order of the set is by start effective date. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Returns:

a list of Bids

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getWinningBidsOnDate

BidList getWinningBidsOnDate(DateTime from,
                           DateTime to)
                             throws OperationFailedException,
                                    PermissionDeniedException

Gets a list of all winning bids effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known bids or an error results. Otherwise, the returned list may contain only those bids that are accessible through this session. In both cases, the order of the set is by the start of the effective date. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

from - start of date range

to - end of date range

Returns:

the returned Bid list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getWinningBidsForAuction

BidList getWinningBidsForAuction(Id auctionId)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Gets a list of all winning bids for an auction. In plenary mode, the returned list contains all known auctions or an error results. Otherwise, the returned list may contain only those auctions that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

auctionId - an auction Id

Returns:

the returned Bid list

Throws:

NullArgumentException - auctionId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getWinningBidsForAuctionOnDate

BidList getWinningBidsForAuctionOnDate(Id auctionId,
                                     DateTime from,
                                     DateTime to)
                                       throws OperationFailedException,
                                              PermissionDeniedException

Gets a list of winning bids for an auction and effectiveduring the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known bids or an error results. Otherwise, the returned list may contain only those bids that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

auctionId - an auction Id

from - start of date range

to - end of date range

Returns:

the returned Bid list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - auctionId, from, or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getWinningBidsForBidder

BidList getWinningBidsForBidder(Id resourceId)
                                throws OperationFailedException,
                                       PermissionDeniedException

Gets a list of all winning bids for a bidder. In plenary mode, the returned list contains all known auctions or an error results. Otherwise, the returned list may contain only those auctions that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

resourceId - a resourceId Id

Returns:

the returned Bid list

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getWinningBidsForBidderOnDate

BidList getWinningBidsForBidderOnDate(Id resourceId,
                                    DateTime from,
                                    DateTime to)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Gets a list of winning bids for a bidder and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known bids or an error results. Otherwise, the returned list may contain only those bids that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Parameters:

resourceId - a resource Id

from - start of date range

to - end of date range

Returns:

the returned C ommission list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - resourceId, from, or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBids

BidList getBids()
                throws OperationFailedException,
                       PermissionDeniedException

Gets all Bids. In plenary mode, the returned list contains all known bids or an error results. Otherwise, the returned list may contain only those bids that are accessible through this session. In effective mode, bids are returned that are currently effective. In any effective mode, effective bids and those currently expired are returned.

Returns:

a list of Bids

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.