View source for OpenPETRA Project Structure and Namespace Descriptions

(imported from Petra Wiki in September 2010)

==openPETRA Project Structure==
openPETRA consists of many Projects (>80 DLL Projects plus some Executable Program Projects).

=== Conceptual Overview ===
* '''Petra Server''' and '''Petra ServerAdmin''' are small EXE projects (result in console applications)
** Contain only little functionality, main functionality is located in referenced DLL's
** allows rather easy creation of WinForm EXE by reusing functionality from the same DLL's

* '''Petra Client''' EXE is a small EXE project (results in a WinForm application) 
** Contains only little functionality, main functionality is located in referenced DLL's 
*** small classes provide main functionality (eg. establish .NET Remoting connection to Petra Server, start 'Keep Alive' Thread, different Cache Managers, etc); 
** WinForms, Logic etc. for Petra Modules are contained in separate DLL's

* '''all other Projects''' are DLL projects (resulting in a DLL)

==== Reasons for having many DLL's ====
* separation of functionality between Client and Server (and Petra-independent [ICT Common] functionality)
* logical structure: files in one project are in one directory (most of the times)
* logic and verification are not in the same file as the WinForm -> much cleaner
* smaller compilation targets -> quicker compilation of changes
* to resolve circular references/dependencies
* contrary to Win32 programming, having many DLLs in .NET causes nearly no run-time overhead
** no run-time speed difference whether a class/procedure/function is locally available or in a different namespace, different dll, etc.


==openPETRA Namespace Descriptions ==
(last updated on January 5th, 2010)

'''This description of the openPETRA Namespace structure is intended for developers so that they can get an understanding of the project structure and to help them in deciding in which Namespace to put Units and Classes that are to be added.'''

It covers most of the Namespaces that currently exist and Namespaces that will be used in the future. It is not always going down to detail level.


=== <span style="color:darkblue">Ict.*</span> ===
Main namespace for all ICT applications. ''No Projects/no program code is to be put directly in this Namespace - it just serves as a root namespace!''

----

==== <span style="color:darkblue">Ict.Common.*</span> ====
Namespace for anything that is ''not'' specific to Petra and which therefore can be used by other ICT applications (no other ICT applications exist yet, though).

===== Ict.Common =====
Namespace for universal utility and helper functions. Contains eg. string helper functions, logging, helper functions, enums, etc. Can be used by all parts of openPETRA (Petra Client and Petra Server, etc).

===== Ict.Common.Controls =====
Namespace containing universal custom .NET WinForms controls. Some controls merely extend an existing control with some functionality, other controls are 'compositions' of controls with special functionality. Used eg. by the Petra Client.

===== Ict.Common.Conversion =====
Namespace containing Classes for data conversions.

===== Ict.Common.Data =====
Namespace containing base classes for Typed DataTables, Typed DataSets and the DataStore.

===== Ict.Common.DB =====
Namespace containing the DBAccess unit (for RDBMS-agnostic DB access) and other DB-related units. Used eg. by the Petra Server.

===== Ict.Common.EMailing =====
Namespace containing classes for accessing e-mail clients.

===== Ict.Common.IO =====
Namespace containing various Input/Output utilities, eg. MS-Excel automating class, XML Parser class.

===== Ict.Common.Printing =====
Namespace containing printing routines. At the moment used only by the Petra Reports.

===== Ict.Common.Verification =====
Namespace containing Classes for data verifications and for returning detailed errors and lists of detailed errors. Can be used by all parts of openPETRA (Petra Client and Petra Server, etc).

----
----

==== <span style="color:darkblue">Ict.Petra.*</span> ====
Main namespace for the openPETRA application. ''No Projects/no program code is to be put directly in this Namespace - it just serves as a root namespace for the Petra application!''

----

===== <span style="color:darkblue">Ict.Petra.Shared.*</span> =====
Namespace containing shared libraries, used by the Petra Server and the Petra Client (as well as the Petra ServerAdmin program). This Namespace contains Classes that are used both by the Petra Server and the Petra Client (or by the Petra Server and the Petra ServerAdmin program) and classes that can be passed from the Petra Server to the Petra Client (and vice versa). Also contains custom Exceptions.

