# com.bea.commerce.ebusiness.discount.association
DiscountAssociationMgr Interface

public interface DiscountAssociationMgr
extends `EJBObject`

This interface defines the public interface of the `DiscountAssociationMgr` service. This service is responsible for associating `Customer`s, using thier `CustomerPK`, with discounts. Once the association has been made the number of times the customer has used the discount is tracked. The user can only use the discount up to the number of time specified in the discount's `allowedUses`field. There is a minor difference in the way user's become associated with discounts depending on whether the discount is global or not. For non-global discounts the user must be associated with the discount, prior to attempting to use it, using either of this class's `add` methods. The discount can then be used, which from the point of view of this service means calling this class's `updateUses` method. This method is called by the pricing service. In the case of global discounts, which by definition are available to all customers the pricing serivce simply calls `updateUsesGlobal`. This method call will create the association, setting the use count to 1, if one does not already exist or attempt to the use count if the association already exists. In either case if a call to `updateUses` or `updateUsesGlobal` would cause the association's use count to exceed the discount's allowed uses limit those methods will throw a `UseCountLimitException` and not update the association's use count.``

All Superinterfaces
  `EJBObject`, `Remote`

## Method Summary

`public void` | `add`(`CustomerPk` user, `QualificationDiscountId` discountId, `String` description) Creates an association between the `Customer` specified by the `user` parameter and the discount specified by the `discountId` parameter.
`public void` | `add`(`CustomerPk` user, `String` applicationName, `String` discountName, `String` description) Creates an association between the `Customer` specified by the `user` parameter and the discount specified by the `setName` and `discountName` parameters.
`public int` | `archive`() Not currently implemented, throws UnsupportedOperationException if called
`public `DeleteResults`` | `delete`(`QualificationDiscountId` discountId) Delete the associations for the given discount ID.
`public `DeleteResults`` | `delete`(`String` applicationName, `String` discountName) Delete the associations for the given discount described by set name and discount name
`public int` | `prune`() Not currently implemented, throws UnsupportedOperationException if called
`public int` | `prune`(`QualificationDiscountId` discountId) Not currently implemented, throws UnsupportedOperationException if called
`public `Set`` | `queryGlobal`(`CustomerPk` user, `Set` idSet) Gets all of the `user`'s discount associations where the discount in the association is global
`public `Set`` | `queryUser`(`CustomerPk` user, `Set` idSet) Gets all of the `user`'s discount associations where the discount in the association is non-global
`public void` | `updateUses`(`CustomerPk` user, `Set` discountIds) Updates the use count for each of the associations for this `user` whose discount id is in the `Set` specified by `discountIds`.
`public void` | `updateUsesGlobal`(`CustomerPk` user, `Set` discountIds) Updates the use count for each of the associations for this `user` whose discount id is in the `Set` specified by `discountIds`.

Methods from interface `javax.ejb.`EJBObject``
`getEJBHome, getHandle, getPrimaryKey, isIdentical, remove`

## Method Detail

### add(CustomerPk, QualificationDiscountId, String) Method

    public void add(CustomerPk user,
                    QualificationDiscountId discountId,
                    String description)
         throws RemoteException, DiscountNotFoundException, InvalidAssociationException, AssociationCreationException

Creates an association between the `Customer` specified by the `user` parameter and the discount specified by the `discountId` parameter. An optional `description` may also be supplied that should indicate how or why the association was created. Only non-global discounts can be associated with a user through this method call. Any attempt to specify a global discount will result in an InvalidAssociationException being thrown.

#### Parameters

user
  the `CustomerPk` of the customer being associated with the discount specified by `discountId`

discountId
  the `QualificationDiscountId` of the discount being associated with the customer specified by `user`

description
  a `String` describing how or why the association is being created

#### Exceptions

``RemoteException``
  on a communication error or other system level failure
``DiscountNotFoundException``
  if the specified discount cannot be found.
``InvalidAssociationException``
  if the discount specified is global
``AssociationCreationException``
  if the association could not be created due to a system level failure

### add(CustomerPk, String, String, String) Method

    public void add(CustomerPk user,
                    String applicationName,
                    String discountName,
                    String description)
         throws RemoteException, DiscountNotFoundException, InvalidAssociationException, AssociationCreationException

Creates an association between the `Customer` specified by the `user` parameter and the discount specified by the `setName` and `discountName` parameters. An optional `description` may also be supplied that should indicate how or why the association was created. Only non-global discounts can be associated with a user through this method call. Any attempt to specify a global discount will result in an InvalidAssociationException being thrown.

#### Parameters

user
  the `CustomerPk` of the customer being associated with the discount specified by `setName` and `discountName`

applicationName
  the current J2EE application name

discountName
  the discount name of the discount being associated with the customer specified by `user`

description
  a `String` describing how or why the association is being created

#### Exceptions

``RemoteException``
  on a communication error or other system level failure
``DiscountNotFoundException``
  if the specified discount cannot be found.
``InvalidAssociationException``
  if the discount specified is global
``AssociationCreationException``
  if the association coul not be created due to a system level failure

### archive() Method

    public int archive()
         throws RemoteException

Not currently implemented, throws UnsupportedOperationException if called

#### Exceptions

``RemoteException``
  on a communication error or other system level failure

