This release now fully supports XML-based constraint definitions and all JSR-303 constraint-annotations.

If you download and test this release, we welcome your feedback. If you think you found a bug, you can post an issue at agimatec-validation/issues.

Creating DOM nodes from Javascript can be painful. The amount of code needed to create nodes and to reference each other as needed is non-acceptable, and the resulting code is far away from being readable or maintainable.

There are some projects out there that try to solve this issue, but their API feels alien inside a Javascript environment because of their declarative nature. So i decided to try to create my own library. The result is mkup, which you can find as open source project at google code: http://code.google.com/p/mkup/.

You can try out all examples listed here inside your browser using the mkup workbench: http://mkup.googlecode.com/svn/trunk/workbench.html.

Design goals

Mkup was written with some things in mind that make a node builder useful.

• code should reflect what is being built
• easy access to the nodes created
• code should be as short as possible

Target one: code should reflect what is being built

This code:

var mkup = Mkup.mkup($('results'));
mkup
  .div()
  .childSpan('note_this')
  .text('Inside Span')
  .write();

creates the following nodes:

<div>
  <span class="note_this">Inside Span</span>
</div>

As you can see calls to mkup are designed to be chained. This removes clutter when specifying what should be done. Of course, chaining is optional, to make using mkup with loops comfortable:

var mkup = Mkup.mkup($('results'));
mkup.ul().child();
for(var i=0; i<3;i++){
    mkup.li().text('Item #'+i);
}
mkup.write();

creates:

<ul>
  <li>Item #0</li>
  <li>Item #1</li>
  <li>Item #2</li>
</ul>

Target two: easy access to nodes created

After building up the nodes you need, getting a reference to one ore more nodes just created is often needed to -for example- change node contents or add listeners. This can be done using mkup:

var mkup = Mkup.mkup($('results'));
mkup
  .div()
  .childA({href:"#"},"link")
  .text("Trigger some fancy stuff");
var createdNodes = mkup.write();
createdNodes.link.observe("click", function(event){
  Event.stop(event);
  alert("Fancy! Wow!");
});

creates:

<div>
  <a href="#">Trigger some fancy stuff</a>
</div>

Target three: code should be as short as possible

Well judge yourself:

Without mkup:

var div = new Element("div");
var link = new Element("a",{href:"#"});
div.appendChild(link);
link.appendChild(document.createTextNode("Link"));
$('results').appendChild(div);

using mkup:

var mkup = Mkup.mkup($('results'));
mkup.div().childA({href:"#"}).text("Link").write();

How to help

If you are interested in mkup, you can help us to improve it:

• tell us that you use it – because it’s motivating to know that mkup is useful to someone
• tell the world that you use it – see above
• run the test suite in your browser and report bugs here – you can find the test page here
• add a feature – mkup is a small project, so this is your chance to participate in a open source project without a steep learning curve. Checking out the code using subversion is easy and explained here

In this blog entry I want to give you an impression of an alternative solution by agimatec, that is slightly different. It is the solution we are using in our products for more than two years and with which we are satisfied. It would be interesting to hear your options on this.

The concept

Database:

We generate history tables for each table for which we need auditing. We generate database triggers (oracle or postgres) to automatically insert data in the history tables when entities are stored/deleted.

We do not store duplicate data, which means that our history tables contain only OLD data. All current data is ONLY stored in the application’s tables (usually mapped by hibernate/Ejb3).

Configuration:

We have a XML configuration, that contains the table names for which we want to enable our history solution. This configuration lets you specify:

• name of history table (or a default name will be used)
• which columns to exclude from history (default is that all columns are historised)
• optionally you can turn off history for insert and/or update, change trigger names etc.

The XML configuration controls the tables and triggers generated by freemarker templates.

Features:

It is not only important to version the changes, but also to store, the timestamp of a change and some context information about the change (e.g. who is the actor, which application, from which sessionID etc.). Any context information can be associated with a version record by storing a contextID in the history table’s rows.

This is also a way to separate changes from user-specific data, which might be a judical requirement. An extended Hibernate event handler stores the contextID into the database session by calling a stored procedure, so that the history triggers and access the contextID to store it together with the history data.

Each history table has additional columns:

• HIST_TIME (timestamp of change)
• HIST_CONTEXTID (ID of context providing additional information)
• HIST_TYPE (to distinguish INSERT, UPDATE and DELETION)

A simple java API exists to query historical data. It returns the same classes as you use for your hibernate entities, but it materializes the objects itself. Hibernate does not know anything about the history tables or mappings.

The benefits

There are some differences between the solution provided by Envers and agimatec:

