Download Solar Opportunity

SFSU – COMPUTER SCIENCE DEPARTMENT
Solar Opportunity
EXTERNAL DOCUMENTATION
This document aims to help future developers understand the implementation details of the Solar
Opportunity application.
Solar Opportunity
TABLE OF CONTENTS
TABLE OF CONTENTS..................................................................................................................................... 1
1.
SYSTEM OVERVIEW ............................................................................................................................... 2
2.
SUB-SYSTEM DESCRIPTION ................................................................................................................... 2
2.1
SOLAR ADMIN ............................................................................................................................... 3
2.1.1
FEATURES / FUNCTIONALITY................................................................................................. 3
2.1.2
UI ........................................................................................................................................... 4
2.1.3
IMPLEMENTATION DETAILS .................................................................................................. 5
2.1.3.1
SEQUENCE DIAGRAMS .......................................................................................................... 6
2.1.3.2
SYSTEM FLOW ....................................................................................................................... 8
2.1.3.3
JSP PAGES & FILTERS ............................................................................................................. 9
2.1.4
CLASS DIAGRAMS ................................................................................................................ 11
2.1.5
DATA FLOW DIAGRAMS ...................................................................................................... 14
2.1.6
SEARCH & NOTIFY / GENERATE LETTERS ............................................................................ 15
2.1.6.1
HOW-TO GENERATE LETTERS & UPDATE DATABASE.......................................................... 17
2.1.7
CODE LOCATION.................................................................................................................. 29
2.2
ROOF SELECTOR .......................................................................................................................... 31
2.2.1
FEATURES / FUNCTIONALITY............................................................................................... 31
2.2.2
UI ......................................................................................................................................... 31
2.2.3
IMPLEMENTATION DETAILS ................................................................................................ 32
2.2.3.1
SEQUENCE DIAGRAM: ......................................................................................................... 35
2.2.3.2
ROOFDATA – XML SCHEMA ................................................................................................ 36
2.2.3.3
EXAMPLE AREA CALCULATION ............................................................................................ 38
2.2.3.4
XML to ROOFDATA CONVERSION ....................................................................................... 40
3.
SUB-SYSTEM INTERACTION ................................................................................................................. 40
4.
SETUP .................................................................................................................................................. 44
5.
OTHER DOCUMENTATION .................................................................................................................. 46
6.
DATA GLOSSARY / REFERENCES .......................................................................................................... 46
Solar Opportunity – External Documentation
Page 1
Solar Opportunity
1. SYSTEM OVERVIEW
The following figure gives a high level description of how the Solar Opportunity application
works. The application itself and the database reside on the server (barlev.sfsu.edu). The
application communicates with the Oakland GIS server to retrieve GIS Image for a particular
property. The RoofData selected by the user is saved to the database. The RoofData for a
particular property can be retrieved from the database.
Figure 1
Detailed description of each component and how they interact with one another is provided in
the following sections.
2. SUB-SYSTEM DESCRIPTION
The Solar Opportunity application has two sub-systems /modules:
a) Solar Admin
b) Roof Selector
Solar Opportunity – External Documentation
Page 2
Solar Opportunity
2.1
SOLAR ADMIN
2.1.1
FEATURES / FUNCTIONALITY
The Solar Admin module provides the following features:






