Developers Manual - Judy Paul

aquahellishSoftware and s/w Development

Dec 13, 2013 (3 years and 6 months ago)

77 views

DEVELOPER’S MANUAL

Table of Contents

Introduction

................................
................................
................................
................................
.................

2

System
Overview

................................
................................
................................
................................
.........

2

Requirements Summary

................................
................................
................................
............................

2

Site Map

................................
................................
................................
................................
....................

4

ERD

................................
................................
................................
................................
...........................

5

Environment Overview

................................
................................
................................
..............................

6

Server Information

................................
................................
................................
................................
....

6

List of Open Source Components Used

................................
................................
................................
....

6

Eclipse Information

................................
................................
................................
...............................

6

Tapestry Information

................................
................................
................................
............................

6

Hibernate
Information

................................
................................
................................
...........................

6

Maven Information

................................
................................
................................
...............................

7

Tomcat Information

................................
................................
................................
..............................

7

Environment Set Up Tutorial

................................
................................
................................
....................

7

Maintenance Standards

................................
................................
................................
............................

14

Code and I/O Standards

................................
................................
................................
..........................

14

Backup Procedure

................................
................................
................................
................................
...

18

Questions and Concerns

................................
................................
................................
...........................

18

Possible Concerns

................................
................................
................................
................................
...

18

Organization of Code and I/O Standards

................................
................................
............................

18

Limited
Backup Procedure

................................
................................
................................
.................

18

Known Issues

................................
................................
................................
................................
..........

19

CSS Design

................................
................................
................................
................................
.........

19

Cookie ID

................................
................................
................................
................................
............

19

Tomcat Deployment

................................
................................
................................
...........................

19

Troubleshooting

................................
................................
................................
................................
........

19

Most Common Errors
................................
................................
................................
..............................

19

List of Symptoms and Causes

................................
................................
................................
.............

19


Introduction



The goal of this manual is to provide future developers with insightful information about
the code, tools, components and design used to create the new e
-
commerce website for Judy Paul
at
www.judypaul.com
. This manua
l focuses on maintainability and scalability.


System Overview


The system is an e
-
commerce website with focus on selling paintings online and
providing information about upcoming events. It was designed based on a list of prioritized
requirements created

by the client. The requirements are divided into high (***), medium (**)
and low (*) as per specified by the client.



Requirements Summary


1.

Improve Painting Gallery

a.


Buying Process


*** Add new features to gallery so that customers will be able to view
different
paintings, and then choose size and format of each painting (e.g. original, small mounted
print, large mounted print, and postcard).


** Create search options to help customers find paintings more easily.


* Create keyword tags for each painting
to link it with other paintings by categories,
themes, colors, dimensions, etc.


* Integrate similar items on each painting’s page to provide easy access and higher
amounts of sales.


b.

Maintenance Process


*** Create add, delete, and modify paintings functi
onalities for Judy.


** Update website automatically when the database is changed and vice versa.



** Create intuitive and simple maintenance process, reducing the time Judy currently
spends updating the gallery.


2.

Create Shopping Cart


*** Incorporate
shopping cart feature into the website so that customers can store items
they wish to buy.


*** Purchase multiple items with one transaction, instead of individual transactions.
Continue shopping option after adding to shopping cart.


** Use cookies to mai
ntain the customer’s information on the shopping cart for a pre
-
determined number of days.


** Let PayPal handle all purchase transactions once the customer checks out.


3.

Add website expansion (news, events, eventual growth)


*** Include the following
characteristics in the website: paintings, events, news,
biography/artistic statement, links, contacts.


*** Add, delete, and modify Events on the website.


*** Add, delete, and modify News on the website (blog
-
style).


** Design the website for potential
future expansion. Judy should be able to create new
galleries, new links and new products.


4.

Change Layout


*** Create CSS to make the layout easy to maintain and modify


** Use Judy Paul’s vision and ideas to redesign the artistic design and layout of the
website.


5.

Integrate Current Mailing List


*** Create a link to sign up for mailing list on master page of website


** Customize mailing list to fit the website’s current layout


* Merge mailing list program features with website


6.

Integrate Search Optimiza
tion


** Create search optimization keywords on the website to have it ranked higher on search
engines




Site Map


JudyPaul
.
com
(
homepage
)
Paintings
.
html

Events
.
html

News
.
html

Links
.
html

Bio
.
html

Contact
.
html

PaitingsDetails
.
html

ShoppingCart
.
html

PayPal Login
Screen
Order
Confirmation
screen

