Introduction

After spending some time with Liferay and doing a bunch of portlets, I noticed that they share some common functionality which is just copy-pasted which is wrong.

I also knew that Liferay offers its Service system – a service is a combination of Interface and Util class that land into tomcat’s lib/ext folder backed up by implementation located in either portlet or an ext environment and some spring xml to wire them up.

A first approach suggested that this is going to be a piece of cake but unfortunately I got NPE 🙁

So I started looking through Liferay source code to find out how service-builder generated services fetch implementation from global spring context and expose it to the rest of portlets through Util class. It all seemed as easy as casting Object into given interface buf unfortunately wasn’t and I got ClassCastException (spring forums recognizes as not programming to interfaces…)

I was kind of stuck.

So maybe there was something special about classes generated by service-builder  which makes them accessible from non-owning-portlet.

Class loader proxy

The answer is yes and it’s called Class loader proxy – the architecture that grew from the need to allow inter-portlet communication across tomcat class loader. It transformed into somewhat complex architecture, that requires following steps:

  1. Create an interface
  2. Wrap your code in static calls using service-util
  3. Acesses your impl through spring bean context
  4. Wrap bean aquired from bean context in Class loader proxy.
  5. Store proxy inside local portlet context.
As you can see number of layers that need to be written for a single method call can cause a headache. Additionally  CLP uses MethodKey/MethodInvocation classes internally which makes it even more complicated.
Exposing a single method through all these layers seemed rather exaggerated task but this way I could focus on building all the layers by hand and finally see my implementation class called properly from different portlets.

APT generator for boilerplate

At this point I felt the need for some kind of code-generator that would free me from declaring all these service/clp layers by hand and I reminded myself that Java 5 offered a tool called APT. APT is annotation pre-processor used by JPA2 authors to create type-safe Criteria API (in java6 it’s part of javac compiler). Using it is as simple as placing annotaton on desired item, declare processor being used and your annotation is pre-processed during some phase before compilation and compiled – magic!

Generating Liferay-service code with APT

After this a big lengthy introduction I can finally say that in this post I’m going to concentrate on building LiferayService processor that will generate Liferay’s service boilerplate code, using java interface as starting point. I’m fully aware of the factthat Liferay’s service builder generates interface from implementation but for most people I spoke with, this is counter-intuitive so I’ll stick to contract-first approach.

Afterwards I’ll show you how to create sample ext-plugin project in order to test your new processor in action.

If you don’t have any experience in building annotation processor I recommend reading Jorge Hidalgo annotation series which starts from the very basics and finishes on writing simple annotation Processor.

Define annotation

As you can see the annoation is only preserved for compile-time, that’s all we need for annotation processor.

@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
public @interface LiferayService {
	public String value() default "portalClassLoader";
	public String initMethod() default "afterPropertiesSet";
}

LiferayService.java

Define view – templates for generated code

Now following best-practices adviced by Jorge from the formentioned blog entry I decided to use velocity template engine as view. We’re going to need 2 templates LiferayClp/LiferayUtil.

Their task is not that complicated:

  • add package declaration
  • add class declaration – using original name + suffix (Clp/Util)
  • add declaration for all passed methods
  • add init-method declaration
  • add class loader fetch

Define model – pass pieces of information from processor to view

All the pieces of information required by view are contained in processor model:
	public final Name getClassName() {
		return get(KEY_CLASS_NAME);
	}

	public final Name getPackageName() {
		return get(KEY_PACKAGE_NAME);
	}

	public final String getClassLoader() {
		return get(KEY_CLASS_LOADER);
	}

	public final String getInitMethod() {
		return get(KEY_INIT_METHOD);
	}

	public final Map getMethods() {
		return get(KEY_METHODS);
	}

	public final Map getModelMap() {
		return Collections.unmodifiableMap(modelMap);
	}

	public String getQualifiedName() {
		return getPackageName() + "." + getClassName();
	}

	public Set getSuffixes() {
		return EnumSet.allOf(Suffix.class);
	}
The code above is just an excerpt to see the main interface, you can view whole model here.

Get list of methods that need to be proxied

So now we have to decide what methods are the right ones that we would like to use in our service. Using interface as an entry point makes it a little bit easier since we don’t need to distinguish between implementation methods and some utility methods – getMethods can just take all methods that are abstract and non-native:


	private Map getMethodsToProxy(TypeElement classElement) {
		Map methods = new HashMap();

		List members = processingEnv.getElementUtils().getAllMembers(classElement);

		UniqueNameSupplier uns = new UniqueNameSupplier();

		for (Element member : members) {
			if (isInterfaceMethod(member)) {
				String methodName = uns.supplyUniqueName(member.getSimpleName());
				methods.put(methodName, member);
			}
		}

		return methods;
	}

It uses UniqueNameSupplier class which might need some extra attention – CLP class contains list of fields that share their name with proxied method name. So for each interface method we have a method declaration and field declaration but there is no mechanism that mimics method overloads for fields, so we just need to make sure that field names are unique. The uniqueness of CLP field is achieved by giving field name the same name as method and in case there’s a potential name-clash appending a number that prevents it – not a very sofisticated name-mangling.

Combine it all together

In order to use it inside IDE like Eclipse it’s best to have a simple archive – that’s why I decided to use maven assembly plugin with a simple configuration that just filters out all META-INF directories in order to preserve processor service file.

Summary

Basically this is it – there are some other extension points that you might use but feel free to explore them on your own:)

Sources and binaries

Sources are available on github.
Binaries in my private repo.

In my next installment I’ll write some basic usage scenario with ext-pluign and sample portlet.

That’s it!