Annotation Reference

Entity Annotations

@QfEntity

Declares a class as a Q-Framework entity. Placed on the domain entity class.

java

@QfEntity(
    appKey = "app",
    name = @QfI18n(
        defaultMessage = "Product",
        texts = { @QfI18nText(locale = "ko", message = "상품") }
    ),
    autoHistoryEnabled = false,
    deletePolicy = @QfCrudPolicy(enabled = true),
    capabilityKey = "product-management"
)
public class ProductEntity { }

Attribute	Type	Description	Default
`appKey`	String	Owning client app key	`""` (uses declared app)
`name`	@QfI18n	Localized display name	`@QfI18n(texts = {})`
`autoHistoryEnabled`	boolean	Enable automatic change history	`false`
`deletePolicy`	@QfCrudPolicy	Delete operation policy	`@QfCrudPolicy(enabled = false)`
`treePolicy`	@QfTreePolicy	Tree/hierarchical structure config	`@QfTreePolicy` (disabled)
`organizationPolicy`	@QfOrganizationPolicy	Organization-based data filtering	`@QfOrganizationPolicy(enabled = false)`
`masterRelation`	@QfMasterRelation	Master-detail relationship	`@QfMasterRelation(enabled = false)`
`capabilityKey`	String	Linked capability key	`""` (derived from class name)
`excelDownloadable`	boolean	Enable Excel export endpoint	`true`
`excelUploadable`	boolean	Enable Excel import endpoint	`true`

@QfClientApp

Declares a client application. Placed on a configuration class.

java

@QfClientApp(
    key = "app",
    name = @QfI18n(
        defaultMessage = "App",
        texts = { @QfI18nText(locale = "ko", message = "일반 앱") }
    )
)
public class AppConfig { }

Attribute	Type	Required	Description
`key`	String	✅	Unique client app key
`name`	@QfI18n		Localized display name

Capability / Permission Annotations

@QfCapability

Declares a business function area (Capability). Placed on a dedicated class.

java

@QfCapability(
    key = "product-management",
    name = @QfI18n(defaultMessage = "Product Management", texts = {}),
    entities = { ProductEntity.class },
    privileges = {
        @QfPrivilege(key = "product-management__create"),
        @QfPrivilege(key = "product-management__delete")
    }
)
public final class ProductManagementCapability { }

Attribute	Type	Required	Description
`key`	String	✅	Unique capability key
`name`	@QfI18n		Localized display name
`entities`	Class[]		Primary managed entity classes
`privileges`	@QfPrivilege[]		Privileges defined by this capability

Entities are linked to a capability via @QfEntity(capabilityKey = "..."), not by placing @QfCapability on the entity class.

@QfPrivilege

Declares a permission unit within a @QfCapability.

java

@QfPrivilege(
    key = "product-management__create",
    name = @QfI18n(defaultMessage = "Create Product", texts = {})
)

Attribute	Type	Required	Description
`key`	String	✅	Unique key (scoped within Capability)
`name`	@QfI18n		Localized display name

Security Annotations

@QfCrypto

Automatically encrypts and decrypts a field. Placed on a field.

java

@QfCrypto
private String email;

Restriction

Cannot be combined with @QfSearch (compile error).

@QfOrganizationPolicy (element)

Configures organization-based data filtering. Used as an element inside @QfEntity:

java

@QfEntity(
    organizationPolicy = @QfOrganizationPolicy(
        enabled = true,
        attribute = "orgId"   // field name holding the org ID
    )
)

Attribute	Type	Description	Default
`enabled`	boolean	Enable org filtering	`true`
`attribute`	String	Field name holding org ID	`""`
`include`	QfOrganizationInclude	Traversal direction	`ANCHOR_ONLY`

Validation Annotations

@QfValidationRule

Declares a validation rule on a field. Repeatable.

java

@QfValidationRule(
    rule = QfValidationRule.Rule.regex,
    params = "^[A-Za-z0-9_]+$",
    invalidValueMessageKey = "validation.loginId.invalid"
)
private String loginId;

Attribute	Type	Required	Description
`rule`	Rule	✅	Validation rule type
`params`	String[]		Rule parameters (pattern for `regex`)
`invalidValueMessageKey`	String		Error message key
`invalidValueMessages`	@QfI18n		Inline error message
`serverOnly`	boolean		Server-side only validation
`applyOn`	@QfConditionExpr[]		Conditions for rule application

Rule enum values:

Rule	Description	params
`regex`	Custom regex	`params[0]` = pattern
`unique`	Server uniqueness check	`params[0]` = URL (optional)
`login_id`	Login ID format (from config)	—
`user_pwd`	Password policy (from config)	—

Display Annotations

@QfListAttribute

Displays as a column in the list view.

java

@QfListAttribute(sortable = true)
private String name;

Attribute	Type	Default	Description
`sortable`	boolean	`false`	Whether sortable
`isTreeNodeTitle`	boolean	`false`	Use as tree node title
`isTreeNodeSubTitle`	boolean	`false`	Use as tree node subtitle
`cannotHide`	boolean	`false`	Prevent user from hiding column
`buttons`	@QfButton[]	`{}`	Row-level action buttons
`exposeOn`	@QfExposeOn[]	`{}`	App/capability visibility rules

@QfDetailAttribute

Displays in the detail view.

java

@QfDetailAttribute
private String name;

@QfCreateAttribute

Displays as an input field in the create form.

java

@QfCreateAttribute(
    requiredOn = @QfRequiredOn(always = true)
)
private String name;

Attribute	Type	Description
`requiredOn`	@QfRequiredOn	Required rule
`readonlyOn`	@QfReadonlyOn	Read-only rule
`initialValue`	String	Static initial value
`showOn`	@QfConditionExpr[]	Visibility conditions
`disableOn`	@QfConditionExpr[]	Disable conditions

