Assignment A07: API Design for iHale

The acronym API gets thrown around a lot these days and it is intended that a programmer know exactly what it entails. API stands for "Application Programming Interface." This interface sets the foundations to describe the usage of an application. This sounds simple enough, but this is a very difficult practice. To create a good API, one must consider all the needs of the user.

The API must provide flexibility and functionality, especially for cases that the designer has not thought of yet (although they should try to think of everything). The task becomes exponentially hard when the user doesn't even know what they want, thus the programmer must guess. And this was the case in A07: API Design for iHale.

As mentioned in previous blogs, my team and I are responsible for designing the the system for a self sustaining house. It can be assumed that there are sensors to monitor various environments belonging to the house and actuators to invoke changes on these respective environments. And at this point of time, we are still guessing at the requirements of the engineers.

According to Joshua Bloch, an employee of Google, a good API must be:

• Easy to learn
• Easy to use, even without documentation
• Hard to misuse
• Easy to read and maintain code that uses it
• Sufficiently powerful to satisfy requirements
• Easy to evolve
• Appropriate to audience

So in a sense, the programmer is trapped by his/her API once it is created. Thus, we have to think carefully at how we would like to design the API surrounding the system behind the inner workings of the house. We have to plan for a future that we can't readily picture and make sure our application has the flexibility to placate to unforeseen needs/problems.

It is with this intention that we designed our Java API and Restlet API. For the task of designing our Java API, we need to create objects that can be readily used to interact with the front end of the system and the Berkley DB backend. For the task of designing our Restlet API, we need to create resources to interact with sensors and actuators contained by various environments of the house. Since as of yet there is no agreed standard for each system, we tried to abstractly generalize the requirements.

In the restlet (http) interaction between the simulated house and iHale, we generalized that there would be multiple systems to be monitored. Each system could contain multiple environments. For example, there could be an aquaponics system which could contain a fish-tank environment and a plant-tank environment. Each of these environments could be monitored by sensors and modified by actuators. For another example, a sensor could monitor pH (or consolidate pH and temperature, etc) and an actuator could provide measures to offset pH (i.e. adding base/acid). These sensors and actuators will be our resource objects which will be interacted with by the back end.


As for the Java API, we provide a MasterSystemObject that will act as a proxy/boundary for any interaction with the house simulation. It will contain subsystem objects which in turn will contain environments. The environments will contain devices that will either be sensors or actuators. It should be again noted that the user of the Java API will not see these subclasses. The MasterSystemObject will provide intuitive methods to allow the programmers to invoke changes as they see fit.

All in all, I'm not sure if we met the required criteria for our API design as many of our fellow class mates went in a completely different direction. This was not an easy task by any means. Design is a very hard subject to teach and often takes a lot of experience to make good design decisions.

Assignment A06: BerkeleyDB code katas

The purpose of the following entry is to introduce the use of the Oracle Berkley DB via an exercise and describe how it works in combination with Restlet and Wicket.

The Berkeley DB library is a building block that provides the complex data management features found in enterprise class databases. These facilities include high throughput, low-latency reads, non-blocking writes, high concurrency, data scalability, in-memory caching, ACID transactions, automatic and catastrophic recovery when the application, system or hardware fails, high availability and replication in an application configurable package. Simply configure the library and use the particular features available to satisfy your particular application needs. Berkeley DB is a reliable solution with over 15 years of production use in products ranging from cell phones to e-commerce. The primary goal of Berkeley DB is to deliver fast, scalable and flexible data management services to your application while remaining transparent to your end-user.

Kata 1: Timestamp as secondary index (Completed: True, Time: ~ 1 hour)

Part I: Implementation
The example system we were introduced to by Professor Johnson provides a single key for retrieval of a Contact object. This "primary key" is the object's unique ID. For this Kata, we first implemented a "secondary key" alternative for Contact. The secondary key consists of a timestamp represented as a long value that can either be inputted directly, or generated dynamically.

Once the secondary index was implemented we had to extend the ContactClient system with two new commands:

get-timestamp: returns the Contact with the given timestamp, if such a Contact exists.
get-range: returns the set of Contacts with timestamps between two specified values.

I should have used the cursor function to iterate through the contacts currently stored in the database, but instead I used a naive for loop. This accomplishes the functionality by going through the range of timestamps specified by the user. This would be very bad, especially if there is significant differences between the times in which the timestamps are created.

For example:

If the user specifies 1 1000 for the range, but there are only 3 secondary keys between this range, the current method is inefficient. When I have time later, I would like to research more on the cursor function.

Part II: Testing
When one creates the timestamps for a contact dynamically upon creation, it can be problematic for JUnit testing. Creating two Contacts, one right after the other, can happen so fast that they will have the same time stamp. It is because of this that the implementor may wish to add the timestamp in just before it's entry into the database.

Kata 2: Wicket, REST, and BerkeleyDB: A match made in heaven (Completed: True, Time: ~ 6 hours)

For this example we created a client-server (i.e. web application) system for managing contacts. We provide a Wicket client front end using Restlet to communicate with BerkleyDB. The Wicket client consist of a single page, and allows the user to store a contact given its information. The functionality to retrieve a contact given its unique ID is also there. The Wicket client code essentially invokes an underlying Restlet-based module to send a request to a ContactDB server to put or get data.

This Kata was highly dependent on the fact that you already knew how to "get" and "put" contacts using Restlet's framework and were very comfortable dealing with Documents and DomRepresentations. I had to cut and paste a few methods from the previous Kata assignment to make everything work smoothly.

The use of sessions to store the data was a neat review and is important to have all transactions on the web application independent of each other no matter what user is on it.

It should be noted that I had to disable the checkstyle check in verify.build.xml as

Missing package-info.java file

is causing the verify to fail and I couldn't readily find a solution. I hope to figure this out for a later blog post.

Here is a link to my distribution

Assignment A05: Restlet Code Katas, Part II

The second part of the Restlet Code Katas involved learning how the service works with XML. This was a very interesting exercise in that I've never really worked with XML. It's nice to finally understand how information is dynamically made and stored in this format.

The Katas are as follows:

Kata 5: Contacts resource (~3 hours)

For this particular Kata, we we modified the Restlet system to support a new resource called "contacts" and its associated URL: http://<host>/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.  To support the RESTful style of hypertextual links, the XML had to look like the following:

<contacts>

  <contact>http://host/contactservice/contact/ID</contact>

  <contact>http://host/contactservice/contact/ID</contact>

</contacts>

The actual <host> and actual <ID> for all <contact> elements are substituted and returned in the XML.
This requires the system to programmatically determine the URL of the current host.  We accomplished this by use of this type of call inside of the ServerResource method:

getReference().getHostDomain() ... etc.

We also needed to extend the createInboundRoot() method to support the new resource, and add a new package, class, and associated unit test. Overall, there was quite a bit of code to be added. One had to understand the use of objects:

• DomRepresentations (org.restlet.ext.xml)
• Document (org.w3c.dom)
• Element (org.w3c.dom)

to implement the changes required to access the resource "contacts" and have it display the information "put" into memory storage. I did not know that chrome and safari automatically translated XML when viewed. I wasted much time on this trying to figure out why my pages weren't showing up.

Kata 6: Command line client manipulation of Contacts resource (~3 hours)

After we implemented the contacts resource, we were required to extend the command line client to support a "get-all" and "delete-all" operation.

The get-all operation had to invoke the GET contacts command to get the XML representation containing links to all the contacts, then extract the URL of each contact and perform a GET to retrieve its representation. Then print out the contact info associated with that URL (I.e. first name, last name, info).  The main changes had to be done in ContactClient.java.

The next step, which used the get-all operation, was delete-all operation. This operation had to use the GET contacts command to get the XML representation containing links to all of the contacts, then extract the URLs, then call DELETE to delete them. Sample output can be seen below.

I had a few odd thread errors during this kata (i.e. concurrentHashMap was having issues). I'm still not exactly sure how I fixed it, honestly. I ended up having to wipe my set up at least once and rebuild. The (only) good part about having to redo some work is that it reinforced quite a bit of knowledge imparted to us by Professor Johnson.

