Automatic Data Validation: Difference between revisions

From OpenPetra Wiki
Jump to navigation Jump to search
 
(11 intermediate revisions by the same user not shown)
Line 1: Line 1:
==DOCUMENTATION IS WORK IN PROGRESS==
==Introduction==
'''This wiki page is ''under construction''. Information contained on it should not be relied on until this message is no longer present!!!'''
'''The term 'Automatic Data Validation' relates to Data Validation code that is automatically generated by the OpenPetra ORM Generator and the OpenPetra WinForms Generator.'''


==Introduction==
The ORM Generator for Cacheable DataTables creates program code...
'''The term 'Automatic Data Validation' relates to Data Validation code that is automatically generated by the OpenPetra WinForms Generator.'''
* in Shared DLL's
** auto-generated data validation methods (get placed in separate *-generated.cs-files [e.g. 'Common.Validation-generated.cs']).
* in Server DLL's
** in the generated C# files for Cacheable DataTables
*** these are calls to auto-generated data validation methods which are found in Shared DLL's


The WinForms Generator automatically creates program code...
The WinForms Generator automatically creates program code...
* in Client DLL's (in the generated C# files of Forms/UserControls),
* in Client DLL's  
* in Shared DLL's and
** in the generated C# files of Forms/UserControls
* in Server DLL's
*** these are calls to auto-generated data validation methods which are found in Shared DLL's
...for the automatic data validation of Controls ''which are bound to certain DataColumns of OpenPetra DB Tables''.


==Scope==
==Scope==
''Automatic Data Validation code is generated only for DB Tables that are specified in the petra.xml file!''
''Automatic Data Validation code is generated only for DB Tables that are specified in the petra.xml file!''


