API Design

Overview
Just wanted to start by saying this was my first real experience creating an API, though I did have a vague understanding of how they worked before. API stands for application programming interface and while I could probably try to come up with my own explanation of what an API is used for, wikipedia probably has the most suitable explanation:

An Application Programming Interface (API) is a particular set of rules and specifications that a software program can follow to access and make use of the services and resources provided by another particular software program that implements that API. It serves as an interface between different software programs and facilitates their interaction, similar to the way the user interface facilitates interaction between humans and computers.

Given that explanation, APIs are good in the sense that they can simplify design, allow for multiple implementations, and enable scaling. Though there are a lot of benefits to using an API, there are some drawbacks such as: increased implementation complexity, boundaries created by limits of the API, and using an API can cost performance/optimization. Given that information, we are designing an API for the iHale system because we feel it will simplify the interactions between the home's sensors and other interfaces. Developing an API for the home will make it easy to develop applications on multiple platforms that can interface with the home.

REST API
The first step in designing the Team Kai's iHale API was to develop a REST based API for communicating with the home's sensors. Our goal was to create a API that would simplify the communication between our iHale system and the home's systems. As a result, we came up with an XML representation for each system, that makes it easy to view and modify the system's states.

iHale REST API

To maintain a REST-like API we support the idea of modifying and reading from resources. Each of the home's system will have a corresponding URI where the systems arduino board can be communicated with. For example, the Aquaponics resource might be accessible from the URI http://aquaponics.halepilihonua.org. Our API allows for the PUT and GET operations which work with XML to represent the readings. A GET will retrieve the XML representation of the readings from the arduino board, and PUT will generate XML telling the arduino board it needs to modify the system.

Java API
Along with creating a REST API, we created a Java API which will use the data retrieved using the REST API. The XML retrieved from the home's systems will be parsed and placed into Java objects which can then be stored and manipulated. By creating a Java API for iHale, as mentioned above, it will be very easy for external developers to come along and develop applications for the home. Eventually we plan to expand the system developed here to include a front-end, back-end, and simulator (at least till we have access to the actual sensor readings). Currently the Java API we have developed contains an object class for each system (e.g. aquaponics, hvac, lighting) and methods for storing, retrieving, and deleting of these objects. By using these object classes, as long as we are provide with all of the parameters, we can generate xml to PUT to the systems.

Development Experience
I think that the most unexpected and hardest part of developing our REST API was figuring out how everything fit together; it was really tough trying to understand how the systems of the home would interact with the iHale system. Eventually we determined that the iHale system would be able to communicate with each of the home's systems using a generic XML representation. After solving how the communication worked between systems worked, we had to carefully figure out what data readings/states we would need from each system. Developing the Java API was pretty straight forward compared to the REST API; the biggest issue was fixing minor errors so the system would pass verify (findbugs, pmd, checkstyle, etc).

As well as being the hardest part, understanding how everything fit together was probably the most interesting part of the development process. We had to actually sit down and draw diagrams and write out what variables we would need for each system; doing this probably took the most brainpower. Looking through the sample api was also interesting as it allowed me to see how the API interacted with the front-end and back-end.

Deliverables

• iHale API Download

Berkeley Database Katas

Overview
For this task we continued working with Restlet and Wicket, but we added a persistent database into the mix this time. In the previous set of katas, the database we used was not persistent and the contacts would be wiped out when the program was quit. To maintain persistency in our system, we decided to use the embedded database system Berkeley DB. Because Berkeley DB is embedded, the database is stored within our contact system allowing our contacts to be persisted unlike our previous system.

For the first half of the exercise, we got practice using the secondary key functionality of Berkeley DB. For the first task we added a secondary timestamp key, which is calculated when adding a new contact to the database. Once we implemented the secondary key, we added functionality for get-timestamp which allows a user to request a contact by their timestamp, and get-range which allows users to request a group of contacts by supplying a range of timestamps. For the second task, we designed a system that consists of three parts: a Wicket web application client, a Restlet based server, and a persistent/embedded database using Berkeley DB. The Wicket webpage is a web based client which allows users to add and retrieve contacts by interfacing with the Restlet based server. The server, in turn, communicates with and performs actions on our embedded Berkeley database.

Berkeley Database Katas
These katas were pretty similar to the previous Restlet katas we did. These Berkeley DB katas actually used a combination of skills we learned while doing the first two sets of katas. We combined the Wicket web application from the first set of Katas, and the idea of a database from the second set of katas. The only difference was that the database used in these exercises was a persistent database while the one used in the previous assignment was not.