• Envers needs a global _revision table, agimatec’s history rows are identified by the primary key and a version number (@Version) incremented from 1 for each entity/no global _revision
• You can change data with any SQL tool.Historisation does not rely on hibernate as the only API to change the database.
• Whenever you increment a row’s version, the history triggers will automatically write historical data. By this way, you can use migration scripts that can control whether history data will be stored.
• Envers stores current data in history tables, which makes it a bit easier to query the data, but with means redundancy (and potential data inconsistencies).
• Both framework are integrated with Hibernate by extending the Hibernate Events (to provide context information).

Examples

History configuration

<historyConfig>
<tableConfig>
<tableName>booking</tableName>
</tableConfig>
<tableConfig>
<tableName>customer</tableName>
<historyTable>h_cust</historyTable>
<insertTrigger>TR_I_cust</insertTrigger>
<updateTrigger>TR_U_cust</updateTrigger>
</tableConfig>


Generated tables

CREATE TABLE H_JOURNAL (
ID INTEGER NOT NULL,
HIST_TABLE VARCHAR(50) NOT NULL,
HIST_TIME TIMESTAMP NOT NULL,
HIST_CONTEXTID VARCHAR(40),
CONSTRAINT H_JOURNAL_PK PRIMARY KEY (ID, HIST_TABLE)
);

CREATE TABLE H_booking (
VERSION INTEGER NOT NULL,
booking_id INTEGER NOT NULL,
price NUMBER,
HIST_TIME TIMESTAMP NOT NULL,
HIST_CONTEXTID VARCHAR(40),
HIST_TYPE CHAR(1) NOT NULL,
CONSTRAINT H_booking_PK PRIMARY KEY (VERSION, booking_id)
);
CREATE TABLE H_cust (
VERSION INTEGER NOT NULL,
cust_id INTEGER NOT NULL,
first_name VARCHAR2(40),
last_name VARCHAR2(40),
HIST_TIME TIMESTAMP NOT NULL,
HIST_CONTEXTID VARCHAR(40),
HIST_TYPE CHAR(1) NOT NULL,
CONSTRAINT H_cust_PK PRIMARY KEY (VERSION, card_id)
);

Generated triggers

CREATE OR REPLACE TRIGGER TR_I_cust
AFTER INSERT ON customer
REFERENCING NEW AS NEW
FOR EACH ROW
BEGIN
setTATime();
INSERT INTO H_JOURNAL (ID, HIST_TIME, HIST_CONTEXTID, HIST_TABLE)
select :NEW.card_id, h.ts, h_session.getContextId, 'customer' from h_tatime h;
END;
/

CREATE OR REPLACE TRIGGER TR_U_cust
AFTER DELETE OR UPDATE
ON customer
REFERENCING NEW AS NEW OLD AS OLD
FOR EACH ROW
BEGIN
IF(DELETING) THEN
setTATime();
INSERT INTO H_cust (
cust_id,
version,
first_name,
last_name,
HIST_TIME, HIST_CONTEXTID, HIST_TYPE)
select
:OLD.cust_id,
:OLD.version,
:OLD.first_name,
:OLD.last_name,
h.ts, h_session.getContextId, 'D' from h_tatime h;
ELSIF (UPDATING AND :OLD.VERSION != :NEW.VERSION) THEN
setTATime();
INSERT INTO H_cust (
cust_id,
version,
first_name,
last_name,
HIST_TIME, HIST_CONTEXTID, HIST_TYPE)
select
:OLD.cust_id,
:OLD.version,
:OLD.first_name,
:OLD.last_name,
h.ts, h_session.getContextId, 'U' from h_tatime h;
END IF;
END;
/

Java API

The implementation of class HibernateHistoryReader was rather complex, because of the need to resolve the relationships through the current tables and the history tables. All changes done inside a single transaction are joined together by using a timestamp in HIST_TIME that is unique inside the running database transaction.

Here is interface HistoryReader:

interface HistoryReader {

void open(EntityManager entityManager);
void close();

List<EntityRevision> getRevisions(Class entityClass, Object primaryKey, Timeframe timeframe);
EntityRevision getRevision(Class entityClass, Object primaryKey, int version);

Map<Object, List<EntityRevision>> getChildrenRevisions(Class parentEntityClass,EntityRevision parentRevision,String relationship);

<E> HistoryEntity<E> loadEntity(Class<E> entityClass, Object primaryKey,Timestamp time);
<E> List<HistoryEntity<E>> loadChildren(Class parentEntityClass, String relationship,
Object parentPrimaryKey, Timestamp time);

}

Where class HistoryEntity contains the entity instance for a given point of time and some additional information, such as the contextID and the foreignKey values to load some to-one-references.

