Daniel Watrous on Software Engineering

A Collection of Software Problems and Solutions

Posts tagged software licensing

Software Engineering

Software licensing: Wicket pages and panels

My initial perception of wicket panels was that they were like includes. This naturally lends itself to header, footer and style content that will be the same throughout a web application and avoids duplicating code.

It seems wicket panels are more widely used than I first expected. For example, I keep seeing examples of a very lightweight page where panels represent the majority of the content too. This is a more segmented approach than I have seen in the past, and I can see some benefits and drawbacks to it.

Based on other frameworks I would typically structure each page with the following files:

  • header [common]
  • footer [common]
  • page

This would be repeated for additional pages with the header and footer representing the only elements common among all pages. In wicket the design changes by adding a new file

  • header [common]
  • footer [common]
  • page [common]
  • panel

By segmenting the content of the page out into panels, the page frame itself becomes reusable. It also makes it possible to use some clever wicket extensions, like breadcrumbs and tabbed ajax panels. These can save a lot of time in development. Another benefit is that it keeps you in the habit of creating panels for page sub-components, which can increase code reuse and maintainability.

The biggest pitfall I have found so far is that panels rely on state and the URLs are not bookmarkable. I know that’s what wicket is all about, but in terms of search engines and bookmarking pages, this can be a big drawback.

For example, when implementing the documentation pages for the API of the software licensing appication, I made use of the breadcrumb extension and put all the content in panels. I found afterward that based on the way it is implemented, it’s not possible to bookmark a link to a specific API document. The same lack of bookmarkable links exists in the tabbedpanel that I planned to use. Unfortunately this won’t do.

While I may leave the content as a panel, I now see that my implementation needs to be pages so that I can map them to specific URLs.

The alternative would be to make use of the extensions and give up the bookmarkable URLs. However, when I’m working with an API, emailing a support or user list or creating tutorials I frequently link to specific API documentation and I rely on Google to know how to find that documentation when I search for it.

I have sent an email to the wicket user list about the whether the breadcrumb extension can be made to work with bookmarkable URLs, but I didn’t get a response. If anyone responds then I’ll update this post with the solution.

Software Engineering

Software licensing: Authentication and authorization for admin pages

For simplicity and security I’ve decided to integrate with the Google Account authentication mechanism that’s built into Google App Engine. This allows anyone with a Google account to login to my application without the need to setup another account. This also gives me access to the user’s valid email in order to send messages and other communication related to the service I provide.

So far I have three separate ‘areas’ for interfacing with my service. The first area is comprised of public pages, such as the home page or privacy policy. The next area is the API where RESTful access will take place. That leaves the administration area where an account administrator will be able to view statistics, adjust licenses, etc. These are mapped as follows

http://domain/
http://domain/api/
http://domain/admin/

The API will require authentication with each call in the form of an apikey (may change to oAuth in the future). I was able to secure the admin area of the site by adding a security-constraint to the web.xml file. Here’s what that looks like.

