GeoLog
Design Description
Version 1.0
Doc. No.:
GeoLog
Design Description
Version:
1.01
Date: 2007-11-25
Revision History
Date
Version
Description
Author
2007-11-25
0.1
Initial Draft
Juraj Misur
2008-01-24
1.0
Final version
Ana Petricic
Page 3
GeoLog
Design Description
Version:
1.01
Date: 2007-11-25
Table of Contents
1.
2.
Introduction
5
1.1
1.2
1.3
1.4
Purpose of this document
Intended Audience
Scope
Definitions and acronyms
1.4.1 Definitions
1.4.2 Acronyms and abbreviations
1.5
References
5
5
5
5
5
6
6
External interfaces
7
2.1
3.
4.
5.
Web interface
2.1.1 Anonymous user interface
2.1.2 Registered user interface
2.1.3 Content administration pages
2.1.4 System administration pages
7
7
8
10
10
Software architecture
11
3.1
Conceptual design
3.1.1 High-level Overview
3.1.2 Internal design
3.2
System specification
3.2.1 File system structure
3.2.2 Database specification
3.3
Error handling
11
11
12
13
13
15
17
Detailed software design
17
4.1
4.2
4.3
4.4
17
17
17
17
Web tier
Core tier
Database tier
Integration
Approvals
18
Page 4
GeoLog
Design Description
Version:
1.01
Date: 2007-11-25
1.
Introduction
1.1
Purpose of this document
This document contains detail information about GeoLog project design and technologies used. It
should help reader gain knowledge about project architecture, design and its overall working.
1.2
Intended Audience
Intended audience of this document is:
 customers, who need to know detail specifications of this project in order to evaluate
work which has been done or for later continuation
 supervisors, who need to supervise this project
 members of project, who need to know design details in order to develop correctly
 other developers, who may later continue with development of this project
1.3
Scope
All programming parts of project – Web, Core and Tier - are explained in detail as well as high-level
architecture, internal architecture, project management specific details such as file system structure,
database specification and technologies used in every part.
1.4
Definitions and acronyms
1.4.1
Definitions
Keyword
location
location category
content
registered user
privileged user
content administrator
system administrator
Hibernate
Spring
Definitions
Specific place to write about
Groups of locations with similar contents
Articles and comments for specific location
Ordinary user (non privileged), whose content need to be checked before
publishing
User with good ranking and much content published. His articles are
published immediately before CA approval
A person who checks and approves articles/comments, takes care of
registered users and adds new location categories. He can also do
everything that normal user can for example writing articles, giving
comments, etc.
A person who is in charge of maintenance GeoLog system and takes care
of assigning content administrators by location categories
Object/Relational mapping technology
Layered Java/J2EE application framework
Page 5
GeoLog
Design Description
1.4.2
Acronyms and abbreviations
Acronym or
abbreviation
JSP
CSS
SA
CA
SQL
DAO
1.5
Version:
1.01
Date: 2007-11-25
Definitions
JavaServer Pages technology used for creating dynamic web pages
Cascading Style Sheets technology used for customizing web page design
System Administrator
Content Administrator
Structured Query Language
Data Access Object - a design pattern used in software engineering
References
These GeoLog project documents are available at FER http://www.fer.hr/rasip/dsd/projects/geolog
 GeoLog Project Description
 GeoLog Installation Manual
 GeoLog Requirements Definition
 GeoLog Technical Documentation
Other related technological references:
 JSP - http://java.sun.com/products/jsp/
 CSS - http://www.w3.org/Style/CSS/
 Spring framework - http://www.springframework.org/
 Hibernate - http://www.hibernate.org/
Page 6
GeoLog
Design Description
2.
Version:
1.01
Date: 2007-11-25
External interfaces
The external interface for user interaction is Web interface, which is dynamically created using JSP,
Java servlets and JavaScript for handling user input and CSS technologies.
After authentication, user interface will be customized and user will be able to perform custom
operations depending on his/her role.
Adding content is intended to be as easy as possible from any page.
2.1
Web interface
2.1.1
Anonymous user interface
Every user is able to perform basic operations such as searching for locations and viewing all content,
around which are focused all user actions.
Picture 1 – Searching for locations in various ways
Page 7
GeoLog
Design Description
Version:
1.01
Date: 2007-11-25
Picture 2 – Viewing an article
2.1.2
Registered user interface
After authentication, user menu is customized and user is able to perform custom operations depending
on his/her role.
Registered users can add new content to existing locations or can propose new location. Also,
registered users can report inappropriate content to content administrators.
Page 8
GeoLog
Design Description
Version:
1.01
Date: 2007-11-25
Picture 3 – Searching for locations in various ways and adding new location
Page 9
GeoLog
Design Description
Version:
1.01
Date: 2007-11-25
Picture 4 – View of an article and direct location menu for adding content
2.1.3
Content administration pages
Registered users with CA role have access to content administration pages. CA interface consists of
several tabs for each content type that CA administers:
 Users tab – for administering users, CA can view user profile for each user and ban user
 Articles tab – for approving/rejecting articles published in categories assigned to particular CA
 Comments tab – for approving/rejecting comments published in categories assigned to
particular CA
 News tab – for publishing news
Picture 5 – CA interface, approving an article
2.1.4
System administration pages
System administrators also have a special interface which has several tabs:
 System properties tab – setting system properties
 Users tab – administering users; changing user’s profile, deleting users
 Content admins tab – administering content administrators; assigning new CAs, removing
CAs, changing categories assigned to existing CAs
 News tab – publishing news, deleting existing news
