Kundenanpassungen¶

Kundenanpassungen können auf verschiedenen Ebenen in der Programmiersprache Python relativ einfach durchgeführt werden. Dazu wurden viele Schnittstellen geschaffen, um eine einfache Erweiterung von NCDiff zu ermöglichen.

Zuerst ist es nötig einen Überblick über den Aufbau von NCDiff zu geben.

Aufbau von NCDiff¶

Nach dem auspacken von NCDiff-X.Y.zip liegt folgende Verzeichnisstruktur unterhalb von NCDiff-X.Y.zip vor:

doc - Dokumentation zu NCDiff
- guide - NCDiff Benutzerhandbuch
examples - Beispiele für NCDiff
- data - Dateien für den alt vs. neu Vergleich
  
  new - „ALT“ Report Dateien
  
  old - „NEU“ Report Dateien
- results - Verzeichnis für die diff Ergebnisse
libs - Python Bibliotheken von NCDiff
- extensions - Ort für Kundenerweiterungen
- ncdiff - Standardmodule von NCDiff
- …. - verschiedene 3rd Party Python Module
python - Windows Portable Python Installation
resources - Verzeichnis für Ressourcen zur Ergebnisdarstellung
- html - Ressourcen für das HTML Diff Ergebnis
  
  css - Stylesheets
  
  font - Schriftarten
  
  img - Bilder
  
  js - JavaScript
- gui - GUI Icons und Konfigurationsdatei
templates - Templates für das Diff Ergebnis, z.B.: Excel, ResultFilter

Python Module in libs/ncdiff¶

comparator
Dieses Modul führt den aktuellen Zellvergleich mit Differenzbildung für unterschiedliche Datentypen durch. Verwendet den Converter um die Zellwerte umzuwandeln.

configuration
Enthält einen Parser für Konfigurationsdateien und erstellt Konfigurationsobjekte für Diff Targets (TargetConfiguration). Jede TargetConfiguration beinhaltet die gesamte Konfigurationsinformation die nötig ist um ein Target zu diffen.

constants
Konstanten für alle NCDiff Standardmodule.

constraint
Enthält Constraint Klassen welche Constraint Funktionen implementieren die sich in der Constraint Sprache verwenden lassen. Die Constraint Sprache wird bei Row Filter, Result Filter und bei der Definition von Toleranzen die vom Inhalt einer anderen Spalte abhängen verwendet.

constraint_translator
Dieses Modul übersetzt die Ausdrücke aus der Constraint Sprache in ausführbaren Python Code.

converter
Um effektiv Differenzen bilden zu können, ist es nötig die Zell Werte von Text in andere Datentypen (Zahlen, Datum, …) umzuwandeln. Dieses Modul enthält Implementierungen, die sich in oldColumnFormats/newColumnFormats Konfigurationseinträgen angeben lassen.

diff_value
Enthält die Klassen welche die Ergebnisse eines diffs representieren.

differ
Der Differ verarbeitet die sortierten Dateien um einen Zeilenvergleich durchzuführen und übermittelt den Writern die gefunden Unterschiede. Verwendet den Comparator für den Zellvergleich.

history
Code des ncdiff-history Tools zum visualisieren der zeitlichen Entwicklung von Vergleichen.

launcher
Code des ncdiff-launcher Tools zum starten vom NCDiff vergleichen.

licenses
Der Lizenztext von NCDiff und 3rd Party Modulen.

main
Beinhaltet das Hauptprogramm. Dieses Modul wird vom Befehlsskript ncdiff geladen und aufgerufen.

postprocessing
Code der nach der Verarbeitung von NCDiff aufgerufen wird. Enthält hauptsächlich die Erweiterungspunkte um Kunden-Code auszuführen.

preprocessing
Code der vor der Verarbeitung von NCDiff aufgerufen wird. Enthält hauptsächlich die Erweiterungspunkte um Kunden-Code auszuführen.

result_filter
Das Modul ist für die optionale Filterung von vorgefundenen Unterschieden verantwortlich. In der ResultFilter Excel Datei können Regeln definiert werden um vorgefundenen Unterschiede als „bereits Bekannt“ markieren zu können. Es besteht die Möglichkeit diese bekannten Unterschiede erst gar nicht in der Ausgabe anzugeben bzw. diese durch entsprechenden Status von „normalen“ Differenzen zu unterscheiden.

