ByggSøk plan Project Structure And Build Process

Transcription

1 Page 1 of 14 ByggSøk plan Project Structure And Build Process Document id doc-05 Doc version 1.0 Status Date Mar 30, 2012 Author(s) ON Checked by DK Approved by PH

2 Page 2 of 14 Document revision history Rev Description Status Date Author Approved Conventions used in this document Names of interface elements (buttons and text boxes) and names of files are given in the regular Bold font. Names of system parameters and environment variables are given in the Italics font. Titles of chapters of this document are referred to in the Italics font. Examples with text strings or values to be entered by user are given in the Courier typeface.

3 Page 3 of 14 Table of Contents 1 Introduction 4 2 General Notes on Parts of ByggSøk plan 4 3 Project Source Folders 4 4 Configuration Folder in the Source File Set Structure of the Resulting Web Application Package 12 7 Configuration Folder in the Distribution 13 8 Reference Documents 14

4 Page 4 of 14 1 Introduction This document describes ByggSøk plan folder structure, structure of the resulting web application package and information necessary for building the web application. The ByggSøk plan web-application is available for modification and re-building at any time. 2 General Notes on Parts of ByggSøk plan There are several theses on the design of ByggSøk plan: 1.1 The project was developed on the basis of an earlier similar project, Byggesak. There are a few folders in the project folder structure, which contain both byggesak and plansak subfolders. This means that the byggesak subfolder contains the basis source files, and the plansak subfolder contains additional source files. 1.2 As a cross-platform application, ByggSøk plan faces the following typical situation: not every platform has True Type fonts used by ByggSøk plan, the font names and particular locations may differ on different platforms. To make accessing the fonts uniform, the fonts being used are added to the web application. 1.3 The project makes use of the Castor open source library as of year It can save Java objects to database, read them from database, convert them into XML files and restore them from XML files. EPMT has patched and modified the Castor library file set, and the package of patches is included here. The library itself (in the outside world) has gotten its own development to a point far aside, and at the moment, its open sources are incompatible with what is needed for ByggSøk plan. 1.4 In this project, an XSD schema is the source for the whole application data structure. To use this approach to the full, EPMT has developed special generator (hereinafter referred to as generator ). It carries out the following tasks: Ensures correct settings for the Castor library. Uses the XSD file to create Java classes that describe particularly this data structure. Creates full DDL description for the database. Using this DDL description, MySQL creates the whole database. Creates another description, which enables correct saving the objects (objects with data) to this relational database, and reading them from there. 1.5 The whole web application build process is performed by means of XML build files run by Ant. 3 Project Source Folders Folder, where the whole source file set of web application is located, hereinafter is called the root folder of source file set, or the source root folder, or (the Unix style) source home folder. It contains two files: MakePlansak.bat This is the command file to start building the web application. build.xml This is the main build file.

5 Page 5 of 14 The top-level subfolders of the source root folder represent basic parts of the ByggSøk plan web application. build This is a reserved folder for the build process and the resulting application file. Here all the project files are collected together and built. CastorPatch Contains patches and modifications for the Castor open source library (see clause 1.3). Here, file build.xml carries out part of the overall build process with regard to the Castor library. CommonServices Contains the application s own code intended for execution (business logic, etc.). Here, file build.xml carries out part of the overall build process with regard to the common services code. There are two basic subfolders: CommonServices\src\com\epm\byggesak Contains reusable code of the Byggesak web application. CommonServices\src\com\epm\plansak Contains code for own functionality of the ByggSøk plan web application. Here, the plansak subfolder structure (logical parts of application) follows that of byggesak, and contains code for own functionality of ByggSøk plan (see clause 1.1). DataBeansGenerator Contains all the files with regard to the generator. Here, file build.xml carries out part of the overall build process with regard to the code of generator and its participation in the build process. DataBeansGenerator\byggsokgenerator Contains the generator Java source code files. DataBeansGenerator\inputdata\plansak Contains additional files for the generation process initial configuration. Here: ddl.sql, map.xml manually created templates for the generator to put the generated stuff into them. DataBeansGenerator\inputdata\plansak\xsd Contains the XML schema, which is the source for creating the Java beans, DDL description, and so on. Here, the main file is plansak_0_5.xml, other files are statically included into it.