''Except for Interfaces, DataTables, DataSets and DataAccess Libraries we should keep the Ict.Petra.Shared.* Libraries as small as possible - we want to share as little as possible functional code with the Client!''

====== Ict.Petra.Shared ======   
Namespace containing Classes and other things that need to be present on Server and Client side of openPETRA.

Examples: common Constants, common Remoted Exceptions, common Enums, etc.

====== Ict.Petra.Shared.Interfaces ======
Namespace containing a number of Interfaces to Classes on the Petra Server side. These are used by the Petra Client (some as well by the Petra ServerAdmin program) to make remote calls to classes for which they don't have the executable code of the classes. 
The Interfaces are a kind of 'contract' between Petra Client and Petra Server - the Petra Client knows through them what methods exist in the Petra Server, the Petra Server's Objects provide all the properties and methods as advertised in the Interfaces and execute the actual code. (Interfaces are not Objects themselves, but get implemented by Server Objects.)

Every Petra Module has several interfaces, eg. to create UIConnectors.

Reasons why we use Interfaces
* needed for .NET Remoting calls: Petra Client needs to call something on the Petra Server, for this it needs to know which methods and parameters are available - for compiling and running
* we don't want to distribute large parts of the Petra Server code to the Petra Client
* create a virtual Object Hierarchy in the Petra Server

''All Interfaces that are located in files whose name ends in '.AutoHierarchy.cs' are auto-generated from the NamespaceHierarchy.xml file. Do not edit those files manually, otherwise your changes will be overwritten once those files are re-generated!!!''

====== Ict.Petra.Shared.Resources ======
Namespace containing shared resources (eg. Strings, Icons).

====== Ict.Petra.Shared.UserInfo ======
Namespace containing a shared class that holds information about the currently connected user.

====== Ict.Petra.Shared.Verification ======
Namespace containing data verifications that can be used in procedures and functions to perform certain data verifications. Can be used both on Petra Server and Petra Client side.

This is a central place for verification code that is ''general'' rather than a concrete verification of certain fields of a certain DataTable.

None of the data verifications in here must access the DB since the Client doesn't have access to the database!

Examples: Date checks (eg. Date1 earlier then Date2), e-mail validity check (logical only), is-string-numeric, etc.

====== Ict.Petra.Shared.M* ======
Namespaces containing Classes that can be passed from the Petra Server to the Petra Client (and vice versa) as well as functions which perform certain calculations that are needed on both sides - specific for the one Petra Module (Partner, Personnel, etc). Also may contain shared Exceptions, Types, Enums, Constants, etc.

====== Ict.Petra.Shared.M*.DataTables ======
Namespaces containing Typed DataTables for all Petra DB tables - specific for the one Petra Module (Partner, Personnel, etc). 
Automatically created from Petra XML file.

