org.osid.cataloging

Interface CatalogAdminSession

All Superinterfaces:

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

public interface CatalogAdminSession
extends OsidSession

This session creates, updates, and deletes Catalogs. 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 Catalog, a CatalogForm is requested using getCatalogFormForCreate() specifying the desired record Types or none if no record Types are needed. The returned CatalogForm 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 CatalogForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each CatalogForm corresponds to an attempted transaction.

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

The delete operations delete 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	aliasCatalog(Id catalogId, Id aliasId) Adds an Id to a Catalog for the purpose of creating compatibility.
boolean	canCreateCatalogs() Tests if this user can create Catalogs.
boolean	canCreateCatalogWithRecordTypes(Type[] catalogRecordTypes) Tests if this user can create a single Catalog using the desired record types.
boolean	canDeleteCatalogs() Tests if this user can delete Catalogs.
boolean	canManageCatalogAliases() Tests if this user can manage Id aliases for Catalogs.
boolean	canUpdateCatalogs() Tests if this user can update Catalogs.
Catalog	createCatalog(CatalogForm catalogForm) Creates a new Catalog.
void	deleteCatalog(Id catalogId) Deletes a Catalog.
CatalogForm	getCatalogFormForCreate(Type[] catalogRecordTypes) Gets the catalog form for creating new catalogs.
CatalogForm	getCatalogFormForUpdate(Id catalogId) Gets the catalog form for updating an existing catalog.
void	updateCatalog(CatalogForm catalogForm) Updates an existing catalog.

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

canCreateCatalogs

boolean canCreateCatalogs()

Tests if this user can create Catalogs. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Catalog 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 Catalog creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateCatalogWithRecordTypes

boolean canCreateCatalogWithRecordTypes(Type[] catalogRecordTypes)

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

Parameters:

catalogRecordTypes - array of catalog record types

Returns:

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

Throws:

NullArgumentException - catalogRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getCatalogFormForCreate

CatalogForm getCatalogFormForCreate(Type[] catalogRecordTypes)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Gets the catalog form for creating new catalogs. A new form should be requested for each create transaction.

Parameters:

catalogRecordTypes - array of catalog record types

Returns:

the catalog form

Throws:

NullArgumentException - catalogRecordTypes 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.

createCatalog

Catalog createCatalog(CatalogForm catalogForm)
                      throws OperationFailedException,
                             PermissionDeniedException

Creates a new Catalog.

Parameters:

catalogForm - the form for this Catalog

Returns:

the new Catalog

Throws:

IllegalStateException - catalogForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - catalogForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - catalogForm did not originate from getCatalogFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateCatalogs

boolean canUpdateCatalogs()

Tests if this user can update Catalogs. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Catalog 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 Catalog modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getCatalogFormForUpdate

CatalogForm getCatalogFormForUpdate(Id catalogId)
                                    throws NotFoundException,
                                           OperationFailedException,
                                           PermissionDeniedException

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

Parameters:

catalogId - the Id of the Catalog

Returns:

the catalog form

Throws:

NotFoundException - catalogId is not found

NullArgumentException - catalogId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateCatalog

void updateCatalog(CatalogForm catalogForm)
                   throws OperationFailedException,
                          PermissionDeniedException

Updates an existing catalog.

Parameters:

catalogForm - the form containing the elements to be updated

Throws:

IllegalStateException - catalogForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - catalogForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - catalogForm did not originate from getCatalogFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteCatalogs

boolean canDeleteCatalogs()

Tests if this user can delete Catalogs. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a Catalog 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 Catalog deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteCatalog

void deleteCatalog(Id catalogId)
                   throws NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

Deletes a Catalog.

Parameters:

catalogId - the Id of the Catalog to remove

Throws:

NotFoundException - catalogId not found

NullArgumentException - catalogId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageCatalogAliases

boolean canManageCatalogAliases()

Tests if this user can manage Id aliases for Catalogs. 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 Catalog aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasCatalog

void aliasCatalog(Id catalogId,
                Id aliasId)
                  throws AlreadyExistsException,
                         NotFoundException,
                         OperationFailedException,
                         PermissionDeniedException

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

Parameters:

catalogId - the Id of a Catalog

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - catalogId not found

NullArgumentException - catalogId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.