6 Page 6 of 14 DataBeansGenerator\inputdata\src Contains a few manually written Java source files (the DbBase class among them), they are to be added to the source files generated by the generator, thus to form the complete set of source files for further process. The output Java beans will inherit the DbBase class. Libs Contains all open source libraries necessary for ByggSøk plan to operate. Some of them are necessary for compiling. These file sets are verified and tested for ByggSøk plan. Their copies in internet may have been updated and may be not fully compatible already. Therefore, it is better to use files from here rather than their copies from internet. Libs\forcompileonly Contains JAR files needed at the compilation step only, for either Ant or some our utilities, which help to perform build. These files do not get into the WAR file, they are for correct operation of build.xml. PlansakServer Contains mostly the web application static content and configuration files. PlansakServer\ROOT Contains standard folder structure of the resultant WAR file and its static content, except for code and various dynamic things. When running the build script, Ant copies almost the whole ROOT folder to the build folder and, accordingly, to the WAR file. ROOT is what later becomes the web application root folder. Its subfolders are: PlansakServer\ROOT\css Contains cascade styles for HTML pages. PlansakServer\ROOT\i Contains static picture files used in HTML pages. Here, the i folder contains language-independent pictures (they do not contain any text), the EN subfolder contains pictures with text in English, the NO subfolder contains those with text in Norwegian. Another subfolder, NN (for Nynorsk), may also be present. PlansakServer\ROOT\js Contains javascripts, which are external with regard to HTML pages. PlansakServer\ROOT\jsp Contains JSP Web components (templates) for dynamic web pages. Here, the include subfolder contains common parts of templates. PlansakServer\ROOT\pdf Is not used, empty.

7 Page 7 of 14 All the above-mentioned subfolders of the ROOT folder, except for the jsp subfolder, will be accessible on the web site through URL. PlansakServer\ROOT\WEB-INF Contains the application resources, they are inaccessible for users through URL. Its subfolders are: PlansakServer\ROOT\WEB-INF\classes Is not used. This subfolder is provided only to meet specifications [1], [2]. PlansakServer\ROOT\WEB-INF\lib Is not used in the source file set, empty. PlansakServer\ROOT\WEB-INF\config Contains configuration files necessary for the web application. For more about them, see the next chapter. PlansakServer\ROOT\WEB-INF\fonts Contains fonts for generator of PDF reports (see clause 1.2). Also, WEB-INF contains two files, which fully meet specifications [1], [2]: web.xml This is a standard description of web application parameters: which parts of code are for which URLs, user session timeout, and so on. It is for HTTP GUI of the application. server-config.wsdd This is the same thing, but for the SOAP server part of ByggSøk plan, which communicates with SOAP clients. 4 Configuration Folder in the Source File Set Content of this folder in the source file set differs from that of the final distribution. For more about this folder in the distribution, see chapter Configuration Folder in the Distribution. In the source file set, this folder path relative to the source root folder is: PlansakServer\ROOT\WEB-INF\config It contains the following files. AllResources.txt This is the initial list of translations, all the text phrases, which need translation (the language-specific resources, not only in the server GUI). All of them are given in the standard Java form: key = value, where key is the language-independent parameter, value is its GUI name (text phrase) translated to particular language. Given the application provides switching the user interface language, this file provides particular interface language.

8 Page 8 of 14 This is the initial list because it is used to initialise the database. After the database is initialised, the database itself contains all these text phrases. Bygningstypekoder.xls This is the list of building codes and their textual descriptions, which are to be shown in GUI. Formal - list 2.xls One more list of codes and their textual descriptions, which are to be shown in GUI. komkat2002 v2.xls This is the list of Norwegian county and municipality names and their numeric codes. PBL_formal.xls Another list of codes and their textual explanations. db.xml This is the configuration file for the Castor library, it describes connection to the MySQL database. This file is never edited manually in the source file set. When the application runs, the application administrator accesses and modifies its values through the Application Configuration page. PassordbrevAutomatisk.pdf This is an electronic form to be filled in and sent by . Mapping gui - xml.xls This is a table of user interface element visibility. It specifies whether a web page or a data box is visible to a user depending on conditions: type of application, user role, and so on. If a page or element is ticked with a cross in this table, then the web application shows it under these specific conditions. The table consists of two sheets. TreeMenu.xls, TreeMenuConfig.txt These two files form a pair, they provide almost full description for all the pages and data in the web site GUI: web page names, their location, data they contain, where these data are taken. These two files together with Mapping gui - xml.xls declare part of Java code functionality, this is a way to make it more visual and easier to modify, when necessary. During the build process, data from these three files form the object data dump file (image, TreeMenuConfig.ser), which better suits the launching of web site. fdf This subfolder is empty, not used. xml This subfolder contains single file, an XSD schema for the data to be sent back to municipality. This schema file is to be downloadable for a municipality user, this is ensured by means of URL to this XSD schema. The web application generates an XML file (plansak.xml) with the applicant s data and URL, and sends this file (plansak.xml) to the municipality. The web server itself does not use this XSD schema. 5 The whole build process is implemented by means of four build files mentioned above. To manually start building ByggSøk plan, first go to the root folder of the source file set and check file MakePlansak.bat for correct parameters of command line. Particularly, check the BUILDPATH system property of Java. Then start this file.

9 Page 9 of 14 It sets several Java system properties and launches Ant with file build.xml in this folder (the main build file). While running the main build file, Ant launches separate sessions with three files build.xml in turn, for the Castor library, the Common Services library, and Java Beans generator (see figure 1).

10 Page 10 of 14 Setting temporary paths Target Init Sets 5 properties CastorPatch / build.xml Target Compile Runs 3 build files in turn DataBeansGenerator / build.xml CommonServices / build.xml Target Compile_xls Creates application GUI map out of three files Target Compile_jsp Compiles JavaServer pages into Java classes Target Patch_web_xml Modifies file web.xml Target Dist1 Copies common and built libraries, configuration and property files, fonts, packs JAR with static content Target Dist Creates web application distribution file Figure 1 Steps of the main build file

11 Page 11 of 14 Setting temporary paths Target Init Creates 3 folders Target Compile Compiles patches for Castor Unpacks original Castor Updates original Castor with patches Target Dist Packs patched Castor library Figure 2 Steps of the Castor Patch build file Setting temporary paths Target Init Sets 4 properties Creates temporary folders Target Compile Compiles generator code Target Gen Runs generator, creates ddl.sql, map.xml and java beans Target Dist Copies 3 generated files to distribution Figure 3 Steps of the Data Beans generator build file

12 Page 12 of 14 Setting temporary paths Target Init Sets 6 properties, creates temporary folders Target Compile Compiles all source files Copies necessary non-source files to the compiled classes Target Dist Packs Common Services library Figure 4 Steps of the Common Services build file After Ant runs the build files to the end, the web application file will appear as: ${BUILDPATH}WAR/build/PlansakServer.war 6 Structure of the Resulting Web Application Package META-INF Contains almost empty file MANIFEST.MF. The JAR utility automatically creates it, just because it is obliged to. WEB-INF Contains all the web application components. File web.xml and server-config.vsdd are taken from the source file set. WEB-INF\classes Contains a pair of property files copied from the source file set. WEB-INF\config Contains configuration files of web application. For more about them, see the next chapter.

13 Page 13 of 14 WEB-INF\fonts Contains font files necessary for PDF documents, which the web application creates. WEB-INF\lib Contains all the libraries to be used by the web application. Most of them are copied from the Libs folder in the source file set. Other files here include: commonservices.jar This is the compiled contents of the CommonServices folder. patchedcastor.jar This is the compiled and rebuilt Castor library. databeans.jar This is the output of the Data Beans generator, it is archived into JAR file and put here as a library. jsps.jar The JSP files (pages from PlansakServer\ROOT\jsp) compiled into Java source files, then into Java classes and archived into JAR file. 7 Configuration Folder in the Distribution In the distribution, this folder path relative to the application root folder is: WEB-INF\config It contains the following files. AllResources.txt The copy of the same file from the configuration folder of the source file set. Bygningstypekoder.xls The copy of the same file from the configuration folder of the source file set. Formal - list 2.xls The copy of the same file from the configuration folder of the source file set. komkat2002 v2.xls The copy of the same file from the configuration folder of the source file set. PBL_formal.xls The copy of the same file from the configuration folder of the source file set. db.xml The copy of the same file from the configuration folder of the source file set. PassordbrevAutomatisk.pdf The copy of the same file from the configuration folder of the source file set. ddl.sql The generator creates this file during the building process. map.xml This is the file of mapping between databeans.jar and ddl.sql, it specifies relationship between Java objects (beans) and database. The Castor library needs this file to save (read) Java beans to (from) the database. The generator creates it, and then Ant copies it to the distribution.

14 Page 14 of 14 TreeMenuConfig.ser This is the object data dump file, Ant creates it from files Mapping gui - xml.xls, TreeMenu.xls and TreeMenuConfig.txt during the build process. staticcontent.jar This is the archive with static resources from the css, i, js subfolders of PlansakServer\ROOT (styles, pictures and javascripts). Since it is not a Java library, it is put here. fdf, xml The copies of the same subfolders from the configuration folder of the source file set. Note ejbddl.sql, orm.xml These files are an alternative for the pair of ddl.sql and map.xml, for the database of another DB server type, which currently is not used. The Castor generator creates them because this function is not disabled yet. Ignore these files both. 8 Reference Documents [1] Sun Microsystems Java Servlet 2.3 Specification. [2] JavaServer Pages (JSP) v1.2.