Kata 7: Add a telephone number to the Contact resource (~1.5 hours)

The final kata required the extension of the Contact resource to include a telephone number.  The telephone number must contain only numbers and the "-" character.  The following regular expression validates that the user has inputted a number-number format.

Pattern p = Pattern.compile("^\\d+(-\\d+)+");

Thus, when clients do a PUT of a Contact representation in XML format, the server checks that the telephone number field has the correct format and set the Status field to indicate an error if the telephone number is incorrectly formatted. Both unit tests to check valid input and invalid input are provided in my distribution.

A link to my distribution file can be found here

Assignment A04: Restlet Code Katas

Code katas are exercises in programming that help you to refine your skills. In this assignment, we  actively worked with an example REST architecture: the restlet-dateservice.

The RESTLET tutorial proved to be the initial step to solving most of these katas:

Kata 1: Time resources (~1 hour)
For this Kata, I was required to add three new resources called "hour", "minute" and "second" that return the current hour, minute and second.  I then wrote JUnit tests for each of these resources and made sure they passed. The tests simply required that I make simple cases that checked to see if the data returned by the server matched the curent java.util.Calendar date. Since all of these sample tests passed in flying colors and I deleted the test cases as they weren't worth having. My test case for Kata 4 is very similar to these.

Kata 2: Logging (~3 hours)
This particular Kata required that I figure out a way to enable a logging feature for Restlet.
By default, Restlet logs data about each request to the command line using the Java Logging API.  I had to read a few tutorials to get familiar with the API. The trickiest part, I found, was deciphering what exactly I had to put into the logging properties file and what all the commands entailed. This step took a little trial and error while I defined a ~/.dateservice/logging.properties file that enables the user to specify (among other things) that the logging information should go to a file, not the command line.
tell the restlet-dateservice application to read and use the logging properties file in ~/.dateservice/logging.properties

These are the resources I looked for inspiration to solve this particular Kata.
http://www.naviquan.com/blog/restlet-cookbook-log
-This link hand the most concise break down of the appropriate steps to achieve the required functionality.
http://download.oracle.com/javase/6/docs/technotes/guides/logging/
http://onjava.com/pub/a/onjava/2002/06/19/log.html

Kata 3: Authentication (~1 hours)
The current restlet-dateservice system, given to us by Professor Johnson, performs no authentication.  This again required that I vist the user guide (and/or google) for guidance. From here, implementing the HTTP Basic authentication was pretty straight forward. Since all resources stem from the server resource, they all should naturally be should be available due to the fact that it only required that I modify DateServer.java. Thus, HTTP Basic authentication is enabled in my distribution. and passes the username "guest" and password "pw". These were hardcoded to work in the form:

http://guest:pw@localhost:8111/dateserver/...

Kata 4: Wicket (~3 hours)

This was the most tricky kata. This task required that we create a new client for the DateService server that is a web application using Wicket and not a default command line application.  The web application brings up a single page with a single form that requests what aspect of the date (year, month, day, hour, minute second) the user desires. When the user submits the form, the web application uses Restlet to obtain the appropriate information from the DateService server, then presents the results to the user in the page.

It required that one really understand how the restlet http get protocol works in regards to server challenges. If it were not for the authentication feature added in the previous kata, the task would have been extremely straight forward. However, I noticed I was getting authentication errors (401)
The following code describes what must be modified to get the proper retrieval of resources in which a server issues challenges for authentication:

    Reference ref = new Reference("http://guest:pw@localhost:8111/dateserver/" + props.get("Unit"));
    string[] userinfo = ref.getUserInfo().split(":"); // "username:password"
    string username = userinfo[0];
    string password = userinfo[1];
    ClientResource clientRes = new ClientResource(ref);
    clientRes.setChallengeResponse(ChallengeScheme.HTTP_BASIC, username, password);
  
    try {
      add(new Label("ValueLabel", clientRes.get().getText()));
    }
    catch (ResourceException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
    }