If you are interested in more details contact us.

What you should know:

• Metadata for scaffoling your GUI (described here).

What you need to compile/run the examples:

• java1.5 or newer
• opensource framework: agimatec-validation : download agimatec-validation.jar
• optional: javax.servlet.jar (servlet-api)
• optional: opensource frameworks/tools: agimatec-tools : download annomark-dist.zip and annogen.jar

1. Create model classes

We start with a plain java class, our model, used to transport attributes from the server to the GUI. (You can use DWR for marshaling object instances between Java and JavaScript/JDOM).

Example class “Business”:

import javax.persistence.*;

public class Business {
@Id
@Column(name=”business_id”, nullable=false, unique=true)
Long businessId;
@Column(name=”name”, nullable=false, unique=true, length=200)
String name;
@Column(name=”active”, nullable=false)
boolean active;
// getters, setters follow…
}

2. Write or generate xml meta data

You can write the xml meta data manually, or – if your classes have javax.persistence.* annotations – you can generate them using agimatec-tools/annomark.jar (described here):

<bean id=”com.agimatec.Business” impl=”com.agimatec.Business”>
<feature key=”mainKey”>
<value class=”string”>businessId</value>
</feature>
<property name=”businessId”>
<feature key=”uniqueKey”>
<value class=”boolean”>true</value>
</feature>
</property>
<property name=”name” mandatory=”true” maxLength=”200″>
<feature key=”uniqueKey”>
<value class=”boolean”>true</value>
</feature>
</property>
<property name=”active” mandatory=”true”/>
</bean>

Store the file as “beaninfos-default.xml” in the classpath.

2. Access the MetaBean

This requires agimatec-validation.jar to compile:

import com.agimatec.validation.MetaBeanManagerFactory;
import com.agimatec.validation.model.MetaBean;

MetaBeanManagerFactory.getRegistry().
addResourceLoader(“beaninfos-default.xml”);

MetaBean metabean = MetaBeanManagerFactory.getFinder().findForClass(Business.class);

3. Generate JSon for metabean(s)

We want to use the meta data in the AJAX layer, to have information about the properties, their types and additional features (mandatory, max-length, …) as a JSON formatted string. agimatec-validation offers a JSONGenerator, based on a freemarker template:

import com.agimatec.validation.json.JSONGenerator;

JSONGenerator generator = new JSONGenerator();
String json = generator.toJSON(metabean);
System.out.println(json);

This prints this JSON string:

agimatec.namespace(“agimatec.metadata”);

(function(){

var metaBean0 = {
“id” : “com.agimatec.Business”,
“beanClass” : “com.agimatec.Business”,
“name” : “Business”,
“features” :{   “mainKey” : “businessId”},
“properties” :{
“active”:{
“name” : “active”,
“type” : “boolean”,
“features” : {       “mandatory” : true       }},
“businessId”:{
“name” : “businessId”,
“type” : “long”,
“features” : {       “uniqueKey” : true       }},
“name”:{
“name” : “name”,
“type” : “java.lang.String”,
“features” : {       “maxLen” : 200,       “mandatory” : true,       “uniqueKey” : true       }},
“version”:{
“name” : “version”,
“type” : “int”,
“features” : {       }}}};

agimatec.metadata.metaBeans = {“com.agimatec.Business” : metaBean0};})();

4. Write a servlet to deliver JSON for the AJAX GUI

The java code for the servlet should not be a surprise, for it consists of what we have seen so far:

public void init() throws ServletException {
super.init();
MetaBeanManagerFactory.getRegistry().addResourceLoader(“beaninfos-default.xml”);
}

public void service(HttpServletRequest servletRequest, HttpServletResponse res)
throws ServletException, IOException {
Map<String, MetaBean> metaBeans = MetaBeanManagerFactory.getFinder().findAll();
// output JSON:
res.setContentType(“text/javascript”);
PrintWriter writer = res.getWriter();
String json = new JSONGenerator().toJSON(metaBeans.values());
writer.write(json);
}

Thats basically all! With this infrastructure your AJAX GUIs have access to meta information about the model classes.

5. Enrich meta data with information for the GUI-layer

You can enrich the xml meta data with additional hints (field sequence, formats, …) – whatever your GUI needs. If hhe additional information cannot be generated automatically, you should keep them in a separate xml-file:

<bean id=”com.agimatec.Business”>
<feature key=”DESCRIPTION”>
<value class=”string”>{name}</value>
</feature>
<feature key=”SORTING”>
<value class=”list”>
<string>name</string>
<string>active</string>
</value>
</feature>
<!–Visualisation as table–>
<feature key=”TABLE_COLUMNS”>
<value class=”list”>
<string>name</string>
<string>active</string>
</value>
</feature>
</bean>

Save this as “beaninfos-gui.xml ” in the classpath and register the file in the init() method of the servlet, too:

MetaBeanManagerFactory.getRegistry().addResourceLoader(“beaninfos-gui.xml”);

You see, that the JSON code will contain the additional information as well, because the MetaBeanManager merges them.

So far, we have the infrastructure to support meta data that allows us to build generic AJAX GUIs. The JSON string can be cached, because it will never change while the application is running.

6. User-specific meta data

We can go one step further: We can also support user-specific meta data! A usual requirement in a web application is, that – depending on the role of a user that is logged in – field-level permissions must be supported:
User A is allowed to change the “active”-state of our “Business” entity, while User B has read-only access to the field and the field is hidden for User C, …

This could also be useful, when a user can customize its GUI (disable fields) by himself or when the application is used by different companies with different settings for their users….

How does it work? – Use additional xml files and merge them in the JSON servlet. (You can also generate the meta beans during runtime programmatically).

beaninfos-role1.xml:

<bean id=”com.agimatec.Business”>
<property name=”active”>
<feature key=”readonly”>
<value class=”boolean”>true</value>
</feature>
</property>
</bean>

Extension of the servlet:

String customInfos = “beaninfos-role1.xml”; // determine this from session or request dynamically!
XMLMetaBeanInfos xmlInfos =
new XMLMetaBeanURLLoader(getClass().getResource(customInfos)).load();
Map<String, MetaBean> metaBeans =
MetaBeanManagerFactory.getEnricher().enrichCopies(xmlInfos);

The statements after “// output JSON” stay the same (see previous code fragment).

More information?

We already got some more posts in German about metadata and code generation, explaining the concepts and giving examples:

• TransferObjects generieren
• agimatec-tools als OpenSource auf google.code released!
• Statt Modellieren: Annotieren und generieren
• Klassen mit Mehrwert: Validierung und Metadaten

The open-source frameworks have a WIKI and additional examples or junit testcases, that help you.

If you have questions, do not hesitate to contact us!

This is the fifth article in our mini-series about developing highly ajaxified portlets. Other articles are:

• Generate Your UI Using Metadata
• Inter Portlet Communication
• Using YUI loader for your own javascript modules
• Portlet namespaces and javascript

This is the situation we are in. And here is how we ease the pain: we are generating the user interface.

Generating a Form

To generate a form using our framework, you need to tell it :

• what should be edited
• the type of what is edited

Say we are building a form to edit a user object that contains user ip addresses:

var user = {
	name:"Sebastian Schuth",
	ipAddress:"192.168.1.33",
	active:true
}

The form fields needed are described using object literals:

var fields = [
	{
		key:'name', //name of the edited property
		label:'User name', //label to use in the form
		type: 'string',//type information
		permissioning:{denied: false, readonly: false}
	},
	{
		key:'active',
		label:'User is active',
		type: 'boolean',
		permissioning:{denied: false, readonly: false}
	},
	{
		key:'ipAddress',
		label:'IP Address',
		type: 'ipAddress',//this is a custom type
		permissioning:{denied: false,readonly: false}
	}
];

The properties needed for each field are:

• key – name of the property that gets described by the entry
• label – description shown as label inside the form
• type – the type of the data stored in the property. This information is used by the framework to choose an editor implementation
• permissioning – data about what the user is allowed to do with the entry. This reflects what the server allows the user to do.

Using this information, we can create a form using the following API:

/**
 *

Adds a form with into the given container element using the given fieldDefinitions.

 *

The structure of the form's contents depend on the editor implementation inside fieldDefinitions. This
 * function creates just a form element as container for the elements the editors return and which it adds to the DOM.

 *

A Save button is added to the form as long as the addSaveBtn
 * config option is not set to false.
 * The fnOkCallback function must takes one parameter: it gets a new object filled with the values from the
 * created form.
 * 

 *
 * @param {object} namespace                The javascript portlet namespace (used to get I18N information)
 * @param {Element} container               HTML node to which the form is added
 * @param {object[]} fieldDefinitions       The definitions of the form fields
 * @param {function} fnOkCallback           Function which is called when the form's save button is clicked
 *                                          (if no save button is added (oConfig.addSaveBtn === false),
 *                                          this function is never called!)
 * @param {object} [oConfig]                Optional configuration.
 * @config {object} [formAttributes]        Attribute definitions for the form as key/value object.
 * @config {boolean} [addSaveBtn]           If false, no save button gets added to the form. Defaults to true.
 * @config {object[]} [additionalButtons]   Array of additional buttons that should get added left of the save button
 *                                          (if a save button is added) to the form.
 *                                          The contained objects need to members:
 *

 *
label {string} Label of the button.

 *
callback {function} Function called if the button gets clicked.

 *                                          

 *                                          Note: Make sure to stop the click event inside the callback function
 *                                          to make sure that the form does not get send!
 *
 * @return {function} An error handling function that can be called to check for errors and add error messages to the
 * form as needed.
 */