DataColumns in the petra.xml file for which automatic data validation code is generated:
* Generated code in Shared DLL's and in Server DLL's is for the automatic data validation of all DataColumns of all OpenPetra DB Tables (as specified in petra.xml).
* Generated code in Client DLL's is solely for the automatic data validation of Controls ''which are bound to DataColumns of OpenPetra DB Tables that are found on the individual Forms/UserControls''.
 
 
DataColumns in the petra.xml file for which automatic data validation code is generated (see Method 'GenerateAutoValidationCodeForDBTableField' in file \csharp\ICT\BuildTools\CodeGeneration\Validation.cs for details):
* DataColumns which are part of a ''Primary Key'' or are part of a ''Unique Key''
* DataColumns which are part of a ''Primary Key'' or are part of a ''Unique Key''
** Data Validation code enforces that NULL must never be assigned to those DataColumns.
** Data Validation code enforces that NULL must never be assigned to those DataColumns.
* DataColumns with a ''NOT NULL'' restriction (applies to any DataColumn that isn't part of a Primary Key or Unique Key)
* DataColumns with a ''NOT NULL'' restriction (applies to any DataColumn that isn't part of a Primary Key or Unique Key)
** Data Validation code enforces that NULL must never be assigned to such a DataColumn.
** Data Validation code enforces that NULL must never be assigned to such a DataColumn.
* DataColumns of ''varchar/string'' Type
* DataColumns of ''varchar'' Type (<code>string</code> Type in C#)
** Data Validation code enforces that the length of the String is not exceeded.
** Data Validation code enforces that the length of the String is not exceeded.
* DataColumns of a ''numeric'' Type
* DataColumns of ''number'' Type (<code>decimal</code> Type in C#)
** Data Validation code enforces that the numeric range of the Type (e.g. Int16, Int32, Decimal) and it's precision (if applicable) is not exceeded.
** Data Validation code enforces that the number precision is within the range that is specified.
 
*** A Validation Error is raised if the total count of significant digits in the whole number, that is, the number of digits to ''both sides'' of the decimal point, is exceeded.
Multiple automatic data validations may be generated for a single DataColumn to enforce multiple rules! Example: Automatic data validation code that will be created for a varchar/string column which is part of a Unique Key: 1) code for a NOT NULL check, 2) code for a string length check.
*** A Validation Warning is raised if the number of digits after the decimal point is larger than specified (rounding will occur in the DB in this case and so the user knows about it).
*** Example: petra.xml specifies "lenght=6", "decimals=2" for a certain DataColumn. The check results in...
**** an Error if the user enters more than 4 digits to the left of the decimal point (6-2=4);
**** a Warning if the user enters more than 2 digits to the right of the decimal point.
* DataColumns of ''date'' Type (<code>DateTime</code> Type in C#)


Multiple automatic data validations may be generated for a single DataColumn to enforce multiple rules! Example: Automatic data validation code that will be created for a varchar column which is part of a Unique Key (or Primary Key): 1) code for a NOT NULL check [because the column is part of a Key], 2) code for a string length check.


==Placement of Automatic Data Validation Code==
==Placement of Automatic Data Validation Code==
===Client DLL's===
===Client DLL's===
Calls to automatic data validation code contained in Shared DLL's will ''automatically'' be placed in all the appropriate places of a generated C# file of a Form/UserControl. The only requirement for this to happen is that the YAML file that specifies the Form/UserControl contains data bound Controls. '''<code>''Validation=true''</code> does not need to be set on Controls for that to happen''' - this must only be done to indicate to the WinForms Generator that ''manual'' data validation code needs to be called for a DataColumn that is bound to that Control!
Calls to automatic data validation code contained in Shared DLL's are ''automatically'' be placed in all the appropriate places of a generated C# file of a Form/UserControl. The only requirement for this to happen is that the YAML file that specifies the Form/UserControl contains data bound Controls. '''<code>''Validation=true''</code> does not need to be set on Controls for that to happen''' - this must only be done to indicate to the WinForms Generator that ''manual'' data validation code needs to be called for a DataColumn that is bound to that Control!
 
The hook-ups for all automatically and manually validated Controls can be found in the 'BuildValidationControlsDict()' Method of a Form/UserControl. Automatic ones have a comment '// Automatic Data Validation ...' next to them.
Calls to the automatic data validation code always precede calls to the manual data validation code (if manual data validation code is present at all in a Form/UserControl). This allows manual data validation code to modify the TVerificationResult objects that the automatic data validation code may create, should that be necessary (e.g. to modify the standard texts that are presented to the user for).


Calls to the automatic data validation code always precede calls to the manual data validation code (if manual data validation code is present at all in a Form/UserControl). This allows manual data validation code to modify the TVerificationResult objects that the automatic data validation code may create, should that be necessary (e.g. to modify the standard texts that are presented to the user).


===Shared DLL's===
===Shared DLL's===
The automatically generated code in the *.ManualCode.cs file of the Form/UserControl that calls the automatic data validation calls a Method in a shared DLL to do this.  
The automatically generated code in the *.ManualCode.cs file of the Form/UserControl and the automatically generated code in the C# files for Cacheable DataTables on the server side call automatically generated data validation Methods in the shared DLL's.  


That called Method performs the actual Data Validation:
That called Method performs the actual Data Validation:
* If a Data Validation occurs, a TVerificationResult object is created
* If a Data Validation Error or Warning is identified, a TVerificationResult object is created for it
** the TVerificationResult object gets appended to a Collection that is held in the Form where the Data Validation is run.
** the TVerificationResult object gets appended to a TVerificationResultCollection
* Once a Data Validation error got rectified by the user, the corresponding TVerificationResult object is removed from the Collection.
*** In case the Method is called from the client side that Collection is held in the Form where the Data Validation is run.
**** Once a Data Validation Error/Warning got rectified by the user, the corresponding TVerificationResult object is removed from the Collection through this Method, too.
*** In case the Method is called from the server side that Collection is held in the Method that calls the Data Validation.


More details about the code in Shared DLL's can be found [[Instructions for the Implementation of Data_Validation#The_Data_Validation_Method|here]]. - Though that section relates to manually written code, the same applies for the automatically generated code, with the exception of the Method names, which are ''<code>ValidateData</code> / <code>ValidateDataDetails</code>'' instead of <code>ValidateDataManual</code> / <code>ValidateDataDetailsManual</code>, respectively.
More details about the code in Shared DLL's can be found [[Instructions for the Implementation of Data_Validation#The_Data_Validation_Method|here]]. - Though that section relates to manually written code, the same applies for the automatically generated code, with the exception of the Method names, which are ''<code>ValidateData</code> / <code>ValidateDataDetails</code>'' instead of <code>ValidateDataManual</code> / <code>ValidateDataDetailsManual</code>, respectively.


Regarding the placement of the automatically data validation code in the various C# files and Shared DLL's please refer to [[Instructions for the Implementation of Data_Validation#Choosing_the_right_Shared_DLL_for_the_Data_Validation_Methods|this]] section, which again relates to manually written code, but the same applies for the automatically generated code.
Regarding the placement of the automatically data validation code in the various C# files in the Shared DLL's please refer to [[Instructions for the Implementation of Data_Validation#Choosing_the_right_Shared_DLL_for_the_Data_Validation_Methods|this]] section, which again relates to manually written code, but the same applies for the automatically generated code.


===Server DLL's===
===Server DLL's===
'''TODO'''
Calls to automatic data validation code contained in Shared DLL's are ''automatically'' placed in all the appropriate places of all the generated C# files for OpenPetra's Cacheable DataTables.
 
Calls to the automatic data validation code always precede calls to the manual data validation code (if manual data validation code is present at all in the Class that contains Cacheable DataTables). This allows manual data validation code to modify the TVerificationResult objects that the automatic data validation code may create, should that be necessary (e.g. to modify the standard texts that are presented to the user).

Latest revision as of 12:57, 27 September 2018

Introduction

The term 'Automatic Data Validation' relates to Data Validation code that is automatically generated by the OpenPetra ORM Generator and the OpenPetra WinForms Generator.

The ORM Generator for Cacheable DataTables creates program code...

  • in Shared DLL's
    • auto-generated data validation methods (get placed in separate *-generated.cs-files [e.g. 'Common.Validation-generated.cs']).
  • in Server DLL's
    • in the generated C# files for Cacheable DataTables
      • these are calls to auto-generated data validation methods which are found in Shared DLL's

The WinForms Generator automatically creates program code...

  • in Client DLL's
    • in the generated C# files of Forms/UserControls
      • these are calls to auto-generated data validation methods which are found in Shared DLL's

Scope

Automatic Data Validation code is generated only for DB Tables that are specified in the petra.xml file!

  • Generated code in Shared DLL's and in Server DLL's is for the automatic data validation of all DataColumns of all OpenPetra DB Tables (as specified in petra.xml).
  • Generated code in Client DLL's is solely for the automatic data validation of Controls which are bound to DataColumns of OpenPetra DB Tables that are found on the individual Forms/UserControls.


DataColumns in the petra.xml file for which automatic data validation code is generated (see Method 'GenerateAutoValidationCodeForDBTableField' in file \csharp\ICT\BuildTools\CodeGeneration\Validation.cs for details):

  • DataColumns which are part of a Primary Key or are part of a Unique Key
    • Data Validation code enforces that NULL must never be assigned to those DataColumns.
  • DataColumns with a NOT NULL restriction (applies to any DataColumn that isn't part of a Primary Key or Unique Key)
    • Data Validation code enforces that NULL must never be assigned to such a DataColumn.
  • DataColumns of varchar Type (string Type in C#)
    • Data Validation code enforces that the length of the String is not exceeded.
  • DataColumns of number Type (decimal Type in C#)
    • Data Validation code enforces that the number precision is within the range that is specified.
      • A Validation Error is raised if the total count of significant digits in the whole number, that is, the number of digits to both sides of the decimal point, is exceeded.
      • A Validation Warning is raised if the number of digits after the decimal point is larger than specified (rounding will occur in the DB in this case and so the user knows about it).
      • Example: petra.xml specifies "lenght=6", "decimals=2" for a certain DataColumn. The check results in...
        • an Error if the user enters more than 4 digits to the left of the decimal point (6-2=4);
        • a Warning if the user enters more than 2 digits to the right of the decimal point.
  • DataColumns of date Type (DateTime Type in C#)

Multiple automatic data validations may be generated for a single DataColumn to enforce multiple rules! Example: Automatic data validation code that will be created for a varchar column which is part of a Unique Key (or Primary Key): 1) code for a NOT NULL check [because the column is part of a Key], 2) code for a string length check.

Placement of Automatic Data Validation Code

Client DLL's

Calls to automatic data validation code contained in Shared DLL's are automatically be placed in all the appropriate places of a generated C# file of a Form/UserControl. The only requirement for this to happen is that the YAML file that specifies the Form/UserControl contains data bound Controls. Validation=true does not need to be set on Controls for that to happen - this must only be done to indicate to the WinForms Generator that manual data validation code needs to be called for a DataColumn that is bound to that Control! The hook-ups for all automatically and manually validated Controls can be found in the 'BuildValidationControlsDict()' Method of a Form/UserControl. Automatic ones have a comment '// Automatic Data Validation ...' next to them.

Calls to the automatic data validation code always precede calls to the manual data validation code (if manual data validation code is present at all in a Form/UserControl). This allows manual data validation code to modify the TVerificationResult objects that the automatic data validation code may create, should that be necessary (e.g. to modify the standard texts that are presented to the user).

Shared DLL's

The automatically generated code in the *.ManualCode.cs file of the Form/UserControl and the automatically generated code in the C# files for Cacheable DataTables on the server side call automatically generated data validation Methods in the shared DLL's.

That called Method performs the actual Data Validation:

  • If a Data Validation Error or Warning is identified, a TVerificationResult object is created for it
    • the TVerificationResult object gets appended to a TVerificationResultCollection
      • In case the Method is called from the client side that Collection is held in the Form where the Data Validation is run.
        • Once a Data Validation Error/Warning got rectified by the user, the corresponding TVerificationResult object is removed from the Collection through this Method, too.
      • In case the Method is called from the server side that Collection is held in the Method that calls the Data Validation.

More details about the code in Shared DLL's can be found here. - Though that section relates to manually written code, the same applies for the automatically generated code, with the exception of the Method names, which are ValidateData / ValidateDataDetails instead of ValidateDataManual / ValidateDataDetailsManual, respectively.

Regarding the placement of the automatically data validation code in the various C# files in the Shared DLL's please refer to this section, which again relates to manually written code, but the same applies for the automatically generated code.

Server DLL's

Calls to automatic data validation code contained in Shared DLL's are automatically placed in all the appropriate places of all the generated C# files for OpenPetra's Cacheable DataTables.

Calls to the automatic data validation code always precede calls to the manual data validation code (if manual data validation code is present at all in the Class that contains Cacheable DataTables). This allows manual data validation code to modify the TVerificationResult objects that the automatic data validation code may create, should that be necessary (e.g. to modify the standard texts that are presented to the user).