Login
Logout
Create / Edit Account
Database Update
Search & Notify
Launch Roof Selector applet
Solar Opportunity – External Documentation
Page 3
Solar Opportunity
2.1.2
UI
Following is the Home page that is visible to the user after successful login.
Clicking on the Menu items – Search And Notify, My Account, Create Account, Edit Accounts,
Database Update, opens a new web page and allows the user to perform the specific action.
Clicking on the Launch Applet link launches the Roof Selector applet.
Solar Opportunity – External Documentation
Page 4
Solar Opportunity
2.1.3
IMPLEMENTATION DETAILS
The Solar Admin uses Command pattern to implement various features. Command Interface –
is the interface that all the command classes implement
The following classes implement the Command interface and each one handles a separate
functionality:
Command
Login
CreateAccount
SearchAndNotify
DBUpdate
Logout
Change Password
Generate Letter
EditAccount
Java Class
LoginCommand.java
CreateAccountCommand.java
SearchAndNotifyCommand.java
RunDataMover.java
LogoutCommand.java
ChangePasswordCommand.java
GenerateCSVCommand.java
EditAccount.java
UI (jsp Page)
login.jsp
createAccount.jsp
searchAndNotify.jsp
DBUpdate.jsp
welcome.jsp
manageAccount.jsp
generateCSV.jsp
editAccount.jsp
Feature
Launch Applet
Implementation / Code
RoofSelector.jar
UI
RoofSelector.jsp
All the above commands are initialized in MasterServlet.java.
/**
* Creates a HASH table with the possible commands in the system.
* the method is called by init(), eg. the method is only called at system startup.
*/
private void initCommands() {
commands = new HashMap();
commands.put("login", new LoginCommand(securedir + "welcome.jsp")); //'Login'-btn in
login.jsp
commands.put("logout", new LogoutCommand("login.jsp"));
commands.put("changepassword", new ChangePasswordCommand
(securedir + "manageAccount.jsp")); //change password
commands.put("createaccount", new CreateAccountCommand(securedir + "welcome.jsp"));
commands.put("searchandnotify", new SearchAndNotifyCommand
(securedir + "searchAndNotify.jsp"));
commands.put("editaccount", new EditAccountCommand
(securedir + admindir + "editAccount.jsp"));
commands.put("dbupdate", new RunDataMover(securedir + admindir + "DBUpdate.jsp"));
commands.put("genLetter", new GenerateCSVCommand(securedir + "generateCSV.jsp"));
}
Solar Opportunity – External Documentation
Page 5
Solar Opportunity
Clicking on Launch Applet link takes the user to RoofSelector.jsp web page, which has the
applet container.
RoofSelector.jsp
<div id="appletContainer">
<APPLET name="RoofSelector" id="RoofSelector" code="UI.RoofSelectorApplet.class"
archive="<%=domain%>/ secure/RoofSelector.jar" width=1170 height=700>
<PARAM name="apiUrl" value="<%=domain%>/api;jsessionid=<%=session.getId()%>"/>
<PARAM name="username" value="<%=
((Profile)session.getAttribute("solar.profile")). getUsername() %>"/>
You need a Java-enabled browser to view this.
</APPLET>
</div>
2.1.3.1
SEQUENCE DIAGRAMS
The diagram below depicts the sequence diagram for the login command. This sequence diagram
depicts the use case login and every other command is a variation over this sequence pattern.
login.jsp is current page
WebBrowser
MasterServlet.java
LoginCommand.java
AccessDB.java
SolarDB / MySQL
Login with usr/pwd
Send Request to LoginCommand
Look up user credentials
Find user data in DB
Redirect to Next URL
Return Next URL
Return Profile Object
Return Profile Data
Next URL is either login.jsp or welcome.jsp
Solar Opportunity – External Documentation
Page 6
Solar Opportunity
To illustrate the resemblance between the different commands an alternative sequence diagram
for the search on intern and date can be seen below. Every search follows this sequence
diagram.
searchAndNotify.jsp is the current page
WebBrowser
MasterServlet.java
SearchAndNotifyCommand.java
Search on intern and date interval Send Request to SearchAndNofityCommand
Redirect to searchAndNotify.jsp again
Save results in Session Object
AccessDB.java
SolarDB / MySQ
Send search criteria
Perform Search
Return List of HashMaps with results
Return Search results
searchAndNotify.jsp always checks
if the session object contains
results and presents them in
the search result box if there are any.
Solar Opportunity – External Documentation
Page 7
Solar Opportunity
2.1.3.2
SYSTEM FLOW
1. MasterServlet starts by executing init() and initCommands(), Init sets an instance of the
AccessDB in the session object.
accessDB = new AccessDB();
session.setAttribute("solar.DB", accessDB);
2. initCommands() initializes a hashmap with all the possible commands in the system.
commands = new HashMap();
commands.put("login", new LoginCommand(securedir+"welcome.jsp"));
3. When a request is made from user interaction on a jsp page the request is sent by submitting
an area in the jsp page defined by the <form></form> tag.
<form name="login" action="/../TheSolarAdmin/SolarAdm"method="POST">
<input type="hidden" name="command" value="login">
User Name <input id="uid" name="uid" size="25" type="text"/>
Password <input id="pwd" name="pwd" size="25" type="password"/>
<input id="searchsubmit" value="Log In" type="submit"/>
</form>
4. service() is executed in masterservlet, service() looks up the parameter “command”(hidden
field in every jsp form) sent from the jsp page via the request object. Calls
lookupCommand() that returns the correct command to be executed.
5. service() calls the execute method, which executes the corresponding functionality like login,
logout etc. The command class finishes its execute by returning the next url the system
should go to and the MasterServlet’s service method ends by redirecting to the new url.
Command command = lookupCommand(req.getParameter("command"));
next = command.execute(req);
RequestDispatcher rd;
rd = getServletContext().getRequestDispatcher(jspdir + next);
rd.forward(req, res);
6. Parameters to the jsp pages are stored and accessed in the session object. In the jsp example
below we check if the session attribute solar.AssessorData is null, if it is null the attribute is
set to an empty arraylist.
<%
if(session.getAttribute("solar.AssessorData") == null) {
ArrayList<HashMap<String, Object>> myNewList = new
ArrayList<HashMap<String, Object>>();
session.setAttribute("solar.AssessorData", myNewList); }
%>
Solar Opportunity – External Documentation
Page 8
Solar Opportunity
2.1.3.3
JSP PAGES & FILTERS
unsecure
secure
login.jsp
welcome.jsp
searchAndNotify.jsp
propertyInfo.jsp
manageAccount.jsp
about.jsp
admin
createAccount.jsp
editAccount.jsp
The above model shows all jsp pages in the system. They are organized in 3 levels and access to
them is protected by filters. The system uses 2 filters:
AUTHENTICATION FILTER: Every request object with a request path in /secure/* activates
this filter. The filter checks if the user is logged in and redirects the user to login if this is not the
case.
ROLE FILTER: Every request object with a request path in /secure/admin/* activates first
Authentication Filter and then Role Filter. The Role Filter checks if the user logged in is an
admin if the user is not an admin the request is canceled and the user is redirected to
secure/welcome.jsp.
The mapping of servlets and filters is done in web.xml. Below is an example of the AdminFilter
is defined and mapped in web.xml. The filter is defined by the <filter> tag and is given the
name adminFilter. This name shall correspond to the one used in the filter mapping. The
<filter-class> tag refers to the class implementing the filter in this case RoleFilter.java in the
solar package.
Solar Opportunity – External Documentation
Page 9
Solar Opportunity
The filter is given two init parameters role = “admin” and noAccessPage =
“/secure/welcome.jsp”. The <filter-mapping> defines which URL’s that will activate the filter.
In this example any request to a resource in /secure/admin/ will active this filter.
<filter>
<filter-name>adminfilter</filter-name>
<filter-class>Solar.RoleFilter</filter-class>
<init-param>
<param-name>role</param-name>
<param-value>admin</param-value>
</init-param>
<init-param>
<param-name>noAccessPage</param-name>
<param-value>/secure/welcome.jsp</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>adminfilter</filter-name>
<url-pattern>/secure/admin/*</url-pattern>
</filter-mapping>
The general use and mapping of filters is described in the JEE tutorial from Sun
http://java.sun.com/javaee/5/docs/tutorial/doc/ in the PDF version pages 114-122 will give you
an introduction to how filters work.
Solar Opportunity – External Documentation
Page 10
Solar Opportunity
2.1.4
CLASS DIAGRAMS
Solar.AccessDB.java
Solar.AuthentificationFilter.java
Solar Opportunity – External Documentation
Page 11
Solar Opportunity
Common.Common.java
Solar.MasterServlet.java
Solar.RoleFilter.java
Solar Opportunity – External Documentation
Page 12
Solar Opportunity
Solar.Profile.java
Solar.SearchAndNotifyCommand.java
The rest of the command classes only have an execute method.
Solar Opportunity – External Documentation
Page 13
Solar Opportunity
2.1.5
DATA FLOW DIAGRAMS
File execution order for “DB Update” and other DB related functions
Solar Opportunity – External Documentation
Page 14
Solar Opportunity
2.1.6
SEARCH & NOTIFY / GENERATE LETTERS
How to generate letters/files
It is a two-step procedure. First create multiple letters at once, save them on the server side. In
second step, fetch them using SSH.
After searching for all the owners you want to notify (on "Search and Notify" tab), and getting
the results of search in lower left box (Records Found), select those that need letters generated
for them and “Add” them to lower right box (Owners To Notify). Next, select owners you want
to generate letters for, and click on "Save & Generate Letter Data" button. Letters in Word
format will be generated from the template and data that is available from the DB. For each
owner one letter will be generated, and saved on the server side.
[To see the details of implementation of above described functions, see following files:
searchAndNotify.jsp, SearchAndNotifyCommand.java, generatedLetters.jsp]
File-name is composed of APN number and the date and time when letter was generated. Easiest
way to retrieve them is using some file-transfer program, SSH.
[Locations of template files and generated letters are listed in DBUpdater_constants.java]
In addition to the generated letters, all data compiled for the letters is outputted as plain text data,
comma-separated, which then can be used in Word mailmerge.
How the letters are created
Letters are created by populating Word template with information compiled from data found in
the DB, and calculated using code Bill Wierenga wrote.
[All the code Bill Wierenga developed is located in Source Packages, in
Solar/LetterDataCalculator package]
Java library used to manipulate Word files is still not fully functional, and documentation for it is
not complete. [The web-page of the project is http://poi.apache.org/hwpf/]
Created Word file can not be opened with MS Office (tested using Office 2003). However, file
can be opened using Open Office 3.0 (http://www.openoffice.org/).
Since in created files Oakland logo in the upper right corner was missing, letters now generated
using simplified Word template, one that has text only. Such compiled letter can be then printed
on paper that has pre-printed header/logo of the City of Oakland. Both of these things are due to
the use of Apache POI library, only one I could find for this purpose.
Solar Opportunity – External Documentation
Page 15
Solar Opportunity
How the letter data is compiled:
Some of the data are read from “roofdata” and “oaklandassessor” tables. The rest of the data is
calculated at the moment when letter is created. Since information from the “roofdata” table is
necessary for other calculation, letter data and letters can be compiled only for properties that are
in “roofdata” table and have valid data.
More details about the data that had to be calculated:
SystemSize, GrossCost, NetCost and CO2 are calculated using mostly code Bill Wierenga
developed. I only integrated that code (parts of the code that calculate data we need for the letter
that is) in TheSolarAdmin application.
Calculator.java does the following:
- extract data for one roof plane at the time
- calculate all the values
- after all the roof planes are processed, sum them up together
Processing property has basically three steps.
1) go through the list of available benchmarks (benchmarks are manually created using Clean
Power Estimator", and loaded in the DB), "rank" them against the property (more about
"ranking" later), find the benchmark that has the smallest "rank"
2) calculate "size multiplier": "system size of selected benchmark" subtracted from "system size
of the property", that divided by "system size of selected benchmark", and all that incremented
by 1
3) using "size multiplier", calculate required letter data:
- example for how "Annual Generation KWh", "CO2", "Gross Cost", "Meet Current
Consumption", "Net Cost" and "Net Cost Per Month" are calculated:
"Annual Generation KWh" = "size multiplier" * "Annual Generation KWh of selected
benchmark"
- example for how "Annual Disc Cash Flow", "Main Cost Yearly", "Non Disc Cash Flow" and
"Payoff Period" are calculated:
"Annual Disc Cash Flow" = "size multiplier" * "Annual Disc Cash Flow Factor for selected
benchmark" * "Annual Disc Cash Flow for selected benchmark"
As for the "ranking" of the benchmarks, "rank" is the sum of three numbers:
a) absolute difference between "system size of the property" and "system size of the benchmark"
multiplied by "RankArea" ("Rank Area" is the constant loaded from the DB)
Solar Opportunity – External Documentation
Page 16
Solar Opportunity
b) absolute difference between "roof pitch of the property" and "roof pitch of the benchmark"
multiplied by "RankPitch" ("Rank Pitch" again constant from the DB)
c) absolute difference between "roof orientation of the property" and "roof orientation of the
benchmark" multiplied by "RankOrient" ("Rank Orient" constant from the DB)
Benchmark that gets the smallest rank is considered to be the best match for the property.
2.1.6.1
HOW-TO GENERATE LETTERS & UPDATE DATABASE
Generating letter(s)
1. Log in to www.solaropportunity.org
2. Select “Search And Notify” tab
Solar Opportunity – External Documentation
Page 17
Solar Opportunity
3. Use one of the “Search by…” fields to find owners of properties who should be notified;
Search results will be given in “Search Results” field, on its left side, their number given
with “Total Records Found: #”
Solar Opportunity – External Documentation
Page 18
Solar Opportunity
4. Select whatever number of results given on the left side of “Search Results” field, and
“Add” them to the right side; Number of results selected will be noted with “Total
Owners To Notify: #”
5. If some of the results/owners were added by mistake, you can always select and
“Remove” them
6. To generate letters & letter data, select owners you want to generate letters for, and
“Generate Letters and Letter data”; Letters will be generated and stored on the server side
7. New window will be opened with following information:
- List of generated letters/files, specifying their location (absolute path on the
server’s file-system)
Solar Opportunity – External Documentation
Page 19
Solar Opportunity
-
Data for the letters, in CSV format, so it can be used with a template file in
Word’s Mail-merge to generate letters manually
Property information, Owner information and Roof Data for each of the letters
generated
Along with that, for each generated letter/file, one entry will be made to
“lettersgenerated” table in the application’s DB
Retrieve generated letters from the server:
1. Connect to the linux server using SSH
2. Parameters for connection:
Host Name: barlev.sfsu.edu
User Name: projxyz
Password: q$AI49vB
Port Number: 22
3. Select Window->New File Transfer (this opens a new file transfer window)
4. In the right side pane of the window (represents server machine), navigate to the server
location where generated letters are saved (see above screenshot)
Solar Opportunity – External Documentation
Page 20
Solar Opportunity
5. Now you can select the generated letters, right click on them and choose ‘Download’.
The files are transferred to the location selected in the left pane of the window (represents
your local machine)
Updating database:
The database contains the property information of Oakland homes in OaklandAssessor table.
This table is stored in the MySQL database on the server. The property information changes
from time to time. Hence, it is important to be able to sync the table with Oakland data.
The new table with (MSAccess file) is provided by City of Oakland. The database update
functionality applies this file to MySQL table, effectively syncing the MySQL database with the
Oakland database.
1. Log in to www.solaropportunity.org
2. Select “Database Update”
3. “Browse” to locate the update file
4. “Submit”. File will be uploaded and placed into temporary table.
Solar Opportunity – External Documentation
Page 21
Solar Opportunity
5. “Apply” new update.
6. Report page will be displayed.
Solar Opportunity – External Documentation
Page 22
Solar Opportunity
Backup table
Save OaklandAssessor, Backup, Update table or table with Generated Letter Data as a CSV file.
All tables that are saved can later be displayed.
To backup a table:
1. On “Database Update” page select “Backup tables” sub-page
2. Select a table you want to backup
3. Select character sequence you want to use as a field-delimiter (comma [,] by default)
Solar Opportunity – External Documentation
Page 23
Solar Opportunity
4. “Save”
Table will be saved as a CSV file on a server’s file-system. Name of the file will be
composed from name of the table and time-stamp when backup was made.
To retrieve backup of a table:
Two options are available. You can either follow the link “See previously saved tables” from
“Backup tables” sub-page, or you can access file directly by connecting to the server
To “See previously saved tables”:
-select the table
Solar Opportunity – External Documentation
Page 24
Solar Opportunity
- View” saved table
For details on how to connect directly to server, follow procedure given in “Retrieve generated
letters from the server”.
Solar Opportunity – External Documentation
Page 25
Solar Opportunity
Review previously performed updates
When update of OaklandAssessor table is performed, deleted or modified records are not
completely erased. If a record is deleted from OaklandAssessor table, before being deleted it is
copied into OaklandAssessor_Backup table. Likewise, if a record in OaklandAssessor table is
modified, first it is being copied into OaklandAssessor_Backup table. In this way, if there is a
need to restore a record that was deleted, it can be done after the update is finished.
To review previous updates:
1. On “Database Update” page select “Review previous updates” sub-page
2. Select the date of the update you want to review
Solar Opportunity – External Documentation
Page 26
Solar Opportunity
3. “View”
A page of records relevant to that update will be presented. Deleted records will be tagged with
red color and modified records will be tagged with gray color.
For records that were modified, important information will be current value of the same record in
the OaklandAssessor table. That record is given alongside modified records, and is tagged with
green color.
To return deleted record to OaklandAssessor table, or reverse the effect of modification, select
checkbox besides desired record(s) and “Revert records”.
Solar Opportunity – External Documentation
Page 27
Solar Opportunity
Notes:




Reverting or returning of modified and deleted records to OaklandAssessor table is not
by itself new update
“Depth” of memory for record modification is 1, which means that if same record is
modified in two consecutive updates, it will be possible to revert only the change made
by second update
All errors that occur during the update process are written in a log file located on the
server, in “update_DB/logs” directory
Word template used for the generating of the letters can be modified; The file is located
in “generated_letters_files” folder, and is named
“template_as_plain_word_document_redux.doc”; Name of the file can be changed, but in
that case appropriate change has to be made to value of the
“template_Word_file_for_letter” variable in
trunk/SolarAdmin/TheSolarAdmin/src/java/Solar/DBUpdater_constants.java file; When
modifying the template, important thing is to use following character sequences as
placeholders for the desired values (meaning of the placeholders is evident, I believe…):
- <<ownerAddr>>
- <<ownerUnit>>
- <<ownerCityState>>
- <<ownerZipPlusFour>>
- <<propAddrNum>>
- <<propStreetName>>
- <<ownerName>>
- <<propAddrNum>>
- <<propStreetName>>
- <<SYSTEMSIZE>>
- <<GrossCost>>
- <<NetCost>>
- <<CO2>>
Solar Opportunity – External Documentation
Page 28
Solar Opportunity
2.1.7
CODE LOCATION
The java classes that implement the commands are located at: TheSolarAdmin/Source
Packages/Solar
Solar Opportunity – External Documentation
Page 29
Solar Opportunity
The jsp pages that implement the user interface are located at: TheSolarAdmin/Web
Pages/Secure and at TheSolarAdmin/Web Pages/Secure/Admin
Solar Opportunity – External Documentation
Page 30
Solar Opportunity
2.2
ROOF SELECTOR
2.2.1
FEATURES / FUNCTIONALITY
Roof selector module provides the following functionality:





Load Roof Data for a property (using Street Address/ APN)
Get GIS Image for the property
Set the scale (pixels per foot)
Create/Edit Roof Data (Planes & Obstructions)
Save Roof Data
2.2.2
UI
Solar Opportunity – External Documentation
Page 31
Solar Opportunity
2.2.3
IMPLEMENTATION DETAILS
The Solar Admin module sends a HTTP request to the Oakland GIS server requesting it
for the GIS Image of a property identified by the APN (or street address). The HTTP
response from the Oakland GIS server is sent back to the RoofSelector module
(Application.java) which parses the image and displays it.
GISRequest.java
private String parseImageURI() throws UnknownHostException,
IOException {
String queryBody =
"AppID={E8802E39-0BDC-4EAA-9524-8F26D306B71C}"+
"&AttributesAvailable=0" +
"&BufferDistance=" +
"&BufferDownload=0" +
"&BufferList=" +
"&BufferSource=" +
"&BufferTarget=" +
"&BufferUnits=0" +
"&CurrTool=11" +
Solar Opportunity – External Documentation
Page 32
Solar Opportunity
"&EnvIsDegrees=0" +
"&EnvIsMapUnits=0" +
"&MapFunction=40" +
"&MapLayerActive=ParcelAssessor" +
"&MapLyrVis_BART=1" +
"&MapLyrVis_BartStations=1" +
"&MapLyrVis_CityFacilitiesFootprint=0" +
"&MapLyrVis_Contours=0" +
"&MapLyrVis_FaceofCurb=1" +
"&MapLyrVis_Majorst=1" +
"&MapLyrVis_ParcelAssessor=1" +
"&MapLyrVis_Parcels=1" +
"&MapLyrVis_Railroads=0" +
"&MapLyrVis_Trails=0" +
"&MapLyrVis_citylimits=0" +
"&MapLyrVis_councildistrict=0" +
"&MapLyrVis_freeways=1" +
"&MapLyrVis_generalplan=0" +
"&MapLyrVis_haywardfault=0" +
"&MapLyrVis_haywardfaultzone=0" +
"&MapLyrVis_image=1" +
"&MapLyrVis_intersections=1" +
"&MapLyrVis_land=1" +
"&MapLyrVis_neighborhoods=0" +
"&MapLyrVis_parks=0" +
"&MapLyrVis_planareas=1" +
"&MapLyrVis_publicrow=0" +
"&MapLyrVis_redevelopment=0" +
"&MapLyrVis_sewergrid=0" +
"&MapLyrVis_streets=1" +
"&MapLyrVis_water=1" +
"&MapLyrVis_zoning=0" +
"&MapMaxX=" +
"&MapMaxY=" +
"&MapMinX=" +
"&MapMinY=" +
"&MessageAvailable=0" +
"&MouseBtn=0" +
"&QueryName=ByAPN" +
"&QueryValue=" + this.apn.replace(' ', '+') +
"&ShiftKey=false" +
"&SummaryReportAvailable=0" +
"&ToolsVisible=0" +
"&UserShapeID=" +
"&WinLeft=-1" +
"&WinTop=-1" +
"&WinVisible=0" +
"&WindowHeight=639" +
"&WindowWidth=1028" +
"&XML=" +
"&attribLeft=304" +
"attribTop=145" +
"&layersLeft=0" +
"&layersTop=0" +
"&layersVisible=0" +
"&legendLeft=0" +
Solar Opportunity – External Documentation
Page 33
Solar Opportunity
"&legendTop=0" +
"&legendVisible=0";
URL url = new URL("http://gismaps.oaklandnet.com/cedap/map.asp");
HttpURLConnection conn = (HttpURLConnection)
url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Host", "gismaps.oaklandnet.com");
conn.setRequestProperty("User-Agent", "Mozilla/5.0 (Windows; U;
Windows NT 5.1; en-US; rv:1.8.1.12) Gecko/20080201
Firefox/2.0.0.12");
conn.setRequestProperty("Accept", "text/xml,application/xml,
application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=
0.5");
conn.setRequestProperty("Accept-Language", "en-us,en;q=0.5");
conn.setRequestProperty("Accept-Encoding", "gzip,deflate");
conn.setRequestProperty("Accept-Charset", "ISO-8859-1,utf8;q=0.7,*;q=0.7");
conn.setRequestProperty("Referer",
"http://gismaps.oaklandnet.com/cedap/map.asp");
conn.addRequestProperty("Cookie", String.format("%1$s",
cookies.get(0)));
conn.addRequestProperty("Cookie", String.format("%1$s",
cookies.get(1)));
conn.setRequestProperty("Content-Type", "application/x-www-formurlencoded");
conn.setRequestProperty("Content-Length",
String.valueOf(queryBody.length()));
conn.setDoInput(true);
conn.setDoOutput(true);
conn.connect();
PrintWriter out = new PrintWriter(conn.getOutputStream());
out.write(queryBody);
out.close();
// parse the returned html
GisHtmlImageParser delegate = new GisHtmlImageParser();
new ParserDelegator().parse(new BufferedReader(
new InputStreamReader(conn.getInputStream())), delegate,
true );
conn.disconnect();
if (delegate.urlFound()) {
return delegate.getUrl();
} else {
return "missing.jpg";
}
}
Solar Opportunity – External Documentation
Page 34
Solar Opportunity
2.2.3.1
SEQUENCE DIAGRAM:
The following sequence diagrams details the process of searching for a property, loading the
GIS image of that property and saving the roof data if the user has changed existing areas or
added new areas (planes/obstructions). MainPanel.java listens to the user generated events
and is responsible for updating the Image display. Application.java communicates with the
Solar Admin module using APIRequest object. (APIRequest and APIResponse objects are
explained in more detail in the next section ‘Sub-System Interaction’)
Solar Opportunity – External Documentation
Page 35
Solar Opportunity
2.2.3.2
ROOFDATA – XML SCHEMA
The roof data of a property is converted into XML format before being stored in the database.
The following XML schema stores the entire roof data information of a property.
The XML schema is stored at the location: RoofSelector/Source Packages/<default
package>/RoofDataSchema.xsd
<?xml version="1.0" encoding="utf-8"?>
<xs:schema targetNamespace="http://solaropportunity.org/RoofData.xsd"
xmlns="http://solaropportunity.org/RoofData.xsd"
xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xs:element name="ROOFDATA" type="ROOFDATA" />
<!--Declare ROOFDATA Type-->
<xs:complexType name="ROOFDATA">
<xs:sequence>
<xs:element name="HEADER" type="HEADER" />
<xs:element name="PLANES">
<xs:complexType>
<xs:sequence>
<xs:element name="PLANE" type="PLANE"
maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<!--Define HEADER Type-->
<xs:complexType name="HEADER">
<xs:sequence>
<xs:element name="APN" type="APN" />
<xs:element name="USERNAME">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="IMAGE_SCALE" minOccurs="0">
<xs:complexType>
<xs:attribute name="PIXELS" type="xs:double"
use="required" />
<xs:attribute name="FEET" type="xs:double"
use="required" />
<xs:attribute name="PIXELSPERFOOT" type="xs:double"
use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<!--Define APN Type-->
<xs:simpleType name="APN">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
</xs:restriction>
Solar Opportunity – External Documentation
Page 36
Solar Opportunity
</xs:simpleType>
<!--Define ROOF AREA Type-->
<xs:complexType name="ROOFAREA">
<xs:sequence>
<xs:element name="PIXEL_AREA_AFTER_OFFSET" type="xs:double" />
<xs:element name="OFFSET" type="xs:unsignedInt" />
<xs:element name="OUTEREDGE" type="POLYGON" />
<xs:element name="INNEREDGE" type="POLYGON" />
</xs:sequence>
</xs:complexType>
<!--Define POLYGON Type-->
<xs:complexType name="POLYGON">
<xs:sequence>
<xs:element name="POINT" maxOccurs="unbounded" minOccurs="3">
<xs:complexType>
<xs:attribute name="X" type="xs:double" use="required" />
<xs:attribute name="Y" type="xs:double" use="required" />
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<!--OBSTRUCTION Type-->
<xs:complexType name="OBSTRUCTION">
<xs:sequence>
<xs:element name="OBSTRUCTION_ID" type="xs:unsignedInt" />
<xs:element name="REFPLANE_ID" type="xs:unsignedInt" />
<xs:element name="ROOFAREA" type="ROOFAREA" />
<xs:element name="OBSTRUCTIONAREA" type="xs:double" />
</xs:sequence>
</xs:complexType>
<!--PLANE type-->
<xs:complexType name="PLANE">
<xs:sequence>
<xs:element name="PLANE_ID" type="xs:unsignedInt" />
<xs:element name="PITCH" type="xs:double" />
<xs:element name="ORIENTATION">
<xs:simpleType>
<xs:restriction base="xs:int">
<xs:maxInclusive value="359" />
<xs:minInclusive value="0" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="ROOFAREA" type="ROOFAREA"/>
<xs:element name="TOTAL_USABLE_PLANEAREA" type="xs:double" />
<xs:sequence>
<xs:element name="OBSTRUCTION" type="OBSTRUCTION"
minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:sequence>
</xs:complexType>
</xs:schema>
Solar Opportunity – External Documentation
Page 37
Solar Opportunity
2.2.3.3
EXAMPLE AREA CALCULATION
<ROOFDATA xmlns="http://solaropportunity.org/RoofData.xsd">
<HEADER>
<APN>001 019500600</APN>
<USERNAME>b</USERNAME>
<IMAGE_SCALE FEET="60.0" PIXELS="176.02557373046875"
PIXELSPERFOOT="2.933759562174479"/>
</HEADER>
<PLANES>
<PLANE>
<PLANE_ID>0</PLANE_ID>
<PITCH>0.0</PITCH>
<ORIENTATION>13</ORIENTATION>
<ROOFAREA>
<PIXEL_AREA_AFTER_OFFSET>14524.0
</PIXEL_AREA_AFTER_OFFSET>
<OFFSET>0.0</OFFSET>
<INNEREDGE>
<POINT X="354.0" Y="316.0"/>
<POINT X="415.0" Y="197.0"/>
<POINT X="607.0" Y="303.0"/>
<POINT X="544.0" Y="420.0"/>
</INNEREDGE>
<OUTEREDGE>
<POINT X="354.0" Y="316.0"/>
<POINT X="415.0" Y="197.0"/>
<POINT X="607.0" Y="303.0"/>
<POINT X="544.0" Y="420.0"/>
</OUTEREDGE>
</ROOFAREA>
<TOTAL_USABLE_PLANEAREA>1624.8796438183044
</TOTAL_USABLE_PLANEAREA>
<OBSTRUCTIONS>
<OBSTRUCTION>
…….
<TOTAL_OBSTRUCTION_AREA> 31.515
</TOTAL_OBSTRUCTION_AREA>
</OBSTRUCTION>
<OBSTRUCTION>
…….
<TOTAL_OBSTRUCTION_AREA> 31.079
</TOTAL_OBSTRUCTION_AREA>
</OBSTRUCTION>
</OBSTRUCTIONS>
</PLANE>
Solar Opportunity – External Documentation
Page 38
Solar Opportunity
Each plane element contains the information related to the plane itself and the obstructions that
lie in it.
<PLANE>
<PLANE_ID> 1 </PLANE_ID>
….
<OBSTRUCTIONS>
<OBSTRUCTION>
<OBSTRUCTION_ID> 2 </OBSTRUCTION_ID>
<REFPLANE_ID> 1 </REFPLANE_ID>
</OBSTRUCTION>
</OBSTRUCTIONS>
</PLANE>
In the above example, the plane 1 contains obstruction 2 (The obstruction element with id=2 lies
within the plane element). The plane that an obstruction belongs to can be determined easily
using the ‘Refplane_id’ (which gives the id of the plane that it belongs to).
XML ELEMENT
DESCRIPTION
<PIXEL_AREA_AFTER_OFFSET>
Area of the Plane/Obstruction in pixels, after
taking the offset into consideration
<TOTAL_OBSTRUCTION_AREA>
Area of the Obstruction in Sq. Ft =
Area of the Obstruction in Pixels /
(pixelsperfoot * pixelsperfoot)
<TOTAL_USABLE_PLANEAREA>
Total area of the plane that can be used for
solar panels = Area of Plane in Sq. Ft Sum of Obstruction Areas
Area of Plane in Sq. Ft =
Area of the Plane in Pixels /
(pixelsperfoot * pixelsperfoot)
= 14524 / (2.93376 * 2.93376)
= 1687.46369
Sum of all Obstructions Areas =
31.515 + 31.079
= 62.594
Total Usable Plane Area = 1688.248 – 62.594
= 1624.86
Solar Opportunity – External Documentation
Page 39
Solar Opportunity
2.2.3.4
XML to ROOFDATA CONVERSION
When the Roof Data for a particular property is fetched from the database, it is in XML format.
It is parsed by RoofDataParserHandler.java. It is a SAX parser handler that is designed to parse
Roof Data XML fragments. Similarly, when the Roof Data is to be saved, the Roof Data object
has to be converted to a XML format and then sent to SolarAdmin using APIRequest object.
This conversion is done by RoofDataToXML.java. It creates an XML serialization of the roof
data instance.
Both files are located at: RoofSelector/Source Packages/XML
3. SUB-SYSTEM INTERACTION
RoofSelector module when compiled/built generates RoofSelector.jar file. This file is referenced
by the SolarAdmin module when RoofSelector applet is launched.
RoofSelector.jar file is located at: TheSolarAdmin/Web Pages/secure
Solar Opportunity – External Documentation
Page 40
Solar Opportunity
Roof Selector and Solar Admin modules communicate with each other using APIRequest and
APIResponse.
/**
* Used in RoofSelector.Application to switch on the type of request
* when a response is received so we know how to handle the response.
*
*/
public enum RequestType {
GetGISImage,
GetRoofData,
SaveRoofData,
APN
}
Solar Opportunity – External Documentation
Page 41
Solar Opportunity
The files that implement the API Request and API Response in Roof Selector module are located
at: RoofSelector/Source Packages/net
Solar Opportunity – External Documentation
Page 42
Solar Opportunity
The files that implement the API Request and API Response in the Solar Admin module are
located at: TheSolarAdmin/Source Packages/api
Solar Opportunity – External Documentation
Page 43
Solar Opportunity
4. SETUP
File paths have to be changed accordingly when the application is being deployed on a Windows
or Linux server.
Example:
LINUX
- file_location = "/home/update_DB/logs";
WINDOWS - file_location = "D:\\update_DB\\logs";
The paths have to be changed in the following files:



DBUpdater_constants.java
AccessDB.java
SearchAndNotify.java
Set up information for installing the application on a Linux server:
a) Sudo user
To install and configure the application on the server, the user has to be in the sudoers list.
b) Install tomcat
Sudo apt-get install tomcat6 tomcat6-admin tomcat6-common tomcat6-user tomcat6examples tomcat6-docs
c) Configure tomcat users
Tomcat needs to have the tomcat manager web site login info in the tomcat-user.xml file.
Assume user: b and password: b
Add the following to /etc/tomcat6/tomcat-users.xml
<role rolename="manager-gui"/>
<user password="b" roles="manager-gui,manager,admin" username="b"/>
d) Install MySQL
Sudo apt-get install mysql-server
Sudo apt-get install mysql-client
Sudo apt-get install libmysql-java
e) Configure MySQL <-> Tomcat
Modify solar web site to connect to database with root login credentials:
Assume user: root password: 123
Solar Opportunity – External Documentation
Page 44
Solar Opportunity
Find the xml file context.xml under
/trunk/SolarAdmin/TheSolarAdmin/web/META-INF/context.xml in your file system. In that
file modify the resource line to
“<Resource auth="Container" driverClassName="com.mysql.jdbc.Driver" maxActive="100"
maxIdle="30" maxWait="10000"
name="jdbc/myDatasource" password="123" type="javax.sql.DataSource"
url="jdbc:mysql://localhost:3306/solar" username="root"/>
f) Login MySQL
Login to MySQL with root credentials:
 Mysql –u root –p 123
