Here is the plugin section of my pom.xml, it will generate JPA Metamodel classes into the target/generated-sources directory of your build and compile them into the end product.

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <executions> <execution> <id>generate-entity-metamodel</id> <phase>generate-sources</phase> <goals> <goal>compile</goal> </goals> <configuration> <source>1.6</source> <target>1.6</target> <optimize>true</optimize> <showDeprecation>true</showDeprecation> <showWarnings>true</showWarnings> <proc>only</proc> <compilerArgument>-Aopenjpa.metamodel=true</compilerArgument> <generatedSourcesDirectory>${project.build.directory}/generated-sources</generatedSourcesDirectory> </configuration> </execution> <execution> <id>compile</id> <phase>compile</phase> <goals> <goal>compile</goal> </goals> <configuration> <source>1.6</source> <target>1.6</target> </configuration> </execution> </executions> </plugin>

If you want to store these classes in your SCM, try the following instead:

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <executions> <execution> <id>generate-entity-metamodel</id> <phase>generate-sources</phase> <goals> <goal> compile </goal> </goals> <configuration> <source>1.6</source> <target>1.6</target> <optimize>true</optimize> <showDeprecation>true</showDeprecation> <showWarnings>true</showWarnings> <proc>only</proc> <compilerArgument>-Aopenjpa.metamodel=true</compilerArgument> <generatedSourcesDirectory>${basedir}/src/main/java</generatedSourcesDirectory> </configuration> </execution> <execution> <id>compile</id> <phase>compile</phase> <goals> <goal> compile </goal> </goals> <configuration> <source>1.6</source> <target>1.6</target> <generatedSourcesDirectory>${basedir}/src/main/java</generatedSourcesDirectory> </configuration> </execution> </executions> </plugin>

Hopefully this helps somebody out there.

It is a work in-progress, but I hope this works out to be a good resource for OSGi \ Virgo programmers and a starting point for some discussion around the below points – I invite comments…

Eclipse Virgo

In summary, Virgo (now Virgo Tomcat Server to differentiate between it’s sibling Virgo Jetty Server) is neat little Tomcat web server embedded as an OSGi module within Equinox. It uses the OSGi extender pattern to create a bridge between Equinox and Tomcat so that Web artifacts (WARs) inherit the same properties and lifecycle as a regular OSGi bundle – meaning they can be hot-deployed at runtime – with little effort from the developer.

It has some excellent features, including out-of-the-box declarative services support, the ability to specify dependencies on entire bundles or libraries (instead of tediously entering in billions of error prone Import-Package statements – use with caution) using Import-Bundle and Import-Library manifest headers, OSGi configuration artifacts and possibly the most import – the concept of a ‘plan’; an XML artifact that specifies the atomic installation order of various other OSGi modules, optionally limiting the scope the modules to other modules within the plan. In my view, the ‘plan’ artifact coupled with configuration artifacts provide a clean and dramatically simpler deployment packaging process across environments.

From a Web Application point-of-view, under the hood, it is still Tomcat. Clustering and most configuration is straightforward and is performed in the same manner as you would normally. In fact, your application doesn’t need to be an OSGi bundle, so if you want to migrate slowly to a complete OSGi system over time, Virgo supports this. As a bonus, the latest 3.0.0.M05 Milestone release contains Tomcat 7 meaning the Servlet 3.0 and EL 2 specifications is also now available and the default.