JudyPaul
.
com
/
admin

Paintings
.
html

Events
.
html

News
.
html

EditLinks
.
html

EditBio
.
html

EditContact
.
html

AddPaintings
.
html

EditPaitings
.
html

Judy’s Public Pages

(
Customer Side
)
AddEvents
.
html

EditEvents
.
html

EditNews
.
html

AddNews
.
html

AddNewsPhoto
.
html

EditNewsPhoto
.
html

AddEventsPhoto
.
html

EditEventsPhoto
.
html

AddProductCategory
.
html

AddMenuLink
.
html

ChangeDesign
.
html

ManageWebsite
.
html

Pay
P
al
M
anages
P
ayments
Judy’s Private Pages

(
Admin Side
)

ERD

tblOriginalArtwork
PK
OriginalArtworkID

Title

Medium

DateCreated

OriginalLength

OriginalWidth

Image

Sold

Timestamp
tblCategories
PK
CategoryID

Type

Length

Width
tblProducts
PK
ProductID
FK
2
CategoryID
FK
1
OriginalArtworkID

Price
tblShoppingCart
PK
ShoppingCartItemID
FK
1
ProductID

CookieID
tblEvents
PK
EventID

EventTitle

DateofEvent

Description

Location

Address

City

State

Zip Code

TimeStamp
tblEmployee
PK
EmployeeID

EmployeeRole

FirstName

LastName

Biography

Password
tblEventPhotos
PK
EventPhotoID
FK
1
EventID

Description

ImageURL
tblNews
PK
NewsID

Title

Description

Timestamp
tblNewsPhotos
PK
NewsPhotoID
FK
1
NewsID

Description

ImageURL
tblMetaTags
PK
MetaTagID
FK
1
OriginalArtworkID

Tag
tblAdditionalDetails
PK
DetailID
FK
1
OriginalArtworkID

Description

Value


Environment Overview



The environment and the server offered the latest trend in development: Open Source and
the Cloud. The environment used for the project was Open Source components. The
development tool was Eclipse, which could be downloaded for both Windows and Open Source

Operational System (OS). The web framework chosen was Tapestry, with hibernate to connect
with the database and maven for the libraries. Tomcat was the web http server, which was hosted
by the Cloud


Amazon EC2.




Server Information



The host was Amazo
n EC2. More information about the host may be found at
http://aws.amazon.com/ec2/
. The client’s configuration for the host is:



Standard Instance



Elastic Block Store



S3 for backups


List of Open Source Components U
sed

1.

Eclipse Information


Eclipse is an open source community, whose projects are focused on building an open
development platform comprised of extensible frameworks, tools and runtimes for building,
deploying and

managing software across the lifecycle. The website for eclipse is:
http://www.eclipse.org/

The team used Eclipse IDE for Java Developers which may be downloaded at:
http://www.eclipse.org/downloads/



2.

Tapestry Information


Tapestry is an open
-
source framework for creating dynamic, robust, highly scalable web
applications in Java. Tapestry complements and builds upon the standard Java Servlet API, and
so it works in a
ny servlet container or application server. The website for tapestry is:
http://tapestry.apache.org/tapestry5/


The team used Tapestry 5, which may be downloaded at:
http://tapestry.apache.org/download.html



3.

Hibernate Information


Hibernate is a powerful, high performance object/relational persistence and query service.
Hibernate lets you develop persistent classes following object
-
oriented idiom


including
association, inheritance, polymorphism, composition and collections. The website for hibernate
is:
https://www.hibernate.org/



4.

Maven Information


Maven is a software project management and comprehensi
on tool. Based on the concept
of a project object model (POM), Maven can manage a project’s build, reporting and
documenting from a central piece of information. The website for maven is
:

http://maven.apache.org/



5.

Tomcat Information


Apache Tomcat is an implementation of the Java Servlet and Java Servlet Pages
technologies. The Java Servlet and Java Servlet Pages specifications are developed under the
Java Community Process. The website for Tomcat is:
http://tomcat.apache.org/


Environment Set Up Tutorial


Programs:

JDK 1.6

Apache Tomcat 5.5

Tapestry 5

Maven 2.0.10

Eclipse JEE

Hibernate

Derby

Tutorial

Configuring the Environment for Windows:

o

Download and install JDK 1.6
from:



http://java.sun.com/javase/downloads/index.jsp

(the second download button)

o

Find out where JDK was installed at (probably
C:
\
Program Files
\
Java
\
jdk1.6.0_07)

o

Now to change the Environment
Variables with Windows go to:



On Windows XP, select
Start > Control Panel > System
, and then select the
Advanced tab in the System Properties dialog.



On Windows Vista, select
Start > Control Panel > System and Maintenance >
System
, and then, in the left pa
ne, Advanced system settings.

o

You will see something like this:


o

Press the
Environment Variables

button, and you will see:


o

Check if there is a variable named JAVA_HOME on the bottom panel

o

If there isn’t one, then click on
New
. If there is one, then select it and click on
Edit
.

o

Make sure the
Variable Name

is JAVA_HOME and the
Variable Value

is the path to
your JDK folder (i.e.
C:
\
Program Files
\
Java
\
jdk1.6.0_12)

o

Now check if there is a variable name Path on the bottom panel

o

If

there isn’t one, then click on
New
. If there is one, then select it click on
Edit
.

o

Make sure the
Variable Name

is Path and the
Variable Value

is the path to your JDK’s
bin folder (i.e.
C:
\
Program Files
\
Java
\
jdk1.6.0_07
\
bin)

Install and Extract Tomcat

o

Do
wnload Tomcat from:



http://www.hightechimpact.com/Apache/tomcat/tomcat
-
5/v5.5.27/bin/apache
-
tomcat
-
5.5.27.zip


o

Extract to an easily accessible folder

Install and Launch Eclipse


http://www.eclipse.org/downloads/

(Eclipse IDE for Java EE Developers (163 MB))

Define the JDK

o

Window

>
Preferences

o

Java

>
Installed JREs

o

Add

JDK 1.6 if necessary (not JRE 1.6)

o

Add
>

Standard VM

>

JRE Home: (browse to your jdk 1.6 folder)

o

Then remove the other JRE file

Define Settings

o

Window

>
Preferences

o

Type “content”

o

Select
Content Types

o

Click on
Text

>
HTML

and then click on Add

o

Add .tml


Define a server Runtime

o

Window

>
Pre
ferences

o

Server

>
Runtime Environments

o

Click
Add

o

Select Apache >
Apache Tomcat v5.5

and click
Next

o

Browse

to and select your Tomcat folder

o

Select JDK 1.6 and click
Finish

Define a Server Instance

o

Window

>
Show View

>
Other

o

Open the

Server

>
Servers view

o

Right click on the Servers view and click
New

>
Server

o

Select Apache >
Tomcat v5.5 Server

and click
Finish

Installing M2Eclipse

o

Open Eclipse

o

Select
Help

o

Select
Software Updates


o

Expand
Maven Integration for Eclipse Update Site

o

Select
Available Software
Tab

and click on
Add Site
:



http://m2eclipse.sonatype.org/update/

o

Check
Maven Integration

o

Expand
Maven Optional Components

> Check
Maven Central Repository Index

o

Expand Maven Project Configurat
ors > Maven Integration for WTP

o

Click
Install

o

Follow the wizard

Create a Skeleton Tapestry Project

o

Open Eclipse

o

Select File> New > Other

o

Expand Maven and select Maven Project

o

Click Next

o

Find group id: org.apache.tapestry, artifact id: quickstart (it might

need to download the
indexes on the first try, so just click back and then next again once it finishes
downloading)

o

For “groupId:”


Anything is fine (this is group to which the project belongs to, i.e.
com.example)

o

For “artifactId:”


Anything is fine (t
his is the name of the project, i.e. HelloWorld)

o

For “package:”


Anything is fine (makes logical sense if you name this your
groupID.artifactID, i.e. com.example.HelloWorld)

o

Click finish

o

Expand your new project folder and right click on JRE System
Libraries

o

Select
Properties

o

Select
Workspace Default

o

To check if it works:



Right click on your project folder and select Run As > Run on Server



Select the tomcat server your previously set up




Open a browser and go to:



http://localhost:8080/(project

name)



Now whenever you want to run it, just select the Run As arrow on your toolbar
and click on your project name

o

A couple of warnings might pop up but you can ignore them. If it bothers you, you can
either: dele
te the layout files, or right click on each warning and select quick fix.

Derby


There are two separate Eclipse plugins for Derby:

o

derby_core_plugin
-

provides the Derby jar files to other plugins in Eclipse.



http://mirror.jimbojay.com/apache/db/derby/db
-
derby
-
10.4.2.0/derby_core_plugin_10.4.2.zip


o

derby_ui_plugin
-

provides an Apache Derby Nature in Eclipse for easy database
application development.



http://mirror.jimbojay.com/apache/db/derby/db
-
derby
-
10.4.2.0/derby_ui_plugin_1.1.2.zip

