\chapter{Software architecture}
\section{Packets}
The software of the project is clearly separated in three big sets: the
\textit{application source code}, the \textit{tests source code} and the
\textit{installation files generation code}.
The application source code contains all the Java code, external libraries and
resource files needed to build an executable instance of the application
TaskStack.
The tests source code contains all the Java code used to test the developed
software.
The installation files generation code is a set of NSIS (Nullsoft
Scriptable Installation System) scripts, Bash scripts and resource files needed
to build the Windows and Debian Linux installers.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Tests}
\section{Need for tests}
I choose to use basic tests in this application for two basic reasons:
\begin{itemize}
\item It helps designing the software. We can adopt test-driven programming
and we can find lack of flexibility or functionality earlier in the project
when we are defining the tests.
\item It helps maintaining the quality of software that is likely to change in
the time. Since the functionality might change and the tests are more likely
to be static, any change in the software that makes a malfunctioning in some
related or unrelated functionality will be systematically detected.
\end{itemize}
\section{JUnit}
To test this project we chose JUnit. It provides an easy way to code, organize,
execute and collect results from tests.
JUnit tests are coded in Java classes. Its structure is the same as other java
classes, but a set of annotations define what is a test and what are the test
suites.
A test is a method containing a set of operations and some assertions about the
results of the operations. We can code the test methods in the same class to
test or we can create different classes containing test methods. Test methods
are only differentiated from the regular tests by adding a
\lstinline[language=Java]|@test| annotation.
\section{Design of the test suites}
The set of tests designed for this application would be defined as:
\begin{description}
\item[Basic test] because they only test the classes, its methods
and its algorithms. They do not test user functionality.
\item[Black-box test] because they do not check the internal state of the
classes but only its public methods and attributes.
\end{description}
In order to keep the main code clear, the tests were designed in a parallel
package structure. A new folder named test was created in the same level than
the folder src and the packet tree was duplicated there. Then the test for each
class is stored in the same package than the tested class, but in a different
src folder. It keeps the code organized and also keeps the main code clear.
This project has only one test suite composed of all of the available tests.
This is possible due to the small size of the project. There is no need to
separate the tests in different test suites because they are all basic test,
black-box test and they can be executed relatively fast.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{New version discovery service}
The TaskStack application is provided with an automatic new version discovery
system. Every time the application is launched it checks for new versions and it
offers to the user the option to open a web browser loading the project web
page, where to download the new version of the software.
Every time a new version of the application is released, a file containing the
name of the last version is uploaded to a web server accessible in the Internet.
The file is accessible by the application. Its content is downloaded in the user
computer and the version written in the file is compared with the installed
application version. If the version pointed by the file is higher than the
currently installed one, the application offers to the user the possibility to
download the last one.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{User preferences and application properties}
There is some set of variable information that the application must manage. This
information may vary during the cycle of development of the product or during
the cycle of use of the application. We will define two kind of variable
information depending of who and when does it change.
\begin{description}
\item[User preferences] are managed by the user. It's original value is
defined by the developer, but then it might be changed by the user many times
during the cycle of use. This information is user-dependent.
\item[Application properties] are managed by the developer. The user cannot
modify them. They are common for every user in the system. Their value is
updated by the programmer in every version of the product.
\end{description}
\section{User prferences}
User preferences are implemented with the Java preferences class:
\lstinline[language=Java,backgroundcolor=\color{yellow}]{java.util.prefs.Preferences}.
This class provides a way to store key/value pairs the OS file system. The way
the OS uses to access and store the information is hidden for the developer.
The following are examples of user preferences:
\begin{enumerate}
\item Default output directory for the log files.
\end{enumerate}
\section{Application properties}
Application properties are implemented with the Java Properties class:
\lstinline[language=Java]|java.util.Properties|. This class provides
a way to store key/value pairs in text files. The adopter format is
a .properties file. This file s composed by a set of key/value pairs written
each in a line in a plain text file. An $=$ symbol separates the key and the
value in each line. A global system is provided to manage property values all
along the application.
The following are examples of application properties:
\begin{enumerate}
\item Application version.
\item Application last version URL.
\end{enumerate}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Persistence}
The TaskStack application is provided with a persistence system that
allow the user data to persist from one execution to another.
TaskStack application persistence is based in a database. Keeping the data in a
database and accessing it from the outside we
can clearly separate the storage location from the application implementation.
In a first version of the program, the storage is performed in an embedded
database. In later versions, storage will be performed in a dedicated shared
database in the cloud. To effectively separate the database from the application
and simplify the implementation, Java Persistence API (JPA) was chosen. Direct
connection with JDBC has been ruled out because it needs for a implementation
of the storage and retrieval logic. With JPA, most of the work with the database
is automatically done. See the section \ref{sec:implementation:JPA} for more
information about JPA.
\section{Java Persistence API}
\label{sec:implementation:JPA}
Java Persistence API (JPA) is a Java framework that manages the mapping between
data classes and database tables and relationships in relational databases
(RDBMS).
It allows to persist objects in database and retrieve them from the tables
abstracting the programmer from the database details. Also the database
structure is created by the framework in the initialization of the program (if
it were not already created). The configuration of the mappings between data
objects and database records requires almost no programmer intervention. The
data classes meta information related with database storage is detailed in java
annotations in the java .class source file.
JPA is a standard and it does not impose an implementation. There are several
options as JPA implementations that can be considered. Among them, here are the
most famous ones:
\begin{description}
\item [Hibernate:] Probably the most advanced one. Not too stuck to the
standard JPA. It is generally said that it is difficult to switch from
Hibernate to other providers. It requires a lot of libraries that give
complexity and overweight to the project. Its license is GNU Lesser General
Public License (LGPL).
\item [TopLink:] Too simple. It lacks from the powerful options that other
libraries have. It is licensed under Oracle License.
\item [EclipseLink:] It was taken from TopLink. It has been chosen to be the
JPA implementation for the GlassFish server v3.0. It guarantees that this
project is going to be stable. It is simple, powerful and well documented.
It is easy to find examples and documentation in the Internet. It is
easily integrated with the Eclipse IDE, the tool that has been used for the
implementation of the project. Its license is Eclipse Public License, Eclipse
Distribution License.
\item [OpenJPA:] Very well documented and easy to use. This project still does
not show a mature state. Frequent bugs arise and it takes long time to get
fixed. Its license is Apache License 2.0.
\end{description}
For the implementation of TaskStack, the ease of use and the lightweight of
the JPA implementation was a requirement so, based on this, EclipseLink was
chosen.
\section{Database}
Regarding to the database selection, the same rule as with JPA implementation
has been applied. Ease of use and small overload of the project had been the
main constraints.
Derby database has been chosen because of:
\begin{itemize}
\item The programmer already has experience on it.
\item It is embedded, what simplifies the configuration.
\item It requires no installation. It is included with the software.
\item There are plenty of examples of use in the Internet.
\end{itemize}
In future versions, the local database would be substituted (on user request) by
a centralized remote database. This future database would be a more powerful
on-line database.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Versioning}
All the source code for the application, the tests the documentation and the
installers is under version control to allow:
\begin{itemize}
\item Bug corrections on stable not interfering with development versions
\item Maintenance of different versions
\item Bug tracking.
\end{itemize}
The address of the subversion repository is
\url{https://taskstack.svn.sourceforge.net/svnroot/taskstack}
Version naming follows the convention XX.YY.ZZZ-RRR where:
\begin{description}
\item[XX] Is the main number indicating ``commercial'' naming. Under the same
XX naming the system maintains the same design and aim. This number is not
likely to change very often. To increase the XX number a deep analysis has to
be done over the product and its future.
\item[YY] Is the functionality version. Every time the product incorporates a
new important functionality the YY number is increased.
\item[ZZZ] is the delivery number. Every time a version is delivered, its
delivery number is increased by one.
\item[RRR] is the \textbf{maturity} indicator. Maturity indicators do not keep
relation with the numbers that it follows. It indicates how reliable and
tested is the named version. Its values are explained in the section
\ref{sec:maturityDescriptors}
\end{description}
\section{Maturity descriptors}
\label{sec:maturityDescriptors}
\begin{description}
\item[Nightly build] versions are not tagged in the repository.
\item[P - Pre-Alpha] versions are marked as \textbf{P}. They include a new
functionality and no deep test has been done. Continuous development of
functionality is done in pre-alpha versions.
\item[A - Alpha] versions are marked with \textbf{A}. They are being tested
and no development is done on them. The functionality is frozen and only tests are
developed.
\item[B - Beta] Versions are marked with \textbf{B}. In beta versions all
basic testing is already done. It is offered to public test to discover new bugs.
usability test is done and minor changes are performed to get greater user
experience.
\item[RC - Release candidate] versions are marked with \textbf{RC}. Only bugs
are fixed and functionality is completely frozen.
\item[Stable - General availability] versions are marked with \textbf{Stable}.
General availability versions are the most updated and tested version for
every branch.
The application always tries to update to the next General Availability
version.
\end{description}
\section{Version Control System}
Versioning of source code is done in a Subversion repository. The repository is
organized as a regular Subversion one with three main folders: \textbf{trunk},
\textbf{Tags} and \textbf{branches}.
\begin{description}
\item[Trunk] folder allocates the last stable version.
\item[Tags] folder allocates the frozen versions, no mater what kind of
version they are.
\item[Branches] allocate main branches let them be main branches or
deliverable branches.
\end{description}
\section{Deliverables}
The deliverables of the project are some times stored in the Software Version
Control System. However this is not a good idea because it keeps a lot of space
and it is not necessary to store each version as long as the source code is
correctly labeled. This way every version of the deliverables would be easily
generated by compiling the frozen version used to compile it.
The correct place to store the deliverables of the product is in the SourceForge
storage service. There we can offer to the public the historical of all the
deliverables of the product.
\chapter{Releasing}
\label{sec:releasing}
Every time a new version of the product is generated and put on the internet
for public availability, a set of tasks is done in order to ensure that the
product is consistent. The process of releasing includes:
\begin{enumerate}
\item Pass the required test suite for acceptance.
\item Update changes log.
\item Create the version file that logs all the versions, their changes with
respect to the previous one and states what is the last stable version.
\item Create the executable jar for \TaskStack.
\item Test the jar in an ``user environment''.
\begin{enumerate}
\item Test it in Windows
\item Test it in Linux
\end{enumerate}
\item Create the installer for Windows.
\item Test the installer for Windows.
\item Create the installer for Debian Linux.
\item Test the installer for Debian Linux.
\item Generate the documentation files.
\item Upload the jar, the installers and the documentation files to
SourceForge.
\item Synchronize code with Subversion version control system.
\begin{itemize}
\item Source
\item Tests
\item Documentation sources
\end{itemize}
\item Upload the version file to its location in the Internet.
\item Check that the previous version is able to get the current version file
from the Internet and offers updates if (and only if) available.
\item Tag the current version in Subversion for sources, tests and
documentation.
\item Start a new branch or merge with the parent one when necessary.
\end{enumerate}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Apache Ant}
Apache Ant was used to automate the following tasks:
\begin{enumerate}
\item Generate the executable jars
\item Generate the version file
\item Copy the files from the development environment to the user system test
environment.
\item Help to automate the creation of the windows installer.
\end{enumerate}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Software installers}
The development of the application includes the development of two installer
applications: one for the Microsoft Windows operative system and another one for
Debian based Linux operative systems. Both of them provide an easy way to
install and un-install the application from the user system.
For the development of the installers for both platforms, free software tools
have been used.
\section{The Windows installer}
The \TaskStack~ Windows installer has been developed with Nullsoft
Scriptable Install System (NSIS). From the NSIS web page at
\url{http://nsis.sourceforge.net/Main_Page} we can see a description of the
system:
\begin{quotation}
NSIS (Nullsoft Scriptable Install System) is a professional open source system
to create Windows installers. It is designed to be as small and flexible as
possible and is therefore very suitable for Internet distribution.
\end{quotation}
NSIS installers are based on a script where all the process of installation and
un-installation is specified. Later this script is compiled to generate the
installation executable. The un-installation executable is also generated along
with the installation one and it is copied to the target machine during the
installation process.
\subsection{The Windows launcher}
To launch the \TaskStack~Java application as a regular Windows application an
.exe launcher was created. This launcher was created with a NSIS script and
compiled with the NSIS compiler.
\section{The Linux installer}
The \TaskStack~Linux installer was created as a Debian binary package. This is a
file with the extension \textit{.deb}. The Debian Packages can be installed and
un-installed easily with the operative system packages manager.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Libraries included in the project}
This is a list of the libraries included and its license.
eclipselink
lombok
ferramentas de creación do instalador para windows?
