DataSource Programming: Overview

Web Central data access layer implements declarative object-relational mapping, secure data access, and transparent data localization using metadata defined in Archibus data dictionary.

The DataSource is a programming interface to the Web Central data access layer. You can define the DataSource in an AXVW file, or create it programmatically in Java code. When you use the DataSource to read or write some data, it transparently performs Archibus-specific processing:

• Applies Archibus security: checks whether the current user has read/write permissions for fields.
• Applies current user VPA restrictions (if they are applicable to the query table/fields).
• For tables with localized fields, chooses fields according to the current user locale.
• Converts data values from database-specific formats to Java objects and back.
• Generates SQL queries using database-specific SQL dialect.
• Handles transactions and exceptions, maps database-specific exceptions to Archibus user-friendly exceptions.
• Optionally formats data values for the current user locale.

The following are general rules:

• In the application, Java code should operate on Java objects, and not on string values.
• The String data type should not be used to represent numeric or date/time values in calculations or business logic.
• The application code should not operate on strings formatted for database-specific SQL dialect, or values returned by JDBC driver.
• In Web Central, the application code should not access JDBC directly and bypass the Archibus data access layer. In particular, the code should never directly read schema tables such as Archibus Tables and Archibus Fields .

Data records loaded by the DataSource are represented as instances of the com.archibus.datasource.data.DataRecord class in the event-handler Java code.

DataRecord field values are Java objects whose type corresponds to the Archibus field type:

• String
• Integer
• Double
• Date
• Time

The diagram below shows how the data objects are interchanged between Web Central application layers.

The Archibus neutral format is defined as a String produced by the toString() method of a corresponding Java class, except for date/time types. The date and time neutral formats are defined in \WEB-INF\config\context\compatibility\afm-config.xml, in preferences\locale element. The time format is defined with three digits for milliseconds, so that precise time values would survive the roundtrip from the database to the client and back. This is especially important for time values used as primary keys. The date format is defined with four digits for year.