agimatec.scaffolding.createForm = function(namespace, container, fieldDefinitions, fnOkCallback, oConfig){
	// ...
}

(as you can see, we are using JSdoc toolkit to generate our API docs)

So, let’s create a form:

agimatec.scaffolding.createForm(this, formContainer, fields, null);

This call does two things: it creates a form inside formContainer and adds editor objects (read on to learn more about them!) to the field description objects given to it.

Now, we need to fill the form:

agimatec.scaffolding.fillFields(user, fields);

Now, we can see what we have constructed:

Form generated by the example code

Reading the values from the form is as easy as:

var objectFromForm = {};
agimatec.scaffolding.readValues(objectFromForm, fields, callbackWhenDone);

After this call, objectFromForm contains all data as edited by the user.

About Editors

Inside the framework, editor objects are used to create the form parts needed to edit object properties. All an editor does is create a fieldset which is added to the form created by agimatec.scaffolding.createForm(), which itself gets added to the DOM.
This means that if a special kind of data entry is needed, you will need to implement a special editor, which has to provide the following functions:

• getReadWriteElement() – returns the DOM element used to edit entries
• getReadElement() - returns the DOM element used to display
• setValue() – this is called by the framework when using agimatec.scaffolding.fillFields()

We have put together some editors (current count: 21), including ones to connect objects to other objects, upload files, entering IP addresses, weekdays, dates, times and so on. This makes maintaining our webapp much easier and guarantees the consistency our customers appreciate.

Now entering the stage: Metadata

Well, as easy defining fields using object literals is, this does not solve the issue of additions and changes to existing objects. This is where we added metadata to the mix. The metadata we get from the server tells us enough to create the field definitions we need to generate the forms!

So here we go:

	/**
	 * Gets the field definitions for a dynamic form element (@see scaffolding.js).
	 * This function returns the sorted field definitions for a specified object. These describe which
	 * editor is used and adds further information like key and label to it.
	 * If we have an enum type, it adds also the options to an feature object.
	 * Features:
	 *

	 *
sorting of field definitions using a bean's SORTING feature

	 *
AJF type matching for root type and all related beans (depends if the feature "include" is set)

	 *
adding type of modelObject AJF type as feature "refBeanId"

	 * 

	 *
	 * @param {object} namespace    The javascript portlet namespace (used to get I18N information)
	 * @param {string} beanInfoId   The bean info id (e.g. 'com.agimatec.connecta.model.XFireTemplate')
	 *
	 * @return {object[]} Field definitions for the given beanInfoId.
	 */
	agimatec.metadata.getFieldDefinitions = function(namespace, beanInfoId) {/*...*/};

All you need to pass is which kind of object you want to display, the rest is handled by the framework.

Whats next

In this post, i explained how our framework makes creating forms for data entry easy and how we use metadata to make things even more “magic”. But this is not the end of the story. Our metadata is generated in a multi-step process, which will be described in a future post. To wet you appetite: we are generating metadata from multiple sources: Java Beans and XML descriptors and are able to merge multiple descriptors and user-based permissions.

Of course, generated UIs always need to be highly configurable to meet your user’s needs. Our framework offers a lot of options for this, up to defining rules that can manipulate the form reflecting what the user entered (and it looks like: formManager.when("lifecycleStatus").isSetTo("ACTIVE").changeForm(/*...actions...*/)). This makes the forms more friendly to use and prevents the user from doing things that make no sense. If you are interested, i would like to hear from you, just leave a comment.

Another theme i did not mention in the example is client-side validation. This is built in, too. And it is not hard to use, but explaining it would have made this article even longer. Again: if you are interested, leave a comment. If there is interest, i will blog about it.

This is the fourth article in my mini-series about developing highly ajaxified portlets. In this blog, you can also find articles about:

Maven is a good tool to handle your dependencies. You shouldn’t copy the necessary artifacts by hand in your lib folder. It is the beginning of the end for your project. Transitive dependencies could ease the management of your dependencies and Maven is the right tool for this. But sometimes it is to much magic behind the scenes. There could be a lot of transitive dependencies and there could be conflicts. Even more if your projects gets larger and uses more and more open source frameworks. We had problems with two actions:

• Change the version of a dependency
• Update the version of Maven

Change the version of a dependency

If you update the version of a dependency this could cause completely different transitive dependencies to be fetched. Normally no big deal, but you need to clean your artifacts. Often you just use mvn install to install your artifact. But without the clean target, the old dependencies are still in your target folder. Remember to use mvn clean install when changing the version of a dependency. But there is also another place, where old dependencies can survive. If you hot deploy your artifacts to your server, you should also delete the old artifacts and extracted folders. After that you are in a really clean condition.

Update the version of Maven

We had problems with transitive dependencies when changing the version of Maven. Make sure that every team member and build server uses the same version. Then you can still have problems, but there are no different transitive resolutions on different computers. Can be very confusing if one person in the team has version A and another one has version B. I think the Maven team tries to reduce this, but if there are changes in the dependency resolution, it could happen that conflicts are solved in a different way.

What about real trouble?

If you have a lot open source dependencies, there are much more transitive dependencies. Maven tries to resolve conflicts, but you will often find a situation, where dependencies A and B needs the same transitive dependency but in a different version. This can produce situations, described in the post: Maven supports JAR hell. Something is wrong and you have a lot of unwanted dependencies in your library folder. The next step is to find out, where they come from. This can be complicated, because transitive dependencies also have own transitive dependencies.

Find out where the dependencies come from

There are different solutions for this and Maven has improved the detection of dependencies for users. Most of the time I use the Maven site. It is always a good idea to use this feature, because it can give you a nice overview of your project. Take the time and configure your site, it is very helpful for the team.

To generate the Maven site just use: mvn site

This will generate a linked web site, where you can use a lot plugins. There is also the section dependencies, where you can have a look what dependencies exist and watch the transitive dependencies tree.

But there are also command line options. First of all the Maven Dependency Plugin. To get the transitive dependencies tree just type: mvn dependency:tree

It will display where the dependencies come from. It is also possible to filter the output or find conflicts.

We also use the concept of parent POMs with a deeper hierarchy. Sometimes you need to know, how your effective POM in the sub-project looks like. To get this information use: mvn help:effective-pom

You should have a look at the Maven Help Plugin, because there are some interesting other options.

Start your own dependency management

That doesn’t mean that you don’t use Maven. But most of the time you know your artifacts and their actual version. And you want a specific version to be included. You also want to have a consistent version of an artifact used through all sub-projects, then you can use declarative dependency management in Maven. That can avoid classpath issues. It is also very easy to upgrade a version, because the child-POMs don’t have a version included. They use the version defined in the parent POM.

We manage our dependencies in our master parent POM. There is a section in the XML called dependencyManagement. There you can list your dependencies and add the group, the artifactId and very important: the version. Now every time Maven tries to resolve a dependency it is using this specified version. Easy, isn’t it? Yes, the dependency management list is getting larger, but in a large project you are very pleased to find always the correct version of your dependencies.

Read more about this in the Maven documentation.

For us it was a great time saver, because we had less problems with Maven. You don’t need your own dependency management, but if you run in trouble think about using it.

If you want the know about the best Maven plugins, check out the Top 10 Maven plugins on our blog.

In theory.

In practice, you will be faced with a problem that is obviously a blind spot of the portlet definition (at least, the “old” JSR-186): how to communicate between portlets. The ability to mix-and-match portlets is key to a truly pluggable application formed of portlets.

To solve the communication problem, we have developed a solution much like the one developed by the folks at liferay, but a bit more tuned and optimized for a fully pluggable solution.

Portlet Services and Invokers

Our implementation follows a simple pattern: Portlets are able to promote services to a page-central instance and can include interaction elements that are used to invoke services that match certain criteria:

• the type of object the service must be able to handle
• the type of operation the service offers

Promoting a service to other portlets includes:

• specifying what type of operation (CREATE/READ/UPDATE/DELETE) is offered
• a text telling the user what happens when invoking the service
• the function that should get called on service activation

Using these simple building blocks we can offer users a list of actions that are available for a specific object:

Completely discoupled

The major advantage of our solution is that we do not hard-wire which portlets offers what to other portlets. All you have to do is insert a service invoker into the UI and the framework does the work for you. All people working on the project can work in parallel, the communication overhead is minimal. All the developers must do is offering a portlets services using the framework and give services a name that speaks.

This makes turns our product into a completely customizable platform that fits exactly our users’s needs.

Maximum flexibility

The framework makes splitting up responsibilities between portlets easy and puzzling just the right application for the job together possible. After adding a new portlet to a page, all service menus are automatically updated to offer new services that may have been added by the new portlet.

A generated service menu

Service menu for a different set of portlets

What you see in these screenshots is that depending on which portlets are available, the portlet will offer different actions for an object (for Screenshot 2, the “Ping” portlet was added). All information about which services are available is calculated client-side and for the current setup. Adding a new portlet will add its services to the actions list. The text that appears inside the menu is set by the portlet offering the service.

Invoking services is not limited to the context menus. We also use buttons for services that enable the creation of new items.

Impacts on portlet design

All this makes it easy to develop portlets that are designed to fulfill small tasks the right way. Reusability of portlets is massively increased. And on top of all this you get a consistent usage pattern that your customers will be familiar with when you are adding more functionality.

This is the third article in my mini-series about developing highly ajaxified portlets. In this blog, you can also find articles about:

• Using YUI loader for your own javascript modules
  
• Portlet namespaces and javascript

In my next post in this series, i will give a little insight into how we use metadata generated by our server to make creating a fully ajax portlet a breeze. Meanwhile, check out our posts about testing our Ajax frontends using Selenium and the YUI Test framework.

Can you guess the difference between

select * from dual d where  d.dummy <= ‘X’ /* {} */

and

select * from dual d where  d.dummy <= ‘X’

?

Just a comment? -

Well, the surprise is, that the driver throws

java.lang.NullPointerException  at oracle.jdbc.driver.T4C8Oall.getNumRows(T4C8Oall.java:876)

in the first case that contains the comment and executes the statement correctly in the second case.

Thanks, Oracle!

The easiest method are unit tests. We have tried several JS unit test frameworks. Including JSUnit, Scriptaculous Unit Test Runner and YUI test. With a lot of YUI components like the YUI Loader and many YUI widgets we refactored our unit tests to use YUI Test. We like the Yahoo User Interface because of its documentation and also of its code quality.

YUI Test is not bundled with YUI. You can use it with YUI but we also use other frameworks like Prototype and DWR. To learn more about YUI Test you can watch the presentation of Nicholas C. Zakas.

Ok, this is great, now I can test my Javascript. But wait, what is if I have a lot of Javascript. I can group my tests in test cases and test cases in test suites. This is supported. But while the amount of Javascript is growing one file for all tests isn’t enough. We have a lot of different modules. Each consists of a lot of test cases. Sure, you can copy them all together in a file which is several thousand lines long. But every test run takes then a lot of time, debugging is more complex and it is more complicated to manage this file.

YUI TestManager

Wouldn’t it be great to have a test runner. A script which takes a lot of unit test files and run them one after another.  Our first approach was based on the Scriptaculous Unit Test Runner embedded in a frameset. We had a navigation frame and some Javascript included to run one unit test file in the main frame. One problem was to collect the results of all unit test files. We patched the Unit Test Runner and collected the data. It was ok and I wanted to refactor the solution to publish it. After starting I suddenly found an undocumented feature of YUI Test – The YUI TestManager. It is exactly what I wanted to do, define the unit test files, run through all of them and collect the results. I think Yahoo is using this feature internally and didn’t talk a lot about it. But it is included in the API, so please YUI team, include it to the documentation. It is a great piece of code.

Continuous Integration of Javascript with Selenium

Before I will show you how to use it, some more thoughts about this. We are coming from the agile Java world. So continuous integration is very important for us. Please search for “Continuous Integration Javascript” in your search machine. There are just a few hits and no ready to use solution. Yes, you can try to go back to the Java world and run tests with Rhino. There are some Java based unit test frameworks for Javascript. But there are two downsides. You are leaving the Javascript world and you are leaving the browser. It can be ok for you but I don’t trust the different browsers. I want to be able to run the tests fast in the browser when I’m developing and I want to test as many browsers as I can. We searched for a solution and what we have running is a suite of Selenium tests. They are at another level. Functional tests which run through use cases in the web frontend. But if we could give them a result of our unit tests we are able to include this in our setup. Then we can run the unit tests in IE, Firefox and Opera automatically.

YUI Test gives you the logger to view the results of your tests. It is not the best view for test results but it is ok. Also there are a lot of events which include the results of the tests after running them. We have implemented a little script which displays a nice summary which we test with Selenium.

Source code

Now let’s head to the source code.