o

Download and extract these two zip into your eclipse home directory
(i.e. c:
\
eclipse)

o

Add to your pom.xml file:

<
dependency
>

<
groupId
>
org
.
apache
.derby
</
groupId
>



<
artifactId
>
derby
</
artifactId
>



<
version
>
10.4.2.0
</
version
>

</
dependency
>

Hibernate Tools

o

Open the pom.xml file and add this somewhere under <dependencies
>:


<
dependency
>


<
groupId
>
org
.
apache
.tapestry
</
groupId
>


<
artifactId
>
tapestry
-
hibernate
</
artifactId
>


<
version
>
${tapestry
-
release
-
version}
</
version
>


</
dependency
>

<
dependency
>




<
groupId
>
org
.
apache
.derby
</
groupId
>




<
artifactId
>
derby
</
artifactId
>




<
version
>
10.4.2.0
</
version
>

</
dependency
>

o

http://www.hibernate.org/30.html

o


Download Hibernate tools and unzip to the eclipse home

o

Configure the connection

o

Right click on your project and
select New > Other

o


Selected Hibernate>Hibernate

o


Click Next

o


Change the settings to:

o


Database Dialect: Derby

o


Driver class: org.apache.derby.jdbc.EmbeddedDriver

o


Remember the database URL you previously saved?



Connection URL: Copy and paste that URL

o


UserName: test

o


Password: test

o


Check: Create a console configuration



Project: Your project name



Database Connection: Your connection name



Configuration file: Your configuration file

o


Click Next

o


Name: Shop (Or anything you want)

o

After the hibernate.cf
g.xml file is created, open it and add this after your other properties:



<
property

name
=
"hbm2ddl.auto"
>
update
</
property
>




<
property

name
=
"hibernate.show_sql"
>
true
</
property
>



<
property

name
=
"hibernate.format_sql"
>
true
</
property
>

o

Now if you open th
e hibernate perspective, and expand your configuration file, you
should see your previously created database tables

SVN Repository

o

Open Eclipse

o

Install Subclipse by adding this URL to:
Help

>
Software

Updates




http://subclipse.tigris.org/update_1.4.x


o

Install all three of the folders (subclipse and the extra libraries)

o

Go to
Windows

>
Preferences

>
Team

>
SVN

o

For
Client

Select
SVNkit (Pure Java)

o

Go to SVN re
pository perspective

o

Right click, new

o

svn+ssh://svn.trsvax.com/u2/svnrepo/

o

Try the password Barry gave us through email

o

Right click > Checkout project to save project into your workspace

Adding extra T5 Chenillekit Components


Add this to your pom.xml fil
e

<
dependency
>


<
groupId
>
org
.
chenillekit
</
groupId
>


<
artifactId
>
chenillekit
-
tapestry
</
artifactId
>


<
version
>
1.0.0
</
version
>

</
dependency
>

<
dependency
>


<
groupId
>
org
.
chenillekit
</
groupId
>


<
artifactId
>
chenillekit
-
hibernate
</
artifactId
>


<
version
>
1.0.0
</
version
>

</
dependency
>

<
dependency
>


<
groupId
>
org
.
chenillekit
</
groupId
>


<
artifactId
>
chenillekit
-
access
</
artifactId
>


<
version
>
1.0.0
</
version
>

</
dependency
>

<
dependency
>


<
groupId
>
org
.
chenillekit
</
groupId
>


<
artifactId
>
chenillekit
-
google
</
artifactId
>


<
version
>
1.0.0
</
version
>

</
dependency
>

<
repository
>

<
id
>
chenillekit
</
id
>

<
url
>
http://www.chenillekit.org/mvnrepo/release
</
url
>

<
snapshots
>

<
enabled
>
true
</
enabled
>

</
snapshots
>

</
repository
>


Now go learn tapestry/java and start coding!


Maintenance
Standards


Code and I/O Standards

Purpose:

Coding standards will help the developers create a uniform structure
which could be easily maintained and fixed. The uniform coding standards will
also allow our client to be able to further expand the system if
it is required.


Naming Conventions:

Database objects will be named with one of these three
-
letter prefixes depending on its purpose:

OBJECT
TYPE

PREFIX

Table

tbl

Query

qry

Variables will be named with one of these three
-
letter prefixes depending on its
data
type:

DATA
TYPE

PREFIX

String

str

Integer

int

Double

dbl

Float

flt

Date

dat

Boolean

bln


Project Architecture:

Java class files will be placed in these defined
folders depending on its content and purpose:

FOLDER NAME

DESCRIPTION

Data

Java classes defining data properties from the database will be placed inside
this folder.

Entities

Classes which create data that does not need to be saved into the database
will

be placed inside this folder.

Pages

The classes of the actual pages that will show on the website will be placed
inside this folder.

Util

Utility classes that can be reused will be placed inside this folder.


Comments:

Comments will be used to briefly

describe the purpose of a class. Due to our client’s request,
comments will not be used to define the code.




INPUT / OUTPUT STANDARDS


Purpose
:

I/O standards are defined to ensure that the user will be able to use the system with
ease and efficiency.
The standards listed below are based on the client’s current layout of her
website. Our team will work with
Judy Paul

throughout the designing process to optimize the
user experience.


Formatting Standards for Screens (resolution of 800 x 600 pixels):


HEADER:

Background color value =
White

Background image = outside_in_3.jpg

Width = 748 pixels

Height = 10
8

pixels

Title:
Palatino

16pt

(right on the banner
)

BODY:

Background color value = White

Height: Variable

Subtitles:
Palatino
,

12pt, Bold, #990000

Text Boxes / Labels:
Palatino

1
1
pt
, Gray

Buttons:
Palatino
,

12pt, Bold, #990000

Buttons Dimensions: 142 X 31 pixels

Button image: redGradient.jpg

FOOTER:

Background color value = White

Font:

Palatino, 14pt, Bold, #990000

Height = 50 pixels


Formatting Standards for Printable Reports:


ORIENTATION:

Portrait

BODY:

Title:
Palatino

h3 size
, Bold,
#990000

Subtitles:
Palatino

h4 size
, Bold,
#990000

Text
:
Palatino

1
1pt,
black

Data: Palatino 11
pt, black











Screens
Examples:




Backup Procedure


The backup procedure chosen by the team was a CSV uploader. The uploader

is located
on the admin site of the website, under the settings button on the menu. The idea is that a
spreadsheet with all the products and their information is created, which the client may use in
case all the information is lost.

The interface on the w
ebsite is simple to use and as long as the spreadsheet is kept up to
date, the client will have a fresh backup with all the information contained on the products.



Questions and Concerns


Possible Concerns


1.

Organization of Code and I/O Standards


The organization of the Code and I/O Standards are limited. The client’s husband, Barry,
who will be most likely maintaining the website in case of more complex problems, advised the
team with the current standards in place.

Although the standards followe
d by the team are different from the norm, it should not be
hard to understand. The code follows the Object Oriented structure. It is fragmented into many
layers to provide better understanding of the program. It also facilitates isolating problems.


2.

Limit
ed Backup Procedure


The team has a backup procedure in place for Judy to use, however, it is limited to a CSV file
and file uploader. The file uploader is found in the website admin side.

The procedure is limited for a few reasons:

1.

The backup is limited
to the sections of products in the spreadsheet,

2.

The backup will be outdated as the client adds more products to the website,

3.

No other information such as events, news and personal information will be backed up,

These limitations provide a faulty backup.
Due to time constraints and limited knowledge,
however, it was the best the team could do.






Known Issues


1.

CSS Design Change


When the project ends on May 14, 2009, the CSS design will be inaccessible to the client,
because of its location in the serve
r. Barry, the client’s husband, is responsible for placing the
design
-
related files into a folder which will be accessible to the client. The files related to the
layout are:



Layout.tml



Layout.java



Judypaul.css

The Judypaul.css is referenced in the
layout.java file. Any further fragmentation of the CSS
files or changes to the CSS must be referenced in the layout.java file.


2.

Cookie ID


The shopping cart creates a cookie ID for each customer that visits the website. The idea is
that the customers may k
eep their shopping cart saved without the need to log in or create a
profile. The limitation of this method is that cookie IDs will be continuously stored in the
database. Once in a while, the database will need to be cleared of the cookie IDs. Barry has
v
olunteered to do it when he flushes his databases, which are also located in the server.


3.

Tomcat Deployment


Tomcat may be deployed at most 4 (four) times a day. More than that and the server stops
responding. The result is that the server must be rebooted
. This is a known issue in Tomcat and
should not be a problem as long as the limitation is respected.


Troubleshooting


Most Common Errors


There was only one which were left and not fixed by the team. Because it involves a very
simple solution but a very
complex modification in the code, it was not a priority.


List of Symptoms and Causes


Symptom: Random Characters on the Screen

Cause: Blob leak

Solution: Refresh browser’

Screenshot: