Portals, Portlets and Alfresco

Portlets are self-contained web applications that are meant to be deployed in portals or, to be more precise, portlet containers.
All major application server vendors have extended their products with a portlet container, and the open-source world provides us with some implementations, too. To mention a few, we have Jetspeed, GateIn, Liferay...
In theory portlets should be able to deploy in any portlet container, but in practice we're developing portlets having in mind the concrete portal implementation we're working with. Often we need to add to our portlets some vendor-specific config files that make them integrate nicely in that particular portal and, as a side effect, make them useless for any other.
In this little example I have stuck to the portlet specification, kept the code portal-free and let the container inject whatever the portlet needs to run in it. And it works, at least in GateIn, my chosen portal. Later I will try to drop it in Liferay and see what happens; I'll let you know the results in another post.

Let's build a portlet that calls an Alfresco webscript to pull some data, and displays the results.

Alfresco

First we need an instance of Alfresco up and running. If you don't have it yet, download the latest community edition from here and install it. The default settings will almost do for our purposes, you don't even need to create a site for this example to work.
The only configuration items we need to change are the authentication settings since we need to ensure that Alfresco accepts remote calls. We achieve this by enabling external authentication. Edit alfresco-global.properties (in $ALFRESCO_HOME/tomcat/shared/classes) to include the following:

authentication.chain=external1:external,alfrescoNtlm1:alfrescoNtlm
external.authentication.enabled=true
external.authentication.proxyUserName=

If you have already an authentication.chain setup you only need to add external1:external to your current value. Note also that we have intentionally left empty the proxyUserName; this tells the external authentication subsystem that the user accessing Alfresco is the one specified in a header parameter in the remote request, as you will see when we develop the portlet. For more details about external authentication parameters see Alfresco docs.

Portlet

Now let's make this portlet. I have already mentioned GateIn, but there are some more pieces in this little demo. Let me show you the techonology stack we're going to work on:

• Eclipse IDE.
• Maven. Let the experts do the build.
• commons-httpclient. We're going to call an Alfresco webscript via HTTP, remember?
• Jackson. The webscript returns JSON, and Jackson parses JSON like hell.
• JSF. Why not? It's the technology I'm using at work right now.
• GateIn. It comes bundled either with Tomcat or JBoss. Take JBoss, which can talk JSF without the need of any additional libraries.

GateIn installation