[[Overview openPETRA architecture#Typed_DataTables|See Typed DataTables]]

====== Ict.Petra.Shared.M*.DataSets ======
Namespaces containing Typed DataSets - specific for the one Petra Module (Partner, Personnel, etc).
Automatically generated from Typed DataSet XML files. We maintain these XML files on our own and need to re-generate the Typed DataSets after each change.

[[Overview openPETRA architecture#Typed_DataSets|See Typed DataSets]]

====== Ict.Petra.Shared.M*.DataAccess ======
Namespaces containing DataAccess objects for all Petra DB tables - specific for the one Petra Module (Partner, Personnel, etc).
Automatically created from Petra XML file.

[[Overview openPETRA architecture#Data_Stores|See Data Stores]]

====== Ict.Petra.Shared.M*.DataCascading ======
Namespaces containing DataAccess objects for cascading data operations (eg. cascading delete) for all Petra DB tables - specific for the one Petra Module (Partner, Personnel, etc).
Automatically created from Petra XML file.

[[Overview openPETRA architecture#Data_Stores|See Data Stores]]

----

===== <span style="color:darkblue">Ict.Petra.Server.*</span> ===== 
Namespace for the PetraServer libraries.

====== Ict.Petra.Server.<span style="color:darkblue">App</span> ======

* '''Ict.Petra.Server.App.Core'''<br />Namespace containing core classes (eg. Server settings) for the Petra Server that are used by many parts of the Server.

* '''Ict.Petra.Server.App.ClientDomain'''<br />Namespace containing classes that manage the set-up and destruction of AppDomains for Client connections and the set-up of .NET Remoting Lifetime Management for those AppDomains.

* '''Ict.Petra.Server.App.ClientDomain.CallForwarder'''<br />Namespace containing helper classes for making remoted calls to AppDomains.

* '''Ict.Petra.Server.App.Main'''<br />Namespace containing the main logic for the Petra Server.

====== Ict.Petra.Server.<span style="color:darkblue">MCommon</span> ======
Namespace containing utility and helper functions that are Petra Server specific and are shared between several Petra modules.

====== Ict.Petra.Server.<span style="color:darkblue">MPartner</span> ======
Namespace for the Partner Module.

* '''Ict.Petra.Server.MPartner.Common'''<br />Namespace for utility and helper functions that are Partner Module specific.

* '''Ict.Petra.Server.MPartner.Partner'''<br />Namespace for all Partner-related processing, business rules, data verification and data segmentation.<br />Also contains Classes that return cacheable Typed DataTables (used by the [[openPETRA_Technical_Implementation_Details#Data_Caching|Client-side data cache]]). Contains functions that perform server-side processing of data and enforce business rules. These can be called eg. from UIConnectors. Example: TPPartnerAddressAggregate. Will in the future also contain Objects that handle the verification of data and segmentation of data. Both will be automatically called from DataAccess Objects. Examples (not yet existing): TPartnerVerification, TPartnerDataSegmentation, etc.

* '''Ict.Petra.Server.MPartner.Extracts'''<br />Namespace that will hold all Extract-related functionality.

* '''Ict.Petra.Server.MPartner.Subscriptions'''<br />Namespace that will hold all Subscription-related functionality.

* '''More examples of sub-namespaces'''<br />Ict.Petra.Server.MPartner.PartnerMerge, Ict.Petra.Server.MPartner.PartnerMerge.Locations, Ict.Petra.Server.MPartner.ImportExport, Ict.Petra.Server.MPartner.Reports, Ict.Petra.Server.MPartner.Mailing, Ict.Petra.Server.MPartner.TableMaintenance, etc.


====== Ict.Petra.Server.MPartner.<span style="color:darkblue">UIConnectors</span> ====== 
Namespace for Business Objects that send and receive only necessary data (for a specific screen) in a most efficient way.<br />[[openPETRA_Architecture#UIConnectors_.28User_Interface_Connectors.29_.3D_Business_Objects_of_openPETRA|See 'UIConnectors (User Interface Connectors) = Business Objects of openPETRA']]<br /><br />Contains eg. TPartnerEditUIConnector, TPartnerFindUIConnector, etc.

====== Ict.Petra.Server.MPartner.<span style="color:darkblue">Instantiator</span> ======
Namespace for Objects that create (=instantiate) UIConnector objects on behalf of the PetraClient.

''Code that is located in the 'Instantiator.AutoHierarchy.cs' is auto-generated from the NamespaceHierarchy.xml file. Do not edit anything outside the '#region ManualCode' section in this file manually, otherwise your changes will be overwritten once that file is re-generated!!!''


====== Ict.Petra.Server.<span style="color:darkblue">MPersonnel</span> ======
Namespace for the Personnel Module.

* '''Ict.Petra.Server.MPersonnel.Common (not yet created)'''<br />Namespace for utility and helper functions that are Personnel Module specific.

* '''Ict.Petra.Server.MPersonnel.Person (not yet created)'''<br />Namespace for all Person-related processing, business rules, data verification and data segmentation.<br />Will in the future 
** contain Classes that return cacheable Typed DataTables (used by the [[openPETRA_Technical_Implementation_Details#Data_Caching|Client-side data cache]]).
** contain functions that perform server-side processing of data and enforce business rules. These can be called eg. from UIConnectors.
** contain Objects that handle the verification of data and segmentation of data. Both will be automatically called from DataAccess Objects. Examples: TPersonVerification, TPersonDataSegmentation, etc.

* '''Ict.Petra.Server.MPersonnel.Unit (not yet created)'''<br />Namespace for all Unit-related processing, business rules, data verification and data segmentation.<br />Will in the future
** contain Classes that return cacheable Typed DataTables (used by the [[openPETRA_Technical_Implementation_Details#Data_Caching|Client-side data cache]]).
** contain functions that perform server-side processing of data and enforce business rules. These can be called eg. from UIConnectors.
** contain Objects that handle the verification of data and segmentation of data. Both will be automatically called from DataAccess Objects. Examples: TUnitVerification, TUnitDataSegmentation, etc.

====== Ict.Petra.Server.MPersonnel.<span style="color:darkblue">UIConnectors</span> ======
Same as Ict.Petra.Server.MPartner.UIConnectors.<br />Would contain eg. THierarchyUIConnector, TJobsUIConnector, TCostsUIConnector, etc.

====== Ict.Petra.Server.MPersonnel.<span style="color:darkblue">Instantiator</span> ======
Same as Ict.Petra.Server.MPartner.Instantiator.


====== Ict.Petra.Server.<span style="color:darkblue">MFinance</span> ======
Namespace for the Finance Module.

* '''Ict.Petra.Server.MFinance.Common (not yet created)'''<br />Namespace for utility and helper functions that are Finance Module specific.

* '''Ict.Petra.Server.MFinance.Gift'''<br />Namespace for all Gift-related processing, business rules, data verification and data segmentation.<br />Will in the future
** contain Classes that return cacheable Typed DataTables (used by the [[openPETRA_Technical_Implementation_Details#Data_Caching|Client-side data cache]]).
** contain functions that perform server-side processing of data and enforce business rules. These can be called eg. from UIConnectors.
** contain Objects that handle the verification of data and segmentation of data. Both will be automatically called from DataAccess Objects. Examples: TGiftVerification, TGiftDataSegmentation, etc.

* '''Ict.Petra.Server.MFinance.AccountsPayable (not yet created)'''<br />Namespace for all AccountsPayable-related processing, business rules, data verification and data segmentation.<br />Will in the future
** contain Classes that return cacheable Typed DataTables (used by the [[openPETRA_Technical_Implementation_Details#Data_Caching|Client-side data cache]]).
** contain functions that perform server-side processing of data and enforce business rules. These can be called eg. from UIConnectors.
** contain Objects that handle the verification of data and segmentation of data. Both will be automatically called from DataAccess Objects. Examples: TPartnerVerification, TPartnerDataSegmentation, etc.

====== Ict.Petra.Server.MFinance.<span style="color:darkblue">UIConnectors</span> ======
Same as Ict.Petra.Server.MPartner.UIConnectors.

====== Ict.Petra.Server.MFinance.<span style="color:darkblue">Instantiator</span> ======
Same as Ict.Petra.Server.MPartner.Instantiator.


====== Ict.Petra.Server.<span style="color:darkblue">MConference</span>======
Namespace for the Conference Module.

* '''Examples of sub-namespaces'''<br />Ict.Petra.Server.MConference.Common, Ict.Petra.Server.MConference.Setup, Ict.Petra.Server.MConference.Management, etc.

====== Ict.Petra.Server.MConference.<span style="color:darkblue">UIConnectors</span> (not yet created) ======
Same as Ict.Petra.Server.MPartner.UIConnectors.

====== Ict.Petra.Server.MConference.<span style="color:darkblue">Instantiator</span> ======
Same as Ict.Petra.Server.MPartner.Instantiator.


====== Ict.Petra.Server.<span style="color:darkblue">MFinDev</span>====== 
Namespace for the Financial Development Module.

* '''Examples of sub-namespaces'''<br />Ict.Petra.Server.MFinDev.Common, etc.


====== Ict.Petra.Server.MFinDev.<span style="color:darkblue">UIConnectors</span> (not yet created) ======
Same as Ict.Petra.Server.MPartner.UIConnectors.

====== Ict.Petra.Server.MFinDev.<span style="color:darkblue">Instantiator</span> ======
Same as Ict.Petra.Server.MPartner.Instantiator.


====== Ict.Petra.Server.<span style="color:darkblue">MSysMan</span> ======
Namespace for the System Manager Module.

* '''Ict.Petra.Server.MSysMan.UserDefaults'''<br />Namespace containing System Manager maintenance functionality for User Defaults.

* '''Ict.Petra.Server.MSysMan.SystemDefaults'''<br />Namespace containing System Manager maintenance functionality for System Defaults.

* '''Ict.Petra.Server.MSysMan.ErrorLog'''<br />Namespace containing Petra Error Logging functionality.

* '''More examples of sub-namespaces'''<br />Ict.Petra.Server.MSysMan.Common, Ict.Petra.Server.MSysMan.Application, Ict.Petra.Server.MSysMan.PrintManagement, etc.

====== Ict.Petra.Server.MSysMan.<span style="color:darkblue">UIConnectors</span> (not yet created) ======
Same as Ict.Petra.Server.MPartner.UIConnectors.

====== Ict.Petra.Server.MSysMan.<span style="color:darkblue">Instantiator</span> ======
Same as Ict.Petra.Server.MPartner.Instantiator.


----

===== <span style="color:darkblue">PetraServerConsole.exe</span> =====
The Petra Server application. Implemented as console application.



----

===== <span style="color:darkblue">Ict.Petra.ServerAdmin.Core</span> ===== 
Contains logic for the PetraServerAdmin application.

===== <span style="color:darkblue">PetraServerAdminConsole.exe</span> =====
'Remote control' application for the PetraServer. Implemented as console application.


----

===== <span style="color:darkblue">Ict.Petra.Client.*</span> =====
Namespace for the PetraClient libraries.

====== Ict.Petra.Client.App.* ======
Namespace for the internal logic of the GUI application. 

* '''Ict.Petra.Client.App.Core'''<br />Core classes (eg. for Server connection, caching, user preferences) for the Petra Client that are used by many parts of the Client.
** Ict.Petra.Client.App.Core.RemoteObjects<br />Contains a class which holds all references to instantiated Server-side objects that are remoted by the Server.
** Ict.Petra.Client.App.Core.Shared<br />Contains things that should be in Ict.Petra.Client.App, but would create too many dependencies in other projects.

* '''Ict.Petra.Client.App.Formatting'''<br />Contains functions and procedures for custom formatting/parsing on the Client side.

* '''Ict.Petra.Client.App.Gui'''<br />Contains procedures and functions to help with various GUI issues.

====== Ict.Petra.Client.CommonControls, Ict.Petra.Client.CommonDialogs, Ict.Petra.Client.CommonForms ====== 
Namespaces containing Petra-specific re-usable parts of the GUI that are not tied to a certain Petra Module. 

* '''CommonControls'''<br />contains Petra-specific .NET WinForms Custom Controls and UserControls

* '''CommonDialogs'''<br />contains Petra-specific Dialog-style windows (eg. Login, Progress Dialog, etc)

* '''CommonForms'''<br />contains Petra-specific inheritable WinForms which help maintain a common look-and-feel and functionality.

====== Ict.Petra.Client.M*.Gui ======
Contains the screens (WinForms) of the GUI (Graphical User Interface) for each of the Petra Modules. Classes in this Namespace should only be WinForms and they should not contain logic or verification code at all!

Contains screens like PartnerEdit, PartnerFind, etc.

====== Ict.Petra.Client.M*.Logic ======
Contains the logic parts that make the GUI for each of the Petra Modules work. Each Class contains logic for one associated screen, such as loading/processing/saving data.

====== Ict.Petra.Client.M*.Verification ======
Contains code for data verification of each of the Petra Modules. Each Class contains data verification for one associated screen. 

Example: Checking whether 'From Date' lies before 'To Date', e-mail verification, etc.

Note: Code in here will in most cases just make a series of calls into Ict.Petra.Shared.Verification with the data and texts as applicable to the one screen.

----

===== <span style="color:darkblue">PetraClient.exe</span> =====
The Petra Client application. Implemented as WinForms application.


----

== Resulting Assemblies ==

Apart from some exceptions (see below), we create an assembly (DLL) from the fourth level namespace onwards:

* Ict.Petra.Server.''MPartner''.dll (contains  all classes in Ict.Petra.Server.MPartner.Partner, Ict.Petra.Server.MPartner.Partner.Cacheable, ...)
* Ict.Petra.Server.''MPersonnel''.dll (contains all classes in Ict.Petra.Server.MPersonnel.Person, Ict.Petra.Server.MPersonnel.Unit, ...)
* Ict.Petra.Server.''MFinance''.dll (contains all classes in Ict.Petra.Server.MFinance.Gift, Ict.Petra.Server.MFinance.AccountsPayable, ...)
* Ict.Petra.Server.''MConference''.dll (contains all classes in Ict.Petra.Server.MConference.Setup, Ict.Petra.Server.MConference.Management, ...)
* Ict.Petra.Server.''MSysMan''.dll (contains all classes in Ict.Petra.Server.MSysMan.Security, Ict.Petra.Server.MSysMan.Maintenance, ...)
* Ict.Petra.Server.''MFinDev''.dll (similar than those above)

...except for some fifth-level namespaces that are either a) likely to change frequently, b) likely to not change frequently, c) are quite big, d) are shared between Server and Client:

* Examples for a): Ict.Petra.Server.M*.''UIConnectors''.dll, Ict.Petra.Server.M*.''Instantiator''.dll<br />Contain/create business objects (eg. TPartnerEditUIConnector) that are called by the Client. These form the server-side logic of a certain Petra Screen/functionality.

* Example for b): Ict.Petra.Server.M*.''Common''.dll<br />Contain common functions that are not likely to change often.

* Examples for c): Ict.Petra.Server.MPartner.''PartnerMerge''.dll, Ict.Petra.Server.MPersonnel.''Person''.dll<br />Namespaces that are likely to result in a lot of code lines and are rather independent of a) the fourth-level namespace business objects in the same Petra module (eg. Partner Merge), b) or other fifth-level namespaces in the same Petra module (Person).

* Examples for d): Ict.Petra.Shared.''Interfaces''.*.dll, Ict.Petra.Shared.M*.''DataAccess''.dll and Ict.Petra.Shared.M*.''DataTables''.dll<br />Shared between Server and Client and therefore in separate assemblies.


For the Client, some fifth-level namespaces are separate assemblies as well:

* Ict.Petra.Client.MPartner.Gui.dll
* Ict.Petra.Client.MPartner.Logic.dll
* Ict.Petra.Client.MPartner.Verification.dll

The reasons for that are: 1) keep GUI definition separated from logic (and database field names), 2) building a project that contains WinForms takes considerably longer than other projects because of resource compiling and linking, therefore if we change something in the logic (eg. database field names) or data verification we don't want to compile the WinForm (that hasn't changed at all), 3) allows smaller libraries (although they will have hundreds of files in them...), which compile faster.


For certain namespaces and the executables for Server, ServerAdmin and Client we create separate assemblies as well:

* Ict.Common.dll
* Ict.Common.DB.dll
* Ict.Petra.Shared.dll
* PetraServer.exe
* PetraServerAdmin.exe
* PetraClient.exe