org.osid.inventory.shipment

Interface ShipmentLookupSession

All Superinterfaces:

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

public interface ShipmentLookupSession
extends OsidSession

This session defines methods for retrieving shipments. A Shipment is a Resource related to the billing system.

This lookup session defines several views:

• comparative view: elements may be silently omitted or re-ordered
• plenary view: provides a complete result set or is an error condition
• isolated warehouse view: All shipment methods in this session operate, retrieve and pertain to shipments defined explicitly in the current warehouse. Using an isolated view is useful for managing Shipments with the ShipmentAdminSession.
• federated warehouse view: All shipment lookup methods in this session operate, retrieve and pertain to all shipments defined in this warehouse and any other shipments implicitly available in this warehouse through warehouse inheritence.

The methods useFederatedWarehouseView() and useIsolatedWarehouseView() behave as a radio group and one should be selected before invoking any lookup methods.

Shipments may have an additional records indicated by their respective record types. The record may not be accessed through a cast of the Shipment.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupShipments() Tests if this user can perform Shipment lookups.
Shipment	getShipment(Id shipmentId) Gets the Shipment specified by its Id.
ShipmentList	getShipments() Gets all Shipments.
ShipmentList	getShipmentsByGenusType(Type shipmentGenusType) Gets a ShipmentList corresponding to the given shipment genus Type which does not include shipments of types derived from the specified Type.
ShipmentList	getShipmentsByIds(IdList shipmentIds) Gets a ShipmentList corresponding to the given IdList.
ShipmentList	getShipmentsByParentGenusType(Type shipmentGenusType) Gets a ShipmentList corresponding to the given shipment genus Type and include any additional shipments with genus types derived from the specified Type.
ShipmentList	getShipmentsByRecordType(Type shipmentRecordType) Gets a ShipmentList containing the given shipment record Type.
ShipmentList	getShipmentsBySource(Id resourceId) Gets a ShipmentList from to the given source.
ShipmentList	getShipmentsBySourceOnDate(Id resourceId, DateTime from, DateTime to) Gets a ShipmentList from the given source and received between the given date range inclusive .
ShipmentList	getShipmentsForStock(Id stockId) Gets a ShipmentList for to the given stock.
ShipmentList	getShipmentsForStockOnDate(Id stockId, DateTime from, DateTime to) Gets a ShipmentList for the given stock and received between the given date range inclusive .
ShipmentList	getShipmentsOnDate(DateTime from, DateTime to) Gets a ShipmentList received between the given date range inclusive.
Warehouse	getWarehouse() Gets the Warehouse associated with this session.
Id	getWarehouseId() Gets the Warehouse Id associated with this session.
void	useComparativeShipmentView() 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	useFederatedWarehouseView() Federates the view for methods in this session.
void	useIsolatedWarehouseView() Isolates the view for methods in this session.
void	usePlenaryShipmentView() A complete view of the Shipment 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

getWarehouseId

Id getWarehouseId()

Gets the Warehouse Id associated with this session.

Returns:

the Warehouse Id associated with this session

Compliance:

mandatory - This method must be implemented.

getWarehouse

Warehouse getWarehouse()
                       throws OperationFailedException,
                              PermissionDeniedException

Gets the Warehouse associated with this session.

Returns:

the warehouse

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupShipments

boolean canLookupShipments()

Tests if this user can perform Shipment 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 not offer lookup operations to unauthorized users.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeShipmentView

void useComparativeShipmentView()

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.

usePlenaryShipmentView

void usePlenaryShipmentView()

A complete view of the Shipment 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.

useFederatedWarehouseView

void useFederatedWarehouseView()

Federates the view for methods in this session. A federated view will include shipments in catalogs which are children of this catalog in the warehouse hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedWarehouseView

void useIsolatedWarehouseView()

Isolates the view for methods in this session. An isolated view restricts retrievals to this warehouse only.

Compliance:

mandatory - This method is must be implemented.

getShipment

Shipment getShipment(Id shipmentId)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Gets the Shipment specified by its Id. In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Shipment may have a different Id than requested, such as the case where a duplicate Id was assigned to a Shipment and retained for compatibility.

Parameters:

shipmentId - the Id of the Shipment to retrieve

Returns:

the returned Shipment

Throws:

NotFoundException - no Shipment found with the given Id

NullArgumentException - shipmentId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getShipmentsByIds

