Datadescriptor Metadata Structure

A DataDescriptor is a metadata structure with multiple layers that describes physical data structure and the way data values are displayed in the UI. A DataDescriptor itself is specified in an XML format or you can set it programmatically . The DataDescriptor has a main attributes part that describes the DataDescriptor generic settings. The DataDescriptor column part contains column-level settings.

icon-maximize DataDescriptor schema
The DataDescriptor has logical connections to the physical data access layer and describes the following:

  • Physical data attributes: describes the structure of the physical data layer.
  • Data business attributes: you can specify minimal business logic here.
  • Data visualization attributes: describes how data values are visualized in the UI.

DataDescriptor main attributes

The header of the DataDescriptor XML file contains the main attributes.

Name

This attribute describes the unique (within the application) name of the DataDescriptor. The name specified here must be identical to the field name in the data class in the DataDescriptor. Use this if you want to store something in the DataDescriptor.

Data class

You have to specify the entity/POJO class, that contains the data for the DataDescriptor. You have to specify the complete name of the entity/POJO class.

Connector type

The type of Data connector that will be used by the DataDescriptor can be specified in this attribute. If it is not specified, it will use the JPA connector by default.

Currently, JBStrap supports the following types:

  • JPA
  • SQL
  • InMemory
  • ElasticSearch
  • LDAP
  • REST

You can also create your own, custom connector type.

Default filter criteria

The defaultFilterCriteria attribute is used in the DataDescriptor. Only data values that correspond to these criteria are displayed in the DataDescriptor.

Access

You can specify the access rights of the DataDescriptor in this tag. To specify an access, you can specify further tags in the tag:

  • type : The access type. It can be either Public or Private. If set to Public, the rest of these settings will be ignored, since everyone (even people who did not sign in) will be able to read and write the data.
  • read : You can specify which roles can read from the DataDescriptor. If not specified, every logged-in user has access to it. If you specify multiple roles, you must separate them by using commas. You can also use "*" as a wildcard character. For example, if you specify "a*", every role that begins with "a" will have access.
  • write : You can specify which roles can write/modify the data of the DataDescriptor. If not specified, every logged-in user has access to it. If you specify multiple roles, you must separate them by using commas. You can also use "*" as a wildcard character. For example, if you specify "a*", every role that begins with "a" will have access.

Params

You can specify DataDescriptor parameters in this tag. The framework won't use these parameters, but the program logic can access these at any time. Use this to specify your own, custom parameters, that you can later use.

Let's look at a few examples of what this looks like in practice. Our first example specifies the name, data class and connector type of the DataDescriptor.

In the below example, we set the DataDescriptor access settings to private and specify that members of the USER group can see it. Members of the ADMIN and POWER_USER groups can write to this DataDescriptor.

In the next example, we use the <defaultFilterCriteria> tag to specify the default filter criteria. Data values from the "active" column are displayed if their value equals "Y".

In this example, a few parameters will be set:

DataDescriptor column settings

Column name

The unique (within the application) name of the DataDescriptor. The name specified here must be identical to the field name in the data class in the DataDescriptor. (If this is not the case, the data from the entity won’t appear in the DataDescriptor column.) You can use this if you want to store something in the DataDescriptor that you don’t want to save to the database. If you want to do this, name the column something that does not exist in the data class. The column name must be specified.

Physical data attributes

Primary key

The "primaryKey" attribute specifies if the column has the primary key of the DataDescriptor. This attribute accepts "true" and "false" as values. This corresponds to Yes and No, respectively. The default value is "false".

Data type

