org.osid.ordering

Interface ProductAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

ProductBatchAdminSession

public interface ProductAdminSession
extends OsidSession

This session creates, updates, and deletes Products. The data for create and update is provided by the consumer via the form object. OsidForms are requested for each create or update and may not be reused.

Create and update operations differ in their usage. To create a Product, a ProductForm is requested using getProductFormForCreate() specifying the desired record Types or none if no record Types are needed. The returned ProductForm will indicate that it is to be used with a create operation and can be used to examine metdata or validate data prior to creation. Once the ProductForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each ProductForm corresponds to an attempted transaction.

For updates, ProductForms are requested to the Product Id that is to be updated using getProductFormForUpdate(). Similarly, the ProductForm has metadata about the data that can be updated and it can perform validation before submitting the update. The ProductForm can only be used once for a successful update and cannot be reused.

The delete operations delete Products. To unmap a Product from the current Store, the ProductStoreAssignmentSession should be used. These delete operations attempt to remove the Product itself thus removing it from all known Store catalogs.

This session includes an Id aliasing mechanism to assign an external Id to an internally assigned Id.

Method Summary

Methods

Modifier and Type	Method and Description
void	aliasProduct(Id productId, Id aliasId) Adds an Id to a Product for the purpose of creating compatibility.
boolean	canCreateProducts() Tests if this user can create Products.
boolean	canCreateProductWithRecordTypes(Type[] productRecordTypes) Tests if this user can create a single Product using the desired record types.
boolean	canDeleteProducts() Tests if this user can delete Products A return of true does not guarantee successful authorization.
boolean	canManageProductAliases() Tests if this user can manage Id aliases for Products.
boolean	canUpdateProducts() Tests if this user can update Products.
Product	createProduct(ProductForm productForm) Creates a new Product.
void	deleteProduct(Id productId) Deletes a Product.
ProductForm	getProductFormForCreate(Type[] productRecordTypes) Gets the product form for creating new products.
ProductForm	getProductFormForUpdate(Id productId) Gets the product form for updating an existing product.
Store	getStore() Gets the Store associated with this session.
Id	getStoreId() Gets the Store Id associated with this session.
void	updateProduct(ProductForm productForm) Updates an existing product.

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

getStoreId

Id getStoreId()

Gets the Store Id associated with this session.

Returns:

the Store Id associated with this session

Compliance:

mandatory - This method must be implemented.

getStore

Store getStore()
               throws OperationFailedException,
                      PermissionDeniedException

Gets the Store associated with this session.

Returns:

the store

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateProducts

boolean canCreateProducts()

Tests if this user can create Products. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Product will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.

Returns:

false if Product creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateProductWithRecordTypes

boolean canCreateProductWithRecordTypes(Type[] productRecordTypes)

Tests if this user can create a single Product using the desired record types. While OrderingManager.getProductRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific Product. Providing an empty array tests if a Product can be created with no records.

Parameters:

productRecordTypes - array of product record types

Returns:

true if Product creation using the specified record Types is supported, false otherwise

Throws:

NullArgumentException - productRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getProductFormForCreate

ProductForm getProductFormForCreate(Type[] productRecordTypes)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Gets the product form for creating new products. A new form should be requested for each create transaction.

Parameters:

productRecordTypes - array of product record types

Returns:

the product form

Throws:

NullArgumentException - productRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createProduct

Product createProduct(ProductForm productForm)
                      throws OperationFailedException,
                             PermissionDeniedException

Creates a new Product.

Parameters:

productForm - the form for this Product

Returns:

the new Product

Throws:

IllegalStateException - productForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - productForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - productForm did not originate from getProductFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateProducts

boolean canUpdateProducts()

Tests if this user can update Products. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Product will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.

Returns:

false if Product modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getProductFormForUpdate

ProductForm getProductFormForUpdate(Id productId)

Gets the product form for updating an existing product. A new product form should be requested for each update transaction.

Parameters:

productId - the Id of the Product

Returns:

the product form

Throws:

NullArgumentException - productId is null

Compliance:

mandatory - This method must be implemented.

updateProduct

void updateProduct(ProductForm productForm)
                   throws OperationFailedException,
                          PermissionDeniedException

Updates an existing product.

Parameters:

productForm - the form containing the elements to be updated

Throws:

IllegalStateException - productForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - productForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - productForm did not originate from getProductFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteProducts

boolean canDeleteProducts()

Tests if this user can delete Products A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a Product will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.

Returns:

false if Product deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteProduct

void deleteProduct(Id productId)
                   throws NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

Deletes a Product.

Parameters:

productId - the Id of the Product to remove

Throws:

NotFoundException - productId not found

NullArgumentException - productId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageProductAliases

boolean canManageProductAliases()

Tests if this user can manage Id aliases for Products. A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.

Returns:

false if Product aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasProduct

void aliasProduct(Id productId,
                Id aliasId)
                  throws AlreadyExistsException,
                         NotFoundException,
                         OperationFailedException,
                         PermissionDeniedException

Adds an Id to a Product for the purpose of creating compatibility. The primary Id of the Product is determined by the provider. The new Id performs as an alias to the primary Id. If the alias is a pointer to another product, it is reassigned to the given product Id.

Parameters:

productId - the Id of a Product

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - productId not found

NullArgumentException - productId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.