SPECIFIC TARGETED RESEARCH PROJECT

INFORMATION SOCIETY TECHNOLOGIES

FP6-IST-2004-26727

Advanced eGovernment Information Service Bus

eGov-Bus

ODRA Web API Specification
Project 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 description
17.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 name
SBQL 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 / Description
id / 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 / Descriptions
id / 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 / Description
id / 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 / Description
id / 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 / Description
id / 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 / Description
id / 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 / Page
odra.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 / Page
BarLineChart / 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 / Page
private 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