@QfUpdateAttribute

Displays as an input field in the update form. Same attributes as @QfCreateAttribute.

@QfSearch

Enables the field as a search filter in the list view.

java

@QfSearch(type = QfSearch.Type.text)
private String name;

@QfSearch(type = QfSearch.Type.select)
private String status;

Type	Description
`auto`	Auto-detect based on field type
`text`	Plain text input
`select`	Single-select dropdown
`true_or_false`	Boolean toggle
`multiselect`	Multi-select
`period_date`	Date range
`period_datetime`	Datetime range

@QfDisplayLabel

Sets the display label for a field.

java

@QfDisplayLabel(text = "Product Name")
private String name;

@QfDisplayLabel(key = "label.product.name")   // resolved from message resource
private String name;

Attribute	Description
`key`	Message resource key for i18n resolution
`text`	Literal label text (fallback)

@QfControlType

Declares the UI control type for a field.

java

@QfControlType(QfControlType.Type.email)
private String email;

@QfControlType(QfControlType.Type.textarea)
private String description;

Structural Annotations

@QfMasterRelation (element)

Declares a master-detail relationship. Used as an element inside @QfEntity:

java

@QfEntity(
    masterRelation = @QfMasterRelation(
        enabled = true,
        masterEntityFqcn = "com.example.OrderEntity",
        masterKeyAttribute = "orderId",
        onMasterDelete = QfMasterRelation.OnMasterDelete.CASCADE_DELETE
    )
)
public class OrderItemEntity { }

`onMasterDelete`	Description
`CASCADE_DELETE`	Delete details when master is deleted
`RESTRICT`	Reject master deletion if details exist
`IGNORE`	Leave details orphaned

@QfParent / @QfTreeDepth / @QfChildren

Declare tree structure fields.

java

@QfParent
private String parentId;

@QfTreeDepth
private Integer depth;

@QfChildren
private List<CategoryEntity> children;

@QfGroup

Groups related fields together in the UI.

java

@QfGroup(key = "address_info")
private String address;

@QfGroup(key = "address_info")
private String zipCode;

Audit Trail Annotations

Auto-populated by the framework at write time:

Annotation	Description
`@QfRgsOperId`	Records the creator's user ID
`@QfRgsOperDt`	Records the creation timestamp
`@QfRgsOperIp`	Records the creator's IP address
`@QfUpdtOperId`	Records the last updater's user ID
`@QfUpdtOperDt`	Records the last update timestamp
`@QfUpdtOperIp`	Records the updater's IP address
`@QfDeleteOperId`	Records the deleter's user ID
`@QfDeleteOperDt`	Records the deletion timestamp
`@QfDeleteFlag`	Marks the record as soft-deleted

Result Code Annotations

@QfResultCode

Declares a result code. Placed on an interface.

java

@QfResultCode(
    code = "PRODUCT_NOT_FOUND",
    httpStatus = 404,
    message = "Product not found.",
    resolution = "Check the product ID and retry."
)
public interface ProductResultCode { }

For details, see the Result Code Reference.

Internationalization Annotations

@QfI18n

Declares a localized message bundle. Used as an element inside other annotations.

java

@QfI18n(
    defaultMessage = "Product Name",
    texts = {
        @QfI18nText(locale = "ko", message = "상품명"),
        @QfI18nText(locale = "ja", message = "商品名")
    },
    key = "entity.product.name.label",   // optional; auto-generated if empty
    sync = false
)

Attribute	Type	Description
`defaultMessage`	String	Fallback text when no locale matches
`texts`	@QfI18nText[]	Locale-specific messages
`key`	String	Message lookup key (auto-generated if empty)
`sync`	boolean	Sync with source on every startup

@QfI18nText

One locale-specific message within a @QfI18n bundle.

java

@QfI18nText(locale = "ko", message = "상품명")

@QfDisplayHint

Declares a hint (tooltip / placeholder) for a field.

java

@QfDisplayHint(
    i18n = @QfI18nText(locale = "en", message = "Enter the product name")
)
private String name;

Annotation Reference ​

Entity Annotations ​

@QfEntity ​

@QfClientApp ​

Capability / Permission Annotations ​

@QfCapability ​

@QfPrivilege ​

Security Annotations ​

@QfCrypto ​

@QfOrganizationPolicy (element) ​

Validation Annotations ​

@QfValidationRule ​

Display Annotations ​

@QfListAttribute ​

@QfDetailAttribute ​

@QfCreateAttribute ​

@QfUpdateAttribute ​

@QfSearch ​

@QfDisplayLabel ​

@QfControlType ​

Structural Annotations ​

@QfMasterRelation (element) ​

@QfParent / @QfTreeDepth / @QfChildren ​

@QfGroup ​

Audit Trail Annotations ​

Result Code Annotations ​

@QfResultCode ​

Internationalization Annotations ​

@QfI18n ​

@QfI18nText ​

@QfDisplayHint ​

Annotation Reference

Entity Annotations

@QfEntity

@QfClientApp

Capability / Permission Annotations

@QfCapability

@QfPrivilege

Security Annotations

@QfCrypto

@QfOrganizationPolicy (element)

Validation Annotations

@QfValidationRule

Display Annotations

@QfListAttribute

@QfDetailAttribute

@QfCreateAttribute

@QfUpdateAttribute

@QfSearch

@QfDisplayLabel

@QfControlType

Structural Annotations

@QfMasterRelation (element)

@QfParent / @QfTreeDepth / @QfChildren

@QfGroup

Audit Trail Annotations

Result Code Annotations

@QfResultCode

Internationalization Annotations

@QfI18n

@QfI18nText

@QfDisplayHint