In general, the documentation is pretty good (http://www.eclipse.org/virgo/documentation) and in true Spring fashion there is a decent reference application that takes you through a fairly sophisticated Web Application.

Find out more here: http://www.eclipse.org/virgo/

Community

Possibly the only downside is that I feel Virgo has a reasonably small community when compared to the likes of Glassfish, for example. It is probably explained by the fact that OSGi in the Web is still relatively new, and the fact that Virgo is the successor to Spring DM Server – a gift from SpringSource. I imagine there are many customers still on that platform and the Spring forums still have some value for OSGi issues.

Again, to be fair, whilst the Glassfish community is large I would say only a small percentage are actually using OSGi.

Debugging

Virgo has an excellent, yet relatively undocumented feature. Glyn Normington hints at it, but I don’t think the post does it enough justice. One of the most difficult problems to solve are uses conflicts. Virgo has some nice features around making them clearer in the log files, but sometimes they are a little cryptic. However, Virgo is configured by default to take a snapshot of the current state of bundles during an installation failure. The snapshot alone is of little use on it’s own, however if you navigate to the admin console at http://localhost:8080/admin and choose ‘OSGi state’ there is an option to select live or the dump just created by Virgo – this allows you to see what Virgo sees when it’s trying to resolve your set of bundles. I won’t go into detail here on this, as I’ve dedicated a separate post to debugging in Virgo.

Spring integration

One of the best features of Virgo for Spring developers, is that it came out of Spring DM server and is therefore ‘Spring ready’. That means, it was designed to work with Spring applications – Web applications or otherwise. To get a basic Spring MVC application running in Virgo is not a big deal; it pretty much boils down to creating an appropriate OSGi manifest and modifying the context in web.xml to use the ServerOsgiBundleXmlWebApplicationContext context class instead of the default. From here on, the usual dependency injection and Spring goodness just works and behaves like Tomcat would. The only difference you need to worry about is breaking apart your application into logical chunks (vertically or horizontally, as described in the docs) and deploying them as separate modules to enable hot-deployment.

You don’t really appreciate this, until you try and install a Web Application into another container; such as Felix or Equinox alone. The magic that happens behind the scenes is completely transparent to you.

Why not Glassfish?

In the early investigation stage, it became immediately clear that there were two front-runners when it came to picking a ready-made, OSGi-enabled web server. Glassfish (3.1+) was the obvious competitor as it had a proven track record in the real world of being a fantastic Application Server, and was now OSGi capable (Apache Felix by default). The down side at the time was that it used CDI (JSR-299) heavily internally which conflicted with the Spring Library DI mechanisms. Theoretically it was possible, but it seemed like we were leading down a more difficult path; bending Glassfish and our application in a way that just didn’t feel like the right way to go. I’ll certainly keep my eyes on projects such as the Spring to CDI bridge which help to make these platforms more open.

Learnings

The world is not OSGi ready – be prepared to Wrap Jars

Whilst Spring have provided the somewhat dated Enterprise Bundle Repository – a repository of ready made OSGi artifacts of common libraries – not all libraries you need exist there. In fact, I’m pretty sure some of the latest Spring releases don’t either i.e. Spring Security Core 3.0.5 (It’s not a huge deal though, all Spring bundles now how OSGi manifests created anyway). Not all is lost, however. Both the Maven Bundle Plugin and Bundlor are able to ‘wrap’ existing libraries and turn them into OSGi ready bundles. The catch is ensuring that you use the correct bundle version, package export and package import versions. Pax Construct provides some nice command line tools to get the job done, which uses the Maven Bundle Plugin.

Import-Bundle is evil

OK maybe not evil, but with one exception, and we’ll get to that, my personal belief is that Import-Bundle should be used with caution. I could pretty much say that all uses-conflict issues (see below) that I’ve encountered have been as a result of lazily importing an entire bundle, when only a few packages are actually required. Whether right or wrong, some 3rd party bundles are huge and contain many packages that you’re never going to use. In these cases, importing the entire bundle is like inviting all of Iran and Iraq to a party without telling them – it’s going to end badly. Conversely, inviting a few like-minded Iranians & Iraqi’s will be a pleasant experience.

What I mean by this, is that all of those extra packages not used in the imported bundle still bring along their baggage – transitive dependencies that need to be resolved – the bigger the bundle, the more baggage. This is because Import-Bundle is a shorthand for ‘import all packages in the bundle’. It is an illusion, and at some point, you’ll have several bloated 3rd party JARs that have been poorly packaged with conflicting dependencies all over the shop.

This article would have you believe otherwise, however my view is that Import-Bundle regresses OSGi development to the old-school ‘throw the JAR in WEB-INF/lib’ view of the world. Whilst we get the benefit of re-use, we lose out on precision. True, the tooling to get the job done is still in progress, and configuration files that result in package dependencies are the main cause of this. Bundlor is a great Spring tool that can not only parse byte-code dependencies, but also look in Spring configuration files to determine what needs to be imported.

Declarative Services is your friend

Simply put, don’t do things the hard way – use Spring DM’s or Blueprint’s declarative services model to implement OSGi services and avoid boilerplate code. Take the time to understand how they work, and then never think about it again. Not only will it simplify things, it will make your code more modular and loosely coupled. Think of it as Dependency Injection for OSGi. Read more on Spring DM \ Blueprint here.

<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:osgi="http://www.springframework.org/schema/osgi" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd http://www.springframework.org/schema/osgi http://www.springframework.org/schema/osgi/spring-osgi.xsd"> <osgi:service ref="myExposedObject" interface="com.melbourneit.foo.bar.AwesomeService"/> <osgi:reference id="someOtherPotentiallyRemoteObject" interface="com.somebody.something.Useful"/> </beans>

The above Spring DM XML declaration located by convention in META-INF/spring/*.xml (I used the recommended osgi-context.xml naming scheme) is all that is required to trigger Virgo to expose an object of type com.melbourneit.foo.bar.AwesomeService with name ‘myExposedObject’ which is now available to any other bundle within the OSGi container. Similarly, it will also search for an object of type com.somebody.something.Useful and wait until it can be found. Once found, it is injected as per any other object injected in Spring.

Notice how we don’t care about searching for services, checking for states, runtime exceptions or anything – the DS library takes care of that for us.

Build API and Implementation Bundles

You want to be able to hot swap code at runtime? Then make sure you create API bundles separate from your implementation bundles, and expose the implementation bundle as an OSGi Service (as above). Here’s why:

• It encourages contract-first development, forcing you to think about the design & features you are implementing up front
• It will decouple your application from implementation specifics, meaning they are more modular in nature
• It allows you to create many different providers of that API which, importantly, allows you to hot-swap them at runtime.
• It (interface first) is a basic principle of Dependency Injection and it will mean many Spring things, like AOP, will work out-of-the-box

So, let’s say for example you decide you want to move from an XML SOAP/RPC based web service to a RESTful one using JSON. For whatever reason, if the WS API objects changed significantly due to the service protocol change your application using it need not worry about it. The implementation bundle can take on that burden to ensure the API interface (contract) is kept consistent. The application simply expresses a dependency on a particular interface which is satisfied at run time by a provider of that interface (service). Turn on this bundle, turn off the old bundle provider and you application should swap over automagically. It need not be as big a change as this, it could be a matter of fine tuning an existing bundle. OSGi and Declarative Services will take care of the wiring for you.

Get to know the console

The Virgo OSGi console contains pretty much all of the information and tools you need to fix bugs, introspect state etc. The Admin application provided with Virgo contains a really nice feature to debug uses-constraints, but apart from that in my opinion the console is much faster and easier to use. Read more about it in my debugging post or at the official documentation.

Bundle-Fragments

We had a need to use Terracotta  for HA session and caching replication, which required a specific Valve customisation to Tomcat’s context.xml configuration file. This is normally really easy – simply add the Valve and put the relevant JAR’s into the shared /lib folder. However, in OSGi this process is not possible. As Tomcat is now an OSGi bundle, it explicitly states the packages that it depends on so dumping a JAR in a directory will do nothing. What you need to do is add the Terracotta packages into the Tomcat classpath when Virgo starts it up.

To achieve this, the most elegant way is to not fiddle with the OSGied Tomcat bundle, nor the boot classpath to make available to all bundles, but to extend it’s classpath using a Bundle-Fragment. Learn more about them on Glyn Normington’s post or at the Spring Documentation.

In practice, you create a bundle for Terracotta (or bundle X) and create a separate bundle consisting only of a manifest file, with the usual headers and a Fragment-Host header specifying the bundle it should latch on to.

Fragment-Host: org.eclipse.gemini.web.tomcat;bundle-version="[2.0.0.,3.0.0)" Manifest-Version: 1.0 Built-By: Matt Fellows ... Bundle-Version: 1.0.0 Bundle-ManifestVersion: 2Bundle-Description: OSGi Web Self-Service Application Reference Implem entation Bundle-SymbolicName: com.melbourneit.web.eclipse.virgo.web.tomcat.terr acotta Import-Package: ...

You may need to get used to these sorts of solutions, especially if enhancing Virgo internals is required.

Tools for the trade

There are at least 3 tools that I use daily to get the job done

• Pax Construct – Logically organises your OSGi project into Maven modules, useful tools to wrap 3rd party JARs to make OSGi compliant, sets reasonable defaults, completely transparent if you want it to be.
• Maven Bundle Plugin – Used by Pax Construct by default, I prefer this tool over bundlor for simple bundles
• Bundlor – Integrates in Eclipse, STS and Maven and can really simplify your Manifest management. Alternative to Maven Bundle Plugin.

The Virgo Team are awesome

In my experience so far, the Virgo team have been extremely helpful with responding to queries and solving issues and are really working toward building a quality product that meets the needs of their customers. You’ll find the forums quite active and a good resource for troubleshooting, and the guys are all over Twitter so you can keep up with the latest news.

Read

Read the following – you’re parallel dimension self with thank you for it.

• http://njbartlett.name/osgibook.html - This should get you started on all of the main concepts, problems etc.
• http://njbartlett.name/2011/02/09/uses-constraints.html – A well explained article on debugging uses-constraints.
• http://www.osgi.org/blog/2006/04/misconceptions-about-osgi-headers.html – OSGi headers explained.
• http://www.ibm.com/developerworks/websphere/techjournal/1007_charters/1007_charters.html?ca=drs- – OSGi Best Practices.
• http://www.eclipse.org/virgo/documentation/ – The Virgo Documentation is pretty good, make sure that you read them in detail

You can find all of my OSGi bookmarks here: http://www.delicious.com/mefellows/osgi

Summary

Overall, I’m quite happy with what Virgo provides in the way of support for Spring and OSGi. I’m not 100% convinced at this stage, that OSGi is the fastest means of development – there is most definitely an overhead – however I believe in the long term this is the direction that the industry is moving in, especially with the upcoming Java Modularity requirements for Java 8 I believe OSGi developers will be well prepared for the change.

I don’t believe that Virgo has really pushed the envelope with respect to Hot deployments – one of the main selling points of OSGi. Automating deployments these days is a key activity in Agile project management, indeed it is a best practice full stop. With the current toolset, it is hard to see an elegant solution to automating deployments that allows for hot deployment of modules whilst the Web Application is still running. Plan files significantly reduce the complexity of a deployment, however an artifact within the plan cannot be hot deployed – the entire plan needs to be redeployed. Doing this by hand is possible and Virgo deals with this as expected; if a service dependency is removed at runtime, the application flow requiring it simply pauses until it comes back online. Better still, if the bundle is an implementation provider of an API, you can hot swap out the service at runtime without the Web Application even knowing. However, the cost is that this is a very manual process and that means it’s error-prone.

I’d like to see the features, like the ability to hot-deploy artifacts within a plan or command-line (aka Glassfish asadmin) tools to perform deployments in an atomic and controlled fashion from deployment scripts, for example.

For me, coming up with a best-practice and elegant solution to this problem would really ensure Virgo is the stand-out choice as a Web-enabled OSGi server for the community.

In these examples, I am using Virgo 3.0.0.M05.

Enable the Equinox Shell in Virgo

By default, the Equinox shell is disabled in Virgo (due to security reasons I suspect). Edit lines 51 and 52 to enable the shell. I’ve changed the port to 2402 as it conflicts with my local CVS:

# osgi console support osgi.console=2402

You will need to restart Virgo for this to take effect. You can then hop into the console by telneting into localhost on 2402:

telnet localhost 2402

Virgo Equinox Console

Now that you’re in, have a play around. Starting with the ‘help’ command is a good idea. See the Virgo User Guide for more info on setting up the shell.

Debugging commands

Look at the bundle Manifest headers, as seen by Virgo

Sometimes your manifest may not behave as you think, and is often the cause of issues. You can easily check the headers of your bundle by issuing the following:

ss headers 120

Virgo OSGi command to view bundle headers

The first command lists all bundles and their states, the second allows you to view the headers associated with that bundle.

Find out importers and exporters of a package

packages javax.xml.bind

Eclipse Virgo OSGi Console Packages Command

Using this command, you can see the exporter of a particular package and version, as well as the bundles (indented) that import that package. This is really handy when you’re trying to work out why a particular package is not wiring to a bundle, or if it’s wiring to the wrong bundle in a uses-conflict.

Examine a bundle \ service in detail

Virgo provides a number of extra commands on top of the Equinox console, one of which I find particularly useful to see if my bundle and osgi contexts (module-context.xml and osgi-context.xml files respectively) have been correctly read by Virgo:

vsh bundle examine 121 vsh service examine 200

As you can see below, when you examine a bundle you are provided with a listing of all of the packages (and their versions) that are imported\exported and the services it publishes\consumes. In this case, my bundle is exporting a service with id 200 which i can examine with the second command. This allows me to confirm that a) my service is being exposed as I expected and b) it is of the correct class – it even gives me the Spring Bean name…

Virgo OSGi console command - vsh bundle examine

Find out what packages import\export a particular class

clhas com.melbourneit.web.provisioning.ProvisioningManager clload com.melbourneit.web.provisioning.ProvisioningManager clexport com.melbourneit.web.provisioning.ProvisioningManager

Virgo OSGi commands to view class import\export\users

Useful commands to work out where are class is located and what other bundles try and load that particular class.

Diagnosing a Uses Violation – Spring MVC, Apache CXF, EHCache and JSF

These pesky problems are really annoying to fix. Neil Bartlett and Glyn Normington have explained what these are in detail, I’m going to show you how you might diagnose them using the Eclipse Virgo and Equinox console commands.

The application in question is a Spring MVC project, that uses the Apache CXF client SOAP\RESTful service communications, JSF for some presentation and uses EHCache and Terracotta for L2 caching. It also takes advantage of JSR-303 validations using the Hibernate RI. The application is multi-layered on a technical level and as you can see has a few moving parts.

The problem

So, I have a Web Application with multiple bundle dependencies, each with their own dependencies and so on. It is a typical situation that leads to a Uses Violation, so it was only a matter of time before I was confronted with the following:

OSGi Uses-Violation

The first step in the debugging process is to find the package that is to blame, that is, the package that has multiple exporters. As Neil points out “This is a necessary precondition for a uses constraint violation”. Unfortunately this is often the hardest part. So the above log snippet gives a few hints, but is particularly unhelpful: one of the following packages has a dependency on another package which has been exported at least twice: org.hibernate.validator.xml, org.springframework.remoting.jaxws, com.melbourneit.web.provisioning.

The issue is, you can’t use the console to assess what packages any of those bundles import at this point because the application has been rejected by the OSGi framework. You could manually install those bundles but it won’t re-create the set of conditions you need. Enter the State Inspector. Glyn teases us with his overview, but I think he under sells it’s value. Let me try and sell it by demonstrating its usefulness.

You need to use the Admin application that comes packaged with Virgo, so ensure that the 3 artifacts below are installed or in the pickup directory:

mfellows /usr/local/virgo5/pickup $ ll total 288 -rw-r--r--@ 1 mattfellows staff 95K 27 May 16:04 org.eclipse.virgo.apps.splash-3.0.0.M05.jar -rw-r--r--@ 1 mattfellows staff 658B 27 May 16:04 org.eclipse.virgo.apps.admin-3.0.0.M05.plan -rw-r--r--@ 1 mattfellows staff 42K 27 May 16:05 org.eclipse.virgo.apps.repository-3.0.0.M05.par

and navigate to http://localhost:8080/admin once it loads. Once in, click on the “OSGi State” menu item in the top menu.

Virgo Admin - OSGi State Screen

Notice how there is the message “Viewing state ‘Live’” at the top right-hand of the screen? Click on the select box next to it and choose the item underneath ‘live’ and hit ‘go’. In this instance, the item is ’2011-06-18-12-47-096′ which references the dump created when the OSGi framework was unable to resolve the Web Application. Once I’ve chosen this, I now get a a snapshot of that point in time in the OSGi framework:

Virgo Admin Dump State - All Bundles

So, as I mentioned earlier, I can now browse around at the 3 bundles from before to see what packages might be the cause. Starting with Hibernate, I need to see what packages it imports. I now click on the hibernate link (com.springsource.org.hibernate.validator) to see what packages it imports/exports:

Virgo Admin Dump State - Bundle com.springsource.org.hibernate.validator

javax.persistance is an optional import which hasn’t been provided, so I choose javax.validation instead to see it’s exporters:

Virgo Admin Dump State - package javax.validation

Unfortunately, it only has one exporter (com.springsource.javax.validation). How about javax.xml.bind?

Virgo Admin Dump State - package javax.xml.bind

Bingo! It turns out that this package has two exporters; bundle 0 providing version 0.0.0 of the package (org.eclipse.osgi), and bundle 57 (com.springsource.javax.xml.bind) providing the correct version of 2.2.0, the version Hibernate is currently wired to. Now, here is the tricky part. We know that it has two exporters, but that doesn’t mean that this IS the problem – we need to confirm that another bundle in the same classpath uses the other exported package. i.e. We need to find another bundle using the javax.xml.bind package provided by bundle 0.

Actually, with the Dump Inspector it turns out not to be that difficult. Notice how some bundles have low Bundle Id’s i.e < 500? These bundles have been resolved  and are not part of the uses-conflict. Bundles with really high Bundle Id’s have not actually been resolved yet – as Glyn puts it, Virgo is attempting resolution in a “side state”, and will only be committed to the framework if resolved. So, the hint here is to look for bundles with enormous bundle id’s and see what packages they are trying to import.

On the javax.xml.bind OSGi state page, you can see that 6 bundles are importing this package but, funnily enough, only 2 packages have really high bundle id’s: Hibernate and the Web Application. Unfortunately, in my case clicking on the Web Application bundle does not reveal the provider of the javax.xml.bind package however I happen to know that bundle 0 is imported into a Web Application bundle by default if the ‘Web-ContextPath’ header is provided, which binds it to a conflicting version of javax.xml.bind. Removing this header removes the uses-conflict.

The Solution

In my case, because my Web Application was tied to bundle 0, I actually needed to prevent bundle 0 from exporting the packages I needed from another bundle. I needed to modify the lib/java6-server.profile and remove the following lines:

javax.xml.bind,\ javax.xml.bind;version="2.0",\ javax.xml.bind.annotation,\ javax.xml.bind.annotation;version="2.0",\ javax.xml.bind.annotation.adapters,\ javax.xml.bind.annotation.adapters;version="2.0",\ javax.xml.bind.attachment,\ javax.xml.bind.attachment;version="2.0",\ javax.xml.bind.helpers,\ javax.xml.bind.helpers;version="2.0",\ javax.xml.bind.util,\ javax.xml.bind.util;version="2.0",\

javax.xml.ws,\ javax.xml.ws;version="2.1.1",\ javax.xml.ws.handler,\ javax.xml.ws.handler;version="2.1.1",\ javax.xml.ws.handler.soap,\ javax.xml.ws.handler.soap;version="2.1.1",\ javax.xml.ws.http,\ javax.xml.ws.http;version="2.1.1",\ javax.xml.ws.soap,\ javax.xml.ws.soap;version="2.1.1",\ javax.xml.ws.spi,\ javax.xml.ws.spi;version="2.1.1",\

These packages are provided by other bundles at runtime (springsource.javax.xml.bind, genonimo etc.). This is not a recommended thing to do, however was required in my particular circumstance. See this forum post for more details.

OSGi State Inspector Summary

To sum up, the OSGi state inspector allows you to:

• View a snapshot of the state of Virgo when a bundle fails resolution
• Browse the bundles in that snapshot and view their properties; import, export and services
• Diagnose uses-conflicts and other OSGi issues much more easily

Read more about it at the Virgo Docs.

Do you have any tips\tricks you’d like to add? Let me know!

To fix this, modify your domain config file ($GLASSFISH_HOME/glassfish/domains/domain1/config/domain.xml) and update the entry as per below:

<jvm-options> -Dorg.glassfish.additionalOSGiBundlesToStart=org.apache.felix.shell, org.apache.felix.gogo.runtime,org.apache.felix.gogo.shell, org.apache.felix.gogo.command, org.apache.felix.shell.remote </jvm-options>

And for those who would prefer the vanilla felix shell sans-gogo, just remove the gogo jar entries:

<jvm-options> -Dorg.glassfish.additionalOSGiBundlesToStart=org.apache.felix.shell, org.apache.felix.shell.remote </jvm-options>

Start the application server and telnet to localhost:

telnet localhost 6666

… and we’re done!

So it has been done. After some serious culling of content, deliberation of style, design & procrastination I’ve ported this blog from Joomla to WordPress – and couldn’t be happier.

Whilst Joomla has a well built, object-oriented, MVC design, I couldn’t resist the elegance, style, user-friendliness and fantastic community associated with WordPress. It makes me want to publish. The plug-in community is fantastic and the documentation is brilliant.

I may well regret it in the future when globals are no longer supported and WordPress doesn’t have an update to remove that dependance but for now I’m blissfully ignorant…

A new look

Whilst I’m no designer, I’ve gone for a clean, elegant, typographical look for the new site to emphasize what this site is about: content.

Add in semantics: HTML5 + CSS3 + Microformats

I’ve also decided to use HTML5 and CSS3 heavily in the new design along with hcard and other Microformats. Given that my audience predominantly uses Firefox, Chrome and Safari, my task was relatively easy, however it also works with IE7+8 with the help of Remy Sharp’s HTML5 enabler.

To infinity, and beyond!

To get the most out of this excercise, I decided I would do what I could to make it high-performance.

With a careful CSS\JS compression cycle built into my standard deployment deployment scripts (another post\project for the future), some nice caching rules implemented in the .htaccess file, heavy use of sprites and the fantastic WP Super Cache plugin I was able to achieve the YSlow reading A (93 \ 100) and Google PageSpeed score of 85. Note that I lost marks for not having an Expires header, ironically, for the Google Analytics script and for not using a CDN.

Performance results

I also tested this from US and AU servers using LoadImpact and Webpagetest. The following are 3 independent tests of the OneGeek home page:

LoadImpact (US):

• 1.88s (I assume this figure is document loaded, not document ready)

WebPageTest (AU):

• 2.782 Document loaded
• 3.010s Document ready
• 0.702s Subsequent request document ready

WebPageTest (US)

• 1.405s Document loaded
• 1.840s Document ready
• .806s Subsquent request document ready

In the end for a blog running on a super-cheap, massively overlcrowded US based hosting provider, I was pretty happy with that.

Time to get publishing!

Have you ever had the tedious job of pipe delimiting data to a cookie and manually checking and retrieving valid data, all just to re-assemble a JavaScript object? Well think again – what if you could serialize an entire object to a string, store that string (say in a cookie) and read it straight back into a JavaScript object without having to manually rebuild it? Serialization offers one way of persisting an entire user experience for retrieval at a later time. When that time comes, simply retrieving the object from the store and deserializing it gives you back the object that you started with. Provided that an Object Oriented approach is followed, in principle, any object can be serialized and retrieved from an external store.

What is serialization?

Serialization is the process of storing an object, and it’s internal state at the point of serialization, in another medium so that it can be transported or retrieved at a later date. When the object is deserialized, the object is recreated with it’s internal state in tact.

Object persistence with GSerializer

GSerializer is a JavaScript class that provides methods to serialize and deserialize any JavaScript object, using an XML format.

These are the basic steps that are required to serialize any JavaScript object with GSerializer:

1. Create and populate an object
2. Create an instance of the GSerializer class
3. Call the serialize method of the GSerializer object and hold onto the serialized string
4. Store the serialized string somewhere (i.e. a cookie, database, file etc.)

To deserialize the object:

1. Retrieve the serialized string from it’s store
2. (Optional) Check for code tampering (see Security )
3. Call the deserialize method of the GSerializer and store the resulting object
4. You can now use that object!

The Code

// The object to serialize var myObject = new MyObject(); // The Serializer var serializer = new GSerializer(); // Grab the serialized XML var serializedXML = serializer.serialize(myObject, 'MyObject'); // Deserialize the object from the serialized XML string var deserializedObject = serializer.deserialize(serializedXML);

Download the library from the Google Code project page.

The Examples

• See a demonstration of JavaScript deserialization using Cookies to persist the object.
• Download the example from the Google Code project page.

Storage

So where should this serialized object be stored? There are many possibilities, but it comes down to choosing between client-side and server-side:

1. Cookie (client-side)
2. Database (server-side)

Storage in Cookies

Since JavaScript is a client-side scripting language, a logical choice is cookies. Cookies are easily accessed via JavaScript and so persisting and retrieving is not limited by bandwidth. In fact, in a recent application I used cookies to store a custom Session object. Each time the Session object was updated (due to an interface change, search etc.) I wrote the object to the cookie so it was essentially storing the live session. This kind of speed and reactivity is not available on the server side where calls to a database are limited by bandwidth.

However cookies suffer from the following drawbacks:

1. Limited storge size (4kb or so)
2. Limited number of cookies (30 or so for a particular domain)
3. Can be accessed on the clients’ machine and thus are susceptible to tampering. Provided no sensitive data is stored in these objects, this may not be an issue

Storage in a database

If cookies can’t get the job done, then perhaps a database can. A database can get around the three main drawbacks of cookies but are more complicated to implement. For example, you would need some service on the server side to store and retrieve the code for a particular user. Live session writing is probably not feasible with a database either; instead the session would likely be retrieved once at the start and saved once when the user is leaving, or perhaps at the users request. If however, the browser crashed or the computer shut down unexpectedly – the changes since the last save will be lost.

Advantages

Using GSerializer provides a number of advantages for a JavaScript application. It;

1. Provides a means to fix the back button: Many AJAX applications suffer if someone accidently clicks the back button in their browser. Instance variables are lost, the interface might change etc. Storing their session to an object means that when they come back, you can reload that object and the user never had to know the difference.
2. Provides a common way to store and retrieve any object. For example, one could write generic methods to take an object, serialize it and store it. Then provide another method to retrieve the object from it’s storage and load it back into memory. This could then be used for any object, preventing the need for object specific string manipulation from cookies.
3. Provides an extensible and re-usable component

Security

There are a number of security risks and precautions that you should take when using this technique:

1. GSerializer uses the Eval function to generate objects, therefore you must take every precaution to ensure that the data coming into the serializer is from a trusted source, and that that source has not been tampered with. (read more )
2. Interception over a non-secure connection is possible, so think carefully about persisting sensitive information (read more )
3. Malicious tampering of the serialized object is possible

Security: Generating a unique key

One approach that could be used to increase the confidence that the code has not been tampered with is to generate a unique key from an undisclosed server side Hash function (or something similar) based on the contents of the serialized XML string. This unique key can be stored on the server side so when the unserialized object is retrieved, the Hash function can be called again on the data to produce another key. If the two keys are identical then the code has not changed between writing and retrieving.

Future

I can see a number of ways in which this technique could be enhanced:

1. Compression of the output string to save space (particularly in the case of using cookies for persistence)
2. Encrpytion methods to prevent interception and tampering
3. Better encoding of functions and objects. Currently, objects of the same type are duplicated in the XML rather than referenced. Ideally only the instance variable/value pairs of the class should be stored and the rest of the class should be referenced to be more efficient on space.
4. Security function to prevent unsafe code from being evaluated by the eval() function during deserialization

JSON vs JavaScript Serialization

Some of you may be wondering: why not use JSON? Aren’t there serializer library’s for JSON similar to this? Well, yes there are (json.js from JSON.org ) to answer simply, but JSON will not work for our purpose because JSON is a notation for passing data, and will not encode functions which are crucial to the re-serialization in our case. A second drawback is that one must write in the JavaScript literal notation to produce a JSON string, which in my opinion is awkward and unreadable. But in saying this JSON is an internationally recognised standard for passing JavaScript Object data and may well be the real answer you are looking for.

When to use JSON and when to use serialization

If you only need to store data and not the objects themselves, then JSON might be the go. For example, perhaps you have a Session Object that takes only a name and some list of parameters describing the user’s session in it’s constructor. If however, you require a complex Session object containing a number of other complex objects, then it is much easier to use serialization as it takes the hassle our of re-populating each of the objects. The Session wrapper Object will already contains a reference to these pre-populated objects and their associated methods upon deserialization.

Acknowledgements

When I first sought the need of a serializer, I naturally started with Google. I found a number of promising starts, but none worked for complex objects and none actually serialized functions along with the objects.

The code used in GSerializer.js is based on code from (dotnetremoting.com – which is unfortunately down at the time of writing). I chose this as a starting point because I admired the use of recursion to achieve the goal. With this base, I made the following changes:

1. turned it into a proper class
2. tidied up the code to use consistent naming conventions, and commented functions
3. introduced methods to properly serialize functions
4. introduced methods to properly deserialize arrays and functions

Want to validate user input for an (X)HTML form without embedding a single line of JavaScript, without having to worry about violating semantics, and all the while providing a reactive, user friendly experience?

Introducing GValidator – a powerful, extensible yet easy to implement JavaScript library that provides constant feedback during form completion. To use the library all you need to do is include it.

Table of Contents

1. Project goals
2. Download
3. Examples
4. XHTML API
5. Options
6. Design
7. JS API
8. Extending with Plugins
9. I8N
10. Extending with OOP
11. Browser support

The Aim

The aim of GValidator is to provide the following:

• A user-friendly experience for our visitors
• Semantically clean code
• Standards compliant code
• Cross browser compatibility
• Reusable JavaScript code
• Code flexibility and extensibility

The Code

GValidator now has a Google Code project. To get the latest version, post bugs, comment on or just look about visit: http://code.google.com/p/gvalidator

• Download the GValidator library, along with examples and CSS

Actually, for basic forms no extra coding is needed other than to include the JavaScript file and to add appropriate class names to your form fields. Here is an example form:

<form action="/action/" method="post" class="gform" ><br /> <input type="text" name="firstname" class="firstname required" /> <br /> <input type="text" name="lastname" class="lastname required" id="lastname"/><br /> <input type="text" name="subject" class="text required" id="subject" /><br /> <input type="text" name="captcha" class="captcha required" id="captcha" /><br /> <input type="text" name="phone" class="phone required" id="phone"/><br /> <input id="submit" type="submit"/><br /></form> 

There are a few things to notice here;

• The form is given a class attribute of “gform”. This is what activates the automatic form validator
• The fields for validation are given various class names depending on how we wish to validate them. i.e. class=”name”, class=”phone”, class=”text” etc.
• To make a field required, simply add the class ‘required’. You can still use the library on non-required fields, as it will cleanse them and validate if not correctly completed.
• There is no embedded JavaScript functions or invalid semantic markup here. Just clean, straightforward XHTML

The Example

There are 4 examples, ranging from simple to advanced implementation:

• See the basic example of GValidator – no javascript coding required
• Plugin – extends GValidator with a validation function type for an IP 4 address
• Internationalization – translates GValidator into German using a translation file so that your forms will have internationalized client side validation.
• Customization – tailors the default behaviour of GValidator on a global and a per-form basis, using only basic javascript

All of the examples are available for download on the Google code GValidator site.

Field Types (default XHTML API)

The following are the field types and corresponding class names that are included in the default implementation. They should cover most cases. If you require more than this or customisation, then you can extend the functionality as discussed below.

GValidator Options

GValidator has the following options, passed in to a variable with name ONEGEEK.forms.GValidator.options.
This variable is a literal object, containing key/value pairs.

GValidator Library Design

The library was designed with simplicity and extensibility in mind. The basic idea was to create an abstract class hierarchy that could be quickly and easily extended to change the validation function for a new field type. This hierarchy exists in three tiers allowing for the following object types:

• One third (top) level AbstractFormField class, which provides the skeleton that all AbstractFormField subclasses inherit from
• A finite number of second level AbstractFormElements which provide the basic implementations for the different form elements (i.e. <input>, <select> etc.)
• An infinite number of first level ConcreteFormElement objects which provide the concrete validation implementations (i.e. validate a phone number field)

By implementing the library in this way, we allow for simple extensibility by implementing subclasses at the lowest level.

JavaScript API

Read the JavaScript API or download it from Google Code.

Class Hierarchy

Extending GValidator

Creating new validation types for GValidator is easy, they are added in the form of plug-ins. All you need to do is add object keys to the ONEGEEK.forms.GValidator.plugins object with the class name of the validator you wish to add.

Customisation example

Let’s say we’d like to create a new validator for an IP 4 Address type on a text field, using the class name ‘ip4address’.

The validation function must:

• Validate the input of an IP 4 Address type i.e. 127.0.0.1
• Remove non-allowed characters from the field before validation
• Have custom messages for each state of the field
• Additionally, the validator must highlight the field on error and clear the highlight on success

Step 1: Create the plugins object and add your new type and extend a type

Place the following object in an external JavaScript file after gvalidator.js has been added to the page.

The new type will use the className ‘ip4address’ to activate the validator on the field.



ONEGEEK.forms.GValidator.plugins = { ip4address: {_extends: 'AbstractTextField', ... };

Note that the _extends key is set to ‘AbstractTextField’ because we are validating a Text field. Other options are ‘ComboBox’, ‘RadioButton’ or ‘Checkbox’ at the second level (see above). Of course, you can extend existing elements such as ‘NameField’ if you wish.

Step 2: Override existing instance variables

Here we override the AbstractFormField messages and AbstractTextField regex and cleanRegex variables. These last variables are used to validate the data and clean out invalid characters respectively (Note: regex has been shortened for display).

ONEGEEK.forms.GValidator.plugins = { ip4address: {... regex: /^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2 cleanRegex: /[^0-9\.]/g, contextMsg: 'Please enter a valid IP 4 Address i.e. 127.0.0.1', errorMsg: 'Please enter a valid IP 4 Address i.e. 127.0.0.1', successMsg: 'Thanks', ... }};

Step 3: OPTIONAL Override validation and other functions

If you are content to keep the validation behaviour consistent with other text fields, then you can stop here – how easy was that?

If, however, you want to do some custom validation behaviour then we need to override the existing validate() function:



ONEGEEK.forms.GValidator.plugins = { ip4address: {... validate: function() {if(!this._validate()) {this.highlight(); } else {this.unHighlight(); }}, highlight: function() {this.field.style.background = 'rgb(200,0,0)'; }, unHighlight: function() {this.field.style.background = 'rgb(255,255,255)'; }} };

Note that the validate function makes a call to _validate(). This is actually the parent (previously overridden) validate function. In fact, any attribute or function that you override will be preserved with a ‘_’ prefix so that you can make reference to it if needed. This means, we can call the existing validation function that we like, and enhance it by highlighting the field. Also note that you can attach any function/attribute that you desire and they will be attached to the this of the new object type, effectively extending the class. Be careful not to clash with existing variables/functions unless you intend to (Check out the API or download it from Google Code if unsure)

Full customisation code

Here is the entire code listing for the customisation (regex has been shortened for display):



ONEGEEK.forms.GValidator.plugins = { ip4address: {_extends: 'AbstractTextField', regex: /^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2 cleanRegex: /[^0-9\.]/g, contextMsg: 'Please enter a valid IP 4 Address i.e. 127.0.0.1', errorMsg: 'Please enter a valid IP 4 Address i.e. 127.0.0.1', successMsg: 'Thanks', validate: function() {if(!this._validate()) {this.highlight(); } else {this.unHighlight(); }}, highlight: function() {this.field.style.background = 'rgb(200,0,0)'; }, unHighlight: function() {this.field.style.background = 'rgb(255,255,255)'; }} };

Internationalisation

Internationalising client-side validation in GValidator is easy. It should work with any almost any language.

Note: GValidator does not change the labels on the form or any other content on the page other than content related to the validation of the form. It assumes that the page itself has already been translated and requires form validation specific to that language.

To specify a language translation for a form, simply do the following:

1. Apply the W3C attribute ‘lang’ to the <form> with the value of the language to translate into i.e. lang=”DE” (see a list of valid values)
2. Create a variable with the format ONEGEEK.forms.GValidator.translation.<LANG> i.e. ONEGEEK.forms.GValidator.translation.DE (Note that uppercase is important)
3. In that Object, override messages/parameters for existing validator types using the className of the field you wish to override i.e. ‘username’
4. To set defaults across ALL validator types, use the special top-level key ‘defaults’. These will only be used in the case that a translation is not available for a given class

I8N example

Create a form specifying the lang attribute:

<form lang="DE" ...>

Create an JS file containing a variable like the following:



ONEGEEK.forms.GValidator.translation.DE = { defaults: {successMsg: 'Danke', contextMsg: 'Bitte füllen Sie', errorMsg: 'Kaputt! Es wurde ein Fehler beim Überprüfen diesem Bereich', emptyMessage: 'Pflichtfeld, füllen Sie bitte.', }, firstname: {contextMsg: 'Wir möchten Sie von Ihrem Namen zu nennen' }, ... };

To set the form level error alert messag, override the ‘fMsg’ property in the options config (see Customisation abve) like the following:

ONEGEEK.forms.GValidator.options = { fMsg: "Bitte korrigieren Sie die markierten Fehler!" };

Extending GValidator (Advanced)

If you prefer to code in a more OOP (and I use that term very loosely) type approach, with the added benefit of code completion in some editors, this might be for you.

To create your own validation types, you need to do the following things:

1. Create a class at the first level, overriding the AbstractFormElement of your choice. i.e. To create a UsernameFormField class you would subclass the AbstractTextField class
2. Override any instance variables of ONEGEEK.forms.AbstractFormField if necessary (Read the JavaScript API or download it from Google Code)
3. Override the validation function (and any other functions necessary) to do the custom form field validation
4. Register the new class with FormFieldFactory

We will run through these steps in the following example.

Customisation example

Lets say we would like to create a new field type username for validating usernames. The requirements are as follows:

• It must be between 8-10 alpha-numeric characters
• It must not already exist in the database
• It is a required field

Step 1: Subclass AbstractFormElement

Create a new class ONEGEEK.forms.GenericTextField and subclass ONEGEEK.forms.AbstractTextField.



ONEGEEK.forms.UsernameTextField = function(field) {this.field = field; ... }ONEGEEK.forms.UsernameTextField.prototype = new ONEGEEK.forms.AbstractTextField();

Step 2: Override existing instance variables

In this case, we need to make the field required and we want to validate the field using a regular expression. We can override the instance variables in ONEGEEK.forms.AbstractTextField to achieve this. Override the following instance variables like so:

this.field = field; // This MUST alwys be here this.regex = /^([a-zA-Z0-9-\'\s]{8,10})$/g this.cleanRegex = /[^0-9a-zA-Z-\'\s]/g this.errorMsg = 'Your username must be between 8 and 10 characters'; this.contextMsg = 'You will use this to login. It must be between 8 and 10 characters';

Step 3: Override the validation function

The validation function is where most of the action happens. This function is responsible for checking whether the data has been modified and is valid, and setting the appropriate state of the field (INFO, OK, ERROR). This is where your custom AJAX code would go.

Assuming that an AJAX function called checkUsername(name, field) exists, which takes a username and a ConcreteFormElement object, this is how you would implement the validation function:

this.validate = function() {this.clean(); this.pattern = new RegExp(this.regex); var validated = this.pattern.test(this.field.value);</p> if (validated) {// Regex validated, now use AJAX to check if username exists // On successfull AJAX validation set state to OK // On failure of AJAX validation set state to ERROR checkUsername(this.field.value, formField); } else {if (this.modified == false) {this.setState(ONEGEEK.forms.FIELD_STATUS_INFO); } else {this.setState(ONEGEEK.forms.FIELD_STATUS_ERROR); }} return true; }

Step 4: Register the class with FormFieldFactory

Your custom validation function wil never be used unless you register with FormFieldFactory and tell it which classes you want it to automatically handle. Let’s say that you want to use the class “username” with this function as in the example form element below:

<input type="text" name="username" class="username"/>

To get your new function to handle this, you simply do the following:

formFieldFactory.registerFormField('username', 'UsernameTextField');

Now when you load the page your new function will handle the validation!

Full customisation code

Here is the entire code listing for the customisation:

ONEGEEK.forms.UsernameTextField = function(field) {this.field = field; this.regex = /^([a-zA-Z0-9-\'\s]{8,10})$/g this.cleanRegex = /[^0-9a-zA-Z-\'\s]/g this.errorMsg = 'Your username must be between 8 and 10 characters'; this.contextMsg = 'You will use this to login. It must be between 8 and 10 characters';</p> this.validate = function() {this.clean(); this.pattern = new RegExp(this.regex); var validated = this.pattern.test(this.field.value); if (validated) {// Regex validated, but use AJAX to check if username exists // On successfull AJAX validation set state to OK // On failure of AJAX validation set state to ERROR checkUsername(this.field.value, this); } else {if (this.modified == false) {this.setState(ONEGEEK.forms.FIELD_STATUS_INFO); } else {this.setState(ONEGEEK.forms.FIELD_STATUS_ERROR); }} return true; }} // Subclass Abstract FormField class ONEGEEK.forms.UsernameTextField.prototype = new ONEGEEK.forms.AbstractTextField(); // Register the field types with FormFieldFactory formFieldFactory.registerFormField('username', 'UsernameTextField');

GValidator Browser Support

The library has been tested successfully on the following browsers on Windows:

• Internet Explorer 6.0
• Internet Explorer 7.0
• Internet Explorer 8.0
• Mozilla Firefox 1.0.6
• Mozilla Firefox 2.0.0.7
• Mozilla Firefox 3.0
• Mozilla Firefox 3.5
• Safari 3 Beta
• Opera 9.25
• Netscape Navigator 8.0
• Netscape Navigator 9.0.0.1
• Google Chrome

and the following browsers on Linux:

• Mozilla Firefox 2+
• Opera 9.62
• Epiphany 2.26

However, the “Object does not support this property or method” message can occur in other strange situations. From my experience, this usually comes down to the following:

• Applying MT to non-standards compliant (X)HTML
• Attempting to use the $ function on an element that has the same id as another element in the DOM

I’ve now found another example with forms. Take for instance the following form that I was fixing for a colleague:

<form id="domainSearch" method="post" action="/domain-names" enctype="application/x-www-form-urlencoded"> <input id="domain" type="text" name="domain" value="" /> <input id="domainSubmit" class="icon_sprite" type="submit" name="send" value="Send"/> </form>

The following JavaScript works fine in normal browsers, but will trigger the above error in IE:

$('domainSearch');

As far as I can tell, this is because the name and id fields have different values and IE doesn’t appreciate it. The following HTML corrects it:

<form id="domainSearch" method="post" action="/domain-names" enctype="application/x-www-form-urlencoded"> <input id="domain" type="text" name="domain" value="" /> <input id="domainSubmit" class="icon_sprite" type="submit" name="domainSubmit" value="Send"/> </form>

Although it is recommended that the name and id attributes have the same value, it technically isn’t a standards compliance issue. This issue won’t be picked up  by those who use the Firefox HTMLTidy plugin or the W3C Validator in strict mode to detect poor compliance so this is one to look out for.

I though I might share my experience with Zend Studio 6.1.1, whilst debugging and unit testing a recent web application. Although in general, Zend Studio is a fantastic product and can make your life extremely easy, it is not without it’s nuances. Here are some of the problems (and resolutions of course!) that I came across.

Poor Error reporting

By far the most frustrating thing about Unit Testing in Zend Studio, is that when your test cases don’t work, you better be good at debugging, becuause Zend Studio doesn’t report the errors very well. You then end up wasting time you could spend doing other things. More enjoyable things like having lunch or playing bingo. However, instead you are spending that time trying to figure out what on earth is going on! I recently had a lot of trouble creating the most basic Zend_Controller test case even though my application appeared to be working correctly. The actual method looked like the following:

public function testHomePageAction() {$this->dispatch('/'); $this->assertModule('default'); }

But no matter what I tried, it never asserted the correct module, not even the error module. The errors that were coming back from the system were vague and of no help altogether (see this issue, at least it is on their radar.

What I found (after hours of debugging and trying a number of things), was that during postDispatch() the ErrorHandler was catching an Exception that didn’t appear to be visible during dispatch. If I stepped in to that class in the PHP Debug perspective and set a breakpoint at line 226 of Zend_Controller_Plugin_ErrorHandler

... // Get exception information $error = new ArrayObject(array(), ArrayObject::ARRAY_AS_PROPS); $exceptions = $response->getException(); $exception = $exceptions[0]; $exceptionType = get_class($exception); $error->exception = $exception; ...

I could look into the Variables window at the $exceptions variable and see the exception that was occurring. It turns out it was just that the Registry had been initialized twice (probably by the testing framework) and that caused it to dispatch twice – once for the intended action and once for the ‘error’.

Lesson: If you are having troubles, cut to the chase and view the Exceptions in Debug mode.

Use your own PHP

The in-built PHP binaries that come with Zend just don’t cut it. No mysqli support, no SoapClient and probably a whole bunch of other things that you or I would require in day to day life. The easiest way to get your application working in and out of Zend Studio is to use the same PHP binary. You can add yours easily into the Studio by adding it to:

Window > Preferences > PHP > PHP Executables > Add

Just point it to the location of your PHP binary and php.ini files and then add the location of the Zend Debugger to your php.ini file as follows:

zend_extension=/usr/apps/Zend/ZendStudioForEclipse-6.1.1/plugins/org.zend.php.debug.debugger.linux.x86_5.2.15.v20080907/resources/php5/ZendDebugger.so

Really really slow Unit Testing / Debugging

If you are finding that to run 1 simple unit test that you have to wait 6 hours (exagerrated) for it to finish and more annoyingly that the IDE itself is unresponsive while doing so, it is probably because you have Code Coverage Statistics and Generate Report options turned on. Do yourself a favour, if you’re not using them, turn it off by unchecking them here:

Window > Preferences > PHP > PHPUnit

Hopefully I have helped some annoyed / frustrated developers.