sorter
Damit ein Zeilenvergleich effizient durchgeführt werden kann, müssen die Zeilen nach Schlüssel sortiert vorliegen. Diese Aufgabe wird von diesem Modul erledigt. Für die Sortierung gibt es zwei Implementierungen:

Sortierung innerhalb des Hauptspeichers

Sortierung über Datei basiertem Merge-Sort

Variante 2 wird automatisch für Dateien >50MB verwendet, um Hauptspeicher zu sparen.

statistics
Modul zum einsammeln von Diff Lauf Statistiken.

utils
Hilfsfunktionen für NCDiff Standardmodule.

validator
Ein Validator ist dazu da, eine TargetConfiguration zu validieren um Nutzungsfehler frühzeitig zu melden.

reader.base
Enthält Reader Basisklassen und Fuktionen, um unterschiedliche Report Dateiformate zu lesen.

reader.csv
Reader für das CSV Format.

reader.dir
Reader um Dateiverzeichnisse zu lesen und für einen Vergleich der Dateistruktur auf zu bereiten.

reader.fixed_width
Reader für textbasierte Formate mit Felder mit definierter Breite.

reader.sql
Reader für SQL Datenbanken.

reader.tar
Reader für den Inhalt von *.tar Dateien um einen Vergleich der Dateistruktur auf zu bereiten.

reader.xls
Reader für XLS und XLSX Dateien.

reader.xml
Reader für XML Dateien.

writer.base
Basismodul der writer um die verschiedenen Ausgabeformate zu schreiben.

writer.cl
Kommandozeilen writer für die Textausgabe auf der Kommandozeile.

writer.converter
Konverter Klassen um die Ausgabe bestimmter Werte zu konvertieren.

writer.csv
Implementierung des writers für das CSV Format.

writer.formatter
Formatierungsklassen um die verschiedensten Datentypen für die Ausgabe zu formatieren.

writer.html
Implementierung des writers für das HTML Format. Dazu wird die HTML Template Bibliothek mako verwendet. Die benutzen Template-Dateien sind unter /templates zu finden.

writer.junit
Implementierung des writers für das Junit Format.

writer.xlsx
Implementierung des writers für das XLSX Format.

Python Anpassungen mittels Erweiterungsmodulen¶

Um NCDiff anzupassen ist es nicht nötig die Standardmodule umzuschreiben, da in NCDiff vorgesehen ist, Funktionalität in Erweiterungsmodule auszulagern. Für jeden vorgesehenen Erweiterungstyp ist eine Python „Factory“ Funktion zu schreiben, welche die Alternativ Implementierung zur Verfügung stellt.

Erweiterungsmodule müssen im libs/extensions Ordner abgelegt werden und können mit dem globalen Konfigurationsparameter extensionModules aktiviert werden. In jedem der angegebenen Extension Module wird nach bekannten Factory Funktionen gesucht, um über deren Aufruf an eine gewünschte Implementierung zu gelangen.

Im Auslieferungszustand von NCDiff ist ein leeres Beispielmodul mit dem Namen ExtensionTemplate.py enthalten, welches für alle vorgesehenen Erweiterungstypen bereits eine leere Factory Funktion beinhaltet. Liefert eine Factory Funktion nichts zurück, so verwendet NCDiff die Standard Funktionalität.

Um eigene Erweiterungen zu erstellen, ist der einfachste Weg ist sich eine Klasse aus der Standard Implementierung zu suchen, von dieser abzuleiten und die benötigte Funktionalität zu implementieren. Diese Implementierung muss dann nur noch in der zugehörigen Factory Funktion zurückgegeben werden. Die folgende Tabelle gibt eine Übersicht über die vorgesehenen Erweiterungsmöglichkeiten und deren zugehörige Factory Funktion.

create_basic_target_configuration_validator¶

Factory: create_basic_target_configuration_validator
Modul: validator
Beschreibung: Validierung der Konfiguration nach Einlesen aus der Datei

create_target_configuration_validator¶

Factory: create_target_configuration_validator
Modul: validator
Beschreibung: Validierung der Konfiguration nach dem einlesen und anreichern mit basis Werten.

create_configuration_preprocessor¶

Factory: create_configuration_preprocessor
Modul: preprocessing
Beschreibung: Definition eines Preprocessor für eine bestimmte Konfiguration.

create_target_preprocessor¶

Factory: create_target_preprocessor
Modul: preprocessing
Beschreibung: Definition eines Preprocessor für ein bestimmtes Diff Target.