A test case similar to those required in the first kata is provided in the distribution. It simply tests the submission and retrieval of the dateservice/hour.

A link to my distribution file can be found here.

33.DecathlonDesign3

I learned a great deal trying to make a pseudo-implementation of our decathlon design. In summary, Wicket is a fickle beast and blueprint CSS is useful. As for the 3 prime directives of software engineering, I will describe how our implementation met the required criteria:

1. The system successfully accomplishes a useful task.

I believe the objective of the system we implemented was to show a way a user would theoretically interact with the solar decalthlon house system. Our product is still a mockup of sort and was pitched to Professor Johnson, who will in turn show it to the leads in charge of the Solar Decathlon Project. The system's usefulness will be evaluated by whether anyone likes it or not. However, I believe we managed to create a useful implementation that will eventually help guide the direction of our ICS414 full implementation of the Solar Decathlon Home System. I believe this provides enough proof that we satisfy the 1st prime directive.

2. An external user can successfully install and use the system.

The documentation of our project can be found at http://code.google.com/p/solar-decathlon-teamhawaii-2/w/list. What is nice about the way wicket works is that one only simply needs to have java installed to run the wicket server via a .jar file. Our respective .jar can be found here. By simply typing in "java -jar wicket-solardecathlon1.3.1.jar," a user is able to start their own web server with our wicket content. This is quite clever as no other third party add-ons are needed.

External users can check-out our project being hosted on Google Code if they wish to see what we've done or wish to make changes (granted they have to be of the proper group). I believe this provides enough proof that we satisfy the 2nd prime directive.

3. An external developer can successfully understand and enhance the system.

Our code is well documented and we have run the ICS413 build system quite thoroughly to make sure the style is uniform with all the other projects being presented. The wiki page mentioned previously will also provide an external developer some other necessary documentation for them to build on what we have started. I believe this provides enough proof that we satisfy the 3rd prime directive.

If we had chance to do this all over again, I probably would have tried to make sure that certain naming conventions and css methodologies be followed when writing the code. There were a few cases were miscommunication on our parts lead to confusion and the wasting of time modifying variables in a convention that each of us would use, yet the others would not. Communication is a huge deal, and an important part of the development process. We had to have quite a few meetings and online chat sessions to make sure all of us were on the same page. The critiques from Professor Johnson during our final presentation proved we had to change our color scheme. Although it displayed well on our screens, it should display well universally. Testing once again struck with vengeance.


As an added note, getting jquery working with wicket was a fairly painful process to learn with the fullcalendar package. But I am confident now I will be able to successfully add more jquery features and move around css much more quickly thanks to the experience I've gained working with the wicket framework and the blueprint css package.

31.WicketKatas

