borland Packages Class Hierarchy dx.dataset Package
java.lang.Object +----com.borland.dx.dataset.Column
Constructors Properties Methods Event Listeners
Implements Designable, Serializable, Cloneable
The Column
component stores important column-level metadata type properties (such as
data type and precision) as well as visual properties such as font and alignment.
For QueryDataSet
and ProcedureDataSet
components, a set of Column
components is dynamically created each time the StorageDataSet
is instantiated,
mirroring the actual columns in the data source at that time.
Data-aware controls pick up Column
properties when bound to a DataSet
. After that, to
affect display, set properties of the ColumnView
or DataSetColumnView
components.
For more information on working with columns, see "Working with columns" in the Database Application Developer's Guide.
Use the column designer in the UI designer to work with Column
components easily and quickly.
You access the column designer by right-clicking any StorageDataSet
in the component tree then selecting Activate Designer. A table with six columns displays the Column
components, column names and data types of each Column
in the StorageDataSet
, however, you can remove and/or add properties to be viewed. The values in the table are editable and you can also select a Column
and view or modify its value in the Inspector.
Press the plus button (+) to add a new Column
to the StorageDataSet
. The new column is added below the selected row and defaults to a String data type. Change this and set other properties in the Inspector. The minus button (-) removes the currently selected Column
from the StorageDataSet
.
Click the check mark button to invoke a restructure of the DataSet
that is part of a DataStore
.
Column's
data type is changed and its DataSet
's store
property is set to MemoryStore
(the default), data values are not converted to the new data type. The old
values are lost. When using a DataStore
, type coercions may occur and are outlined in
Data type coercions in the
DataStore
component documentation.
The column designer also provides type-safe programmatic access to the underlying data by generating an
Exception
in cases of mismatched data. You can design the columns of a StorageDataSet
that uses either implementation of MemoryStore
or DataStore
. Similarly, the StorageDataSet
can reside within your application or a DataModule
.
For more information on the column designer, see "Working with columns" in the Database Application Developer's Guide.
A Column
may derive its values as a result of a calculated expression. Calculated
Columns
can be set using the Column Editor but are not retrieved from its data source. Instead, values for the Column
are calculated for each row of data using a formula defined in the
StorageDataSet
object's calcFields
event handler. Calculated columns are read-only;
you cannot set individual values of a row for columns that are calculated columns.
Typically, the formula for a calculated field uses expressions involving values from other
Columns
in that row to generate a value for each row of the calculated Column
. For
example, a table might have non-calculated columns for Quantity and UnitPrice, and a calculated
Column
for ExtendedPrice, which is calculated by multiplying the values of Quantity and
UnitPrice. Calculated Columns
are also useful for performing lookups in other tables.
For example, a part number can be used to retrieve a part description for display in an invoice line item.
DataExpress calculated columns are read-only, and while JBuilder automatically recognizes this and attempts to discover other non-updateable columns, some JDBC drivers seem unaware that server-side calculated columns are read-only. For this reason, you should set column properties to read-only and not resolvable. While this seems redundant, this can prove crucial to your application.
For more information and a tutorial on calculated columns, see "Using calculated columns" in the Database Application Developer's Guide.
An important Column
property is persistence. Set this property to create a persistent,
unchanging set of columns. Setting a Column
to persistent guarantees that each time your
application runs, it uses and displays the same Column
components every time and in the same
order. In the Column Editor, setting any property sets that Column
to persistent. This is
designated in the Component Tree with square brackets ([]) around the Column
name.
Programmatically, you set the persist
property.
You can define events at the Column
level, however, you must make a column persistent before you can define events on it.
A side-effect of setting a Column
as persistent is that persistent columns may not placed in the same order as they are found in the DataSet
.
When a StorageDataSet
is provided data, it:
DataSet
. Any non-persistent columns are deleted.
DataSet
, in the order they are defined in the DataSet.setColumns()
method call.
preferredOrdinal
property is set to its desired location.
For more information on column persistence, see "Specifying required data in your application" in the Database Application Developer's Guide.
For information on how column persistence can help in situations where there is a master-detail relationship and the potential for an empty master DataSet
, see "Empty master DataSet" in the About section of the MasterLinkDescriptor
class.
Another important Column
level feature is the support of constraints. Supported constraints
include:
These constraints are not enforced when data is loaded into a StorageDataSet
component since it is
assumed that the data satisfied the constraints before being stored in the SQL database. However, you
cannot leave a modified field until its value satisfies the constraints set on that Column
. This is done
automatically; you do not need special code to handle or enforce these constraints. You can extend
constraints by writing a class that implements ColumnChangeListener
or EditListener
if
you want additional validation handling.
Columns can contain various data types of data including Object
. In general, you should provide custom
ItemPainter
and ItemEditor
classes for each Java Object type. Set each Column
that contains Object data to its applicable ItemPainter
and ItemEditor
classes.
The default ItemPainter
prints the toString()
value of the object. The default
ItemEditor
treats the Object as a String. The result of an edit will therefore be an
Object of java.lang.String. If these defaults are acceptable given your Object's data, with the exception
that the edited Object should be of a different data type, set a custom formatter
for this Column.
This formatter
should be able to format the Object into a String and parse a String back into the wanted Object type.
Some columns in a DataSet
are provided, for example, by execution of a query or stored procedure. A provided column's dataType
property is set by mapping the JDBC data type (stored in the sqlType
property of the Column component) to the equivalent Variant
data type (stored in the Column's
dataType
property).
You can override the default data type mapping by setting the Column's
dataType
property. By default, the QueryProvider
and QueryResolver
used by a QueryDataSet
performs automatic type coercions between the various time and numeric data types as data is retrieved from and saved to a
JDBC-based data source. However, there are some type coercions which are not automatically handled. This includes coercions to or from String
, Object
, and InputStream
data types. In addition, the automatic coercions may not be acceptable for your application. For example, the coercion from a double to BigDecimal
may incur undesirable precision loss. An application can override the automatic type coercion by wiring the
CoerceToListener.coerceToColumn(...)
and
CoerceToListener.coerceFromColumn(...)
events. This feature allows for greater portability of an application. For example, code such as
customerDS.setDate("HIRE_DATE",...);could run on any server, even one that supports TIMESTAMP but not DATE.
For more information on Columns
, see
"Working with columns" in
the Database Application Developer's Guide.
public Column()Constructs a
Column
component with the following defaults:
Property | Value |
---|---|
visible | TriStateProperty.DEFAULT |
dataType | Variant.ASSIGNED_NULL |
searchable | true |
resolvable | TriStateProperty.DEFAULT |
editable | true |
public Column(String columnName, String caption, int dataType)Constructs a
Column
component with property values similar to those of its null constructor (Column()
) and as specified by its parameters.
columnName
String
name of the Column
. This name must be unique across all Column
components in the DataSet
.
caption
String
label used when displaying the Column
in a data-aware control. The default caption is the columnName
.
dataType
Column
will contain. Accepted values are defined in com.borland.dx.dataset.Variant
variables
public final AggDescriptor getAgg() public final void setAgg(AggDescriptor aggDescriptor)Stores the
AggDescriptor
object that defines the aggregator properties for a calculated Column
whose calcType
property is AGGREGATE
.
public final int getAlignment() public final void setAlignment(int alignment)Stores the alignment of the items in the
Column
, both horizontal and vertical. To set a new value for both horizontal and vertical alignment, separate the values with a vertical bar (|). Unless otherwise specified, alignment
defaults to center and bottom. Acceptable values for alignment
are defined in com.borland.dx.text.Alignment
variables.
public final Color getBackground() public final void setBackground(Color background)Stores the background color used by the
Column
component in UI controls. Any color object is valid. The java.awt.color
description provides class variables for some common colors.
public final int getCalcType() public final void setCalcType(int calcType)Specifies the calculation type of the
Column
. Valid values for the calculation type are
defined in com.borland.dx.dataset.CalcType
variables. Setting a column to any calculation type (other than NO_CALC
) sets this Column
to readOnly
. On error, the setCalcType()
method throws a DataSetException
.
The DataSet
must be closed in order to set this property.
public final String getCaption() public final void setCaption(String caption)Stores the
Column
object's label that displays in a data-aware control. The value of the caption need not be unique across all Column
objects of the DataSet
. The default caption is the Column
name.
public final ColumnChangeListener getColumnChangeListener()
This is the listener to use for checks on field values that should be done before a user leaves the field. One example of when this might be useful is to check that a part number is in stock before the rest of the line item information is entered. Writing a listener for a StorageDataSet
enables it to be called for all columns. See ColumnChangeListener
for more information.
public final String getColumnName() public final void setColumnName(String name)
Specifies the columnName
used to identify the column in the source table. Use this property to access the data in the DataExpress
API. All column names used in the DataSet
must be unique; these names will be changed to make them unique as necessary.
For columns provided by a data source, the columnName
property is set when the query is run.
When a query is executed again, this property is used to identify columns. If aliases are used, the
serverColumnName
property is also set.
If this property specifies a value other than the original column name on the server table, set the serverColumnName
property so that changes can be resolved back to the data source.
The DataSet
must be closed in order to set this property.
On error, the setColumnName()
method throws a DataSetException
.
setCaption()
public final ColumnPaintListener getColumnPaintListener()The
ColumnPaintListener
interface is used for notification when painting of a value in a Column
at a specific row location is occurring.
public final boolean isCurrency() public final void setCurrency(boolean currency)Stores whether the
Column
defaults to currency formatting as specified in the locale for the Column
.
This property applies only to Column
components containing numeric values. The default for this property is false, meaning that numeric data is not formatted as currency. To display values using default currency formatting, set this property to true.
An explicit displayMask
always takes precedence over the formatting specified in the locale object. Specifying a display mask with currency symbols in it will display the value with currency formatting regardless of the currency
setting.
java.util.Locale
public StorageDataSet getDataSet()Read-only property returns the
StorageDataSet
associated with this Column
component.
public final int getDataType() public final void setDataType(int dataType)Stores the data type of the
Column
. Valid values for the data type are listed under
com.borland.dx.dataset.Variant
variables,
except the BTYE_ARRAY
variable. This property is used when saving changes to the local copy of the data in the StorageDataSet
back to its original source. You typically do not change the data type of a column, however, the DataSet
must be closed in order to set this property.
The setDataType()
method can also be used to set the data type for a calculated field. It should not be called at run time when the Column
already has data in it. On error, this method throws a DataSetException
.
For more information, see Data type conflicts between a column and its data source in the About section for this component.
public final String getDefault() public final void setDefault(String defaultString)Stores the default value for this
Column
in new records as a String
.
The default value must be supplied in a locale-independent format, because the default may be coming from the server as metadata. This format is defined in the code comment for Variant's setFromString()
method. For example, a date must be in the format "yyyy-MM-dd".
If the defaultString
parameter is set to "now" and the dataType
for this
Column
is Date, Time, or Timestamp, the default will be the current time returned from
System.currentTimeMillis()
. The setDefaultValue
method can be used to set the
default as a com.borland.dx.dataset.Variant
, which can be useful for binary data types.
Default values are automatically filled in when a new row is inserted. If no other updates are made to the row, it is considered untouched and is not posted.
public final Variant getDefaultValue() public final void setDefaultValue(Variant defaultValue)Stores the default value for fields in new records as a
com.borland.dx.dataset.Variant
of the same data type as the column.
public final String getDisplayMask() public final void setDisplayMask(String displayMask)
Stores the string specification used to format the data displayed in the Column
.
This can format a Date
column to display as "MM/dd/yy" or "dd/MM/yy" for example. In
numeric columns, this is how you show commas, decimal points, and currency symbols. In
String
columns, display masks can add spaces or special characters that are not contained
in the data itself for display formatting purposes. For example, a telephone number stored as
4084311000 can be displayed as (408) 431-1000 using a display mask of "(999) 999-9999" (without
quotes). A displayMask
for a numeric column is always defined using commas for grouping and a period as a decimal separator. At run time, locale-appropriate characters are substituted.
The displayMask
is also used to parse user input if no editMask
is specified. It does not perform keystroke-by-keystroke validation (as with editMasks
), however, it converts the entire String
input back into the correct data type for the Column
. User input which cannot be parsed using
the specified display mask causes a message to be displayed. The user is kept in the edit field until the data entered is correct. You can display these validation messages by adding a
JdbStatusLabel
control
to your application, and connecting it to the same StorageDataSet
as the data
in your data-aware control. When you want tighter character
validation (for example, character by character validation), set the
editMask
property. The edit mask has the same syntax
as the displayMask
, but it is used only for user input, not for display formatting.
There is no default display mask specification, however, explicitly setting this property to
null or to an empty string causes JBuilder to choose a display mask specification.
If the data type of the column has international (localization) implications, the locale file for
the Column
is accessed for default display settings, for example, date and currency symbol.
Otherwise, the formatter
is bypassed and a basic display mask is used.
Because default display masks are locale-sensitive and built as needed, they are automatically
localized. User-defined display masks are not altered if the column's locale
changes.
Display masks and edit masks are never substituted if one is supplied and the other not. However, the display mask does perform validation of user input even if no edit mask is specified.
The displayMask
property is an easy way to generate an instance of a formatter
object which manages how the data is displayed. If you find that the displayMask
does not
handle your formatting needs, you can create your own class which implements the
ItemFormatStr
interface and assign
it into the Column
component's formatter
property
directly. In such cases, do not assign the displayMask
property as your formatter will be
overwritten.
To reset an edit mask back to its default, call the setEditMask()
method. In the Designer, right-click the property in the Inspector and select Clear Property Setting.
DataSet
and if incomplete, the cursor
is positioned at the offending index. If a StatusBar
or JdbStatusLabel
control has its dataSet
property set to the same DataSet
and the error generated is a ValidationException
,
the error displays on the StatusBar
or JdbStatusLabel
. Otherwise, an error dialog displays with the error. To
prevent this dialog from appearing, customize the DataSetException
error handler to trap for
the exception.
For examples of patterns used with display masks, see "Adding an edit or display pattern for data formatting" in the Database Application Developer's Guide.
editMask
,
exportDisplayMask
, String-based patterns (masks)
public final boolean isEditable() public final void setEditable(boolean editable)Stores whether a
Column
is editable or not through a data-aware control. Programmatic edits
to the Column
are not affected by this property. If false (the default) a
Column
can be modified. To prevent a Column
from being modified, set this property
to true. To prevent edits to the Column
data programmatically or through
data-aware controls, set the readOnly
property.
The setEditable()
method throws a DataSetException
when called on a
Column
of an open DataSet
.
public final String getEditMask() public void setEditMask(String editMask)
Stores the string specification used to format and control the entry of data in the column when the
user starts editing data. Before editing starts, the displayMask
handles the formatting and
parsing. Edit masks affect the formatting of data by displaying spaces or special characters that ease
data entry. For String
columns, these characters may optionally be stored with the data or not. For example, displaying parenthesis for a telephone number can ease data entry by clearly separating the area code from the telephone number. An editMask
for a numeric column is always defined using commas for grouping and a period as a decimal separator. At run time, locale-appropriate characters are substituted.
Edit masks also restrict the type of data the user can enter, for example, by allowing digits only, or requiring entry in certain parts of a field, and so on.
User-defined edit masks are not altered if the column's locale
changes.
When entering data into a edit mask and using the left shift feature where characters are entered from the right end of the pattern specification and shift left, if any character input cannot shift left, shifting stops. If you continue to type when you are positioned at the right of the pattern, the last character is overwritten with each key pressed.
Edit and display masks are never substituted one for the other if one is supplied and the other not. However, if an edit mask is not specified, the display mask performs validation of user input.
If you find that the editMask
does not handle your formatting needs, you can create
your own class which implements the
ItemEditMask
interface and assign
it into the Column
component's editMasker
property directly. In such cases, do not
assign the editMask
property as your editMasker
will be overwritten.
To reset a display mask back to its default, call the
setDisplayMask()
method.
For examples of patterns used with display masks, see "Adding an edit or display pattern for data formatting" in the Database Application Developer's Guide.
displayMask
property, String-based patterns (masks)
public final ItemEditMask getEditMasker() public void setEditMasker(ItemEditMask editMasker)The
ItemEditMask
implementation that
provides the keystroke by keystroke validation of the data in the Column
.
In most cases, the editMask
property is used to provide
formatting rules when data in the Column
is being entered or edited. From the
editMask
, an editMasker
object is created that manages the validation of the data
entry or data editing.
If you want custom rules beyond those provided by the com.borland
classes, create your own class that
implements ItemEditMask
and set
this property to your custom class. Do not set the editMask
property in addition to the
editMasker
property as the editMasker
will be overridden.
public final String getExportDisplayMask() public final void setExportDisplayMask(String exportDisplayMask)The string display mask specification that is used when importing and exporting data to a text file.
When exporting, a schema
file (.SCHEMA file extension) is created that
contains information about the data being exported so that it can be easily read back into a
TableDataSet
component. This mask is also written into the schema file. The
exportDisplayMask
value in the schema file always takes precedence -- you cannot override
this value by setting a new exportDisplayMask
. A displayMask
for a numeric column is always defined using commas for grouping and a period as a decimal separator. At run time, locale-appropriate characters are substituted.
Data can be imported in two ways: with a valid schema file, or by specifying column names and data types. When data is exported, a schema file is created to define the data. When importing data that has been previously exported by JBuilder, assuming that the schema file was created, the exportDisplayMask
information contained in the file is used to import the data. If the schema file doesn't exist (meaning that the data has not yet been exported by JBuilder), the setting for this property is used to import the data. If there is no schema file and the exportDisplayMask
property is not set, and the data type of the
column has international (localization) implications, the locale file for the Column
is accessed for default display settings, for example, date and currency symbol. Otherwise, the export
formatter is bypassed and a basic export mask is used.
The exportDisplayMask
specification is used to create an instance of an exportFormatter
(a VariantFormatter
) class
object that controls the formatting of the exported data. If you want custom rules beyond those
provided by the com.borland
classes, create your own class that implements ItemFormatStr
and set the
exportFormatter
property to your custom class. In this case, do not set the
exportDisplayMask
as it will overwrite the exportFormattter
property.
To reset an export display mask back to its default, call
the setExportDisplayMask()
method.
For examples of patterns used with export display masks, see "Adding an edit or display pattern for data formatting" in the Database Application Developer's Guide.
displayMask
property,
"String-based patterns (masks)"
public final VariantFormatter getExportFormatter() public final void setExportFormatter(VariantFormatter exportFormatter)The
VariantFormatter
implementation
that provides formatting rules when exporting data in the Column
. The implementation is
specific to the data type of the Column
, for example,
BigDecimalFormatter
.
In most cases, the exportDisplayMask
property is
used to provide formatting rules when exporting the data in a Column
. From the
exportDisplayMask
, an exportFormatter
object is created that manages what the
data looks like when it is exported.
If you want custom formatting rules beyond those provided by the com.borland
classes, create a custom class that
extends ItemFormatStr
and set this
property to an instance of that class. Do not set the exportDisplayMask
property in addition
to the exportFormatter
property as the exportFormatter
will be overridden.
public boolean isFixedPrecision() public void setFixedPrecision(boolean fixedPrecision)Stores whether the precision of decimal point values is fixed (true) or not (false).
public final Font getFont() public final void setFont(Font font)Stores the font used to display the
Column
in a data-aware control.
public final Color getForeground() public final void setForeground(Color foreground)Stores the foreground color of the
Column
when displayed in a data-aware control. Any color object is valid. The java.awt.color provides class variables for some common colors.
public final VariantFormatter getFormatter() public final void setFormatter(VariantFormatter formatter)The
VariantFormatter
implementation that provides formatting rules when displaying data in the Column
. The
implementation is specific to the data type of the Column
, for example,
BigDecimalFormatter
.
In most cases, the displayMask
property is used to
provide formatting rules for a Column
. From the displayMask
, a formatter
object is created that manages the display of the data.
If you want more custom display rules than are provided by the com.borland
classes, create a custom class
that extends the VariantFormatter
(or one of its subclasses) and set this property to an instance of that class. Do not set a
displayMask
in addition to the formatter
property as the formatter
will be overridden.
public final int getHash()Read-only property that returns the hash table associated with this
Column
component.
public final boolean isHidden() public final void setHidden(boolean hidden)This method is used internally by other
com.borland
classes. Do not use this method directly.
public final Object getItemEditor() public final void setItemEditor(Object itemEditor)Sets an optional Swing
CellEditor
for use by a visual component bound to the Column
when editing.
For dbSwing components, itemEditor
will be used if its type matches
the type of editor used by the component. For example, if itemEditor
is of type TableCellEditor
, then it will be used when editing the Column
's data in a JdbTable
. Note that it is possible to use the same itemEditor
with different types of Swing components simultaneously by making the itemEditor
implement multiple CellEditor
interfaces.
(For JBCL components, itemEditor
will be used by controls that support ViewManager
properties, for example, the FieldControl
, ListControl
, and GridControl
. The ItemEditor
for this Column
is passed a
ColumnVariant
as the "data" object. The ColumnVariant
class extends
the Variant
class with the getColumn()
and getDataSet()
methods. These can be used to provide more context about the Column
, for example, its pickListDescriptor
and dataSet
properties.)
public final Object getItemPainter() public final void setItemPainter(Object itemPainter)Sets an optional Swing
CellRenderer
or JBCL ItemPainter
for use by a
visual component bound to the Column
when painting.
For dbSwing components, itemPainter
will be used if its type matches the type of renderer used by the component. For example, if itemPainter
is of type TableCellRenderer
, then it will be used when rendering the Column
's data in a JdbTable
. Note that it is possible to use the same itemPainter
with different types of Swing components simultaneously by making the itemPainter
implement multiple CellRenderer
interfaces.
(For JBCL components, itemPainter
will be used by controls that support ViewManager
properties, for example, the FieldControl
, ListControl
, and GridControl
. The itemPainter
for this Column
is passed a ColumnVariant
as the "data" object. The ColumnVariant
class extends
the Variant
class with the getColumn()
and getDataSet()
methods. These can be used to provide more context about the Column
, for example, its pickListDescriptor
and dataSet
properties.)
public final String getJavaClass() public final void setJavaClass(String className)Sets the
javaClass
.
public final Locale getLocale() public final void setLocale(Locale locale)Stores the
Locale
object to use for formatting a Column
. Locale contains
country or area-specific formatting specifications such as date format (MM/DD/YY, DD/MM/YY,
YY/MM/DD), currency symbol, and so on.
Set this property in code or through the Inspector. In the Inspector, select a locale
from the drop-down list of locales, or to
"<default>". Pressing the Delete key when editing this value removes any generated
code that sets the locale
property. This has the effect of resetting the locale
to the DataSet
component's locale.
If this property is not specified at the Column
level, it defaults to the
DataSet
component's locale
, if specified. Otherwise it defaults to
the locale
of the Java environment.
public final String getMax() public final void setMax(String maxString)Specifies the maximum allowable value (inclusive) in this
Column
as a String
.
The setMax()
method throws a DataSetException
if called on
a Column
of an open DataSet
.
The maximum value must be supplied in a locale-independent format, because the maximum may be coming from the server as metadata. This format is defined in the code comment for Variant's setFromString()
method. For example, a date must be in the format "yyyy-MM-dd".
public final int getMaxInline() public final void setMaxInline(int maxInline)
This property can be used on columns of a StorageDataSet
that have their store
property set to a DataStore
. This property is ignored by columns of a StorageDataSet
that has its store
property set to null or MemoryStore
.
This property specifies the maximal "inline" length, in bytes, for Strings and InputStreams. If a Column
value is stored with a length that exceeds this setting, it is stored as a BLOb, which is a little less efficient. To improve performance, set maxInline
to a higher value. Note that setting maxInline
to a higher value limits the maximum number of fields that can be stored in a row.
public final Variant getMaxValue() public final void setMaxValue(Variant maxValue)Specifies the maximum value allowable (inclusive) in this
Column
as a Variant
.
The setMaxValue()
method throws a DataSetException
if called on
a Column
of an open DataSet
.
public final String getMin() public final void setMin(String minString)Specifies the minimum allowable value (inclusive) in this
Column
.
The setMin()
method throws a DataSetException
if called on
a Column
of an open DataSet
.
The minimum value must be supplied in a locale-independent format, because the minimum may be coming from the server as metadata. This format is defined in the code comment for Variant's setFromString()
method. For example, a date must be in the format "yyyy-MM-dd".
public final Variant getMinValue() public final void setMinValue(Variant minValue)Stores the minimum value allowable (inclusive) in this
Column
as a Variant
.
The setMinValue()
method throws a DataSetException
if called on
a Column
of an open DataSet
.
public int getOrdinal()Read-only property that specifies the ordinal position of the
Column
component within the DataSet
.
public int getParameterType() public void setParameterType(int parameterType)Specifies the type of parameter in a
ParameterRow
. For valid values for this property, see
ParameterType
variables.
public final boolean isPersist() public final void setPersist(boolean persist)Stores whether the
Column
is persisted in a DataSet
when the application is run.
Any column for which a property has been explicitly set in the JBuilder Component
Inspector is automatically set (internally) to persistent. This is indicated with square brackets ([]) around the Column
component's name in the Component Tree.
By default, the columns that display in a data-aware control are determined at run-time based on
the Columns
that appear in the DataSet
. If your application depends on particular
columns displaying in the control, set this property programmatically to true before the data is provided.
If the source column of the persistent column changes or is deleted, the column is left empty. No
Exception
is thrown.
Calling StorageDataSet.setColumns(...)
sets the persist
property to true for all columns passed in.
For information on how column persistence can help when a master-detail relationship might have an empty master DataSet
, see "Empty master DataSet" in the About section of the MasterLinkDescriptor
class.
public final PickListDescriptor getPickList() public final void setPickList(PickListDescriptor pickList)Specifies the
PickListDescriptor
for the Column
which describes the relationship between the Column
and a second, separate "pick list" or "lookup" DataSet
.
The DataSet
must be closed in order to set this property.
The dbSwing JdbComboBox
and JdbTable
components will display pick list data when bound to a Column
with its pickList
property set.
The JBCL GridControl
, ListControl
, and FieldControl
controls can also
display pick list data but are limited to displaying only the first
display column defined by the PickListDescriptor
.
For more information on pick lists, see the PickListDescriptor
class.
For an example of how to use the PickListDescriptor
in your application, see
"Looking up choices with a pick list"
in the Database Application Developer's Guide.
public final int getPrecision() public final void setPrecision(int precision)Stores the precision used for the
Column
in data-aware controls.
For a String
column, precision represents the maximum length of a value.
public int getPreferredOrdinal() public void setPreferredOrdinal(int preferredOrdinal)Stores the preferred ordinal position of the
Column
in the DataSet
.
Normally, Columns that are defined in your application that are not provided by the query or procedure will appear before columns that are provided. Set this property to any value greater than or equal to zero to move this Column
to that position in the DataSet
.
The first column ordinal is zero. You can set more than one column to the same ordinal value, however, the
results may not be predictable. Columns whose preferredOrdinal
is not set retain their position relative to each other.
This property defaults to -1 meaning that there is no preferred position for this Column
.
The DataSet
must be closed in order to set this property.
public final boolean isReadOnly() public final void setReadOnly(boolean readOnly)Stores whether the
Column
is writable or read-only. Setting readOnly
to
true disables modification of the data in the Column
(both programmatically
and through a UI control) and prevents the user from navigating to the Column
. Setting
readOnly
to false allows both modification of the data and navigation to the
Column
. To restrict data editing from a data-aware control only (but allow data
editing programmatically), set the editable
property of the Column
.
This property is automatically set to true when you set the
calcType
of this Column
to any value other than
NO_CALC
.
A DataSetException
is thrown if the setReadOnly()
method is called on
a Column
of an open DataSet
.
public final boolean isRequired() public final void setRequired(boolean required)Specifies whether values in the
Column
may be left blank at the time of posting
the row of data to the DataSet
. A DataSetException
is thrown if the
setRequired()
method is called on a Column
of an open DataSet
.
public boolean isResolvable() public void setResolvable(boolean resolvable)
Specifies whether the Column
is included when resolving changes back to it data
source. By default, all non-calculated columns are set to true. If set to
false, this Column
will not be saved back to its data source during
the resolution. This property is useful when saving a DataSet
back to a SQL server
when the DataSet
has calculated or aggregation columns that should not be included
in the resolution.
public final boolean isRowId() public final void setRowId(boolean rowId)Specifies whether the
Column
contains data that uniquely identifies the row. A unique row
identifier (also known as a unique rowID
) is necessary to save changes to the data in the
DataSet
back to its data source.
Several columns may have their rowId
property set to true. This
indicates that the values in these columns together uniquely identify a row.
setRowId(...)
method does not reset the edit blocked state of the StorageDataSet
. Also, if a DataSet
has been flagged as not updateable because it has no row IDs, this flag will be removed when you define row IDs.
For more information on metadata, see "Column properties and metadata" in the Database Application Developer's Guide.
public final int getScale() public final void setScale(int scale)Specifies the number of digits to the right of the decimal point for BIGDECIMAL values. This property is used by data-aware controls when displaying values in the
Column
.
You should set this property when working with BIGDECIMAL values. Otherwise, you get far more decimal places than most applications need.
public final String getSchemaName() public final void setSchemaName(String schemaName)Specifies the schema name of the table that the
Column
belongs to. Used mostly with QueryDataSets
to flag the table that a Column
belongs to.
This property may be left null.
public boolean isSearchable() public void setSearchable(boolean searchable)Specifies whether a
Column
is searchable (true) or not
(false). Not all servers allow search operations on all data types,
for example, binary data is commonly not searchable. JBuilder attempts to read this
information from the server metadata whenever possible.
Columns
that are not searchable are not used in the comparisons
of an update query, even when the updateMode
property is set to ALL_COLUMNS
.
public final String getServerColumnName() public final void setServerColumnName(String serverColumnName)Specifies the column name used by the
QueryResolver
when generating resolution queries.
This property should correspond to a name of a physical column in the table of the database.
This name is used to save back changes to the table on the server. If null, the columnName
property is used instead.
public final int getSortPrecision() public final void setSortPrecision(int sortPrecision)Stores the precision of the data in this Column. This property is used only for non english locales that use Collation keys for sorting.
public final int getSqlType() public void setSqlType(int sqlType)Stores the type of JDBC
SqlType
of the Column
. Accepted values for
SqlType
are defined in
java.sql.Types
.
public final String getTableName() public final void setTableName(String tableName)Stores the
String
table name that the Column
belongs to. This property is used by the QueryDataSet
component to identify the table a Column
belongs to. For all StorageDataSet
objects, the table name is the same for all Column
components (unless the Column
components were instantiated as a result of a SQL JOIN statement), or null.
public final boolean isTextual()Stores whether the
Column
contains data that can be represented by a String
. For example, numeric, date, and string data return true. Data stored as binary data return false.
public final int getVisible() public final void setVisible(int visible)Specifies whether the
Column
is visible or hidden. If not set, default logic is used to
determine whether to display the Column
. For example, the linking column(s) of the detail
DataSet
in a master-detail relationship are hidden by default.
Accepted values for visible
are listed in
com.borland.jb.util.TriStateProperty
.
public int getWidth() public void setWidth(int width)The number of characters requested to display in a control for the given
Column
. The number of characters that can be entered into the column is not restricted by this property, only the display. This property is used in data-aware controls when displaying the Column
.
For information on setting the width of a Column
component's data (for example, the width of a String
column), see the precision
property.
public Object clone()Clones the
Column
and returns it in Object
.
public Column copy()Creates and returns a complete copy of the
Column
, without unbinding the
StorageDataSet
.
public final String format(Variant value)Uses the
formatter
property to produce a String
representation of the
Variant
. If there is no formatter for this Column
, value.toString()
is
returned.
value
Variant
value to return formatted as a String
.
public final void getDefault(Variant value)Returns the default value set for the
Column
.
public boolean hasValidations()Read-only property that returns whether the
Column
has specified validation criteria in the
form of:
String
column, precision greater than 0
ColumnChangeListener
public final void setDisplayMask()Sets the
Column
to its default formatter
. This is different from calling
setDisplayMask(null)
, which explicitly asks to select a preferred formatter
based
on locale
.
public final void setEditMask()Sets the
Column
to its default editMasker
. This is different from calling
setEditMask(null)
, which explicitly asks to select a preferred editMasker
based on
locale
.
public final void setExportDisplayMask()Sets the
Column
to its default formatter for import/export. This is different from
setExportDisplayMask(null)
, which explicitly asks to select a preferred formatter based on
locale
.
public String toString()Returns the
String
representation of the Column
.
public void validate(DataSet editDataSet, Variant value)Validates the specified
value
against the Column
component's validation criteria
(minimum value, maximum value, and so on).
On error, this method throws a ValidationException
or DataSetException
as
applicable.
public void addCoerceFromListener(CoerceFromListener listener) public synchronized void removeCoerceFromListener(CoerceFromListener listener)
public void addCoerceToListener(CoerceToListener listener) public synchronized void removeCoerceToListener(CoerceToListener listener)
public void addColumnChangeListener(ColumnChangeListener listener) public synchronized void removeColumnChangeListener(ColumnChangeListener listener)
public void addColumnPaintListener(ColumnPaintListener listener) public synchronized void removeColumnPaintListener(ColumnPaintListener listener)