1
2
3
4
5
6
7
8
9
10
11
<web-app ...>
	...
	<security-constraint>
	   <web-resource-collection>
	       <url-pattern>/admin/*</url-pattern>
	   </web-resource-collection>
	   <auth-constraint>
	       <role-name>*</role-name>
	   </auth-constraint>
	</security-constraint>
</web-app>

You might have noticed this mechanism is not limited to authentication only. It’s also possible to include authorization preferences by role using role-name.

Software Engineering

Software licensing: User interface design (with video)

User interface design is every bit as important as the core software that runs on the server. A poorly designed user interface can significantly impact the end result of a web development project. Here are a few ways poor design can hurt a web project.

  • Reduced adoption rate due to confusion about accessing features
  • Underutilization of available features
  • Increased frustration for the user and support burden for development team
  • Poor conversion (sales) rate!

User interface is much more than AJAX and color choices

It’s important to clarify that when I talk about user interface design I’m not talking about which components might use AJAX or what color items might be used. Those can be important, but what I mean is the basic structure and function of the user interface.

My long standing rule is to start on paper, just as I do with software design. In the design documents below you can see that I start by just writing down everything I want to be available to the user. I also begin to identify some implementation specifics where they are obvious. The reason to think about implementation at this point (remember we’re using wicket) is that the manner in which our framework renders these components in markup could be useful to the graphic designer who builds the UI.

Design Sketches

These documents serve as a guide while developing the server side software. They are also the entry point for vendors or team members that you bring on to collaborate. One tactic that I use a lot is to scan a hand sketch (like what you see above) and then create a Jing video using Prezi (or even Google Picasa) explaining what I want from a vendor or team member. Below is the video I made to get bids for the client side code development for this project.


Notice that these hand sketches only took me 20 or 30 minutes to draw and scanning took a couple of minutes. The Jing video took about 10 minutes to record and upload to screencast. In under an hour I have a good first iteration for the UI for the software licensing system.

Detail and Quality

Some will argue that such a coarse approach doesn’t provide the attention to detail that is required for a high quality UI or that an approach like this will only work for small scale projects. That may be true, but in my experience I’m not sure that I do any more tweaking to a design that I put together like this or any less tweaking to a design that I hash over for days or weeks. In the end, it’s been my experience that this approach gets me to a finished product faster and leaves me a lot of flexibility without sacrificing long term quality.

Software Engineering

Software licensing: The value of good books

I have a large budget for books (but thanks to Amazon it doesn’t have to be as big as it could be). Sure it’s true that most of the information in programming books is online and available for free. There may even be substance to the argument that most books are out of date as soon as they hit the shelf because technology moves so fast. Oh well.

I get huge value from books. They save me many hours of time that I might spend scouting around for a snippet here or an explanation there. One of my favorite publishers of technology books is O’Reilly.

For this project I purchased Programming Google App Engine by O’Reilly. It’s a fantastic book so far and covers a lot of ground. Bookmarking, highlighting and so on gives me a quick path back to bits that I’ve learned.

Another book I purchased for this project and for my shelf is Thinking in Java (4th Edition) by Bruce Eckel. I previously read the free downloadable version of his 3rd edition. He provides uncommon depth in his approach, tying Java back into the other languages that inspired it. That context is extremely valuable!

If you have a hard time spending $100 or more on books for a project, just ask yourself how many hours you would have to save in order to justify the cost. At today’s contractor rates that might only be two or three hours to hit the break even point. Across the life of a project, a well written and edited book from a trusted publisher can save you many more hours than that.

Software Engineering

Software licensing: Jersey framework for REST

I did some investigation into building the RESTful API for the software licensing system using wicket. At first I was encouraged that URL management was so easy (nevermind that really old article I just linked to).

Wicket Not Ideal for RESTful APIs

In the end I decided that wicket was not a good choice for the RESTful API. The crux came in treating HTTP methods differently. In other words, for a given resource URI, I want to do something different for GET, POST, PUT and DELETE. That’s not one of wicket’s strengths, so I moved on.

The first framework I looked at had a really slick look. I know that’s not necessarily an indication of technical superiority, but the simplicity of the homepage made me believe that Restlet would be a good choice. But before making my choice, I looked for references and found this stackoverflow discussion.

Jersey Wins

I had seen Jersey before reading that, but was turned off thinking I had to dive deep into glassfish and other technologies. The stackoverflow discussion convinced me to give Jersey a try and I’m so glad that I did. In about a half an hour I had my initial API calls framed and responding to web calls in Google App Engine.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
package com.danielwatrous.softwarelicensing;
 
import javax.ws.rs.GET;
import javax.ws.rs.PUT;
import javax.ws.rs.DELETE;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
 
//The Java class will be hosted at the URI path "/sitelicenses"
@Path("/sitelicenses")
public class SiteLicenses {
 
	@GET
	@Produces("text/plain")
	public String getAllSiteLicenses() {
		// Return some cliched textual content
		return "Hello World GET";
	}
 
	@POST
	@Produces("text/plain")
	public String createNewSiteLicense() {
		return "Hello World POST";
	}
 
	// @PUT
	// @DELETE
}

I followed this extremely concise Jersey + GAE tutorial to get things going. There were more jar files required that are shown there. Otherwise I can’t believe how easy it was to get my RESTful API framed in and working.

TIP:

About a year ago I found a great tool to explore REST and test RESTful services. It’s a Chrome plugin named Simple REST Client. This makes it possible to send requests to a URI using any of the HTTP methods and see the full response, including headers. Here’s a screenshot of my first API response:

Software Engineering

Software licensing: RESTful API, resources vs. parameters

I’m starting to build out the RESTful API for the software licensing system. The first api call to implement is this

http://mysite/api/sitelicenses/?apikey=KEYVAL

That came from the initial design documents and implicitly suggests that there is a difference between the resource and parameters passed in when asking for the resource.

This distinction is important and came up today when I was thinking about pagination. As the API is defined currently, the above URI would return all site licenses associated with an apikey. The first thought that came to mind was that the number of licenses could be very large and so there needs to be some way to paginate the results.

Difference between resource and parameters

The pagination itself shouldn’t be too difficult. However, I wanted to be sure that the API calls made sense and would be intuitive. That brought me to this discussion about pagination in a REST web application. What I take away from that post is that it’s fine to mix query string parameters with RESTful identification of a web resource. That wasn’t clear to me before.

One helpful tip given in one of the comments was to look at the Twitter API. I did have a look and I do agree that it’s very clean. They have a clean and clear style of documenting the API and the structure of their RESTful calls, which includes both identification of resources and parameters to paginate, limit or otherwise clarify aspects of that resource.

Structuring my API so that it clearly identifies resources and accepts parameters in a query string in the URI is how I’ll approach development for the current software licensing plugin going forward.

Software Engineering

Software licensing: A slight change in scope

In the current series of articles I’ve been talking about development of a system to enable premium wordpress plugins to be protected by licenses. While working on the design and going through a brain storming session yesterday with a colleague I had two small realizations.

The first is that from the beginning I have planned to keep the WordPress coupling separate from the main licensing API. In fact, I haven’t planned to include any WordPress specific or shopcart type features in the API. This provides me with some benefits. One is that it keeps the focus of the licensing system on licensing only, not on how or where it will be used. It also makes the API more general and flexible.

The second realization should be rather obvious. This is a software licensing system, not just a WordPress plugin licensing system. I’ll be changing the focus of this series to reflect that more general use case.

Once the plugin system is complete, I’ll then go through a series of specific integrations, including WordPress, PHP, Python, C#, etc.

Even though the titles of the articles will change to software licensing, we’re still working on the same project. We’ve just make the important realization that a more general solution is possible and even desirable.