Archive for April, 2010

Active Preview 2.0 Release!

April 25, 2010

Just dropped a major update to Active Preivew, a wordpress preview that allows you to see your changes as you make them! I have fixed issues with previewing newly created posted and most importantly added AJAX callbacks once typing in the editor is complete to refresh the preview automatically in case you are relaying on wordpress to parse and render any tags or markup.

http://wordpress.org/extend/plugins/active-preview/

Advertisements

When to Repeat Yourself

April 18, 2010

One principle in software engineering is “Don’t Repeat Yourself”. It has been around for as long as I can remember and is the hallmark in many cases of good code.  Many times I think developers fundamentally get stuck in this “don’t repeat yourself” mode outside of the code because we train ourselves so much to be constantly thinking about efficiency. Because of this, it creeps into places where it shouldn’t be. And gives developers like myself an excuse to say “we don’t need that document because the information will be in another document” or “just look at the code if you need to know something”. Both are certainly good justifications in some situations, however they don’t always hold up. I want to throw out some ideas for when its OK to repeat yourself to counter balance the efficiency junkies in all of us.

Where is “Don’t Repeat Yourself” abused?

In code its rare where “Don’t repeat yourself” fails because if it didn’t work then the compiler or testers would tell you. That’s the simplicity of code but the places that I see “don’t repeat yourself” being used as an excuse to avoid additional work…

  • Developer to Developer Communication – I’ll single out us developers here but its not necessarily a unique problem. A developer likes to communicate in the most efficient way for himself. One of the main ways we do that is by trying to not have to repeat ourselves when we communicate things. For instance we’ll send out a group wide email or we’ll schedule a meeting to train everyone at once and assume everyone got the message. The problem is you need to repeat communication in many cases because people simply don’t understand (or listen) the first time.
  • Documentation – In some cases the misuse here is trying to combine documents which have similar content but need different levels of detail to cater the correct audiences. The main offense I’m thinking of though is not repeating yourself in documentation because someone can just look at the code. This applies to documentation meant for other developers mainly, especially when someone put work into in-code documentation. The issue isn’t that the source code can’t explain exactly what is happening, it’s that if you plan on having additional people work on the project it increases ramp up time eliminating any time saved previously.

Repeating Yourself = OK

There are a couple of situations which repeating yourself is probably not a bad idea…

  • Different audiences – Anytime you are preparing something for two different sets of people with different perspectives on an application/system, it’s probably a good guess that you’ll need to repeat yourself in either a different format or different level of detail.
  • Buried Information – Many times you’ll have information which is important but gets lost in a larger document or system. When this happens consider repeating it again in a place which is appropriate for the level of importance.
  • Inability to Properly Cross Reference – When you create anything which is dependent upon another piece of information and your not able to actively reference that piece of information for the user to be able to access easily, consider repeating the information. Partial information can be dangerous and leads to issues and confusion.
  • Informal Communication – This is any communication that is not made in a lasting way or requires additional context to understand. Examples of these are a design notes session, training session materials, and many emails actually as well. In this case any communication that wasn’t made in a lasting way needs to be repeated and potentially any supporting documentation may need to be rewritten.

Limited Efficiency

“Don’t Repeat Yourself” is a key concept for being efficient but there is a limit to the efficiency you can gain from it. If you find yourself breaking the guidelines to be able to not duplicate something chances are you just trading efficiency today for lost efficiency down the road. You need to be prepared to repeat yourself for the sake of efficiency of others.

Hidden Gems in Apache Sling

April 12, 2010

One of my favorite open source projects that I’m currently following is Apache Sling. Its a RESTful interface to a Java Content Repository JCR (specifically Apache Jackrabbit out of the box) and also an application framework. I’m less excited about it for the application framework part, but mainly because RESTful content is just that exciting (I’m weird, I know).

Sling is still in the Apache incubator and in my opinion lacking in depth of documentation. Also don’t be fooled into thinking this is a Content Management System, its a system interface into your content which you could build a user interface to manage content on top of. I recently have been doing some searching for additional documentation and peaking around in the source and wanted to expose what I think are two real hidden gems that weren’t easy to find (for me): JSON Query Servlet and JQuery JCR Explorer.

JSON Query Servlet