At the beginning we need a unit test. Because I’m want to concentrate on the TestManager you will find a very very simple test.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>String test</title>

    <!--CSS-->
	<link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.6.0/build/logger/assets/logger.css">
	<link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.6.0/build/yuitest/assets/testlogger.css">

	<!-- Dependencies -->
	<script type="text/javascript" src="http://yui.yahooapis.com/2.6.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
	<script type="text/javascript" src="http://yui.yahooapis.com/2.6.0/build/logger/logger-min.js"></script>

	<!-- Source File -->
	<script type="text/javascript" src="http://yui.yahooapis.com/2.6.0/build/yuitest/yuitest-min.js"></script>

    <script type="text/javascript">
    YAHOO.tool.TestRunner.add(new YAHOO.tool.TestCase({

        name: "String test",

        testEqualityAsserts : function () {
            var Assert = YAHOO.util.Assert;

            Assert.areEqual("hel"+"lo", "hello");     //passes
            Assert.areEqual("YUI test".substr(0,3), "YUI");     //passes
        }
    }));

    YAHOO.util.Event.onDOMReady(function (){

	    if (parent && parent.TestManager) {
            parent.TestManager.load();
        }
        else {
            var logger = new YAHOO.tool.TestLogger();

            //run the tests
            YAHOO.tool.TestRunner.run();
        }
  	});
  	</script>
</head>
<body>
</body>
</html>

In the first part we define our tests. In the second part you will see that the test will be called after the DOM is ready. It is a little bit different from the normal examples, because we call parent.TestManager.load() if it is available. Now you can copy this code, write your own tests, define test suites, … It starts to get interesting, if you have so many tests, that you want to group them into different files. With the code above you can go ahead and create multiple tests. In the example code I have created to test files calcTest.html and stringTest.html.

To run all tests in all your test files you need to call the TestManager:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>JS Unit Tests</title>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>

    <!--CSS-->
    <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.6.0/build/logger/assets/logger.css">
    <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.6.0/build/yuitest/assets/testlogger.css">

    <!-- Dependencies -->
    <script type="text/javascript" src="http://yui.yahooapis.com/2.6.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
    <script type="text/javascript" src="http://yui.yahooapis.com/2.6.0/build/logger/logger-min.js"></script>

    <!-- Source File -->
    <script type="text/javascript" src="http://yui.yahooapis.com/2.6.0/build/yuitest/yuitest-min.js"></script>

    <!-- Source file -->
    <script type="text/javascript">
    	var TestManager = YAHOO.tool.TestManager;

        TestManager.setPages([
            "./stringTest.html",
            "./calcTest.html"
            ]);

        YAHOO.util.Event.onDOMReady(function() {
        	TestManager.start();
        });
    </script>
</head>
<body>

<h1>JS Unit Tests</h1>

</body>
</html>

That’s simple, isn’t it?

That will give you the following output:

We wanted to give it more the feeling of a unit test suite. As I told you there is an event after test completion, which includes the test results. With our script we are building a summary table which gives you a nice overview for your test results.

With the overview table we also can track the results with a simple Selenium test:

package com.agimatec.ostium.portlets.jsunit;

import com.agimatec.ostium.portlets.util.ScreenshottingSelenium;
import com.thoughtworks.selenium.Selenium;
import org.testng.Assert;
import org.testng.Reporter;
import org.testng.annotations.*;

public class JsUnitTest {
    Selenium selenium;

    @BeforeMethod
    @Parameters({"selenium.host", "selenium.port", "browser", "baseUrl", "ostium.login",
            "ostium.password"})
    public void startSelenium(
            @Optional("localhost")String host,
            @Optional("4444")int port,
            @Optional("*firefox")String browser,
            @Optional("http://localhost:8080")String baseUrl
    ) throws Exception {
        Reporter.log("Running selenium");
        selenium = new ScreenshottingSelenium(host, port, browser, baseUrl);
        selenium.start();
    }

    @Test
    public void checkPassedJsUnitTests() throws InterruptedException {
        selenium.open("/portlets/ostium/utilities/ajf/src/test/javascript/testrunner.html");
        for (int second = 0; ; second++) {
            if (second >= 60) Assert.fail("timeout");
            try {
                if (selenium.isElementPresent("//div[@id='testcontainer']/div/h2")) break;
            } catch (Exception e) {
            }
            Thread.sleep(1000);
        }

        Assert.assertTrue(
                selenium.isTextPresent("exact:Result: Passed"),
                "The result of the JS tests should be 'PASSED'.");
    }

    @AfterMethod
    public void stopSelenium() {
        Reporter.log("Stopping selenium");
        selenium.stop();
    }
}

The only thing to do is to run the files on a local server. We use a Jetty with Maven to host the files because Selenium needs to include a proxy which didn’t work if you access the file directly.

Find more to Selenium on our other posts:

• Selenium testing of massive Ajax Apps
• Selenium CI tests with TeamCity
• Robust portlet testing

Download the script and some examples here. We are planning to release it with some other JS stuff as a Google code project, but we are still searching for a name.

If this post was helpful or you have additional ideas, please don’t hesitate to comment.