Finders

Finders allow you to define simple data queries for a DataElement. Finders have a set of FieldOperatorPairs, which combine a reference to a Field with a search operator.

Starship.xml

<dataElement name="Starship">
  <finders>
    <finder name="findByField1Eq">
      <fieldOperatorPairs>
        <fieldOperatorPair>
          <operator>Eq</operator>
          <field name="field1"/>
        </fieldOperatorPair>
      </fieldOperatorPairs>
    </finder>
  </finders>
</dataElement>

A typical naming pattern is:

• findBy<fop1.field><fop1.operator>_<fop2.field><fop2.operator> (e.g. findByNameLk_SizeGt)

Default Finders

There are 2 finders that will always be present:

• findAll{dataElement.name}s (e.g. findAllPersons) returns all instances
• findByNameEq filters based on the names of the instances and is used in dropdowns

note

If the option nameNotWanted is used, the findByNameEq finder will not be added.

Operators

info

In most Finders, the values for each FieldOperatorPair are optional. Every Field that is not set will not be taken into account. This means that findByField1Eq_Field2Eq will function as findByField1Eq is the value for field2 is null.

String-specific Operators

Operator	Name	SQL Operator	Description
Se	Strict equals	=	case-sensitive exact match
Eq	Equals	LIKE	case-sensitive match supporting SQL %
Lk	Like	LIKE	case-insensitive match supporting SQL %
Ne	Not equals	NOT LIKE	case-sensitive match supporting SQL %
Sne	Strict not equals	<>	case-sensitive exact match

Example for a custom finder

// in FinderBean
JPAQueryBuilder queryBuilder = createQueryBuilder()
// Eq
.addParameter(QueryParameter.createStringParameter("name", "LIKE", "Name", details.getName()))
// Lk
.addParameter(QueryParameter.createCaseInsensitiveStringParameter("name", "LIKE", "Name", details.getName()))
// Ne
.addParameter(QueryParameter.createStringParameter("name", "NOT LIKE", "Name", details.getName()))
// Se
.addParameter(QueryParameter.createStringParameter("name", "=", "Name", details.getName()))
// Sne
.addParameter(QueryParameter.createStringParameter("name", "<>", "Name", details.getName()))

caution

The Eq and Ne operators were initially added for use in the UI. Unless it is required to support partial matching, these should be avoided since they support wildcards. Using them can result in unintended behavior. Use the strict matching Se and Sne operators instead.

Value Comparison Operators

Applicable to basic value operators (such as Integer, Double, or Date).

Operator	Name	SQL Operator	Description
Eq	Equals	=	exact match
Se	Strict equals	=	should not be used for non-string values
Ne	Not equals	<>	matches if the value is not equal to a provided value
Sne	Strict not equals	<>	should not be used for non-string values
Gt	Greater than	>	matches if the value is greater than a provided value
Gte	Greater than or equals	>=	matches if the value is greater than or equal to a provided value
Lt	Less than	<	matches if the value is less than a provided value
Lte	Less than or equals	<=	matches if the value is less than or equal to a provided value

Example for a custom finder

JPAQueryBuilder queryBuilder = createQueryBuilder()
// Eq
.addParameter(QueryParameter.createValueParameter("number", "=", "Number", details.getNumberEq()))
// Se
.addParameter(QueryParameter.createValueParameter("number", "=", "Number", details.getNumberSe()))
// Ne
.addParameter(QueryParameter.createValueParameter("number", "<>", "Number", details.getNumberNe()))
// Gt
.addParameter(QueryParameter.createValueParameter("number", ">", "Number", details.getNumberGt()))
// Gte
.addParameter(QueryParameter.createValueParameter("number", ">=", "Number", details.getNumberGte()))
// Lt
.addParameter(QueryParameter.createValueParameter("number", "<", "Number", details.getNumberLt()))
// Lte
.addParameter(QueryParameter.createValueParameter("number", "<=", "Number", details.getNumberLte()))

Collection Operators

Operator	Name	SQL Operator	Description
In	In	IN	matches values that are present in a provided non-empty list
Nin	Not in	NOT IN	matches values that are not in a provided non-empty list

Example for a custom finder

// fop `In:status`
finder.setStatus(asList("Finalized", "Failed"));
// ... perform search ...

// in FinderBean
JPAQueryBuilder queryBuilder = createQueryBuilder()
// In
.addParameter(QueryParameter.createValueParameter("status", "IN", "Status", details.getStatus()))
// Nin
.addParameter(QueryParameter.createValueParameter("status", "NOT IN", "Status", details.getStatus()))

note

• Collection operators on value fields are currently not supported in the UI/view layer.
• The Nin operator is currently not supported on link fields.
• Collection operators on link fields with Ln03, Ln04, Ln05, and Ln06 are currently not supported.
• Providing a null or an empty list to either operator will exclude the parameter from the query.

Nullable Operators

Operator	Name	SQL Operator	Description
Null	Null	IS NULL	matches if the value is null
Notnull	Not null	IS NOT NULL	matches if the value is not null (beware: Notnull, not NotNull)

The operator generates a boolean attribute specifying whether the value should be null or not null.

Null and Notnull operators are direct opposites -- setting value to true of a Null operator is the same as setting false to a Notnull operator (and vice versa).

Example for a custom finder

// fop `Null:status`
finder.setStatus(true);
// same as fop `Notnull:status`
finder.setStatus(false);
// ... perform search ...

// in FinderBean
JPAQueryBuilder queryBuilder = createQueryBuilder()
// Null
.addParameter(QueryParameter.createIsNullParameter("status", details.getStatusNull()))
// Notnull
.addParameter(QueryParameter.createIsNotNullParameter("status", details.getStatusNotnull()))
// Null + Ln01 linkField
.addParameter(QueryParameter.createIsNullParameter("ln01Reference", details.getLn01Reference()))
// Notnull + Ln01 linkField
.addParameter(QueryParameter.createIsNotNullParameter("ln01Reference", details.getLn01Reference()))
// Null + Ln02 linkField
.addParameter(QueryParameter.createIsNullParameter("ln02Reference.id", details.getLn02Reference()))
// Notnull + Ln02 linkField
.addParameter(QueryParameter.createIsNotNullParameter("ln02Reference.id", details.getLn02Reference()))

Setting the value to null (instead of true or false) for either operator will exclude the parameter from the query.

note

Nullable operators are currently not supported in the UI/view layer.