create_execution_preprocessor¶

Factory: create_execution_preprocessor
Modul: preprocessing
Beschreibung: Definition eines Preprocessor für die gesamt NCDiff Ausführung.

create_configuration_postprocessor¶

Factory: create_configuration_postprocessor
Modul: preprocessing
Beschreibung: Definition eines Postprocessor für eine bestimmte Konfiguration.

create_target_postprocessor¶

Factory: create_target_postprocessor
Modul: preprocessing
Beschreibung: Definition eines Postprocessor für ein bestimmtes Diff Target.

create_execution_postprocessor¶

Factory: create_execution_postprocessor
Modul: preprocessing
Beschreibung: Definition eines Postprocessor für die gesamt NCDiff Ausführung.

create_old_reader¶

Factory: create_old_reader
Modul: reader
Beschreibung: Einlesen der alten Report Datei Formate

create_new_reader¶

Factory: create_new_reader
Modul: reader
Beschreibung: Einlesen der neuen Report Datei Formate

get_constraints¶

Factory: get_constraints
Modul: constraints
Beschreibung: Definition neuer Constraint Funktionen

create_old_sorter¶

Factory: create_old_sorter
Modul: sorter
Beschreibung: Ersatz des Sortieralgorithmus

create_new_sorter¶

Factory: create_new_sorter
Modul: sorter
Beschreibung: Ersatz des Sortieralgorithmus

create_converter¶

Factory: create_converter
Modul: converter
Beschreibung: Implementierung neuer Konverter für Zellenwerte

create_comparator¶

Factory: create_comparator
Modul: comparator
Beschreibung: Ersatz der Zellvergleichslogik

create_differ¶

Factory: create_differ
Modul: differ
Beschreibung: Ersatz der Diff Logik

create_writer¶

Factory: create_writer
Modul: writer
Beschreibung: Implementierung neuer Ausgabeformate

create_statistic_writer¶

Factory: create_statistic_writer
Modul: writer
Beschreibung: Implementierung neuer Ausgabeformate

create_result_interpreter¶

Factory: create_result_interpreter
Modul: result_filter
Beschreibung: Einlesen von ResultFilter Daten

create_result_interpreter_reader¶

Factory: create_result_interpreter_reader
Modul: result_filter
Beschreibung: Ersatz der ResultFilter Logik

Excel Templates¶

Unter NCDiff-X.Y/templates finden Sie bereits von uns vordefinierte Templates, welche bei resultFormats=XLSX verwendet werden. Gerne können Sie auch eigene Templates erzeugen, welche für Excel basierte Diff-Ergebnisdateien verwendet werden.

Die XLSX Templates für das Excel 2007 Dateiformat müssen als XLSX Templates mit der Dateiendung xltx abgespeichert werden. NCDiff enthält ein Default-Template template_green-grey.xltx welches als Vorlage für eigene Templates dienen kann. XLSX Templates lassen analog zu XLS Templates sich mit den Konfigurationseinstellungen XLSXTemplate und templateDirectory auswählen.

Für die XLSX Templates müssen Sie folgendes beachten:

Die Formatierung der Ersten Zeile der verschiedenen Sheets wird für die jeweilige Überschrift verwendet

Die Formatierung der Zweiten und Dritten Zeile wird übernommen und wechselt sich in den Ergebnisdateien ab um die gerade und ungeraden Zeilen besser hervorzuheben.

Statistic Sheet: Die vierte Zeile bestimmt die Formatierung der letzten Zeile im Ergebnis welches die Summen enthält.

Overview, Old, New: die Zeilen 4 bis 8 enthalten die Formatierungen für die verschiedenen Fehler und sind im Template dokumentiert.

Config Sheet: hier wird nur die erste Zeile zur Formatierung der Titelzeile verwendet.

HTML Darstellung¶

Die HTML Darstellung verwendet Cascading Style Sheets (CSS), JavaScript zusammen mit Standard HTML Notation. Diese Ressourcen liegen in Unterverzeichnissen von resources/html und werden beim erstellen der Ergebnisse ins das Ausgabeverzeichnis kopiert.

Das Logo lässt sich austauschen in dem das Bild logo.png in resources/html/img durch ein anderes Bild ersetzt wird.

Falls Anpassungen erforderlich sind, welche über den Austausch des Logos hinausgehen, sind Web Technologie Kenntnisse erforderlich.