Concepts - Type Converters
Preface
LLBLGen Pro creates the entity definitions and entity field definitions from the table / view definitions available. This is a very productive technique
to get a lot of entities defined in a very short time. The resulting entity and its fields are often meeting the user's requirements, but sometimes
names have to be altered, and also .NET types of the entity fields are not the ones the user expected. For name construction, LLBLGen Pro offers
patterns which produce names for, for example, fields, but what about the .NET types?
By default, LLBLGen Pro uses the used database driver to produce a .NET type for a field based on the database type definition of the target field (table/view
field). This .NET type is equal to the .NET type of the value returned by the datareader of the .NET provider for that database. For example take a field
in Oracle with database type NUMBER(6,0). A given row's value for that field will be returned as a System.Int32 typed value. Would the type have been
NUMBER(4,0), the type of the value would have been System.Int16. So an entity or typed view field mapped onto a table/view field with type NUMBER(6,0) will
get the .NET type for that database type, which in this case is System.Int32.
The problem with this system is that it doesn't allow the user to specify a
different .NET type for a field. Take the same Oracle database for example.
Oracle doesn't have a boolean type (most databases don't have a boolean type). This is often solved by using a NUMBER(1,0) (single digit numeric value) type,
however the entity field or typed view field will get the type System.Int16, not System.Boolean. The LLBLGen Pro designer didn't let the user define a different
type, because that would require a conversion between the .NET type reported back by the datareader (in this case System.Int16) and the actual type of the
field (System.Boolean), and vice versa: in filters and when the entity is saved, the boolean value has to be converted to a numeric value to be usable in the
database system.
This is solved by specifying a
type converter for a field. A type converter is a class which can convert from a set of .NET types to a given .NET type
(can be any .NET type) and convert from that .NET type to a given set of .NET types. The type converter is defined on the field and works under the hood,
the .NET type of the field holding the type converter becomes the same as the core .NET type of the type converter and everything else is taken care of by
LLBLGen Pro: the .NET type provided by the ADO.NET provider used is converted to the new .NET type of the field by the set type converter and vice versa.
Using a type converter
Lets look at our example again, the absense of a boolean type in some databases. LLBLGen Pro v2.0 comes with a type converter which converts from
a non-fractional numeric type (byte/sbyte/int16/uint16/int32/uint32/int64/uint64), the 'From' type, to boolean, the 'Core' type, and vice versa.
All entity fields which have originally a .NET type which is one of the 'From' types can have this type converter set as their type converter. When a field
of such a From type is set to have this particular type converter, its .NET type changes to the 'Core' type of the type converter, in this case System.Boolean.
Generating the project will result in an entity which now has System.Boolean as type for the entity field in question. This allows the user to set the field
to 'true' or 'false', instead of 0 or 1. Also filters created for this field work with 'true' or 'false', not with 1 or 0.
Under the hood
Every field has
persistence info, which is in fact the mapping information of the field, on which database field it's mapped, what the characterstics
are of the database field etc. etc. This persistence info also contains an
instance of the set type converter (if the field has one set, otherwise it's
null/Nothing). When an entity's data is read from the database, a field which is about to get a value from the data read is checked if it has a
type converter instance set. If that's the case, the type converter is asked to convert the value from the read data and the conversion result is stored
in the entity field. If no type converter is set, no conversion takes place. The other way around is the same: if an entity is saved, right before the
field's value is stored inside a parameter to be used in an INSERT or UPDATE statement, a set type converter is asked to convert the value back, to the
original .NET Type of the field, in our example to Int16. For filters, this mechanism is also followed.
This is completely transparent and very efficient: the application developer has no notice of the usage of the type converter.
All .NET types supported
The usage of a type converter doesn't stop with converting integers into booleans and vice versa. You can use it to write a converter for any .NET type.
For example you can write a type converter to convert a string, which contains an XML document in text, to an XmlDocument and vice versa. Or a type converter
which converts a byte array into a JPEG image and vice versa. This is then done under the hood, transparently.
To write your own type converter, please consult the SDK documentation for further details and the sourcecode of the type converters shipped with LLBLGen Pro,
which is also enclosed in the SDK package.
Type converter structure
Type converters are used in both the LLBLGen Pro designer and at runtime by the generated code. It is therefore essential the class is based on a type which is
known by both the designer and the runtime libraries, as the type converter is used by the designer
and by the generated code and runtime libraries at runtime.
To avoid having to reference runtime libraries in the designer and designer assemblies in the runtime libraries, a type known to both systems was important.
This is why a type converter is a derived class of System.ComponentModel.TypeConverter, a class
of the .NET framework. LLBLGen Pro at startup probes any assembly in the TypeConverters folder in the LLBLGen Pro installation folder for types derived from
System.ComponentModel.TypeConverter. All these types are seen as type converters and stored in the designer internals and are enlisted in the
entity editor and typed view editor when a field is selected.
Type conversion definitions
In a large project, setting a lot of fields to a given type converter can be a cumbersome task. Also, when a catalog is refreshed or when a new entity
is added, you probably want type converters to be set to given fields automatically. For this LLBLGen Pro defines
type conversion definitions.
Type conversion definitions specify filters which can be used to set a type converter to a large group of fields at once. Per project you can
define type conversion definitions, as much as you want. Each type conversion definition works on a given real .NET type, which is selected from the list
of .NET types produced by the used database driver. Based on that .NET type, LLBLGen Pro offers you the list of known type converters which accept that
type as a From type. You can then fine-tune your filter on database type, precision, scale and length, all are optional.
The
preferences of LLBLGen Pro offer you to specify if a type converter should be assigned automatically
to a new field, using the "AutoAssignTypeConverterToNewField" setting (inherited by a new project, so on an existing project, set the property there as well).
When this setting is set to true, LLBLGen Pro will for each new field (for example created by the refresher or when a new entity is added) try to find
a type conversion definition matching the field's .NET type and database type definition. The match with the most matching elements is selected and the
type converter defined in that type conversion definition is set as the type converter for that new field.
LLBLGen Pro also offers a plug-in to quickly set type converters on a set of entities / typed views, using the type conversion definitions defined in the
project.
You can define / edit the type conversion definitions of a project by selecting 'Edit Type Conversion Definitions...' in the context menu of the project node
in the project explorer or from the Project menu of the LLBLGen Pro designer. For more information about defining type conversion definitions, please
see
Defining type conversion definitions in the designer section of this manual.
Note: