byggsøk plan developers guide - dibk · separate set of java classes, with single front-end api....

ByggSøk plan Developers Guide of 23 Document Date/Version 30.03.2012/1.0

Document status Released

©Jotne EPM Technology AS 1998 - 2012

ByggSøk plan Developers Guide

Document id. 11240-doc-06 Doc version 1.0 Status Released Date Mar 30, 2012 Author(s) DK Checked by DK Approved by PH




Document revision history Rev Description Status Date Author Approved

Conventions used in this document Names of interface elements, modules and libraries are given in the regular Bold font. Names of external systems and servers are given in the Italics font.




Table of Contents 1 Architecture 4

1.1 Web application design ............................................................................ 4 1.2 XSD based data model and ORM ............................................................ 5 1.3 Matrix based GUI and Data mapping ....................................................... 8

2 Implementation 9 2.1 Modules overview .................................................................................... 9 2.2 Module group: data definition and access ............................................. 11

2.2.1 PersistenceManager module ...................................................... 11 2.2.2 BeanAccessor module ................................................................ 11 2.2.3 TreeManager module .................................................................. 12 2.2.4 FieldMapper module ................................................................... 13

2.3 Module group: core services .................................................................. 13 2.3.1 Configuration module .................................................................. 13 2.3.2 Translator module ....................................................................... 14 2.3.3 FileUpload module ...................................................................... 14 2.3.4 Log module ................................................................................. 14 2.3.5 Statistics module ......................................................................... 15

2.4 Module group: request processing ......................................................... 15 2.4.1 StateManager module ................................................................. 15 2.4.2 WorkObject module .................................................................... 16 2.4.3 RequestDispatcher module ......................................................... 16 2.4.4 QueryParser module ................................................................... 17 2.4.5 ContentManager module ............................................................ 17 2.4.6 MainHandler module ................................................................... 17 2.4.7 Integration module ...................................................................... 18

2.5 Module group: extended services .......................................................... 18 2.5.1 Validator module ......................................................................... 18 2.5.2 Reports module ........................................................................... 19 2.5.3 XMLHanlder module ................................................................... 19

2.6 Module group: external communication group ....................................... 20 2.6.1 BrregClient module ..................................................................... 20 2.6.2 PostClient module ....................................................................... 20 2.6.3 Help module ................................................................................ 21

2.7 Codes outside modules ......................................................................... 21 2.7.1 Framework classes ..................................................................... 21 2.7.2 JSP helpers ................................................................................. 21 2.7.3 Utilities ........................................................................................ 22

3 Appendix 22 3.1 Configuration files usage table ............................................................... 22




1 Architecture This chapter describes general software design and solutions, split into three main domains: web application framework, basic data definition and GUI-to-data mappings.

1.1 Web application design While ByggSøk plan web application is a Java servlet-based web application, according to standard specification, there are some specific design approaches used in, which will be described below.

Servlet and Listener

Most of functionality in web application is encapsulated in modules, which consist of separate set of Java classes, with single front-end API. There is a single instance of each class representing front-end API, which is created by web application Listener as a result of processing application start-up event (standard contextInitialized event). Correpondingly, same Listener is responsible for destroying module instances on a shutdown event (standard contextDestroyed event). As according to this design, all module instances are singletones, they are multithreaded.

To allow uniform and free access for all functionality offered by modules in any part of web application, all created instances of modules are put into servlet context attributes set using corresponding module name. At the same time, to avoid uncontrolled usage of modules, every module declares set of other modules references which it depends on. Application Listener is responsible to properly fill all such references as soon as corresponding reference is created (instances are created just once, not possible to replace them after application start, so all references are declared as final in code).

To allow asynchronous execution and activities performed on schedulle, each module has ability to declare own timer – an event which will be called on defined time schedule. All timers are collected and handled by Listener. To enhance




resources control, each module also receives information events just after application startup and before application shutdown (also important for flushing in-module caches, etc.).

To process all web requests, in ByggSøk plan web application there is just single Serlvet (and single instance of that servlet), which serves both static and dynamic resources (including JSP pages). There is no response-creation functionality in that servlet itself – it just determines which module is responsible for incoming request, and passes control to that module.

Implemenation of modules is usually located in individual Java packages, with one ’main’ Java class which publishes module API (in small modules there is just one Java class at all) and set of helper classes. As most of modules represent quite general functionality, which can be used in many project and servers, they are designed in ’extandable’ way – so that other projects can inherit ’main’ Java class and create a new version of it, while keeping its compatibility with other modules in the system.

As ByggSøk plan project is very similar in GUI and functionality to the ByggSøk bygning project, it was built as an extention of latter. There is no ’own’ modules in ByggSøk plan web applciation – all of its modules are modules inherited from ByggSøk bygning, with needed small changes in behaviour.

To keep clear structure of common codes and inherited modules, following rules in Java package naming are followed:

• com.epm.PROJECT_NAME

This is the base Java package for a project/web applciation (like com.epm.byggesak, com.epm.plansak). Project name is converted into package naming conventions – small letters, no blanks, etc.

• com.epm.PROJECT_NAME.MODULE_NAME

This is the base Java package for a specific module (like com.epm.byggesak.configuration, com.epm.plansak.queryparser). Module name is converted into package naming conventions – small letters, no blanks, etc.

1.2 XSD based data model and ORM One notable feature in ByggSøk plan web application is its data model – where all data structures and definitions are encapsulated in XSD files.

The origin of such solution was a specification for ByggSøk plan which was based on XML schema describing all user data to be stored in system and sent to the municipality. That schema was extended to support few additional system objects (like user profiles, system administrator settings, binary attachments, etc.).

To conviniently operate XSD-defined data stuctures inside Java code, a separate standalone utility was developed – DataBeansGenerator. This tool is based on Castor open source library, which include built-in XSD-to-Java-source generator utility (which actually creates standard Java bean class for every ’element’ tag in XSD). DataBeansGenerator further modifies Castor-generated sources to provide




additional methods (and especially to form parent-children relationalships between Java classes). Generated classes has built-in ability of marshalling to and from XML format (according to source XSD). Also classes has built-in ability to validate against XSD single data field, single Java bean, or whole object tree.

As ByggSøk plan project was pre-defined to have MySQL relational database as a main storage for all its data, it was needed to store and load Java beans described above into relational database. Castor open-source library ORM is used to perform Java object to relational database mapping. Already mentioned DataBeansGenerator is used to generate both table definitions for the MySQL database (as a DDL script file) and a special mapping file in XML format required by Castor library to perform loading and saving of Java beans.

To avoid integrity checks overhead, all database foreign keys a ’nullable’ – i.e. it is allowed for a child object/table to have no parent. So instead of deleting whole ’tree’ of dependent objects/tables, code erases just a top parent, and later, periodic ’garbage collector’ detects unreferenced table records and deletes them.

It is needed to note, that to simplify accessing and manipulating Java Bean objects that represent single Plan (according to XSD, single Plan is relatively large set of mutually referenced and nested elements – which, after generation process, produce large ’tree’ of Java Bean objects), they are saved and loaded as a ’bulk’ – in single operation. Correspondingly, transactions always cover modifications of whole ’tree’, as there are no individual updates inside ’tree’.

On the diagram below, all objects which are loaded/saved individually are presented together with their relationships and descriptions.




DB & POJO Overview




1.3 Matrix based GUI and Data mapping ByggSøk plan GUI is defined using combination of JPS pages (used as template – to define page layout and look of fields) and a separate site map tree structure (which define both menu hierarchy and individual form fields content).

Site Map tree structure is defined in MS Excel file, below is an example of such matrix. Main column is ’Data field name’, which defines form field. Columns to the left of it represent name of page which contain this field and menu hierarchy which contains page itself. Columns to the right of it are different properties of the field and contain such information, like allowed access to the field for different user roles, dependecy on another fields, and data mapping for the field.

Site Map and Data matrix

In further documentation, this matrix is reffered to as TreeMenu and is loaded and handled by the module with same name. Main goal for using matrix is to group following functionalities in single ’browseable’ space:

• Control access (none, read-only, read-write) to data on menu, page and individual field level. Defined access is controlled both when generating dynamic HTML pages and when validating data submitted by user.

• Provide translation for all menues, pages and individual fields. Names from matrix are used as keys for translation resources.

• Loading data from Java Bean objects into form fields and saving them back after submit. For each field, matrix contains name of Java Bean and string path (similar to ’xpath’ notation in XSLT technology), which are used to read/write correct values.

Another matrix shown below is used to define additional dependecy between Plan ’phase’ and visiblity of form fields and pages (and also if form field is mandatory for this phase or not). There are three columns – one for each phase. Structure of menu, pages and fields should coinside with those in main matrix (the ’Site Map and Data matrix’ discussed above). ’O’ mark means field is visible and mandatory, ’X’ mark means field is visible but optional.




Visibility matrix

2 Implementation This chapter describe individual software modules of ByggSøk plan web application and their responsibilities.

2.1 Modules overview Modules are split into five groups according to the ‘type’ of their functionality (plus small set of classes which are not organized as modules).

• Data definition and access (modules representing data structures and managing data flows)

• Core services (helper modules needed for functioning of web application)

• Request processing (modules providing servlet request processing)

• Extended services (additional modules of application, like reports, etc.)

• External communication services (modules providing client-side integration with other web servers)

Note: standalone utility for generation of Java Bean classes from XSD, DataBeansGenerator, described in chapter ‘1.2 XSD Based model and ORM’, is not part of the web application, and is not delivered in final distributive.

ByggSøk plan Developers Guide of 23 Document Date/Version 30.03.2012/1.0 Document status Released


Modules Overview



2.2 Module group: data definition and access This group contains modules for two different levels of data access:

• On a low level, PersistenceManager is used to locate, load and save Java beans and BeanAccessor is used to read/write properties of Java beans using direct property path given as a parameter.

• On a higher level, FieldMapper is used to read/write data fields of TreeManager which are backed up with some pre-loaded Java bean object (in this case path is known implicitly – through data field definition).

2.2.1 PersistenceManager module • Package: com.epm.plansak.persistencemanager

• Class: com.epm.plansak.persistencemanager.CachedPM2

• Interface: com.epm.byggesak.persistencemanager.PersistenceManager

This module encapsulates work with Castor ORM API and JDBC API.

ORM-related methods allow creation of new persistent Java Beans, loading and saving Java Beans into database. During loading (target object is specified by its integer ID), desired access is specified – read-only or read-write. Transaction is started after loading of single Java Bean object and covers only that object (including all its dependent object ‘tree’, if such exists). Transaction lasts until commit or rollback is performed on that object.

JDBC-related methods allow execution of pre-registered SQL queries and updates (query is registered by specifying its reference name and SQL statement as string, query parameters in string are denoted by ‘?’ mark). Queries which are SQL update statements, return number of affected rows. Queries which are ‘SELECT’ statements, return result as a two-dimensional array of strings, also, for such queries, additional parameters can be passed – for limiting size of result, start position, filters and sorting.

Other helper methods in PersistenceManager API include generating unique IDs (and setting IDs into Java Beans), and possibility to add a listener which will receive events for every JavaBean load, save & create operation.

Internally, PersistenceManager also adds a timer for periodical check of database for integrity – and removing objects which became ‘garbage’.

2.2.2 BeanAccessor module • Package: com.epm.byggesak.beanaccessor

• Class: com.epm.byggesak.beanaccessor.BeanAccessor

This module encapsulates all access to Java Beans objects.



Instead of using direct property getters and setters on Java Beans, everywhere in application, BeanAccessor methods are used to get and set properties of Java Bean object. Target object is passed as a parameter to common getValue/setValue methods, as well as a string ‘path’ which specifies property location and name to read or write. Syntax of ‘path’ is similar to XPATH notation used in XSLT, but ‘/’ separator is replaced with ‘.’, to be looking more Java-friendly. Both simple and array properties can be handled. During set value operation, missing objects in the given ‘path’ are automatically created. All values passed in and out are only strings.

Other helper methods in BeanAccessor API allows to find out type (and Java class) of any property denoted by ‘path’, and perform ‘deep’ clone of Java Bean objects.

During set value operation, when creation of new Java Bean is needed, module also sets its ID and marks modified and newly created objects – which is used to enhance performance during objects commit.

2.2.3 TreeManager module • Package: com.epm.plansak.beanaccessor

• Class: com.epm.plansak.treemanager.TreeManager

This module keeps Site Map which is defined as MS Excel matrix in external files, and encapsulates access to that Site Map.

Site Map (or TreeMenu) is stored as a tree where each node is either Level or Field. Levels can contain other levels (children) and fields. A lot of properties are defined for each node, where each property is either direct value from Excel column, or its interpretation.

Usually TreeLevels are used as web GUI menu items, where each ‘leaf’ Level is a particular web GUI page, and Fields inside that Level are form fields for that web page.

Where ever reference to exact Site Map tree element is needed, there are two ways to provide such reference: by giving Java instance of TreeNode, TreeLevel or TreeField classes which represent desired tree node, or by given special string ‘path’ from the tree root. ‘Path’ consists of node names – from root till leaf, separated by ‘@’ symbol (as an option, instead of string name, order number of node inside its parent can be used). TreeManager provides methods for conversion ‘path’ into node instances and backwards.

Important methods in TreeManager API also include security access validation methods. For the given tree node, and using current servlet request as a holder for current processing state, API can determine which access level is allowed – none, read-only or read-write.

Special sub-service inside TreeManager module allows iterating over the whole tree or its subpart, returning either only structure information, or, if Java Bean object is passed as a parameter, also returning string values read from that object for every encountered Level and Field (for Levels which represent a data table, multiple rows can be returned – then such Level is repeated several times).



2.2.4 FieldMapper module • Package: com.epm.plansak.fieldmapper

• Class: com.epm.plansak.fieldmapper.FieldMapper

This module is responsible for reading and writing values in Java Bean objects, using Site Map tree as a data structure definition.

Main methods of FieldMapper API are set and get property value of target Java Bean object using TreeField object instance as a definition of property location, type and ‘path’.

Other important methods include getting type of value for particular TreeField, and getting list of rows for a TreeLevel which represent a data table (usually a web GUI page on which a table is present).

As TreeFields usually represent web page form fields, this module is a main way of passing data from Java Bean into HTML page, and saving submitted form fields into target Java Bean.

For a more flexible operation, module perform two-level conversion for data read and written through its API. When reading, data is first transformed by designated ‘field mapper’ object (which are small inner classes defined inside module, it’s possible to add more such classes, for some specific data pre-processing), and then transformed by ‘value mapper’ object (which is a similar thing, but on the higher level of abstraction – besides Java conversion code, it’s possible to specify simple Map for replacing one value with another). When writing, conversion is performed in reverse order.

2.3 Module group: core services Modules from this group should be properly initialized for other modules to work correctly. Usually these modules are first created by Listener.

2.3.1 Configuration module • Package: com.epm.plansak.configuration

• Class: com.epm.plansak.configuration.Configuration

This module is responsible for keeping various ‘static’ configuration parameters for current web application – like its name, main object, data package, etc. These parameters are important for the common codes in other modules, which are written in uniform manner and are suitable for many different web applications.

Another responsibility of this module is to create database structure (by performing static DDL script included in distribution), and upgrade it when needed (again by running corresponding DDL and SQL script(s) - current version of database is stored in database table and is simply compared with ‘version’ value statically stored in this module).



2.3.2 Translator module • Package: com.epm.byggesak.translator

• Class: com.epm.byggesak.translator.Translator

This module is responsible initial loading and managing translation service – i.e. multi-language support for the web application GUI, reports, etc.

Initial set of translation resources (which is a number of records in form ‘languageID:resourceKey = translatedValue’) is loaded from static file supplied in distribution and saved into database table (this happens during server installation).

Translator API allows other modules to get currently selected (i.e. for the currently selected language) translation Map, as well as Map for any specific language registered in server.

Translator also allows both per-record update of translations (this includes inserting new, updating existing, deleting existing), and perform bulk updates of translation tables by supplying a translation file with key/value pairs (in this case, deletion of existing records can’t be performed).

It’s important that available languages in the system are determined by presence of at least one translation key with its language ID.

As Translator caches all translation tables, it is needed to invoke corresponding method to reload whole content every time database translation records are changed and it’s desirable to make those changes visible in GUI.

2.3.3 FileUpload module • Package: com.epm.byggesak.fileupload

• Class: com.epm.byggesak.fileupload.FileUpload

This module is responsible for uploading of user binary files and for tracking progress of the uploading process.

Uploading part itself is based on Apache FileUpload library, which allows processing of servlet requests which have binary files included inside. All uploaded files are stored in temporary folder – before they are saved into database.

Progress tracking is supported only in Ajax mode of web application, which is currently not supported by ByggSøk plan project, but base framework implementation supports it.

2.3.4 Log module • Package: com.epm.byggesak.log

• Class: com.epm.byggesak.log.Log

This module is responsible for logging various events and providing info on stored events.



Log record is quite general – it contains time stamp, type and level of event and free-text message with some parameters which describes the logged event. Encoding of parameters and setting correct type and message is responsibility of module which invoke logging.

All records are stored in database, and can be setup to be auto-deleted after some time period (to avoid growing without restrictions). Reading of log records is done via simple SQL query.

In ByggSøk plan, Log is used only for logging incoming SOAP requests received and prcessed by Integration module (it is also dependent on the admin setting parameter – current level of logging, which allows logging for example only SOAP errors, or all invocations including successfull ones).

2.3.5 Statistics module • Package: com.epm.byggesak.statistics

• Class: com.epm.byggesak.statistics.Statistics

This module is responsible for keeping few system counters and providing statistics based on their logged values during different time periods.

Module counts predefined events in web application (like new user creation, new soknad creation, etc. – every call increase counter by one). Every hour counted values for all events are saved into database as separate records, together with time stamp. This allows later to retrieve counted values for any time period and group them in different time units – down to single hour.

To save database space needed to hold statistics, it is possible to set time period through admin settings, after which per-hour records will be re-calculated into per-day records. So for recent time periods statistics will be available for ‘hour’ unit, and for older periods only ‘day’ and above will be used.

Module also includes code needed to provide table with a report for given time period, which is split by given time unit (event type to show is passed as a parameter).

Separate Javascript Dygraph library is used to display table data as a diagram.

2.4 Module group: request processing Modules from this group explicitly participate in servlet request processing, deals with request, session and response attributes.

2.4.1 StateManager module • Package: com.epm.plansak.statemanager

• Class: com.epm.plansak.statemanager.StateManager



This module is responsible for managing navigation, user session, request attributes and current web page location.

As a part of user request processing, module updates user session according to request parameters and validates state of session – i.e. that user has right to be on current page, etc.

‘Current State’ term is commonly used in code to refer to the ‘leaf’ TreeLevel object instance (or ‘path’ from tree root representing that Level) which correspond to a page which user is viewing at the moment (or which is rendered, or from which user just performed form submit).

Module also serves as a wrapper for setting different flags and variables in servlet request attributes and session attributes. Corresponding attributes are written into every generated HTML page content as hidden variables – to be able to restore full page state in case of expired user session.

2.4.2 WorkObject module • Package: com.epm.plansak.workobject

• Class: com.epm.plansak.workobject.WorkObject

This module is responsible for controlling Java Bean objects usage during single request processing, and to provide security-access object for current request.

Module hides object loading by providing ‘preloaded’ objects for every conceptual kind of objects used during request processing: User, Work, Settings. So, according to object IDs stored in user session attributes for every object kind, that objects are loaded before and committed after request processing. Other modules just use object instances without need to explicitly load and commit them.

Security access object is a kind of cache of user security rights of different kind. It’s calculated just once during request processing for better performance.

Some helper methods, like getting current user name and municipality also exist in API.

2.4.3 RequestDispatcher module • Package: com.epm.plansak.requestdispatcher

• Class: com.epm.plansak.requestdispatcher.RequestDispatcher

This module is responsible for data submits – both form fields and separate user commands.

When user submits a form from web page, there could be several filled form fields and, optionally, a command (which is just a reserved string value). Module first saves all submitted fields using FieldMapper module into current ‘Work’ Java Bean (at this time, every field is checked for valid read-write access, also fields dependencies are checked), and then executes command. Each command is implemented as a separate method with same name in module main Java class.



2.4.4 QueryParser module • Package: com.epm.byggesak.queryparser

• Class: com.epm.byggesak.queryparser.QueryParser

This module is responsible for choosing correct JSP page which need to be invoked to render HTML and also responsible to build URL links for downloading reports, attachments, etc.

Changing default JSP page for processing is done either when error is detected during request processing (then special JSP for showing error is chosen), or when special parameter is included into request URL.

Module API builds URLs with corresponding added parameter to show reports, attachments, etc. Individual JSP pages for each kind and type of content exist.

2.4.5 ContentManager module • Package: com.epm.byggesak.contentmanager

• Class: com.epm.byggesak.contentmanager.ContentManager

This module is mainly responsible for delivering static content to the user.

Static content in web application can be delivered in two forms: as a usual downloadable static content, or as a JAR file in WEB-INF with all resources. In any case, as main servlet of web application is defined to handle all URLs, ContentManager module is used to find and return resources. To determine if request URL points to the static resource, servlet asks ContentManager if it can serve that URL, and in case of positive answer, passes control to it. All static resources are normally preloaded by ContentManager in memory (there are not much of them) for faster access, so in case when modification were done to the resources ‘on the fly’, separate method is used to ‘reset’ whole cache.

Separate functionality of the module is handling and invocation of JSP pages. All JSP pages in system are pre-compiled during build process, and become simple servlets, which are registered by ContentManager, and can be called using original file name of source JSP page.

2.4.6 MainHandler module • Package: com.epm.byggesak.contentmanager

• Class: com.epm.byggesak.contentmanager.ContentManager

This module is a simple framework wrapper which calls other modules needed to process servlet request in correct sequence.

Module pre-loads objects, invoke RequestDispatcher module if there are commands/submitted fields, uses StateManager to validate session state and at the



end of request processing, calls ContentManager with chosen JSP to render data into response.

2.4.7 Integration module • Package: com.epm.plansak.integration

• Class: com.epm.plansak.integration.Integration

This module provides server-side implementation of SOAP service published by the web application.

As Apache Axis library is used to publish SOAP service, this module is just Java class with few public methods. Axis library automatically publish as SOAP methods all public methods of this class (WEB-INF/server-config.wsdd file is used to specify which class will provide the service).

Most of operations implemented in Integration module just calls standard servlet request processing pipeline (by creating fake/virtual servlet request, response and session objects) – because most of actions which are needed by 3rd party SOAP clients, already are implemented in RequestDispatcher module.

2.5 Module group: extended services Modules, which provide separate additional functionality. Web application and request processing can work without these modules.

2.5.1 Validator module • Package: com.epm.plansak.validator

• Class: com.epm.plansak.validator.Validator

• Factory: com.epm.plansak.validator.ValidatorFactory

This module provides Plan validation functionality, which is performed before sending Plan to the municipality.

Notice that actual service which is bound to the ServletContext, is ValidatorFactory class instance – because new Validator instance is created for each validation round.

Following types of validation are used: all mandatory form fields are not empty, all attachments which are of ‘electronic’ type have binary files, total and individual file size is within allowed bounds.

Special structure with validation errors is populated during validation run. Other modules, which invoke validation, can both check status of validation and present list of errors to the user.



It should be noted that both form field validation and validation of attachments use Site Map TreeManager value iterator, with access check – so that only fields/attachments visible currently to the user in web GUI are validated.

2.5.2 Reports module • Package: com.epm.plansak.reports

• Class: com.epm.plansak.reports.Reports

This module provides PDF and HTML reports functionality.

Module itself is a factory for report generators of different types. There are two types of generators:

• com.epm.plansak.reports.ReportOld (PDF & HTML)

• com.epm.plansak.reports.Report (PDF)

ReportOld generator uses exactly same Site Map structure as used to build web GUI pages, applying TreeManager value iterator to it. The resulting internal report structure is then just a list of form fields values from all (or part of) GUI pages – section names are made from menu and page name, field title and field value are added as plain text. Internal report structure then can be rendered as a PDF document or as a HTML page. Currently this type of report is used only for generation content of Summary and Overview pages (HTML rendering).

Report generator uses separate sub-trees in Site Map, which are not corresponding to any GUI web page, and thus defines own layout and content for each report. By applying TreeManager value iterator to sub-trees, generator builds internal report presentation, split it into pages and renders as PDF.

In both generators, same set of external fonts is used (supplied in distributive). These fonts are embedded into PDF document to provide same look and feel on all client PCs. Styles for layout are defined directly in generators (so they are overridden in each web application project).

Additional feature of Reports module is PrintForm class which provide list of reports associated with current Plan and corresponding URLs that can be used to download generated reports (all reports are generated ‘on the fly’, so no actual generation occurs until URL is invoked).

2.5.3 XMLHanlder module • Package: com.epm.plansak.integration

• Class: com.epm.plansak.integration.XMLHandler

This module provides different mapping procedures from XML data to Java Bean objects and backward.

Conversion uses XML marshalling code built into Java Bean classes. To achieve compatibility with previous versions of XML, separate XMLConverter class



preprocess all incoming and outgoing XML data – and if found version doesn’t meet currently supported one, conversion is applied iteratively until required version is received (i.e. each conversion code part can convert only neighbor versions – like from 1 to 2 and backward).

Another common format for Java Bean representation is treating Site Map tree as a XML structure (where menus, pages and fields are all nested XML schema elements). XMLHandler supports this format as well, providing methods for conversion XML to Java Beans and backwards.

Additional feature of module, which is used only in Integration, is service for generating XML data from two-dimensional string arrays based on static description which elements to produce (used for error lists, soknad lists, etc.).

2.6 Module group: external communication group Modules which implement client-side stubs and APIs for the external services invocation.

2.6.1 BrregClient module • Package: com.epm.byggesak.brregclient

• Class: com.epm.byggesak.brregclient.BrregClient

This module contains client-side code for invocation of BRREG service.

Apache Axis library is used to generate client stubs for the BRREG SOAP service (using public WSDL file from it).

Module API returned company information by invoking SOAP method. Company number is passed as parameter, while BRREG server address is implicitly read from administration settings. Company information is retuned as a string Map with predefined key names – like RegistreringsDato, Navn, etc.

Other modules uses this information to pre-fill data on web pages, validate addresses, etc.

2.6.2 PostClient module • Package: com.epm.byggesak.postclient

• Class: com.epm.byggesak.postclient.PostClient

This module is responsible for mapping post codes to poststed.

At web application initialization (and later on, periodically) module downloads list of post codes and their corresponding location names from Norwegian post server (server location is read from administration settings). This list is parsed and stored as string Map.



Module API returns location name for the given post code. Other modules uses this information to pre-fill data on web pages, validate addresses, etc.

2.6.3 Help module • Package: com.epm.byggesak.help

• Class: com.epm.byggesak.help.Help

This module is responsible for providing context help.

At web application initialization (and later on, periodically) module downloads from InfoServer (server location is read from administration settings) document with help information, and parse this document into string Map (where for each page and field there is a help text block).

Module API returns help text for the given page or field full ‘path’. Other modules uses this information to show default help text on page and provide individual help for fields when requested by user.

2.7 Codes outside modules General framework codes and helper classes are described in this section.

2.7.1 Framework classes • Class: com.epm.byggesak.ByggesakServlet

This servlet processes all requests for all URLs belonging to the web application. It doesn’t any processing internally, but instead passes control to different modules depending on type of request URL and its parameters.

Servlet also initialize file uploading if when needed, and passes control to the Axis SOAP servlet if URL matches SOAP service.

• Class: com.epm.plansak.PlansakListener

Listener creates instances of all modules in the system during web application startup, and destroys them on shutdown (list of modules to be used is defined directly in Listener class).

During web application work, Listener is responsible for invoking all timer-based events which different modules have registered into it during startup.

Listener also contains static definition list of all globally used SQL queries

2.7.2 JSP helpers • Class: com.epm.plansak.htmltemplates.HTMLTemplates



This class is used to render many HTML primitives like edit boxes, labels, radio buttons, etc. Also used to render HTML tables. Separate methods are available for all types of HTML page elements. JSP pages code invoke that methods to insert required element into generated HTML page.

Besides rendering itself, class performs all additional preparation tasks implicitly – for example, checks for security access for the generated element, reads current value to be shown in edit box, etc.

New instance of this class is created for each request processing.

• Class: com.epm.plansak.JSPHelper

This class contains inner classes and methods which simplify and shortens code of JSP pages. So it’s a kind of utility collection methods for JSP pages. Most important functionalities built into JSPHelper, are: paging control for long tables, automatic sorting for tables, automatic filtering of tables.

2.7.3 Utilities • Class: com.epm.byggesak.util.Util

This class includes a lot of commonly used methods, which are used all over the system. Among them are: sending emails, loading from resources, password generation, date formatting and many others. All methods are made static, so no instances of this class are created.

3 Appendix Additional notes and convenient references are grouped in this chapter.

3.1 Configuration files usage table This chapter shows all configuration files used by ByggSøk plan, listed together with names of modules and Java classes which use them (name of each file is given relative to the root of sources folder):

• PlansakServer/ROOT/WEB-INF/config/ AllResources.txt

Translator module, class: com.epm.byggesak.translator.BulkTranslator

• PlansakServer/ROOT/WEB-INF/config/Bygningstypekoder.xls, PlansakServer/ROOT/WEB-INF/config/Formal - list 2.xls, PlansakServer/ROOT/WEB-INF/config/komkat2002 v2.xls, PlansakServer/ROOT/WEB-INF/config/PBL_formal.xls

FieldMapper module, class: com.epm.plansak.fieldmapper.ValueMapper



• PlansakServer/ROOT/WEB-INF/config/ PassordbrevAutomatisk.pdf

RequestDispatcher module, class: com.epm.plansak.requestdispatcher.RequestDispatcher

• PlansakServer/ROOT/WEB-INF/config/Mapping gui - xml.xls, PlansakServer/ROOT/WEB-INF/config/TreeMenu.xls, PlansakServer/ROOT/WEB-INF/config/TreeMenuConfig.txt

TreeMenu module, class: com.epm.plansak.treemanager.ExcelSheetTreeReader

• PlansakServer/ROOT/WEB-INF/config/db.xml

Configuration module, class: com.epm.plansak.configuration.Configuration (also used by all Castor library codes - DB config, ORM & XML marshalling)

• PlansakServer/ROOT/WEB-INF/config/ddl.sql (generated file)

Configuration module, class: com.epm.plansak.configuration.Configuration

• PlansakServer/ROOT/WEB-INF/config/ map.xml (generated file)

BeanAccessor module, class: com.epm.byggesak.beanaccessor.BeanAccessorDbBase

• PlansakServer/ROOT/WEB-INF/config/ xml/1.2.xsd

XMLHandler module, class: com.epm.plansak.integration.XMLHandler

• PlansakServer/ROOT/WEB-INF/ fonts/*.ttf

Reports module, class: com.epm.byggesak.reports.PDFFonts

• DataBeansGenerator/inputdata/ejbmap.xml, DataBeansGenerator/inputdata/map.xml, DataBeansGenerator/inputdata/plansak/ddl.sql, DataBeansGenerator/inputdata/plansak/ObjectMapping.txt, DataBeansGenerator/inputdata/plansak/binding.xml, DataBeansGenerator/inputdata/plansak/xsd/*.xsd

Generator utility, class: byggsokgenerator.Generator

(also used by Castor library codes for XSD-to-Java class generation process)

byggsøk plan developers guide - dibk · separate set of java classes, with single front-end api....

Documents