• Kata 1: For this Kata, you will first implement a secondary key for Contacts that consists of a timestamp represented as a long value. Also implement get-timestamp and get-range functions for client use. Get-timestamp should allow the user to request a contact by its timestamp and get-range should return a group of contacts given a range of timestamps.
  Completed: Yes
  Time Spent: 1 hour 45 minutes
  
  Summary: This was fairly easy, it just required looking a the Berkeley DB API and examining the pre-existing code for the primary key in our system. Adding and calculating the timestamp was pretty straight-forward, I would say that the most difficult part was adding the get-range functionality, but when looking through the API I was able to find a section on grabbing ranges of keys. Writing the unit test probably took equally as long as completing the task.


• Kata 2: Create a client-server system for managing contacts that Provides a Wicket client which consist of a single page, and allows the user to store a contact given its info, and retrieve a contact given its unique ID. The Wicket client code should invoke an underlying Restlet-based module to send a request to a ContactDB server to put or get data. The system should aslo provide a Restlet and BerkeleyDB server. The server should accept and process requests using Restlet, and use BerkeleyDB to persist the Contacts.
  Completed: Yes
  Time Spent: 5 hours 20 minutes
  
  Summary: The hardest part of this for me was probably conceptualizing how everything would interact with each other. After about an hour of studying how the pieces would fit together I was able to get started, and everything went pretty smooth for the most part. The only issue I ran into was trying to fix a bug with adding contacts through the Wicket web interface. I kept looking over the code thinking that everything should be working, and I couldn't figure out why it wasn't. Eventually I realized that I was passing the parameters, to create an instance of a Contact object, in the incorrect order. I guess it was just another lesson learned though. If you pay attention and do things carefully the first time, you can save yourself hours on trying to fix minor bugs.
  
  Another issue I ran into was having a static field in my WicketWebApp class. PMD was giving me an error saying that that the class had static variables which was unsafe. I believe it was unsafe because the variables were shared by all users accessing the web application. I solved the issue by adding sessions to the Wicket application. By adding sessions, multiple users can now access the web app which modifies one universal database.

Deliverables

• Berkeley DB System Download

Restlet Katas Part II

Overview
This is only my second experience with Restlet, but I am getting more used to it, slowly but surely. I feel like this second exercise has given me much more insight about how Restlet works. The whole framework seems to be very client/server oriented and as a result I've been getting a lot of practice studying and programming the relationship between a client and server. Also, I'm actually starting to enjoy programming with Restlet as it uses Java which makes everything pretty straight forward and when I run into a problem I can always find the solution because there are so many resources for Java programming.

For this task we were asked to modify a pre-made Restlet project which allows for the storage, retrieval, and deletion of contacts using the put, get, and delete. There were three katas which ranged in difficulty: adding a new resource which would get all contacts in the system, adding support for get-all and delete-all, and finally adding a new parameter to the Contact class. In the following section I will go over my experiences with completing each kata.

Restlet Contact Service Katas
These additional katas were designed to help us learn a bit more about the Restlet framework and after completing these katas I feel that I am slowly getting more and more familiar with Restlet.

• Kata 5: Modify the system to support a new resource called "contacts" and its associated URL: http:///contactservice/contacts. This resource only supports the GET operation and when it is invoked, it returns an XML representation of all of the contacts in the system.
  Completed: Yes
  Time Spent: 2 hours 10 minutes
  
  Summary: I think this kata took the longest because I had to actually sit down and study the code to figure out what each part did, before I could successfully finish it. Initially I tried to do the kata without studying the code, this ended up with me finishing it, but sloppily. After running an ant verify I realized how sloppily I had done this kata, so I went back and restructured my code from scratch. The second time around I had a much better idea of what I was doing and I finished it rather quickly. The hardest part for me was figuring out how to determine the host programmatically, after a long time searching I finally figured out I could use the following line:
  
       String host = getRequest().getRootRef().toString();
  
  After solving that, I ran into the issue of figuring out how to output the data in XML format; after studying the code for a few minutes I figured it out fairly easily.


• Kata 6: Now that you have a contacts resource, extend the command line client to support a "get-all" and "delete-all" operation.
  Completed: Yes
  Time Spent: 1 hour 35 minutes
  
  Summary: I had a pretty good idea how to do this when starting the kata, though things didn't go as smoothly as I had planned. The first time I tried to complete this kata, I kept getting a NoClassDef error. I tried searching for a solution, but no matter what I tried I couldn't figure out why I was getting the error. I started from scratch a second time and made sure to test every little milestone of the kata I completed. Doing so helped me finish the kata without issue, like the first time.


• Kata 7: Add a telephone number to the Contact resource, which only supports numbers and dashes.
  Completed: Yes
  Time Spent: 1 hour
  
  Summary: I actually completed this kata first, because it was the easiest of the three katas. Solving this kata was fairly easy, as we just had to add a new parameter to the Contact class. It was just a matter of looking at how the other parameters of the Contact class were used throughout the system, and just modifying the code to support the extra "phone" parameter. The hardest part of this kata was figuring out how to set the error status, if the phone number the user entered had something other than numbers and dashes. Checking for the numbers and dashes was simple using a regular expression, but I couldn't set the response using the piece of code:
  
       getResponse().setStatus(Status.CLIENT_ERROR_NOT_ACCEPTABLE);
  
  After trying to get this working unsuccessfully I consulted with my professor, and I felt really foolish when I realized it was because I was performing the validation in the wrong file. I was suppose to do the check in the ContactResource.java file, but instead I was doing it in the ContactClient.java file. After I moved the check to the proper file everything worked as expected.

Deliverables

• Restlet Contact Service Kata Download

Restlet Katas

Overview
This is the first time that I have ever worked with Restlet, which is web framework for Java that specializes in computer-computer interaction. As of right now, I still don't know too much about it and I'm not sure how we would use this in a larger project. For me there was quite a bit of a steep learning curve, as I was not able to find many examples of the code actually in use (mainly for the basic http authentication kata). Though, it seemed the longer that I worked with it the more familiar it became; hopefully as the semester progresses it will become easier to use.

Restlet Katas
By completing these Katas we were able to see a little of what Restlet does. We were able to set up a restlet web server that can authenticate the client and then spit out date and time to the user.

• Kata 1: Add three new resources called "hour", "minute" and "second" which return the current hour, minute and second.
  Completed: Yes
  Time Spent: 35 minutes
  
  Summary: This exercise was pretty straight forward as I just copied the existing "month" resource and then proceeded to look up Java's Calendar API, to get the appropriate method name for the hour, minute, and second.


• Kata 2: Setup logging by making restlet read in a logging.properties file.
  Completed: Yes
  Time Spent: 1 hour 45 minutes
  
  Summary: This took quite a bit longer than the first kata as the documentation wasn't very specific. Finding the bit of code to put in our server to make restlet read the properties file was easy, but finding the code to put inside of the properties file took much longer. I tried putting a few different things in the properties file which didn't work, after searching for about an hour I eventually found the correct settings for the file.


• Kata 3: Authenticate requests with basic HTTP authentication.
  Completed: Yes
  Time Spent: 2 hours 35 minutes
  
  Summary: This took a really long time to figure out due to the restlet documentation not being very good. I searched for the proper code for about 2 hours trying many different pieces of code which I found; nothing seemed to work. At one point I had it authenticating, but still showing the data on the page before you type in your username and password. Eventually I found a good example of how to authenticate on StackOverflow, which can be seen here.


• Kata 4: For this Kata, create a new client for the DateService server that is a web application using Wicket rather than a command line application.
  Completed: Yes
  Time Spent: 3 hours 25 minutes
  
  Summary: The biggest problem I ran into was that I was unable to get Jetty to work with Eclipse. I added jetty to the build.xml file for Ant, but regardless Eclipse would not recognize the jetty imports in my Jetty.java file even though they were in the lib directory of the project. I tried numerous ways of trying to import the Jetty libraries, eventually I realized I had to add the new Jetty jar files to Eclipse's build path for the project. After nearly three hours of frustration and making no progress, I finally was able to move on and work on the actual Wicket programing. The programing I had to do in Wicket was very simple: I just had to make a simple getResource method that calls on the Dateserver to request the resource. Even though this kata took me the longest to complete, it wasn't the hardest, both the logging and authentication katas were more difficult.

Deliverables

• Restlet Kata Download

Decathlon Design

