# com.bea.p13n.rules.advislets
RulesAdvisletImpl Class

public class RulesAdvisletImpl
extends `AbstractAdvislet`

This class is the implementation class for a generic `Advislet` that handles rules based advice. It is designed to be extended by `Advislet`s that wish to make use of the rules engine and provides a number of methods that can be overridden to change some of the default behaviour.

Required inputs to the `Advislet` are:

- `RULES_FILTER_CLASS_NAME` - the name of an `ObjectFilter` class that should be used to filter the objects returned by the `RulesManager`.
- `RULES_INPUT_OBJECTS` - a `Collection` of input objects to be passed to the `RulesManager`.

The output objects from rule evaluation are placed in a `List` in the `Advice` with the RESULTS key.

Hierarchy
  `Object`
  `AbstractAdvislet`
  `RulesAdvisletImpl`

All Implemented Interfaces
  `AdviceConstants`, `AdviceRequestConstants`, `Advislet`, `AdvisletChainElement`

## Field Summary

`public static final `String`` | `IGNORE_RULE_NAME` The key name for the optional ignore rule name parameter.
`public static final `String`` | `IGNORE_RULESET_NOT_FOUND` The key name for the optional ignore rule name parameter.
`public static final `String`` | `RULESET_NAME` The key name for the optional rule set name parameter.

Fields from com.bea.p13n.advisor`.`AbstractAdvislet``
``advisletMetadata`, `advisor`, `parametersMap``

Fields from interface com.bea.p13n.advisor`.`AdviceConstants``
``RESULTS``

Fields from interface com.bea.p13n.advisor`.`AdviceRequestConstants``
``CATALOG_QUERY_WRAPPER`, `CONTENT_APPEND_QUERY_STRING`, `CONTENT_MANAGER`, `CONTENT_MANAGER_HOME`, `CONTENT_QUERY_CONTEXT_PARAMS`, `CONTENT_QUERY_MAX_ITEMS`, `CONTENT_QUERY_NODE`, `CONTENT_QUERY_SORT_BY`, `CONTENT_QUERY_STRING`, `DATE`, `HTTP_REQUEST`, `HTTP_SESSION`, `NOW`, `RULES_FILTER_CLASS`, `RULES_FILTER_CLASS_NAME`, `RULES_INPUT_OBJECTS`, `RULES_RULENAME_TO_FIRE`, `RULES_RULESET_NAME`, `SHOPPING_CART`, `TIME`, `TIME_INSTANT`, `USER``

## Constructor Summary

RulesAdvisletImpl(`Advisor` advisor, `Metadata` metadata) Construct an instance of this object and bind it to its `Advisor` and `Metadata` instances.

## Method Summary

`protected void` | `addResults`(`Advice` advice, `Iterator` iterator) Adds the contents of a given iterator to a given advice.
`public `Advice`` | `getAdvice`(`AdviceRequest` request) Executes an AdviceRequest and returns the Advice object.s
`protected `Object`[]` | `getInputObjects`(`Advice` advice, `AdviceRequest` request) Returns the input objects for a given advice and advice request.
`protected `ObjectFilter`` | `getObjectFilter`(`Advice` advice, `AdviceRequest` request) Returns the object filter for a given advice and advice request.
`public `Object`[]` | `getRequiredAttributes`() Returns an array of required attributes for the advislet.
`protected `String`` | `getRuleNameToFire`(`Advice` advice, `AdviceRequest` request) Returns the name of the rule that must be fired for a given advice and advice request.
`protected `String`` | `getRuleSetName`(`Advice` advice, `AdviceRequest` request) Returns the rule set name for the given advice and advice request.
`protected `RulesManager`` | `getRulesManager`(`Advice` advice, `AdviceRequest` request) Returns a `RulesManager` instance for a given advice and advice request.
`public boolean` | `initialize`(`Map` parameters, `Object` parameterDocument) Initialize this instance from its XML configuration environment.
`protected void` | `sendRuleEvent`(`AdviceRequest` request, `Advice` advice) Generates a rule event for tracking listeners.
`protected `AdviceRequest`` | `setupRequest`(`Advice` advice, `AdviceRequest` request) Sets up a given advice request.

Methods from `com.bea.p13n.advisor.`AbstractAdvislet``
``getAdvisor`, `getMetadata`, `toString`, `validateAdviceRequest``

Methods from class `java.lang.`Object``
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods from interface `com.bea.p13n.advisor.`Advislet``
``getAdvice`, `getRequiredAttributes`, `validateAdviceRequest``

Methods from interface `com.bea.p13n.advisor.`AdvisletChainElement``
``getMetadata`, `initialize``

## Field Detail

### IGNORE_RULE_NAME

    public static final String IGNORE_RULE_NAME

  The key name for the optional ignore rule name parameter.

### IGNORE_RULESET_NOT_FOUND

    public static final String IGNORE_RULESET_NOT_FOUND

  The key name for the optional ignore rule name parameter.

### RULESET_NAME

    public static final String RULESET_NAME

  The key name for the optional rule set name parameter.

## Constructor Detail

### RulesAdvisletImpl

    public RulesAdvisletImpl(Advisor advisor,
                             Metadata metadata)

  Construct an instance of this object and bind it to its `Advisor` and `Metadata` instances.

## Method Detail

### addResults(Advice, Iterator) Method

    protected void addResults(Advice advice,
                              Iterator iterator)
         throws AdvisorException

Adds the contents of a given iterator to a given advice.

#### Parameters

advice
  The target advice.

iterator
  The source iterator.

#### Exceptions

``AdvisorException``
  On general Advisor exception.

### getAdvice(AdviceRequest) Method

    public Advice getAdvice(AdviceRequest request)
         throws IllegalArgumentException, AdvisorException

Executes an AdviceRequest and returns the Advice object.s

Overrides
  `AbstractAdvislet.getAdvice(AdviceRequest)`

#### Parameters

request
  the AdviceRequest containing the paramters for the request

#### Returns

the Advice instance with the result of the Advisor.getAdvice call.

#### Exceptions

``IllegalArgumentException``
``AdvisorException``

### getInputObjects(Advice, AdviceRequest) Method

    protected Object[] getInputObjects(Advice advice,
                                     AdviceRequest request)

Returns the input objects for a given advice and advice request.

#### Parameters

advice
  The target advice.

request
  The target request.

#### Returns

The input objects.

### getObjectFilter(Advice, AdviceRequest) Method

    protected ObjectFilter getObjectFilter(Advice advice,
                                           AdviceRequest request)
         throws AdvisorException

Returns the object filter for a given advice and advice request.

#### Parameters

advice
  The current advice.

request
  The current advice request.

#### Returns

The object filter.

#### Exceptions

``AdvisorException``
  On general Advisor exception.

### getRequiredAttributes() Method

    public Object[] getRequiredAttributes()

Description copied from `Advislet.getRequiredAttributes()`
Returns an array of required attributes for the advislet. The array contains pairs of items: even items are attribute names while odd items are the Class for the item. This information is used by the Advisor to ensure Advislets are not invoked with invalid parameters. Overide the `validateAdviceRequest``` method to perform additional processing above and beyond attribute type checking.

Overrides
  `AbstractAdvislet.getRequiredAttributes()`

#### Returns

an array that contains the attributes required by the Advislet.

### getRuleNameToFire(Advice, AdviceRequest) Method

    protected String getRuleNameToFire(Advice advice,
                                       AdviceRequest request)
         throws AdvisorException

Returns the name of the rule that must be fired for a given advice and advice request.

#### Parameters

advice
  The current advice.

request
  The current advice request.

#### Returns

The rule name.

#### Exceptions

``AdvisorException``
  On general Advisor exception.

### getRuleSetName(Advice, AdviceRequest) Method

    protected String getRuleSetName(Advice advice,
                                    AdviceRequest request)
         throws AdvisorException

Returns the rule set name for the given advice and advice request.

#### Parameters

advice
  The current advice.

request
  The current advice request.

#### Returns

The rule set name.

#### Exceptions

``AdvisorException``
  On general Advisor exception.

### getRulesManager(Advice, AdviceRequest) Method

    protected RulesManager getRulesManager(Advice advice,
                                           AdviceRequest request)
         throws AdvisorException

Returns a `RulesManager` instance for a given advice and advice request.

#### Parameters

advice
  The current advice.

request
  The current advice request.

#### Exceptions

``AdvisorException``
  On general Advisor exception.

### initialize(Map, Object) Method

    public boolean initialize(Map parameters,
                              Object parameterDocument)
         throws AdvisorException

Initialize this instance from its XML configuration environment.

Overrides
  `AbstractAdvislet.initialize(Map, Object)`

#### Parameters

parameters
  the configuration paramters

parameterDocument
  the XML Document node for the configuration environment

#### Returns

true if required initialization parameters were present.

#### Exceptions

``AdvisorException``

### sendRuleEvent(AdviceRequest, Advice) Method

    protected void sendRuleEvent(AdviceRequest request,
                                 Advice advice)

Generates a rule event for tracking listeners.

#### Parameters

request
  The current advice request.

advice
  The current advice.

### setupRequest(Advice, AdviceRequest) Method

    protected AdviceRequest setupRequest(Advice advice,
                                         AdviceRequest request)
         throws AdvisorException

Sets up a given advice request.

#### Parameters

advice
  The current advice.

request
  The current advice request.

#### Returns

The initialized advice request.

#### Exceptions

``AdvisorException``
  On general Advisor exception.