The "datatype" attribute defines the DataDescriptor column type. The type specified here must adhere to the type of data in the database. Specify the attribute. The available DataDescriptor column types are the following:

  • TEXT, STRING, VARCHAR, VARCHAR2, CLOB, CHAR, or CHARACTER. If you select one of these types, textual information can be stored in the column. Values from columns of this type may be used as String values in the code. If not specified otherwise, data of this type can be edited by the user, using the TextItem editor on the interface.
  • INT, INTEGER or BIGINT. If you select one of these types, integers can be stored in the column. Columns of this type can have their values be used as Integer values in the code. If not specified otherwise, data of this type can be edited by the user, using the IntegerItem editor on the interface.
  • LONG, NUMBER or NUMERIC. If you select one of these types, numbers can be stored in the column. Columns of this type can have their values be used as Long values in the code. If not specified otherwise, data of this type can be edited by the user, using the IntegerItem editor on the interface.
  • DOUBLE or REAL. If you select one of these types, fractions can be stored in the column. Columns of this type can have their values be used as Double values in the code. If not specified otherwise, data of this type can be edited by the user, using the NumberEditor editor on the interface.
  • DATE If you select this type, dates (without hours and minutes) can be stored in the column. Columns of this type can have their values be used as Date (java.util.Date) values in the code. If not specified otherwise, data of this type can be edited by the user, using the DatePicker editor on the interface.
  • DATETIME or TIMESTAMP. If you select this type, dates (with hours, minutes) can be stored in the column. Columns of this type can have their values be used as Date (java.util.Date) values in the code. If not specified otherwise, data of this type can be edited by the user, using the DatePicker editor on the interface.
  • BOOLEAN or BOOL. If you select this type, logic values can be stored in the column. The logic value will be converted by the converter specified in the DEFAULT_BOOLEAN_CONVERTER JBStrap parameter, this ensures that the format will be usable by the database. If not specified otherwise, data of this type can be edited by the user, using the CheckBox editor on the interface.

Scale (numerical)

The "scale" attribute specifies the number of decimal digits. This attribute is only used if the column has DOUBLE or REAL values. If set, the specified amount of decimals will be used when editing or displaying the data on the UI.

Nullable (required)

The "nullable" attribute refers to a required field (it cannot be NULL). In the below example, we create a text input field capable of accepting up to 25 characters. If you display this field in an editor window, an * indicates that it is a required field. If no value has been specified, the Form component validation throws an exception. The "nullable" attribute has two possible values:

  • true: The field is not required (accepts a NULL value). This is the default setting.
  • false: The field is required (does not accept a NULL value).

Data length (string)

The "length" attribute specifies the column length. This is used if the column has textual values. If specified, the user won’t be able to type in the editor that is longer than specified here.

Data descriptor column business settings

Calculated value

The value calculation implementation can be specified in the "calculateValue" attribute. This parameter is only required if you want to create a calculated column. You must specify it, using the full name of the class that contains the implementation.

Recalculate values upon change

The recalculation implementation can be specified in the "recalcOnChange" attribute. This is used if the column is a calculated one, and its value depends on the value of a data record, which values’ changes should trigger an automatic recalculation. Multiple columns can be specified, they must be separated by a comma.

Data provider for sorting

When rendered columns are displayed, in some cases (mostly for the ListGrid), it might be necessary to sort for a column and redirect filtering to another column. The "dataProvider" attribute makes it possible to do this. If you set this attribute, column filtering (adaptive filter for the ListGrid component) and sorting will be performed in the specified column. You can specify another column name in the DataDescriptor.

Values

If the column is edited by a component that has a set of values (e.g. Combobox), and this set is static, (it is not from a DataDescriptor) it can be specified here.

You can specify these values like this:

Column parameters

The <params> tag specifies the column parameters. These could be your own parameters that the framework might not use, but the program can access and use them at any time. The parameters could be ones that were used previously as well. Multiple parameters can be applied to the column.

Data descriptor column visualization settings

Editor type

Use this attribute to specify which component the user can use to edit the DataDescriptor column. If not specified, the editor type will be decided by the column's dataType. For a detailed description of the various editor types, see the Editor types section.

Visibility settings

The "visible" attribute determines the visibility of the column. Possible values:

  • HIDDEN: The column won’t appear at all, either in the list or during editing
  • LIST: The column will only be displayed on the list interfaces, not on the editor ones. If the DataDescriptor is displayed through the list grid component, the user will be able to remove it, and then display the column again.
  • ONLY_LIST_HIDE: The column will only be displayed on the list interfaces, (as a hidden field by default) not on the editor ones. If the DataDescriptor is displayed in a list grid component, the user can place the component on the interface, if they need it.
  • HIDE_LIST: The column won’t be displayed on the list interface, but it will appear on the editor interface. If the DataDescriptor is displayed in a list grid component, the user can place the component on the interface, if they need it.
  • ONLY_EDITOR: The column will only appear on the editor interface, not on the list interface. The user won’t be able to display the column on the list interface.
  • VISIBLE: The column is visible on both interfaces.

Visibility order

The "order" attribute specifies the ordering of the column. A number must be specified here, the smaller the number, the greater the priority of the column. This applies to both the list and editor interfaces. If not specified, the order will be taken from the XML file.