ShipmentList getShipmentsByIds(IdList shipmentIds)
                               throws NotFoundException,
                                      OperationFailedException,
                                      PermissionDeniedException

Gets a ShipmentList corresponding to the given IdList. In plenary mode, the returned list contains all of the shipments 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 Shipments may be omitted from the list and may present the elements in any order including returning a unique set.

Parameters:

shipmentIds - the list of Ids to retrieve

Returns:

the returned ShipmentList list

Throws:

NotFoundException - an Id was not found

NullArgumentException - shipmentIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getShipmentsByGenusType

ShipmentList getShipmentsByGenusType(Type shipmentGenusType)
                                     throws OperationFailedException,
                                            PermissionDeniedException

Gets a ShipmentList corresponding to the given shipment genus Type which does not include shipments of types derived from the specified Type. In plenary mode, the returned list contains all known shipments or an error results. Otherwise, the returned list may contain only those shipments that are accessible through this session.

Parameters:

shipmentGenusType - a shipment genus type

Returns:

the returned ShipmentList list

Throws:

NullArgumentException - shipmentGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getShipmentsByParentGenusType

ShipmentList getShipmentsByParentGenusType(Type shipmentGenusType)
                                           throws OperationFailedException,
                                                  PermissionDeniedException

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

Parameters:

shipmentGenusType - a shipment genus type

Returns:

the returned ShipmentList list

Throws:

NullArgumentException - shipmentGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getShipmentsByRecordType

ShipmentList getShipmentsByRecordType(Type shipmentRecordType)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Gets a ShipmentList containing the given shipment record Type. In plenary mode, the returned list contains all known shipments or an error results. Otherwise, the returned list may contain only those shipments that are accessible through this session.

Parameters:

shipmentRecordType - a shipment record type

Returns:

the returned ShipmentList list

Throws:

NullArgumentException - shipmentRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getShipmentsOnDate

ShipmentList getShipmentsOnDate(DateTime from,
                              DateTime to)
                                throws OperationFailedException,
                                       PermissionDeniedException

Gets a ShipmentList received between the given date range inclusive. In plenary mode, the returned list contains all known shipments or an error results. Otherwise, the returned list may contain only those shipments that are accessible through this session.

Parameters:

from - starting date

to - ending date

Returns:

the returned ShipmentList 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.

getShipmentsForStock

ShipmentList getShipmentsForStock(Id stockId)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Gets a ShipmentList for to the given stock. In plenary mode, the returned list contains all known shipments or an error results. Otherwise, the returned list may contain only those shipments that are accessible through this session.

Parameters:

stockId - a stock Id

Returns:

the returned ShipmentList list

Throws:

NullArgumentException - stockId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getShipmentsForStockOnDate

ShipmentList getShipmentsForStockOnDate(Id stockId,
                                      DateTime from,
                                      DateTime to)
                                        throws OperationFailedException,
                                               PermissionDeniedException

Gets a ShipmentList for the given stock and received between the given date range inclusive . In plenary mode, the returned list contains all known shipments or an error results. Otherwise, the returned list may contain only those shipments that are accessible through this session.

Parameters:

stockId - a stock Id

from - starting date

to - ending date

Returns:

the returned ShipmentList list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - stockId, from, or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getShipmentsBySource

ShipmentList getShipmentsBySource(Id resourceId)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Gets a ShipmentList from to the given source. In plenary mode, the returned list contains all known shipments or an error results. Otherwise, the returned list may contain only those shipments that are accessible through this session.

Parameters:

resourceId - a resource Id

Returns:

the returned ShipmentList list

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getShipmentsBySourceOnDate

ShipmentList getShipmentsBySourceOnDate(Id resourceId,
                                      DateTime from,
                                      DateTime to)
                                        throws OperationFailedException,
                                               PermissionDeniedException

Gets a ShipmentList from the given source and received between the given date range inclusive . In plenary mode, the returned list contains all known shipments or an error results. Otherwise, the returned list may contain only those shipments that are accessible through this session.

Parameters:

resourceId - a resource Id

from - starting date

to - ending date

Returns:

the returned ShipmentList 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.

getShipments

ShipmentList getShipments()
                          throws OperationFailedException,
                                 PermissionDeniedException

Gets all Shipments. In plenary mode, the returned list contains all known shipments or an error results. Otherwise, the returned list may contain only those shipments that are accessible through this session.

Returns:

a list of Shipments

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.