SPECIFIC TARGETED RESEARCH PROJECT
INFORMATION SOCIETY TECHNOLOGIES
FP6-IST-2004-26727
Advanced eGovernment Information Service Bus
eGov-Bus
ODRA Web API SpecificationProject name: / Advanced eGovernment Information Service Bus
Start date of the project: / 01 January 2006
Duration of the project: / 24 months
Project coordinator: / Rodan Systems S.A.
Workpackage: / WP5
Actual submission date / 02.07.2007
Status / working
Document type: / Software documentation
Document acronym: / WP05_02
Authors(s) / Kazimierz Subieta, Mariusz Trzaska, Jacek Bekier
Reviewer(s)
Accepting
Location / WP05
Version / 01
Dissemination level / CO
Abstract:
The purpose of the document is to provide a complete ODRA Web API (Application Programming Interface) specification. ODRA Web is a technology allowing publishing data from an ODRA server on the web. The publication is performed using dedicated library (custom tag library) for the Java Server Pages (JSP). Please notice that this specification does not cover ODRA itself.The eGov-Bus consortium:
Rodan Systems (Rodan)Université Paris-Dauphine (ParisDauphine)
Europaisches Microsoft Innovations Center (EMIC)
Uppsala Universitet (UU)
Polsko-Japonska Wyzsza Szkoła Technik Komputerowych (PJIIT)
Axway Software (Axway)
Zentrum Für Sichere Informationstechnologie - Austria (A-SIT)
Ministerstwo Spraw Wewnętrznych i Administracji (MSWiA) / Coordinator
Partner
Partner
Partner
Partner
Partner
Partner
Partner / Poland
France
Germany
Sweden
Poland
France
Austria
Poland
History of changes
Date / Version / Author / Change description17.03.07 / 1.01 / Mariusz Trzaska / Document creation
21.06.07 / 1.02 / Mariusz Trzaska / Final version
Table of Contents
1.Introduction
1.1Page Definition
1.2Data Source Definition
1.3Bar-Line Chart Component
1.4News Component
1.5Poll Component
1.6Table Component
1.7Text Label Component
2.ODRA Web API Specification
Package odra.web.chartengine
Class BarLineChart
Class Chart
Package odra.web.data
Class DataSource
Class ResultConverter
Class ValueObject
Class ValueObjectList
Package odra.web.demoapp
Class DemoAppInstaller
Package odra.web.html
Class HTMLElement
Class StyleSheetPrinter
Class StyleSheetRule
Package odra.web.page
Class SBQLWebException
Class SBQLWebPage
Package odra.web.styles
Class BarLineChartComponentStyle
Class BasePanelComponentStyle
Class NewsComponentStyle
Class PollComponentStyle
Class TableComponentStyle
Package odra.web.tags
Class DataSourceTag
Class PageTag
Package odra.web.tags.components
Class BaseComponentTag
Class BasePanelComponentTag
Class ChartTag
Class NewsTag
Class PollTag
Class TableTag
Class TextLabelTag
Package odra.web.tags.styles
Class BarLineChartStyleTag
Class BasePanelStyleTag
Class NewsStyleTag
Class PollStyleTag
Class TableStyleTag
Package odra.web.util
Class CommonUtils
Class LineBuffer
List of Figures
11 ODRA Web library in action
12 Simplified class diagram of the implemented components
13 Sample utilization of the SBQL Web Page
14 Sample utilization of the SBQL Data Source object
15 Sample utilization of the Bar-Line Chart Component
16 Sample utilization of chart – source code for case 1
17 Sample utilization of chart – result for case 1
18 Sample utilization of chart – source code for case 2
19 Sample utilization of chart – result for case 2
110 Sample code illustrating utilization of the news component
111 Sample web page with the news component
112 Sample code illustrating utilization of the poll component
113 Web page containing the result of running sample code illustrating utilization of the poll component – question mode
114 Web page containing the result of running sample code illustrating utilization of the poll component – answer mode
115 Sample code describing table component
116 A table created using sample code
117 Sample code showing utilization of the Text Label component
118 Web page containing sample Text Label component
List of Tables
1 JSP tags for items of the object model
2 Tag sw:dataSource parameters
3 Chart component parameters
4 News component parameters
5 Poll component parameters
6 Table component parameters
7 Text Label component parameters
1.Introduction
ODRA Web Components is a library of user interface components parameterized by SBQL queries (see figure 1).Currently the library provides five distinct components:
- Bar-Line Chart Component - bar/line chart.
- News Component - list of articles.
- Poll Component - poll/survey component.
- Table Component - table.
- Text Label Component - line of text.
11 ODRA Web library in action
Figure 2 presents simplified Java class diagram of the implemented components. Notice that almost each of them is connected with appropriate style definition. Such a solution guarantees a separation between business logic and visual appearance of the data.
12 Simplified class diagram of the implemented components
Beside abstract types (SBQL Web Component, SBQL Web Component Style), every item of the object model, could utilized as a tag inside JSP page. Table show tags names for every item of the object model.
1 JSP tags for items of the object model
Object’s name / Tag nameSBQL Web Page / sw:page
SBQL Data Source / sw:dataSource
Bar-Line Chart Component / sw:chart
News Component / sw:news
Poll Component / sw:poll
Table Component / sw:table
Text Label Component / sw:textLabel
Bar-Line Chart Component Style / sw:chartStyle
News Component Style / sw:newsStyle
Poll Component Style / sw:pollStyle
Table Component Style / sw:tableStyle
Each of the components is associated with at least one SBQL query. The SBQL queries are used to retrieve the data presented in the component, or to save the information entered by the user. The system is designed to be used in conjunction with JavaServer Pages (TM) technology.
The system is distributed as 3 Java archive files:
- sbqlweb.jar - contains the custom tag library.
- demo.war - a sample web application designed with SBQL Web Components.
- demoapp-installer.jar - a helper tool. Connects to an ODRA server and adds the modules required to run the sample application.
The following steps are required to run the sample application "demo.war":
- Deploy demo.war to a J2EE web application server, e.g. Apache Tomcat 5.5.17 (copy "demo.war" to TOMCAT\webapps).
- Run ODRA server.
- Run demoapp-installer.jar ("java -jar demoapp-installer.jar").
- The sample application should be available at
Next subchapters describe each of the components with more details.
1.1Page Definition
Every JSP page using ODRA Web Components needs SBQL Web Page item. The SBQL Web Page object corresponds to the sw:page tag. The functionality of the tag (tag handler class) is implemented in the odra.web.tags.PageTag class. The only parameter is „id”, which is a unique identifier of the page. Figure 3 shows sample utilization inside JSP page.
13 Sample utilization of the SBQL Web Page
1.2Data Source Definition
A definition of the SBQL Web Page page could contains any number of SBQL Data Source objects responsible for a connection with an external instance of the ODRA server.
Counterpart of the SBQL Data Source object In the custom tags library is sw:dataSource, which functionality is implemented in odra.web.tags.DataSourceTag class. Table presents a list of tag’s parameters.
2 Tag sw:dataSource parameters
Parameter’s name / Descriptionid / Unique identifier of the object which is utilized in the connection with a data source.
host / Name of the machine where the ODRA Server is running.
port / Number of the port utilized in the connection.
user / Nam of the database user.
pass / Password of the user
module / Name of the module where the queries will be evaluated.
Figure shows a sample utilization of the component.
14 Sample utilization of the SBQL Data Source object
1.3Bar-Line Chart Component
15 Sample utilization of the Bar-Line Chart Component
Bar-Line Chart component allows embedding inside a JSP page bar-line chart. The presented data are retrieved from an ODRA database using defined SBQL query. Both line and a bars collection are optional. Thus it is possible to create a simple line chart or simple bar chart. Implementation details:
- tag handler class: odra.web.tags.components.ChartTag
- Tag’s name: chart.
Table 3describes component’s parameters.
3 Chart component parameters
Parameter’s name / Descriptionsid / Unique identifier of the object.
displayName / Presented name of the component.
dataSourceId / Identifier of the component’s data source.
width / Width of the component (in pixels). „auto” means automatic resizing according to the data width.
height / Height of the component (in pixels). „auto” means automatic resizing according to the data height..
styleId / Id of the component’s style.
query / SBQL query. The result of the query will be visualized on his chart.
collectionName / Query result parameter. Describes the name of a collection which is a source of data for this chart.
categoryFieldName / Query result parameter. Describes the name of an attribute which values are presented on x axis.
barFactFieldName / Query result parameter. Describes the name of an attribute which values are presented on bar chart. If there will be no value, the bar chart will not be shown.
lineFactFieldName / Query result parameter. Describes the name of an attribute which values are presented on line chart. If there will be no value, the line chart will not be shown
Figures from 6to 9present sample utilizations of charts together with the results.
16 Sample utilization of chart – source code for case 1
17 Sample utilization of chart – result for case 1
18 Sample utilization of chart – source code for case 2
19 Sample utilization of chart – result for case 2
1.4News Component
The News component allowing creating lists of articles or news. The current version is able to publish following information:
- Title of the news/article
- Creation date
- Content of the article Or news
Implementation details:
- tag handler class: odra.web.tags.components.NewsTag
- Tag’s name: news.
Table 4 describes component’s parameters.
4 News component parameters
Parameter’s name / Descriptionid / Unique identifier of the object.
displayName / Presented name of the component.
dataSourceId / Identifier of the component’s data source.
width / Width of the component (in pixels). „auto” means automatic resizing according to the data width.
height / Height of the component (in pixels). „auto” means automatic resizing according to the data height..
styleId / Id of the component’s style.
query / SBQL query. The result contains titles, dates and the contents of Publisher articles or news.
collectionName / Query result parameter. Describes the name of a collection which is a source of data for the component.
titleFieldName / Query result parameter. Points to a field containing titles of the articles/news.
dateFieldName / Query result parameter. Points to a field containing dates of the articles/news.
textFieldName / Query result parameter. Points to a field containing content of the articles/news.
Figures 110 and 111show a sample code and a corresponding www result page.
110 Sample code illustrating utilization of the news component
111 Sample web page with the news component
1.5Poll Component
The Poll component supports creating polls or surveys. There are two modes of working:
- Question; The question and possible answers are presented.
- Answer; The mode is activated after a user’s answer and show current results of the poll.
The poll component is the only one from the library which utilizes SBQL queries to send information from a client to a server. Query defined in parameter „submitVoteQuery” is used in case of Whiting user’s answer in a database.
Implementation details:
- tag handler class: odra.web.tags.components.PollTag
- Tag’s name: poll.
Table 5 describes component’s parameters.
5 Poll component parameters
Parameter’s name / Descriptionid / Unique identifier of the object.
displayName / Presented name of the component.
dataSourceId / Identifier of the component’s data source.
width / Width of the component (in pixels). „auto” means automatic resizing according to the data width.
height / Height of the component (in pixels). „auto” means automatic resizing according to the data height..
styleId / Id of the component’s style.
answersQuery / SBQL query which retrieves information about available answers.
collectionName / Query result parameter. Describes the name of a collection which is a source of answers for the component.
idFieldName / Query result parameter. Points to a filed containing id of the answer.
textFieldName / Query result parameter. Points to a filed containing text of the answer.
countFieldName / Query result parameter. Points to a filed containing number of answers voted on the particular answer.
questionTextQuery / SBQL query which retrieves text presented as a question in a poll.
submitVoteQuery / SBQL query which writes user’s answer in a database. Question Mark is replaced by id of the answer.
Figures 112, 113 and 114 show a sample code and a corresponding www result page.
112 Sample code illustrating utilization of the poll component
113 Web page containing the result of running sample code illustrating utilization of the poll component – question mode
114 Web page containing the result of running sample code illustrating utilization of the poll component – answer mode
1.6Table Component
The table component show data in a table form. The source of data is a SBQL query. The number and column’s name are configured using special parameter. Implementation details:
- tag handler class: odra.web.tags.components.TableTag
- Tag’s name: table.
Table describes component’s parameters.
6 Table component parameters
Parameter’s name / Descriptionid / Unique identifier of the object.
displayName / Presented name of the component.
dataSourceId / Identifier of the component’s data source.
width / Width of the component (in pixels). „auto” means automatic resizing according to the data width.
height / Height of the component (in pixels). „auto” means automatic resizing according to the data height..
styleId / Id of the component’s style.
query / SBQL query. The result contains data presented In the table.
collectionName / Query result parameter. Determines the name of a collection which is a source for data presented in the table.
fieldNames / Comma separated names of fields which values will be presented In the table. The number of fields corresponds to the number of table’s columns.
Figures 15 and 16show a sample code and a corresponding www result page.
115 Sample code describing table component
116 A table created using sample code
1.7Text Label Component
Text label component shows single value read from a database, i.e. a text or a number. On contrary to others component, visual properties of the Text Label object are not defined using separate style tag. The way of presenting information depends only on the location inside other HTML items, which describes visual format.
Implementation details:
- tag handler class: odra.web.tags.components.TextLabelTag
- Tag’s name: textLabel.
Table 7 describes component’s parameters.
7 Text Label component parameters
Parameter’s name / Descriptionid / Unique identifier of the object.
dataSourceId / Identifier of the component’s data source.
query / SBQL query which retrieves value show by the component. The result Has to be a single value.
Figures 15 and 16 show a sample code and a corresponding www result page.
117 Sample code showing utilization of the Text Label component
118 Web page containing sample Text Label component
The next chapter covers ODRA Web API in details. For a complete working example see attached source code.
2.ODRA Web API Specification
ODRA-IDE API
17.06.0719:20
Package Summary / Pageodra.web.chartengine / Provides classes for creating charts. / 2
odra.web.data / Provides the API for database access and query result processing. / 10
odra.web.demoapp / Contains the installation tool for the Demo Application. / 24
odra.web.html / Provides helper classes for creating HTML output and CSS rules. / 27
odra.web.page / Contains core classes related to the object model and exception handling. / 34
odra.web.styles / Contains classes related to the graphical properties of the components. / 40
odra.web.tags / Contains core JSP custom tags. / 67
odra.web.tags.components / Contains JSP custom tags representing the components. / 75
odra.web.tags.styles / Contains JSP custom tags for defining the graphical properties of the components. / 105
odra.web.util / Provides miscellaneous utility classes. / 128
-1–
© Copyright by eGov-Bus Consortium
Package odra.web.chartengine
Package odra.web.chartengine
Provides classes for creating charts.
See:
Description
Class Summary / PageBarLineChart / Represents a Bar-Line Chart. / 3
Chart / Base class for charts. / 8
Package odra.web.chartengine Description
Provides classes for creating charts.
-1–© Copyright by eGov-Bus Consortium
Class BarLineChart
Class BarLineChart
odra.web.chartengine
java.lang.Object
odra.web.chartengine.Chart
odra.web.chartengine.BarLineChart
final public class BarLineChart
extends Chart
Represents a Bar-Line Chart. The data is presented using a line, bars or both elements. Tha categories are displayed on X axis.
Field Summary / Pageprivate double[] / barFacts
The array of values displayed in the bar chart. / 4
private int / bottomMargin
The bottom margin size. / 5
private String[] / categories
The array of categories (labels displayed on X axis). / 4
private Font / font
The label font. / 5
private int / height
The height of the chart. / 5
private int / leftMargin
The left margin size. / 5
private double[] / lineFacts
The array of values displayed in the line chart. / 4
private double / maxValueYAxis
Helper variable for storing the maximum value on Y axis. / 5
private int / rightMargin
The right margin size. / 5
private BarLineChartComponentStyle / style
Defines the graphical properties of this BarLineChart. / 4
private int / topMargin
The top margin size. / 5
private int / width
The width of the chart. / 4
Constructor Summary / Page
BarLineChart(int width, int height, String[] categories, double[] barFacts, double[] lineFacts, BarLineChartComponentStyle style)
Constructs a new BarLineChart. / 6
Method Summary / Page
protected BufferedImage / createImage()
Creates an image containing the chart. / 6
private int / getDataAreaHeight()
Returns the height of chart data area (chart size excluding margins). / 7
private int / getDataAreaWidth()
Returns the width of chart data area (chart size excluding margins). / 7
private int / getValueTickmarksNumber()
Returns the number of tickmarks to be displayed in Y axis. / 7
private double / getYAxisMaxValue()
Calculates the maximum value to be displayed in Y axis. / 7
private void / paintAxisX(Graphics2D g)
Draws the horizontal axis. / 6
private void / paintAxisY(Graphics2D g)
Draws the vertical axis. / 6
Methods inherited from class odra.web.chartengine.Chart
writeImage
Field Detail