Package com.orchestranetworks.schema

# Interface TableRefFilter

All Superinterfaces:
  `JavaBeanVersion`

public interface TableRefFilter extends JavaBeanVersion
Defines a filter that depends on the context of a constraint. A custom filter can be defined for a foreign key constraint. For example:

>      <xs:annotation>
>                     <xs:appinfo>
>                             <osd:otherFacets>
>                              <osd:tableRef>
>                                     <tablePath>../catalog</tablePath>
>                                     <labelPaths>/productLabel /productWeight</labelPaths>
>                                     <displayKey>true</displayKey>
>                                     <filter osd:class="com.foo.CatalogFilter">
>                                             <param1>...</param1>
>                                             <param2>...</param2>
>                                     </filter>
>                              </osd:tableRef>
>                             </osd:otherFacets>
>                     </xs:appinfo>
>     </xs:annotation>

where `com.foo.CatalogFilter` is the fully qualified name of the class that implement this interface.

The declaration may use parameters, `param1` and `param2` in the example, which are are JavaBean properties of the `com.foo.CatalogFilter` class.

For more information, see the JavaBean specification.

### Life cycle

1. When the data model is loaded:
   1. the specified class is instantiated through its default constructor and its JavaBean property setters are called (in the example above, the setter methods would be `setParam1(...)` and `setParam2(...)`);
   2. the method `setup(TableRefFilterContext)` is called on the new instance.
   *
   3. the method `JavaBeanVersion.getBeanVersion()` is called for the new instance for checking if its implementation has been modified since the last time the data model has been compiled. That is, since validation reports are persisted into EBX® repository it is important to update the version to indicate that this filter has been modified and the associated foreign key constraint must be revalidated during the next explicit validation of the container dataset or table.
2. During the operational phase: the method `accept(Adaptation, ValueContext)` is called each time an associated element or field is to be checked.

See Also:
  - `JavaBeanVersion.getBeanVersion()`
  - `Request.setSpecificFilter(AdaptationFilter)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `accept(Adaptation aRecord, ValueContext currentContext)`
  Returns whether the specified record is included in the filter result.
  `default UserMessage`
  `getValidationMessage(Adaptation aRecord, ValueContext currentContext)`
  Returns a validation message according to the specified context.
  `void`
  `setup(TableRefFilterContext context)`
  This method is called when the data model is loaded.
  `String`
  `toUserDocumentation(Locale userLocale, ValueContext aContext)`
  Returns the end-user documentation for this filter.

  ### Methods inherited from interface com.orchestranetworks.schema.JavaBeanVersion

  `getBeanVersion`

- ## Method Details

  - ### accept

    boolean accept(Adaptation aRecord, ValueContext currentContext)
    Returns whether the specified record is included in the filter result.

    When the filter is used on large collections, it is important to implement a low-computation method. A prefilter, a feature available since EBX® 6.2, can help to reduce the computational load of a `TableRefFilter`. It can be defined by calling `TableRefFilterContext.setPrefilter(String)` during `setup(TableRefFilterContext)`.

    Parameters:
      `currentContext` - since 6.0 the ValueContext is relative to the table reference node. The behavior is therefore aligned with the contextual XPath predicates.

  - ### getValidationMessage

    default UserMessage getValidationMessage(Adaptation aRecord, ValueContext currentContext)
    Returns a validation message according to the specified context. This message will be displayed to the end user at validation time when the specified record is not accepted by this filter. This method also allows specifying the severity of the message added at validation time if a record is not accepted by this filter.

    This method is not called if this filter also defines a static validation message during its setup.

    If this method returns `null` then a default validation message will be added at validation time if a record is not accepted by this filter.

    Parameters:
      `aRecord` - record in the target table of the foreign key constraint that is not accepted by this filter.
      `currentContext` - dataset or record that contains the foreign key constraint associated to this filter.
    Since:
      5.9.0
    See Also:
      - `TableRefFilterContext.setFilterValidationMessage(UserMessageLocalized)`

  - ### setup

    void setup(TableRefFilterContext context)
    This method is called when the data model is loaded.

    Do note that during this step, all models may not be properly loaded. Thus, the repository should not be accessed during this step.

  - ### toUserDocumentation

    String toUserDocumentation(Locale userLocale, ValueContext aContext) throws InvalidSchemaException
    Returns the end-user documentation for this filter.

    ##### Internationalization strategy

    This method returns `null` if the specified locale is not handled by the current implementation. The container tries several locales when handling a partial internationalization of this method's implementation and/or a mismatch between the locales declared by the associated module and the locales supported by EBX®. In such cases, locales are tried in the following order:

    1. User's preferred locale for the data model (see `Session.getLocaleForSchemaNode(SchemaNode)`);
    2. Session's current locale;
    3. Default locale declared in the file `module.xml`;

    ##### Multi-threading

    For a single instance of this interface, this method may be called concurrently by several threads.

    Throws:
      `InvalidSchemaException` - if a dynamic condition in the data model prevents the execution of this method.