Filterable

The "filterable" attribute determines if the column can be filtered. This attribute is not mandatory, if not specified, the column will be filterable. This means that if the DataDescriptor is assigned to a filter component, or is displayed with a ListGrid component (and that also has filtering enabled), the user can filter the data. If set to false, the DataDescriptor won’t be able to filter based on this column.

Column visualization parameters

You can assign column parameters by using the <params> tag. These parameters can be your own custom ones, that the framework will not use, but can be accessed any time by the program logic. It can also use previously specified parameters. A column can have multiple parameters assigned to it. To read more about these parameters, see the editor types section.

Column titles (optional)

The <title> tag specifies the title of the column. This will be in the header of the list when opened in the list interface, and it will be on the header of the editor component when using the editor interface. If not specified, the system will look for it among the message sources , in this format: dataDescriptorName.columnName. For example, if the name of the DataDescriptor is exampleDataDescriptor and the field name is exampleField, it will look for exampleDataDescriptor.exampleField among the message sources .

Filters

You can assign custom filters to the columns by using this tag. If not specified, then every filter type will use the editor parameters, that were specified previously. This tag must be specified if you want to use a different filter with the filter component. For example, you want to only select the valid states from a combobox, but you want to filter for every state. The attributes of this tag are used to specify the setting of the default filtering. This means that the specified settings here will apply to every filter type unless otherwise specified. 

The following attributes can be used in the filters tag:

  • editorType : Specifies which editor component is used when the user is specifying the filter value. This attribute accepts the same values as the editorType attribute.
  • defaultOperator : Specifies which operator is used by default when using a filter. If not specified, the column type's default operator will be used (text column - LIKE, other columns - EQUALS). The attribute can use the following values:
    • IN_SET
    • NOT_IN_SET
    • IS_NULL
    • NOT_NULL
    • EQUALS
    • NOT_EQUALS
    • LIKE : (Only usable with text columns)
    • STARTS_WITH : (Only usable with text columns)
    • ENDS_WITH : (Only usable with text columns)
    • NOT_LIKE : (Only usable with text columns)
    • NOT_STARTS_WITH : (Only usable with text columns)
    • NOT_ENDS_WITH : (Only usable with text columns)
    • GREATER_THAN
    • GREATER_OR_EQUAL
    • LESS_THAN
    • LESS_OR_EQUAL
  • wildCard : This attribute specifies which character will be used as a wildcard during the filtering. By default, this is not specified, so no wildcards are used in the filtering.

You can further specify the filter settings with the <filters> tag

  • operators : Specifies which operator will be used on the column's filter. This uses the same operators as the defaultOperator attribute.

  Setting the column filter to only use the EQUALS and NOT_EQUALS operators. The user can only select between these two. The default operator will be EQUALS:

  • params : Use this tag to specify the parameters used by the filter's editor component. You can use your own, custom ones, or the ones provided by the framework. You can specify the parameters the same way, as the column tag. It also uses the same parameters as well, only they will apply to the filter's input field. If not specified, the column's parameter(s) will be used.
  • values : Use this tag to specify a static set of values for the filter component's input field (if the component supports the use of value sets). This is specified in the same way it is specified with the column tag.
  • filter : Use this tag to specify the settings of individual filter types. This tag uses the same attributes as the < filters > tag. They function the same as well, but there is an extra tag, that must be specified if using the < filter > tag. This is the type tag, which specified the filter type, that will have the settings applied. This accepts the following values:
    • adaptiveFilter
    • simpleFilter
    • advancedFilter
    • textFilter
    • custom
  • name:  When using a custom filter type attribute, the custom filter's name attribute, which must be specified in the DataDescriptor when using a custom filter type. The custom filter, specified in the attribute, must be created in the JBStrap application, or the custom filter cannot be used.
  • filterClass:  When using a custom filter type attribute, this is the custom filter's class. This implements the filtering. If using a custom filter type, this attribute must be specified in the DataDescriptor.

This example shows a Combobox type data descriptor column's parameters. By default, the column filter only shows the active users. This means that if this combobox is placed on a form, only the active users will be within its value set. If it is applied to a filter on a listgrid, the default filter will be overwritten by the filters specified in the filters tag. This means that you can filter for inactive users as well.

DataDescriptor example

This example is a complete DataDescriptor XML file.