Overview Code katas are exercises in programming that help you to refine your skills.  The goal of this assignment is to: Improve your comfort level with Wicket by performing a number of small changes to existing Wicket systems. Each Kata involves a modification to one of the example systems in the ICS Wicket Examples project.   To start, I downloaded all the .zip distribution of all examples but example05 to your local system.  I edited the build.xml file so that the project name is no longer exampleNN, but rather exampleNN-kteichma. I then ran "verify.build.xml" using Eclipse. These example files were modified in the following ways: The Eleven Wicket Katas Example 01: Kata 1A:  Add a new line to the page that says, "In one week, the time will be <time>", where <time> is replaced by a timestamp one week later than the timestamp that now appears on the page. Kata 1B: Add a button to the page labelled "Refresh".  After pushing the button, the times update themselves. 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.  See this page for details.  This particular example was finished by my partner and I during our class period. It took about 40 minutes. Professor Johnson gave some nice hints on how to you the java Date constructor to make a date from a timestamp. I was able to review form usage in this particular kata and discover the development mode. Example 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. 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". Kata 2A was finished in class. Estimated time it taken to complete was around 40 minutes. I can't remember too much about this one other than it took us a while to figure out that there was an Image object we could use to add pictures stored on the system to the webpage. Kata 2B was a little harder, and I'm not quite pleased with the solution I implemented. I ended up making separate form pages for italicized and bold lettering. There is obviously a better way to do this, such has make bold and other style labels, but this was the only solution that occurred to me in my lack of time. Example 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. This particular example took about 10 minutes as it was very simular to example 2a. It was almost a no brainer as I was able to copy and paste most of the code used in kata 2A. Example 04: Kata 4A:  Add a new cheese called "Velveeta", which costs $0.25/lb. 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. This particular example took 40 minutes. I had some issues with this particular kata in that it took a while to figure out how the data was stored. It will be interesting to eventually see how this front end will end up working with DB back end. As of now, all of the entries are hard coded into the java source. Example 06: Record how long it took you to accomplish each of these katas. Kata 6A:  Get rid of the blue columns that appear when displaying the website. These are for development, not deployment purposes. Kata 6B:  Place the image underneath the form, not to the right. 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.   (Note that ~ means "the user's home directory", and that there is a System property in Java that provides this value.)  This property file should contain a line like the following: deployment = true In other words, it contains a property called "deployment" whose value is true if the Wicket application should run in deployment mode, otherwise the application should run in development mode (see Kata 1C). Your application should read in the properties file and set the System property wicket.configuration before starting up Wicket. The Jetty class is a convenient place to do this processing. Finally, your application should write out a message on startup indicating whether or not it found the file, and what the resulting configuration mode will be.  If the file is not found, or the property is not present in the file, then the application should run in development mode.  This particular example took me another 40 minutes. I still was not able to finish Kata 6C as I have been running out of time juggling ICS311 and ICS413 and ICS321 these past 2 days. Big projects all due at the same time. Kata 6A was a fairly easy change as turning off the grid doesn't require much. As for kata 6B,  this just required some basic knowledge on how grids work and making more area. Overall, I enjoyed the process of experimenting with Wicket and I look forward to using it more extensively in the future. However, I do recommend keeping our options open as http://oodt.jpl.nasa.gov/better-web-app.mov provided by Professor Chin in my 215 scripting class, shows that there are great alternatives out there. Here is a link to my distribution file

30.WicketChart

The Wicket Project we were assigned was to implement a one page web application that provides two components: 

1. A form that accepts a variety of parameters
2. Along with a submit button that when pressed, generates a GoogleOMeter visualization.  

To see what a GoogleOMeter is, go to http://imagecharteditor.appspot.com/, then click "Show full gallery", then scroll to the bottom.  The last three visualizations are GoogleOMeters. I ended up choosing the 3rd visualization

The form should allow the user to: 

• Set the start and end of the Y axis;
• Set the title
• Set the width
• Set the height
• Provide a data value for the pointer

The web application in general should:

• Use Wicket
• Use Blueprint CSS for layout
• Use the ICS 413 build system
• Provide at least one useful test case
• Employ sessions so that multiple users can generate charts independently

In terms of testing, I employed that the lower bound and upper bound values would have error checking to see if the user had inputted nonnumerical characters. Since extract a string from these text boxes via Double.parseDouble(), if there is, for example, a letter in the "Lower Bound" text box, this would cause an exception. My program catches this exception and immediately sets the values of all the bounds, lower, mean, and upper to zero. On the case that the user enters correct input, the "Mean" becomes the average of the lower and upper bounds. My JUnit test explicitly tests for this particular case of erroneous user input and verifies that the "Mean" value gets set to "0.0" to allow for the chart to still be created with safe values.

The overall experience of this assignment was quite good. The CSS grid style layout was fun to play and felt similar to other grid layouts used in other various programming language interface structures. See http://www.learncomputer.com/blueprint-css/ for reference on the CSS system we employ in our web application.


Using sessions and the ICS413 build system proved to be tedious, but nice once everything was working properly. Going through all the errors and satisfying what was generated by our style checkers (build.pmd.xml and build.checkstyle.xml) was a pain to say the least. It was almost as painful as porting the form provided by Professor Johnson's wicket-example06 into a single page to be viewed and interacted with by a user. It really forced me to read through the code and figure out how the wicket system works. However, the overall experience was a good exercise in problem solving and hard work. I look forward to working with Wicket in the future.

My distribution for this assignment can be found here.