You only need to be careful with the ports if you are running Alfresco and GateIn on the same machine. If that's the case, edit the files standalone.xml (there are several) in $GATEIN_HOME/standalone/configuration to change the port numbers. Alternatively you can change Alfresco settings in $ALFRESCO_HOME/tomcat/conf/server.xml.
To launch GeteIn execute standalone.sh (or .bat if you're on Windows) from $GATEIN_HOME/bin.
When you have your portlet ready just drop the .war file into $GATEIN_HOME/standalone/deployments and it will autodeploy.

Maven

As always, it is easy to build a portlet project with Maven. We have a maven-archetype-portlet to get us started. It generates, along with the folder structure that we need, some Jetspeed-specific folders and files that you can simply remove since they're not needed in our example.
If you don't want to get involved in maven archetypes (shame on you), just grab my code from here.
Liferay provides some portlet archetypes, too. Even one for JSF!

Portlet construction

My portlet is very simple. It just calls an Alfresco webscript that returns the list of user groups in JSON format, and then the view displays the list. The webscript I'm calling is /alfresco/wcservice/api/groups.

Portlet descriptor

Let's say that a portlet is a portlet because it has a portlet.xml file.
The maven-archetype-portlet generates a sample descriptor for us; we just have to use it as a template to make the one we need. This is the important bit in mine:

javax.portlet.faces.GenericFacesPortlet

 javax.portlet.faces.defaultViewId.view
 /xhtml/groups.xhtml

There's no much to explain. The portlet class is not ours, the container provides it. On the other hand, the view is something we must implement, as you may expect.

Faces config

faces-config.xml is not generated by maven-archetype-portlet.
In my example, it only declares a managed bean: the backing bean for the view.

 groupsBean
 ie.paco.alfresco_portlet.GroupsBean
 view

Backing bean

GroupsBean.java is the bean linked to the view file groups.xhtml.
It doesn't do anything really especial. Just calls Alfresco webscript and transforms the JSON response into a Java Map, which is then stored in a field called groups.

private static final String ALFRESCO_GROUPS_URL = "http://192.168.145.166:8080/alfresco/wcservice/api/groups";

private Map<String, Object> groups = null;

public GroupsBean() {
 HttpClient client = new HttpClient();
 GetMethod method = new GetMethod(ALFRESCO_GROUPS_URL);
 method.addRequestHeader("X-Alfresco-Remote-User", "admin");
 try {
  // Execute the method.
  int statusCode = client.executeMethod(method);

  if (statusCode != HttpStatus.SC_OK) {
    LOGGER.error("Method failed: " + method.getStatusLine());
  }

  // Read the response body.
  String response = method.getResponseBodyAsString();

  // Deal with the response.
  LOGGER.debug(response);
  ObjectMapper mapper = new ObjectMapper();
  groups = mapper.readValue(response, new TypeReference<Map<String, Object>>(){});

   } catch (HttpException e) {
  LOGGER.error("Fatal protocol violation:", e);
   } catch (IOException e) {
  LOGGER.error("Fatal transport error:", e);
   } finally {
  // Release the connection.
  method.releaseConnection();
   }  
}

Note that the webscript URL is hard-coded in a constant. You need to edit that to make it work in your environment.
Note also how the user is passed in the request header. You may need to edit that line, too, if your Alfresco username is different.
The JSON response from the webscript is going to be something like this:

{
 "data": [
  {
     "authorityType": "GROUP",
     "shortName": "ALFRESCO_ADMINISTRATORS",
     "fullName": "GROUP_ALFRESCO_ADMINISTRATORS",
     "displayName": "ALFRESCO_ADMINISTRATORS",
     "url": "/api/groups/ALFRESCO_ADMINISTRATORS"
  },
  {
     "authorityType": "GROUP",
     "shortName": "EMAIL_CONTRIBUTORS",
     "fullName": "GROUP_EMAIL_CONTRIBUTORS",
     "displayName": "EMAIL_CONTRIBUTORS",
     "url": "/api/groups/EMAIL_CONTRIBUTORS"
  }
 ]
}

So the groups Map in the backing been is going to end up with a single entry with key "data" and a list of group objects as value. The group objects are going to be also Maps.

The view

You can't get it any simpler:

 

Alfresco User Groups

  
 

It iterates over the list of groups in the backing bean and outputs their property "shortName".
This is what my portlet looks like in a GateIn page:

Source code

You can get the source code from here.

 What's next?

Well, this one has been sooooo simple, hasn't it? I'm sure you're missing some action.
So now that we're not scared of portals, portlets and Alfresco, let's enable some clicking on this portlet and make things happen. I will share my work in the next post.

The blank verse

Remember that this section has nothing to do whith technology or consulting. Anyway, this conversation may be of interest:

"It's hard to find a decent room in Castleknock, Fergal. It seems that everybody wants to live there. Offers last just minutes; everytime I call, the room is gone. Browsing the ads in daft.ie is a hard work, and sometimes the unexpectedness strikes you."

"the unexpectedness! Your English, Pepe."

"Yeah, I know. My English...
"Listen to this one I found yesterday, for example: '... single female in her thirties offers a room to let in... blah blah blah Castleknock. More than a lodger I'm looking for someone who wants to relax and feel at home... blah blah blah...'
"...Intriguing".

"Is that room gone, too?"

"I don't know, but that room is out of question. It seems to me that just by answering this ad I would commit myself to no less than... being happy. That's big deal. An exhausting task."

"I think you're reading the message the wrong way, Pepe"

"I've read and re-read 'the message', as you say, several times and thought about it for hours trying to find different interpretations."

"Don't tell me you always arrive to the same conclusion."

"Not the same, but alike. They range from 'nightmare' to 'hell'".

Fergal chuckles. "How's that?"

"Listen, it's very simple." Pepe takes his lecture tone "That room is not my room. That house is not my house. That's not my home. I don't want to feel at home, I don't want to feel comfortable, I don't want to be nice, and I'm ready to pay for not having to."

"So you finally admit it. You are antisocial."

"What's wrong with being antisocial?"

"Well, that question is wrong, too."

"Anyway, that's not all. Listen to this: 'I'm clean and tidy but not over the top.'"

"That's the same lady?"

"That's her. Same lady, same ad.
"What the heck does she mean?"

"What do you think she means, Pepe?"

"I don't know what she means, I'm asking you. But I do know what those words mean: 'she - is - dirty.'"

"For God's sake, Pepe. She's not saying that. She's clean although not to the highest degree."

"Highest degree? There's only one degree of cleanness and many degrees of dirtiness, everybody knows that."

"That's a sophism."

"No, it's true. Listen, Fergal, what would you think of me if I said 'I'm honest but not over the top.'?"

"That's different."

"Because you say so."