Overview
For our final project we were assigned the task of creating an interactive html mockup of our previously designed home management system using wicket. I'm very happy with our final product, as I feel it has a clean designed and useful features. I also feel that our project satisfies the three prime directives, which I will go into more detail about later. You can view our current project hosting page here. On our project hosting page you can see in detail how to use and develop our system farther. Below you can see a screenshot of our home management system's dashboard page:

Lessons Learned
A major point, which I learned about software engineering, is that it is not easy to work in groups; at least without good communication. In the beginning, we were a bit more organized: letting each other know when and what we were committing. Towards the end we were rushing a bit so all of us were all submitting revisions of the same file; this caused quite a bit of conflicts. At one point we had two different versions of a few pages, because of the conflicts I had pick and chose parts of each page to commit for the final versions. If I could've done the project again, I would have made sure we had better communication about what pages we were currently working on and planning to commit. Overall, I would still say we (Noah, Kevin, and I) worked very well as a group.

Aside from that, I definitely feel that working in a group was advantageous. If you have any kind of software engineering project, I would say working and groups and using some sort of version control is key. Being able to split the workload is extremely helpful, and with version control everyone stays up to date, and you never get too far off track.

Prime Directives

1. The system successfully accomplishes a useful task.
   I believe that our project accomplishes a useful task in the sense that it gives Team Hawaii potential ideas for the actual home's management system. Besides providing ideas to Team Hawaii, doing this project allowed me to get more experience with wicket and web design.
2. An external user can successfully install and use the system.
   As long the user has java installed they can simply download the jar or source file from here. We have an in depth user guide on our google project hosting site; the user guide can be viewed here.
3. An external developer can successfully understand and enhance the system.
   Because we used Ant as our build system, any developer can download and further develop our system with ease, regardless of operating system. Also, developers can view our developer guide wiki page here.

Deliverables
All files associated with this project can be downloaded here.

Wicket Katas

Overview
For this assignment we were given eleven different coding katas, for Wicket. A coding kata is a programming exercise, which through practice and repetition, will help you hone your skills. We were given eleven katas as Wicket programming exercises in hopes of helping us get a little more familiar with Wicket. Some of them were really easy while others were a bit more challenging, but doing these katas definitely helped me get more familiar with Wicket. I would definitely say that katas, in general, are good for helping someone get used to a new language, framework, or anything that they're new to. Repeating and practicing small exercises, at least from my experience, will help you get used to the new environment you're working in. I would say if you started with a few simple katas and then moved on to increasingly harder ones, you would probably have a firm understanding of whatever it was you were trying to learn. In the following section I will visit the eleven Wicket katas that we did in detail.

The Eleven Wicket Katas

• Exercise 01
  Kata 1A - Add a new line to the page that says, "In one week, the time will be ", where is replaced by a timestamp one week later than the timestamp that now appears on the page.
  • Finished: Yes
  • Time to complete: 10 minutes
  • Problems Encountered: The only problem I ran into for this kata was whether to use Date or Calendar for displaying the date. I couldn't figure out how to add time using Date, so I ended up using Calendar because it has an add method built in.
  Kata 1B - Add a button to the page labelled "Refresh". After pushing the button, the times update themselves.
  • Finished: Yes
  • Time to complete: 15 minutes
  • Problems Encountered: I had a problem with the buttons onSubmit method. I didn't realize that you have to override the onSubmit method.
  Kata 1C - Wicket, by default, runs in "Development" mode, but production systems should run in "Deployment" mode. Override the getConfigurationType() method so that Example01 now runs in Deployment mode.
  • Finished: Yes
  • Time to complete: 5 minutes
  • Problems Encountered: This kata was particularly easy; it just took a quick search to figure out how to change this setting.
• Exercise 02
  Kata 2A - Add an additional link on the home page that says, "Go to image page". Create this page, which should display an embedded image. This image should be G-rated. It should be in a .jpg file stored with the system, not retrieved from the web.
  • Finished: Yes
  • Time to complete: 1 hour
  • Problems Encountered: I got the image and link working properly within 5 minutes, but it took me an hour to figure out why the image wasn't rendering properly. After some help from other students I was able to fix the issue and get the image to render properly.
  Kata 2B - Add a button on the home page with the label, "Make font bold". After the user pushes it, all the text on the page should become bold, and the button label should change to "Make font italic". When the user pushes that button, all of the text should change to italic and the button label should change to "Make font normal". Pushing that button changes the text back to its original state and the button label should now say "Make font bold".
  • Finished: Yes
  • Time to complete: 25 minutes
  • Problems Encountered: Most of the time I spent on this kata was spent thinking of how I was going to program it. When I started programming it was pretty straight-forward and everything seemed to work smoothly.