### delete(QualificationDiscountId) Method

    public DeleteResults delete(QualificationDiscountId discountId)
         throws RemoteException, AssociationDeleteException

Delete the associations for the given discount ID.

#### Parameters

discountId
  the discount id for which the associations should be deleted

#### Returns

a DeleteResults object that describes the associations deleted and those failed to be deleted.

#### Exceptions

``RemoteException``
``AssociationDeleteException``
  if any failures were encountered during the delete operation. See the DeleteResults object in the exception for specifics.

Related Topics

``DeleteResults``

### delete(String, String) Method

    public DeleteResults delete(String applicationName,
                                String discountName)
         throws RemoteException, AssociationDeleteException

Delete the associations for the given discount described by set name and discount name

#### Parameters

applicationName
  the current J2EE application name

discountName
  the name of the discount.

#### Returns

a DeleteResults object that describes the associations deleted and those failed to be deleted.

#### Exceptions

``RemoteException``
``AssociationDeleteException``
  if any failures were encountered during the delete operation. See the DeleteResults object in the exception for specifics.

Related Topics

``DeleteResults``

### prune() Method

    public int prune()
         throws RemoteException

Not currently implemented, throws UnsupportedOperationException if called

#### Exceptions

``RemoteException``
  on a communication error or other system level failure

### prune(QualificationDiscountId) Method

    public int prune(QualificationDiscountId discountId)
         throws RemoteException

Not currently implemented, throws UnsupportedOperationException if called

#### Exceptions

``RemoteException``
  on a communication error or other system level failure

### queryGlobal(CustomerPk, Set) Method

    public Set queryGlobal(CustomerPk user,
                           Set idSet)
         throws RemoteException

Gets all of the `user`'s discount associations where the discount in the association is global

#### Parameters

user
  the `CustomerPk` of the customer whose discount associations are being fetched

idSet
  an empty `Set` into which the results of this method call are placed. Anything previously in the set is deleted.

#### Returns

a `Set`, the one passed in the `idSet`paramter, of `DiscountAssociation` objects that have the specified `user` as an element. The set will be empty if there are no discount associations for the `user```

#### Exceptions

``RemoteException``
  on a communication error or other system level failure

### queryUser(CustomerPk, Set) Method

    public Set queryUser(CustomerPk user,
                         Set idSet)
         throws RemoteException

Gets all of the `user`'s discount associations where the discount in the association is non-global

#### Parameters

user
  the `CustomerPk` of the customer whose discount associations are being fetched

idSet
  an empty `Set` into which the results of this method call are placed. Anything previously in the set is deleted.

#### Returns

a `Set`, the one passed in the `idSet`paramter, of `DiscountAssociation` objects that have the specified `user` as an element. The set will be empty if there are no discount associations for the `user```

#### Exceptions

``RemoteException``
  on a communication error or other system level failure

### updateUses(CustomerPk, Set) Method

    public void updateUses(CustomerPk user,
                           Set discountIds)
         throws RemoteException, DiscountNotFoundException, InvalidAssociationException, UseCountLimitException, AssociationNotFoundException

Updates the use count for each of the associations for this `user` whose discount id is in the `Set` specified by `discountIds`. If any of the association updates results in the association's use count exceeding the discount's allowed uses a `UseCountLimitException` is thrown. This method call is intended for updating associations whose discount is non-global. If any of the discounts specified in the `discountIds` set are global an InvalidAssociationException is thrown. All of the discount associations specified must have already been created using one of this class's add methods.

#### Parameters

user
  the `CustomerPk` of the customer whose discount associations are being updated

discountIds
  a `Set` of `QualificationDiscountId`s that specifies which of the `user`'s associations to update

#### Exceptions

``RemoteException``
  on a communication error or other system level failure
``DiscountNotFoundException``
  if any of the discounts specified in `discountIds` can not be found
``InvalidAssociationException``
  if any of the discounts specified in `discountIds` are global
``UseCountLimitException``
  if the use count limit has been reached
``AssociationNotFoundException``
  if the association specified by the `user` and any of the `QualificationDiscountId`s in `discountIds` can not be found

### updateUsesGlobal(CustomerPk, Set) Method

    public void updateUsesGlobal(CustomerPk user,
                                 Set discountIds)
         throws RemoteException, DiscountNotFoundException, InvalidAssociationException, UseCountLimitException, AssociationCreationException

Updates the use count for each of the associations for this `user` whose discount id is in the `Set` specified by `discountIds`. If any of the association updates results in the association's use count exceeding the discount's allowed uses a `UseCountLimitException` is thrown. This method call is intended for updating associations whose discount is global. If any of the discounts specified in the `discountIds` set are non-global an InvalidAssociationException is thrown. This method is slightly different from `updateUses` in that if the association specified doesn't already exists an attempt will be made to create it setting it's intial use count to 1.

#### Parameters

user
  the `CustomerPk` of the customer whose discount associations are being updated

discountIds
  a `Set` of `QualificationDiscountId`s that specifies which of the `user`'s associations to update

#### Exceptions

``RemoteException``
  on a communication error or other system level failure
``DiscountNotFoundException``
  if any of the discounts specified in `discountIds` can not be found
``InvalidAssociationException``
  if any of the discounts specified in `discountIds` are non-global
``UseCountLimitException``
  if the use count limit has been reached
``AssociationCreationException``
  if a non-existant association was specified but it could not be created