Tuesday, April 14, 2009

Tutorial: Building Alfresco web scripts, deploying as Liferay Portlets - Part 3

Creating a Web Script using Java

Step 1: Create the Source Code Folder Hierarchy
  • Decide the package structure and URL of your web scripts.
  • For example, if we create web script in package com.infoaxon.repository
  • In this case, our folder structure would be <<root>>\com\infoaxon\repository. The Java source files will start from this folder.
  • Our all Java source files would be in the repository folder or in any of the subfolders, as per the package design suggests.
  • We will later on create a jar of all these classes.
  • One jar should ideally represent one module in Alfresco, hence if we plan to create a number of alfresco modules, we should design our packages accordingly.
  • One alfresco module can have any number of web scripts, and any number of different packages. So technically speaking, there is no need to create a number of modules for different packages; however, still creating separate modules might be a clean design approach.

Step 2: Create the main Java Class
We will now write the main Java class which will be responsible for generating the web script. This class must be inherited from org.alfresco.web.scripts.DeclarativeWebScript class and must implement executeImpl method.

Here is a sample class code

package com.infoaxon.repository;

import java.util.HashMap;
import java.util.Map;
import java.net.InetAddress;

import org.alfresco.service.cmr.repository.NodeRef;
import org.alfresco.web.scripts.WebScriptRequest;
import org.alfresco.web.scripts.WebScriptStatus;
import org.apache.log4j.Logger;

public class myfirstscript extends org.alfresco.web.scripts.DeclarativeWebScript {

Logger logger = Logger.getLogger(myfirstscript.class);

@Override
protected Map executeImpl(WebScriptRequest req, WebScriptStatus status) {
Map model = new HashMap();
String txt = "";
try {
txt = "Hello, Well Done!!! You seems to be got it, this is coming from Java!!!";
} catch (Exception e) {}

model.put("servertext", txt);
return model;
}
}


This class will simply return a hashtable with only one key named servertext. The web script Freemarker template than would take this variable, and would display.

Now to compile this one (assuming the file name is myfirstscript.java):
javac -cp C:\mystackroot\webapps\alfresco\WEB-INF\lib\alfresco-repository.jar;C:\mystackroot\webapps\alfresco\WEB-INF\lib\alfresco-web-client.jar;C:\mystackroot\webapps\alfresco\WEB-INF\lib\log4j.jar myfirstscript.java

This would create myfirstscript.class


Step 3: Package the Class
Now we will package the class, i.e. create jar of this.
For that, go to the root folder (mind that, we are in <<root>>\com\infoaxon\repository folder, and we have create our class and Java files there only). To create the jar:
jar -cvf <<jar-name>> <<root-package-name>>

For example in our case, jar -cvf myfirstscript.jar com
This should create the jar file with root namespace (package) as com.


Step 4: Deploy the Jar
As you know, to define a web script, we need to have:
  1. A description xml file, in our case the name would be myfirstscript.get.desc.xml
  2. An FTL file generating HTML code, in our case the name would be myfirstscript.get.html.ftl
  3. Optionally, a JS file, in our case the name would be myfirstscript.get.js
These files need to be created in C:\mystackroot\webapps\alfresco\WEB-INF\classes\alfresco\templates\webscripts\ folder hierarchy.
  1. Create subfolder hierarchy com\infoaxon\repository under C:\mystackroot\webapps\alfresco\WEB-INF\classes\alfresco\templates\webscripts\ folder.
  2. Under the repository folder, create the following three files:


myfirstscript.get.desc.xml
<webscript>
<shortname>My First Java based Web Script</shortname>
<description> My First Java based Web Script</description>
<url>/infoaxon/repository/myfirstscript</url>
<authentication>none</authentication>
</webscript>


myfirstscript.get.html.ftl
<html>
<body>
<p>${servertext}</p>
<p>${jstext}</p>
</body>
</html>


myfirstscript.get.js
model.jstext = "Hello, what do you think, this is coming from JavaScript!!!";


Step 6: Define a Alfresco Module that binds and deploys the Web Script
Now we need to create an alfresco module that binds the web script.

Alfresco modules are defined and deployed in C:\mystackroot\webapps\alfresco\WEB-INF\classes\alfresco\module folder. We need to register our web script as module in this folder only, so that next time when the server boots, it reads this module and deploys in Alfresco.
  • Create a folder here with name as you think properly represents your module. In our example, we create the folder named myfirstscriptmodule. Note: there is no restriction in module name; in other words, there is no binding in web script name, package name and module name. So you are free to use anything as your module name.
  • Under the myfirstscriptmodule folder, we need to create at least two files (by these names only):
module.properties:
This file renders the details of the module. A typical module.properties file looks like:

#Mon Jul 21 18:34:18 IST 2008
module.version=1.0
module.description=My First Web Script
module.id=myfirstscript
module.repo.version.max=999
module.title=My First Web Script
module.repo.version.min=2.1
module.installState=INSTALLED
module.installDate=2008-07-21T18\:33\:45.875+05\:30


module-context.xml:
This file registers the web script implementation Java class files as beans.
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>

<beans>
<bean id="webscript.com.infoaxon.repository.myfirstscript.get" class="com.infoaxon.repository.myfirstscript" parent="webscript">
</bean>
</beans>


There are a few important things to be noted in this file:
  1. The bean id naming convention is strict:
  2. It must start with keyword webscript, thus Alfresco comes to know that this bean is a web script implementation bean
  3. The further name parts should match the web script package and web script name
  4. The class name should exactly match with the name of the web script along with its package
  5. The parent should always be webscript, since the implementation class is a web script.

Step 7: Start Server: Test your Web Script
That’s it, is everything goes fine, you have just created your first Java based custom web script.
  • Start tomcat server
  • In your favourite browser, navigate to http://localhost:8080/alfresco/service/index. Find your web script and test whether it is working.

In the next installment of this tutorial, we will discuss about how we can deploy the web script as a JSR-168 portlet in Liferay.

Happy Scripting!!!