• Exercise 03
  Kata 3A - Add a new tab called "Image" that takes the user to a page containing an embedded image (your choice, G-rated). It should be in a .jpg file stored with the system, not retrieved from the web.
  • Finished: Yes
  • Time to complete: 5 minutes
  • Problems Encountered: This kata was essentially the same as kata 2A so it was very easy to complete.
• Exercise 04
  Kata 4A - Add a new cheese called "Velveeta", which costs $0.25/lb.
  • Finished: Yes
  • Time to complete: 5 minutes
  • Problems Encountered: None, this was just a matter of adding a new item to the list of cheeses.
  Kata 4B - Add a "country" field to the billing address that appears when checking out. The country field should provide a drop-down menu with a selection of 5 countries.
  • Finished: Yes
  • Time to complete: 30 minutes
  • Problems Encountered: I didn't realize that I needed to modify the Address object at first, so I was only modifying the CheckoutPage java and html file. This caused errors to occur and it took me a while to figure out that I needed to modify the Address object and add in the country.
• Exercise 06
  Kata 6A - Get rid of the blue columns that appear when displaying the website. These are for development, not deployment purposes.
  • Finished: Yes
  • Time to complete: 2 minutes
  • Problems Encountered: No issues came up, I just had to change the style from "container showgrid" to "container".
  Kata 6B - Place the image underneath the form, not to the right.
  • Finished: Yes
  • Time to complete: 2 minutes
  • Problems Encountered: No issues, just had to make both the image and form divs used up the same amount of columns.
  Kata 6C - It is often convenient for web applications to consult a properties file when starting up in order to get configuration values. An easy way to do this is with the standard Java Properties mechanism. (See Java in a Nutshell for details on properties file manipulation.) For this Kata, modify your Example06 system to read in a file (if present) located in ~/.example06/configuration.properties.
  • Finished: Yes
  • Time to complete: 40 minutes
  • Problems Encountered: I just had to do some research on how to use Properties in Wicket, besides that everything was pretty straight forward.

Deliverables

• akinsey-wicket-example01
• akinsey-wicket-example02
• akinsey-wicket-example03
• akinsey-wicket-example04
• akinsey-wicket-example06

Wicket Chart Web Application

Overview
For this venture, we were given the task of creating a website with an interactive graph using Wicket and Google Visualization. Wicket is a Java based web application framework which basically allows you to use Java to create advanced web applications, and Google Visualization allows people to create dynamics graphs with all types of data. For this task we combined Wicket and Google Visualization to produce a webpage that allows you to modify the data values, ranges, and title of the graph displayed on the page.

Learning Wicket
As mentioned by the instructor of my Software Engineering class, Wicket has a very steep learning curve. Needless to say it wasn't easy to learn; even reading Wicket in Action, a book on Wicket, didn't fully prepare me for the actual programming aspect. At first glance, the code seemed quite overwhelming but after sitting down and actually studying the code I began to connect the pieces. In my opinion, frameworks like Wicket require hands on experience to actually learn how to use them.

To be completely honest, my general impression of Wicket is that it's excessively complicated to design what should be a really simple webpage. Take the page I designed for this assignment for example: it took me six java files and one html to create. If I were to create this same page in php, a web scripting language, it would take me a single php file and be immensely simpler. One thing I particularly liked about Wicket is the fact that you can use automated debugging tools such as checkstyle, findbugs, and pmd. Finally, like how I could used an automated building system like Ant to manage the entire project, as this greatly speeds up this development and distribution process.

The Web Application
As mentioned above the function of the web application is pretty straight forward: you can modify the form values on the left of the page and the changes will reflect on the chart displayed on the right. Below is a screen shot of the application to give everyone a better idea of what the application looks like:

Lessons Learned
Given the task, I learned that web application development is definitely not as easy as it seems. The process is definitely tedious, but life can be made easier by using tools such as ant, findbugs, checkstyle, and pmd. While doing this assignment, I was really just reassured about how necessary automated quality assurance tools are. I'm glad that I got some experience with Wicket in the process of doing this assignment, and I in the future it might be useful if I have to design a large web application.

Deliverables
My Wicket chart web application can be downloaded here:
http://www2.hawaii.edu/~akinsey/ics413/wicket-chart-akinsey-1.1.1117.zip