# com.bea.p13n.ad
AdBucketService Interface

public interface AdBucketService
extends `ContentBucket`, `EJBObject`

The remote bean interface for the AdBucketService. The AdBucketService implements the ContentBucket interface and provides ad content to the PlaceholderService. There are two "buckets" of ad that may be searched. Associated with each user is an AdBucket. If the ad isn't found in the users AdBucket then a global AdBucket is searched. When multiple ads are legal, the AdConflictResolver is called to select the "best" ad to be displayed.

The AdBucketService provides methods to add ads to user AdBuckets. In addition, there is a cleanup method which will remove all of the ads associated with a container.

Preview manages the life time of a query preview and allows all possible content matching the query to be rendered and returned to some type of preview object.

All Superinterfaces
  `ContentBucket`, `EJBObject`, `Remote`

## Nested Class Summary

Nested classes from interface com.bea.p13n.placeholder`.`ContentBucket``
``ContentBucket.PreviewInfo``

## Method Summary

`public void` | `cleanupAdBucket`(`String` containerUID) Remove the information about a container from both the user and global ad buckets.
`public `AdInfo`` | `getAdEventInfo`(long adBucketId) Get the AdInfo required to post an event for the specified bucket id.
`public `String`` | `getContent`(`String` placeholderName, boolean mixGlobals, `String` userId, `String` servletBase, `Request` request, int height, int width) Return the content for the requested ad
`public `Collection`` | `getGlobalQueries`(`String` placeholderName) Get the list of AdInfos that represent the global queries for the specified placeholder.
`public `Collection`` | `previewContent`(`String` servletBase, `String` query, boolean renderContent) Return a collection of `ContentBucket.PreviewInfo``` structures which match all of the content for the query.
`public `Collection`` | `previewContent`(`String` userId, `String` servletBase, `String` query) Return a collection of `ContentBucket.PreviewInfo``` structures which match all of the content for the query (with rendered content).
`public void` | `removeGlobalQueries`(`String` placeholderName, boolean removeAll) Remove queries from the add bucket.
`public void` | `setGlobalQuery`(`String` placeholderName, `String` query, int weight) Set a global query for the placeholder.
`public boolean` | `userAddAd`(`AdInfo` adInfo, boolean remove) Add the adInfo to the user's AdBucket
`public int` | `userClearAds`(`String` userId, `String` placeholderName, `String` containerUID, `String` containerType) Clear user ads in a bucket.

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

## Method Detail

### cleanupAdBucket(String) Method

    public void cleanupAdBucket(String containerUID)
         throws RemoteException, ContentException

Remove the information about a container from both the user and global ad buckets.

#### Parameters

containerUID
  The name of the container that we are cleaning up

#### Exceptions

``RemoteException``
``ContentException``

### getAdEventInfo(long) Method

    public AdInfo getAdEventInfo(long adBucketId)
         throws RemoteException, ContentException

Get the AdInfo required to post an event for the specified bucket id.

The AdInfo returned will only have a bucketId, placeholderName, containerUID, and contextUID.

#### Returns

the info on success, null on no such id.

#### Exceptions

``RemoteException``
``ContentException``

### getContent(String, boolean, String, String, Request, int, int) Method

    public String getContent(String placeholderName,
                             boolean mixGlobals,
                             String userId,
                             String servletBase,
                             Request request,
                             int height,
                             int width)
         throws RemoteException, ContentException

Return the content for the requested ad

#### Parameters

placeholderName
  The name of the placeholder

mixGlobals
  Mix globals with bucket ads?

userId
  The user id

servletBase
  The Web App base for the click thru servlet

request
  The HTTP request

height
  The desired height

width
  The desired width

#### Returns

the content of an ad for the placeholder as an XHTML string.

#### Exceptions

``RemoteException``
``ContentException``

### getGlobalQueries(String) Method

    public Collection getGlobalQueries(String placeholderName)
         throws RemoteException, ContentException

Get the list of AdInfos that represent the global queries for the specified placeholder.

#### Exceptions

``RemoteException``
``ContentException``

### previewContent(String, String, boolean) Method

    public Collection previewContent(String servletBase,
                                     String query,
                                     boolean renderContent)
         throws RemoteException, ContentException

Return a collection of `ContentBucket.PreviewInfo``` structures which match all of the content for the query.

#### Parameters

servletBase
  The Web App base for the click thru servlet

query
  The content query to be previewed

renderContent
  true to include the rendering content in the preview, false to not.

#### Returns

the collection of `ContentBucket.PreviewInfo``` structures that would be matched by the content query.

#### Exceptions

``RemoteException``
``ContentException``

### previewContent(String, String, String) Method

DEPRECATED Use previewContent(String, String, boolean) instead.

    public Collection previewContent(String userId,
                                     String servletBase,
                                     String query)
         throws RemoteException, ContentException

Return a collection of `ContentBucket.PreviewInfo``` structures which match all of the content for the query (with rendered content).

#### Parameters

userId
  the user name.

servletBase
  The Web App base for the click thru servlet

query
  The content query to be previewed

#### Returns

the collection of `ContentBucket.PreviewInfo``` structures that would be matched by the content query.

#### Exceptions

``RemoteException``
``ContentException``

### removeGlobalQueries(String, boolean) Method

    public void removeGlobalQueries(String placeholderName,
                                    boolean removeAll)
         throws RemoteException, ContentException

Remove queries from the add bucket. This will remove all or only global queries depending on the removeAll parameter.

#### Parameters

placeholderName
  the name of the placeholder

removeAll
  if true remove all entries for the placeholder, otherwise simply remove the global entries.

#### Exceptions

``RemoteException``
``ContentException``

### setGlobalQuery(String, String, int) Method

    public void setGlobalQuery(String placeholderName,
                               String query,
                               int weight)
         throws RemoteException, ContentException

Set a global query for the placeholder. A placeholder may have more than one global query.

#### Parameters

placeholderName
  the name of the placeholder setting the global query

query
  The query expression of the query.

weight
  The weight associated with the query

#### Exceptions

``RemoteException``
``ContentException``

### userAddAd(AdInfo, boolean) Method

    public boolean userAddAd(AdInfo adInfo,
                             boolean remove)
         throws RemoteException, ContentException

Add the adInfo to the user's AdBucket

#### Parameters

adInfo
  the ad related information

remove
  if the AdInfo already exists, true to remove it, false to update it.

#### Returns

true if the Ad is added, false otherwise

#### Exceptions

``RemoteException``
``ContentException``

### userClearAds(String, String, String, String) Method

    public int userClearAds(String userId,
                            String placeholderName,
                            String containerUID,
                            String containerType)
         throws RemoteException, ContentException

Clear user ads in a bucket.

#### Parameters

userId
  the userId (null for current, only admin users can clear other user's buckets).

placeholderName
  the name of the placeholder to clear (null for all placeholders).

containerUID
  the uid of the container to clear (null for all containers).

containerType
  the type of the container to clear (null for all container types).

#### Returns

the number of ad entries cleared.

#### Exceptions

``RemoteException``
``ContentException``
  thrown on an error.