Page 10
GeoLog
Design Description
Version:
1.01
Date: 2007-11-25
Picture 6 – SA interface, changing system properties
3.
Software architecture
3.1
Conceptual design
This chapter is divided to high-level overview, which is needed by customer to know how GeoLog will
interact with other external applications and what will be its behavior when deployed.
3.1.1
High-level Overview
Since GeoLog is standard web application, it will be deployed in Java Web Server of some kind. This
server will provide runtime environment for the project and handle all communication with clients. As
standard web application it needs a database server, which can be on the same machine or outsourced
to another machine.
Page 11
GeoLog
Design Description
Version:
1.01
Date: 2007-11-25
Picture 7 – High-level overview
3.1.2
Internal design
Project is internally divided into three separate parts: Web, Core and Database Tier which brings
granularity and separation of concerns during development of further enhancement. These tiers are
communicating through interfaces and are wired together with Spring framework. These interfaces,
together with business objects construct API, which can be considered as separate part (and it’s also
divided from other parts in directory structure). Overall view is on Picture 8 – Internal architecture and
further details about internal structure of the project are explained in section 4 Detailed software
design.
Page 12
GeoLog
Design Description
Version:
1.01
Date: 2007-11-25
Picture 8 – Internal architecture
3.2
System specification
3.2.1
File system structure
Directory structure of the project is divided into 3 programming parts corresponding to tiers + API and
one special directory for documentation. Programming parts contain separate subdirectory for main
code development and for testing purposes. These subdirectories are further separated to java (actual
packages and code) and resources (configuration files, etc.) folders as seen on Picture 9 – File system
structure.
Picture 9 – File system structure
Page 13
GeoLog
Design Description
Version:
1.01
Date: 2007-11-25
Java package created for this project is hr.fer.dsd.geolog which is further divided into few subpackages as seen
on Picture 10 – Java packages. Subpackages are:
 Dao – interface and implementation for communication between Core and Database tier
 Exception – custom project exceptions
 Model – business objects (domain models)
 Service – interfaces and implementations for communication between Web and Core tier
 Web – package containing all Web tier related source files
Picture 10 – Java packages
Description of all files within each directory:
Directory
api
core
db
web
doc
*/main/java
*/main/resources
*/test/java
*/test/resources
web/webapp
doc/GoogleMaps
doc/Data Dic
doc/Design
doc/Meeting
doc/Test
Description of the files
Source files for API
Source files for Core implementation
Source files for Database implementation
Source files for Web implementation
Documentation files
Source files for main development
Resource files for main development
Source files for testing
Resource files for testing
Further resources for Web development and deployment
Google Maps API specific files
GeoLog design files
Page 14
GeoLog
Design Description
3.2.2
Version:
1.01
Date: 2007-11-25
Database specification
Database tables correspond to domain models and there are some additional tables:
 System_properties – for remembering ranking boundary and article rank boundary and
similar system-wide properties
 Cat_loc – relation between categories and locations; which location belongs to which
categories
 Cat_user – relation between users and categories; which user (CA) oversees which
categories
 Art_user – relation between articles and users; which user voted for which article for not
allowing user to vote for one article more than one time
Page 15
GeoLog
Design Description
Version:
1.01
Date: 2007-11-25
Picture 11 – Database schema
Page 16
GeoLog
Design Description
3.3
Version:
1.01
Date: 2007-11-25
Error handling
Error handling is managed with java exceptions. These are:
 DataAccessException – generated in Database tier and automatically propagated through
all tiers up to Web tier. This exception means that there has been some error with
database access. It’s a runtime exception, so it doesn’t need to be catched; and it can be
handled globally. This exception is fatal and cancels operation.
 IllegalArgumentException – might be thrown if there was some illegal argument passing
between tiers. Should be absolutely eliminated after proper testing. This exception is fatal
and cancels operation.
The API specifies some checked exceptions. These exceptions are used in contexts where the use case
execution should continue after the error, these are:
 An AuthorisationException is thrown if the user passed as an argument does not have the
required role for performing an operation.
 An OperationFailedException is thrown if a use case part could not be executed (for
instance mail sending failed or the registration code specified in the user confirmation
process is invalid).
 An DuplicateUserException - signals that a user name to be registered is already in use.
 An MailException - signals a problem during mail sending.

User input errors in web pages such as forms will be handled directly in user’s browser or upon posting
to server. These errors will be handled specifically for action performed by user.
Authentication and authorization errors are handled using Acegi framework. Fro more information see
GeoLog Technical Documentation.
4.
Detailed software design
4.1
Web tier
Web tier is made of dynamic JSP pages. It acts as a user interface to GeoLog. It provides the front-end
to the core API.
4.2
Core tier
Core (or business) tier is responsible for main business logic of GeoLog. It consists of implementations
of services (interfaces) between Web and Core tier. It doesn’t use any specific technology. Many
methods are just direct delegations to corresponding Database tier methods.
4.3
Database tier
This tier is just implementation of IGeoLogDao interface between Core and Database tier. It uses
Spring as abstraction above Hibernate technology. In order to use Hibernate, there are corresponding
mapping files *hbm.xml for each domain model. These mapping files are used by Hibernate to provide
automatic mapping between domain models and database tables.
Database tier is also using second-level caching to provide optimal performance. Many caching
libraries are integrated directly in Hibernate; the chosen one is EHCache. This library is fast and
efficient. It can be easily swapped to another if there is need to support distributed caching.
4.4
Integration
All tiers and configuration files are wired together using Spring framework. This framework provides
easy and powerful integration of project components via configuration files using Inversion of Control
and Dependency Injection.
Spring also provides facilities for Aspect Oriented Programming which are used for automatic
Page 17
GeoLog
Design Description
Version:
1.01
Date: 2007-11-25
transaction support on method level in Database tier.
5.
Approvals
Name
Title
Date
yyyy-mm-dd
Signature
Page 18