Conditional Attributes

In an entity class, attributes that can dynamically generate conditions based on Field Parameters are called conditional attributes. Specifically, they can be further divided into two types: Field Attributes and Additional Attributes.

Field Attributes

Field attributes refer to the Java fields declared in the retrieval entity class that are associated with database table fields. For example, all the fields declared in OrderVO in the following example:

@SearchBean(
    tables = "order o, shop s, user u",  // Three-table association
    where = "o.shop_id = s.id and o.buyer_id = u.id",  // Association relationship
    autoMapTo = "o"  // Fields not annotated with @DbField are mapped to the order table
)
public class OrderVO {
    private long id;         // Order ID   o.id
    private String orderNo;  // Order number   o.order_no
    private long amount;     // Order amount o.amount
    @DbField("s.name")
    private String shop;     // Shop name   s.name
    @DbField("u.name")
    private String buyer;    // Buyer name   u.name
    // Getter and Setter are omitted
}

Generally, field attributes are fields annotated with @DbField, but this annotation can be omitted in some scenarios. Refer to the Annotation Omission section. Of course, some Java fields can also be ignored. Refer to the Attribute Ignoring section.

Functions and Characteristics

• In list queries, they serve as query fields in the Select list. Of course, you can also specify or exclude a specific field in the Select list. Refer to the Specify Select Fields section.
• When using the BeanSearcher retriever for list queries, field attributes are used to carry the query results.
• Generate where or having conditions based on Field Parameters.

Additional Attributes (since v4.1.0)

Although field attributes can dynamically generate conditions based on parameters, a field must be declared in the Java class. If you don't want to write this field, you can use @SearchBean.fields to define additional attributes. For example:

@SearchBean(
    tables = "user u, role r",  // Two-table association
    where = "u.role_id = r.id",
    fields = {                  // Define additional attributes
        @DbField(name = "name"),                     // The attribute name is name, automatically mapped to u.name
        @DbField(name = "rType", value = "r.type")   // The attribute name is rType, mapped to r.type
    },
    autoMapTo="u"  // Automatically mapped to u
)
public class UserVO { ... }

The above code defines two additional attributes, name and rType, for UserVO. They must be defined using the annotation @DbField, and @DbField.name cannot be omitted. Its function is equivalent to the Java field name in field attributes.

Functions and Characteristics

• Like field attributes, they can dynamically generate where or having conditions based on retrieval parameters.
• In list queries, they do not appear in the Select list.

Where or Having

When conditional attributes generate conditions, are they where conditions or having conditions? This depends on the following two situations.

When not using grouping (groupBy)

That is, when the value of @SearchBean.groupBy is not specified, all conditions generated by conditional attributes are where conditions.

When using grouping (groupBy)

When @SearchBean.groupBy is specified, whether a where condition or a having condition is generated depends on the value of @DbField.cluster for each conditional attribute. It has the following three values:

• Cluster.TRUE - Indicates that the attribute is an aggregated field, and it only generates having conditions.
• Cluster.FALSE - Indicates that the attribute is a non-aggregated field, and it only generates where conditions.
• Cluster.AUTO - Default value, automatically infer whether the field is an aggregated field: When the conditional attribute is not in the groupBy list and the attribute is also a field in the Java class, it will be automatically inferred as TRUE; in other cases, it will be inferred as FALSE.

Examples of field inference

• All Additional Attributes are automatically inferred as Cluster.FALSE, that is, by default, they all generate where conditions.
• In the following example, courseId is automatically inferred as Cluster.FALSE, and totalScore is automatically inferred as Cluster.TRUE.

@SearchBean(tables = "student_course sc", groupBy = "sc.course_id") 
public class CourseScore {
    @DbField("sc.course_id")    // In the groupBy list
    private long courseId;
    @DbField("sum(sc.score)")   // Not in the groupBy list
    private long totalScore;
    // ...
}