g) Create database
CREATE DATABASE solar;
h) Populate database
source solarDatabaseAndData.sql;
source AssessorCreates.sql
source AssessorInserts.sql
The scripts are located at /trunk/database.
i) Retart Tomcat6, MySQL services after configuration
Sudo service tomcat6 start
Sudo service mysql start
j) Download SSH Secure Shell Client
Use SSH Secure Shell Client to remotely login to the server
k) Upload WAR file to server
Upload the solar opportunity WAR file to the folder - /var/lib/tomcat6/webapps
Solar Opportunity – External Documentation
Page 45
Solar Opportunity
5. OTHER DOCUMENTATION
Several students have worked on the Solar Opportunity project previously and have documented
their work. Information from all these documents has been used to compile this document.
Following is the list of documentation available in SVN:
http://java.net/projects/solarenergy/sources/svn/show/trunk/docs








How to Setup Server for Solar Application
Solar Energy Application Setup Steps Supplimental
TheSolarAdmin - Zorans addition – documentation
Generating letters and Updating DB - How To
Generating letters and Updating DB - How To - with screen snapshots
Description of SolarAdmin
2008SolarEnergy_DataMoverDoc
DataMoverDocumentation
6. DATA GLOSSARY / REFERENCES
[1]
Solar Opportunity: The project title
The existing application URL is www.solaropportunity.org:8080/TheSolarAdmin
[2]
Area: Contiguous section of roof which is of the same pitch and orientation
[3]
Usable Area: The amount of square footage that can actually have solar panels
[4]
Pitch: The angle of the roof
[5]
Orientation: The orientation of the roof with respect to north
[6]
Plane: Usable section of roof. A roof can contain many planes
[7]
Obstruction: Unusable section of a plane. Every obstruction belongs to a plane
Solar Opportunity – External Documentation
Page 46