When you first take a look at Sling you see the ability to be able to request and add specific content nodes RESTfully but no way to query for set of content. This was a real let down because I was interested if  Sling could almost eliminate server side code creation in creating a SOFEA style application. After doing some searching though I found a blog ( http://in-the-sling.blogspot.com/2008/09/how-to-use-json-query-servlet.html ) which detailed the JSON Query servlet which I did not find documentation for on the Sling site.

The query servlet allows you to do xpath or sql like queries on the content repository and get the content back in JSON format. An example xpath query URL would be http://localhost:8080/content.query.json?queryType=xpath&statement=//parentcontentnode/node/*

No install necessary its included within version 5 in the incubator. The drawback is without figuring out access controls it makes your content wide open to anyone who knows your using Sling.

JQuery JCR Explorer Bundle

One of the other things that isn’t included with Sling out of the box is the ability to browse the content repository. You could argue whether or not such a piece of functionality should belong to Sling itself, but it definitely be a nice to have. I looked else where for a quality Open Source JCR Repository explorer. From the explorers I found the best one was an Add-on bundle in the Sling SCM repository at  http://svn.apache.org/repos/asf/sling/trunk/contrib/explorers/jquery. Its a pretty simply jQuery based repository browser which has some issues but overall works well.

To install you’ll need to first build the bundle with maven, ‘mvn package’ should do it. Then start Sling and visit the OSGi administrative interface for the container your running Sling in and install the bundle via the normal process. Once you have installed you’ll have a new ‘explorer’ selector available to visit each piece of content in your JCR. To see the root go to http://localhost:8080/.explorer.html

Active Preview 1.2 Released!

April 4, 2010

Normally I wouldn’t get excited about a point release but we found BIG issues which prevented ALL themes from being supported and issues with firefox file uploading and theme previews. All have been fixed. Hope folks upgrade ASAP! Check it out at http://wordpress.org/extend/plugins/active-preview/.

In case you missed the first release post here is the gist of what the wordpress plugin does.

The plugin provides a new preview button which creates a new window which is updated in real-time with your edits to the WordPress editor (tinyMCE or the HTML editor). Check out the video demo! I know its a little rough.

Plugin site is here http://wordpress.org/extend/plugins/active-preview/

Should I use Open-Session-In-View?

April 4, 2010

The Open-Session-In-View pattern is a very popular strategy for managing open hibernate sessions  for the duration of a request in a server side java web application (possibly for other technologies as well). Basically the pattern uses a servlet filter to open a session on each request as soon as its received and then on completion of processing closes the session. Some people love it, some hate it, and some just use it because they don’t know what else to do.  As with anything I think that there are times to use it and times when its not appropriate. I want to provide some guidelines which I have found are helpful in understanding when it is appropriate.

I’ll assume you know the problem this pattern solves so we won’t talk about that (check out this link for discussion on that). But we’ll need to at least discuss the major implication of the open-session-in-view which is a database connection open for an entire request then cover the guidelines which fall out of that.

Database Connection Open for the Entire Request

Because the pattern is opening a hibernate session first thing on each request which implies that a database connection could be open for basically the entire request. For the purpose of this discussion we’ll assume that the open session ALWAYS correlates to an open database connection for the entire request. In the default case with many versions of hibernate, an open session doesn’t open a connection until it is needed but lets assume the worst case scenario. This will ensure that the pattern is match for you in all situations.

Problems with Open Sessions

If you have an open session over your entire request which is going to have an open database connection associated with it, the problem is that you will be tying up a database connection which is a limited resource in any setting for work which doesn’t necessarily involve the connection. Unless your in a high traffic application this generally won’t affect you but later I’ll show where it could even without large traffic volumes.

Why Most People Don’t Mind Open Sessions

Now most people probably don’t care about having an open session for the entire request or a database connection because in today’s relational database driven web world in a majority of cases 90+ percent of your overhead in a request time is database word anyways. So an extra 10% of time for a session or database connection is worth the cost to drive down complexity in your application.

Exceptions to the Trade Off

The  exceptions to this trade off hopefully becomes pretty clear, when you have application logic which is going to consume most of the processing time of a request the trade off for driving down complexity loses to excessive session and connection time. In many cases your talking a minority of requests which fall into this trap so overall the trade off is still worth it you just need a couple workarounds. In a high request volume situation which limited resources for hibernate sessions/database connections your open-session-view could become a liability.

Guidelines for Open-Session-In-View Usage

  1. Use it when it only when it drives your code complexity down! This pattern isn’t for all applications. when you have complex database interaction either involving multiple databases or complex transaction strategies, it may not make sense. Or if you don’t have hibernate lazy loading issues happening its probably not useful either.
  2. Use when the session/database connection usage is a HIGH percentage of a request’s processing time already. When looking at each request which involves hibernate session/database access and check to see if thats the vast majority of processing time in the request. If this doesn’t apply then either think about another pattern or creating an exception case for those types of requests via filter or some other means.
  3. Use when the only threat to request time is database access itself. If there is potential for something to go wrong like a HTTP to get hung because not timeout is set then this about creating an exception for those types of requests or think about another pattern.
  4. Use when a HIGH percentage of ALL requests filtered require session/database connection access. If you have an application which a low percentage of requests which come into it need database interaction AND you cannot distinguish these requests via your filter or some other means, then don’t use this pattern.
  5. The pattern is preferably used on lower request volume applications. Just a preference in case you are trying to squeeze application resources.

Examples of Where to Avoid Usage

  1. File upload requests – most cases this isn’t an issue but the right combination of semi-large file and slow client network connection could tie up an open session/database connection for some time. Potentially timing out the database connection.
  2. Requests which trigger Service calls – specifically I’m thinking of web service calls where if the timeout on the socket then if the service becomes unresponsive then you’l potentially time up an open session/database connection. Again potentially timing out the database connection.

Active Preview Released!

April 3, 2010

Just finished up a new WordPress plugin called Active Preview. The plugin provides a new preview button which creates a new window which is updated in real-time with your edits to the WordPress editor (tinyMCE or the HTML editor). Check out the video demo! I know its a little rough.

Plugin site is here http://wordpress.org/extend/plugins/active-preview/

WYSIWYG Needs Help

April 3, 2010

WYSIWYG editors (what you see is what you get) have always bothered me a little bit because what you see isn’t always what you get. Because you’re not seeing the content within the context of you entire page theme (in most cases), you could see differences in line wrapping due to page width, styling, and other minor issues. The biggest issue though is that you simply don’t see how your content looks with the rest of the page content.

I have found a pattern to fit this though! I’ll call it the “active preview” pattern in honor of the WordPress plugin I just created with this pattern. Basically you enable a preview window to be opened up and hook it up to receive updates from the WYSIWYG editor (or just text area). That way you can view your changes as you make them without having to hit the preview button each time you make a change and want to see if it fits. In its simplest form it would just be pure javascript (which I’ll show below). But if you needed to pass the text through some back-end processing first to do something like render some business specific tagging or something else you could expand this to some Comet work (maybe you could pull it off with just plain old AJAX though).

Here is how it would look roughly in javascript using jQuery and a tinyMCE WYSIWYG editor

//Hook into your preview button or link's onclick.
var activelink = jQuery('#yourpreivewbuttonorlinkselector');
activelink.click(function (e) {
e.preventDefault();
//Open up the window but keep a reference in the windows DOM.
window.communicator = window.open(this.href,'activepreview','menubar=yes,scrollbars=yes,copyhistory=yes,resizable=yes');
//We need to hook into onKeyUp to catch key strokes.
//If your not using tinyMCE change this to hook into the input in question.
tinyMCE.activeEditor.onKeyUp.add(function (ed, l) {
var jcommunicator = jQuery(window.communicator.document);
var post = jcommunicator.find('selector to get the content area changing');
//Update the content area on the preview page with the data entered into the editor.
post.html(ed.getBody().innerHTML);
});
return false;
});

This pattern works pretty well hopefully you can see how this would change if you weren’t using tinyMCE.

There are two scenarios where this isn’t going to work (at least without some more work)…

  • When content has to be sent through some processing before being displayed on the page.  With some more work on the server side you could work through this issue though.
  • When you cannot reliably identify the area on the rendered page that is being changed.

In the right situation this solution provides a true WYSIWYG experience for users.