Felipe Cypriano

Grails with ZK: How To Create Components in Runtime with The Builder

Felipe Cypriano — Thu, 04 Mar 2010 14:42:30 +0000

ZKGrails plugin has an extremely nice feature which make easier than ever to create ZK components in runtime.

First lets see how is the usual way to create components in runtime using Java. This is the zul representation of what we’re trying to achieve:

And the java code to do the same:

Div div = new Div();
Toolbarbutton tbb = new Toolbarbutton("Clickable Item");
tbb.setHref("#");
tbb.setParent(div);
if (userHasAccess) {
    Toolbarbutton tbbEdit = new Toolbarbutton();
    tbbEdit.setImage("edit.png");
    tbbEdit.setParent(div);
    Toolbarbutton tbbDelete = new Toolbarbutton();
    tbbDelete.setImage("delete.png");
    tbbDelete.setParent(div);
}

As you can easily see the java code is pretty verbose. Using ZKBuilder the code will be easier to understand and smaller, take a look:

Div div = new Div();
div.append {
    toolbarbutton(label: "Clickable Item", href: "#")
    if (userHasAccess) {
        toolbarbutton(image: "edit.png")
        toolbarbutton(image: "delete.png")
    }
}

Which one do your prefer? If you want more continue reading to see how to use the builder as a template to a list of items.

Using ZKBuilder as a Template

I think the builder is specially useful when I’ve a list of items and I need to display these items with a specific layout one that the grid nor the listbox can provide. So I start as I started this post making the layout on a zul page and after I get what I want, I made a ZKBuilder version and put it in a loop to execute for each item I need to show.

// ...
def items = myService.getItems()
items.each { item ->
    div.append {
        toolbarbutton(label: item.name, href:  item.link)
        if (userHasAccess) {
            toolbarbutton(image: "edit.png", onClick: {editItem item})
            toolbarbutton(image: "delete.png", onClick: {deleteItem item})
        }
    }
}
//...
public def editItem(def item) { /* code to edit the item */}
public def deletetem(def item) { /* code to delete the item */}

ZkBuilder is bundled in ZKGrails 0.7.6 and earlier. Enjoy!

Handling events on ZK macro components

Felipe Cypriano — Fri, 15 Jan 2010 10:41:55 +0000

One of the great features of ZK is the possibility to create a new component based only on other existing components using the declarative language ZUML - the same you've been using in you zul files. Those are called Macro Components. The beauty of macro components is that it's very easy to make a new one and hence avoid code duplication on your pages.

Talk about how to implement a macro component isn't the scope of this post, so I suggest you to read the documentation before continue reading.

We'll work on a very simple macro component. But, don't hesitate when you need to make a very complex one. Our macro component is this: WEB-INF/mymacro.zul

Now that you already knows what is and how to make a macro component, let's start talking about what you may think it'll work but actually it doesn't.

Automatically Forward Event Doesn't Work

The standard way to register events on ZK's component, using MVC, is to use the "autowire" feature of GenericForwardComposer. Like this:

WEB-INF/index.zul

src/com/felipecypriano/IndexComposer.java

package com.felipecypriano;

import org.zkoss.zk.ui.util.GenericForwardComposer;
import org.zkoss.zul.Label;

public class IndexComposer extends GenericForwardComposer {
    private Label lblOutside;

    public void onClick$btnOutside() {
        lblOutside.setValue("Button 'not in macro' clicked");
    }
}

The button 'btnOutside' belongs to the window component and therefore its composer can automatically access and configure btnOutside events. When the Composer is initializing it detects the method onClick$btnOutside() and sets this method as a 'btnOutside' onClick event listener, in other words when the component is clicked this method is executed.

Knowing this we can think that add an event to 'myButton', which belongs to 'mymacro', is pretty much the same. Don't we? Let's add the macro in the index.zul and create a new method to handle onClick event of 'myButton':

WEB-INF/index.zul

Just before tag is the macro component definition (line 2), this directive tells to ZK where is the file that contains the component - macroURI="/mymacro.zul" - and what's the tag name we'll use - name="mymacro" - to reference our component (line 8).

Adding the onClick event on 'myButton' cannot be done by just adding this method to IndexComposer:

src/com/felipecypriano/IndexComposer.java

    public void onClick$myButton() {
        lblOutside.setValue("Button 'myButton' clicked");
    }

So, if this doesn't work what should I do?

Using a Speciliazed Class

To take care of mymacro's behavior we need to write some code. We need to create a class to specifically handle our component's needs. The purpose of mymacro component is to update the label when the button is clicked, this will not affect any of the components that doesn't belong to mymacro so it makes sense to put the event in a specialized class that can be used to all pages.

The two components inside the macro - label and button - will be accessed using getFellow(string) method and the event will be dynamically added to the button using addEventListener method.

src/com/felipecypriano/MyMacro.java

package com.felipecypriano;

import org.zkoss.zk.ui.HtmlMacroComponent;
import org.zkoss.zk.ui.event.*;
import org.zkoss.zul.*;

public class MyMacro extends HtmlMacroComponent {
    private Label myLabel;

    @Override
    public void afterCompose() {
        super.afterCompose(); // DON'T forget this
        Button myButton = (Button) getFellow("myButton");
        myLabel = (Label) getFellow("myLabel");

        myButton.addEventListener(Events.ON_CLICK, new EventListener() {
            public void onEvent(Event event) throws Exception {
                myLabel.setValue("Hooray! 'myButton' was clicked.");
            }
        });
    }
}

Now change the component's definition to point to MyMacro.java as the component's class:

Voilà.

Global Component Definition

There's a DRY principle violation and we must solve it. The main reason to use a macro component is to share a set of components between multiple pages, to avoid code duplication. The macro itself does this, but if you pay attention you'll see that the component's definition must be at the very beginning of each page which wants to use the component and this, definitely, isn't a good a thing.

For instance, supposing that you have 25 pages that are currently using the macro component, and in each one of them has the component's definition. Some months later, for some reason, you must change yours component's class. Instead of changing just one simple place you'll have to update 24 more places. Keep your code simple and don't repeat anything.

In order to make the component's definition global we need to create a new xml file called lang-addon.xml:

WEB-INF/lang-addon.xml


    myaddon
    xul/html
    
        mymacro
        com.felipecypriano.MyMacro
        /mymacro.zul

WEB-INF/zml.xml


    
        /WEB-INF/lang-addon.xml

And at last, remove directive from index.zul. From now on mymacro component is available to all zul pages in your application.

Making the macro component shout to the world

Just one more detail to learn, the component can handle its own components events, but how do the page that has the macro component knows what's going on? We need to make the macro component send events to the page, or any listener. And this is the our final step.

To keep it simple the macro component will respond just to onClick event, that's when the button is clicked 'myLabel' will be update as usual and the macro component will send the onClick event to all its listeners. Replace myButton EventListener with the following code:

src/com/felipecypriano/MyMacro.java

myButton.addEventListener(Events.ON_CLICK, new EventListener() {
    public void onEvent(Event event) throws Exception {
        myLabel.setValue("Hooray! 'myButton' was clicked.");

        if (isListenerAvailable("onClick", true)) {
            Event clicked = new Event(Events.ON_CLICK, getParent());

            Iterator listeners = getListenerIterator(Events.ON_CLICK);
            while (listeners.hasNext()) {
                EventListener listener = (EventListener) listeners.next();
                listener.onEvent(clicked);
            }
        }
    }
});

The code between lines 5 and 13 is responsible to send the event to the listeners. But we need a couple more changes, like make IndexComposer listen to mymacro. First put an id in mymacro:

WEB-INF/index.zul

And register the event using the standard way in IndexComposer:

    public void onClick$mymacro() {
        lblOutside.setValue("I can hear you 'mymacro'!");
    }

With all this it's possible to do complex and incredible powerful macro components. Go ahead and try.

Grails with ZK: Embedding ZUL in GSP

Felipe Cypriano — Thu, 10 Dec 2009 17:31:54 +0000

How about zk pages and gsp were so friends that we could use both together? Imagine the possibility to use Sitemesh to decorate your page or use UrlMapping to choose what the URL will be. Or you could move your project to ZK painlessly, you could update the pages one by one and the new code will work side by side.

ZKGrails plugin 0.7.6 has been released with this great new feature, you can use two simple tags to include any zul page in your GSP. To include the necessary css and javascript into head use and to insert the content anywhre you want in the body of your gsp you'll use .

To see it in practice let's change Grails Quick Start. Follow the steps described there and after you complete all the steps, go back here to update the list.gsp to use ZK Grid component. Don't forget to use Grails 1.1.2 and ZKGrails 0.7.6 at least.

Embedding ZK in GSP

Firstly create this file: grails-app/conf/BuildConfig.groovy and configure ZKGrails repository:

grails.plugin.repos.discovery.zkgrails = "http://zkgrails.googlecode.com/svn/plugins"
grails.plugin.repos.resolveOrder = ['zkgrails','default','core']

Now you can install ZKGrails version 0.7.6 by executing grails install-plugin zk 0.7.6. After installing ZK plugin, create the zul page we'll use: web-app/book/list.zul. You can let this file blank for now, before editing it we need to change automatic scaffolding by creating the the gsp pages executing this command:

grails generate-views Book

The command will create 4 gsp files in grails-app/views/book: create.gsp, edit.gsp, list.gsp and show.gsp. We will change the list.gsp to instead of use simple HTML table we'll use ZK components. Now let's get back to our web-app/book/list.zul, the objective is to create a grid using zk components and to add a new functionality to delete all selected books. Open list.zul file and put the following code in it:

Next step is create the composer for this list.zul page, the composer is the thing that controls the page's behavior, just like a controller. Create a BookListComposer.groovy file in grails-app/composers, and this is the content:

import org.zkoss.zkgrails.*
import org.zkoss.zkplus.databind.BindingListModelList

class BookListComposer extends GrailsComposer {

    def wnd
    def listBoxBooks
    def booksModel
    def binder

    def afterCompose = {
        booksModel = new BindingListModelList([], true)
        reloadBooks()
        binder = wnd.getVariable("binder", true)
    }

    public void onClick_btnDelete() {
        if (listBoxBooks.selectedCount > 0) {
            listBoxBooks.selectedItems.each { listItem ->
                def book = listItem.value
                book.delete(flush: true)
            }
            reloadBooks()
        }
    }

    private def reloadBooks() {
        def books = Book.list()
        booksModel.clear()
        booksModel.addAll(books)
        binder?.loadAll()
    }

}

Now we only need to put the zul page in the list.gsp replacing the HTML

tag to , the final code is this:


    
        
        
        
        Book List
    
    
        
            Home
            New Book
        
        
            Book List
            
            ${flash.message}

As you can see - lines 5 and 19 - we only need to put the tags where we want it's content to be in the page. But you might be wondering where is the path to list.zul file? By default the same convention used by Grails' view, so for our example both tags - head and body - automatically resolves to /book/list.zul. And if you need to specify the files you want you can by setting the attribute zul, like:

Now we can mashup our both favorite frameworks to make our projects look and behave even better.

# Update 1

Fixed a missing namespace on zul file; and the binder call on BookListComposer. Thanks André.

# Update 2

GitHub repository with full source code used to made this post: http://github.com/fmcypriano/embedding-zul-gsp

Grails with ZK: Where are my Controllers?

Felipe Cypriano — Thu, 19 Nov 2009 20:37:31 +0000

ZK's zul pages works very differently compared to Grails' gsp pages but they have one thing in common both have a class to control the page's state, the behavior of each piece, the data that is showed or is being inserted by the user and this class is called Composer and Controller respectively. This is the second article about my work with ZK and Grails, read the first part before reading this one to get an overview: Grails with ZK Understanding Both Together.

"A [grails] controller handles requests and creates or prepares the response. They can generate the response or delegate to a view.", this is the definition taken from grails website. In other words the controller receives a request do what it has to do and sends the response back.

ZK's composers are a little different, they can do things that you'd need javascript to do using gsp and controllers. The main power of a controller is that you've full control of all components in the page without need to write any javascript code. You could add or remove any component dynamically from the page, register events and whatever more you java and groovy skills let's you do.

Pages Shouldn't Have Any Code

In both technologies you can embed code directly in the page, in gsp you can use scriptlets:

<% items.each {
    total = it.quantity * it.price
}%>

An in zul pages you can use zkscript tags:


    items.each {
        total = it.quantity * it.price
    }

It's fairly easy to use code inside the pages and I really do believe you shouldn't do this, it makes your code harder to read and a mess to maintain.

The only places where this kind of code is good is in tutorials and that's why you'll see lots of tutorials using it, but in your actual project the composer/controller should do this job always.

Your First Composer

To demonstrate what a composer does lets create a simple editable page. The page will show a text to the user an the user can click on some buttons to change the text. All the actions will happen without refresh and you won't need to write any javascript.

Create a file named editable.zul in <your-project>/web-app/ with this content:

/web-app/editable.zul

Pay attention to the id attribute it's value will be used in the composer to get the java object corresponding to the component. We create an empty div called 'divText' just to make sure where the text will be in: at the top, before the buttons.

Now let's go to the composer - hooray finally eh -. Create a new directory in grails-app folder called composers and inside this new directory create a file called EditableComposer.groovy.

grails-app/composers/EditableComposer.groovy

import org.zkoss.zkgrails.GrailsComposer
import org.zkoss.zul.*
import org.zkforge.fckez.FCKeditor

class EditableComposer extends GrailsComposer {
    def divText
    def btnEdit
    Button btnSave
    def btnCancel

    FCKeditor editor
    String text

    def afterCompose = {
        // This is code execute just after all the components are created, so you can access them safely
        showText()
        viewMode true
    }

    void onClick_btnEdit() {
        if (!editor) {
            editor = new FCKeditor()
        }
        editor.value = text

        divText.children.clear()
        divText.appendChild editor

        viewMode false
    }

    void onClick_btnSave() {
        text = editor.value
        showText()
        viewMode true
    }

    void onClick_btnCancel() {
        showText()
        viewMode true
    }

    private def showText() {
        text = text ?: "This is my first Composer"

        divText.children.clear()
        divText.appendChild new Html(content: text)
    }

    private def viewMode = { isViewing ->
        btnEdit.visible = isViewing
        btnSave.visible = !btnEdit.visible
        btnCancel.visible = btnSave.visible
    }
}

The components in zul are injected in composer's attributes with the same name as the id on zul file. On line 8 we use a specific type to declare the btnSave, this is just to show you that for each component in zul there's a corresponding java class where you can access and/or change all the attributes. You don't need to worry about thread safety here because for each accessed page a new composer is instantiated, this commonly known as prototype scope.

The afterCompose closure - lines 14 through 18 - is execute just after all the components declared in the zul are created and ready to use, here is the right place to put all your initialization code.

One of the features that I really like is how we can declare events to each component. As you can see in lines 20, 32 and 38 we've declared events to listen to the user clicks on the button for each of the 3 buttons. Basically this is how you declared all kinds events for all components:

public void onEventName_componentId(Event event)

Before the underscore character is the event name and after is the component id. You can set events even for components that you didn't declared as composers attributes.

You don't need to worry about javascript to change the state in the client-side ZK will handle it for you, just change the attributes values in your groovy code and you're done. I highly recommend you give ZK a try and start playing with it, if the application you're developing fits this desktop like model ZK is a great framework to boost your productivity.

See Also:

Grails with ZK Understanding Both Together

Felipe Cypriano — Sat, 07 Nov 2009 22:38:30 +0000

You may already know both technologies but I'll briefly introduce them. Grails is the best web framework that I ever work with, it uses Groovy and convention over configuration to simplify our development efforts. To name a few this is what you've out-of-the-box: persistence layer to save your entities to a relational database, dependency injection, lots and lots of great plugins and GSP to build the view.

If Grails is so complete why do I need another framework and why ZK? I'm building an enterprise web app which means it will be used by users of a company to do daily tasks, I needed a more responsiveness app without refresh and without increase the effort of getting it done. Searching for a solution I consider mainly this two frameworks: ExtJS, beautiful interface and a bunch of built-in components but you've to deal with javascript; GWT clever javascript compilation from Java code, but only a few built-in components and build interfaces using only java code isn't a pleasant work for me.

ZK Direct RIA is bundled with lots of very useful built-in components, you can build your pages using a declarative syntax like XHTML or using Java code, since we'll use Grails we can use Groovy to simplify the java code. Your code is processed on the server and because of this you can use your classes without any modifications, all your classes groovy or java will work as is in ZK no modification is need.

ZK will be responsible to render and process the events of the view layer (the pages), the main difference compared to standard Grails is that instead of use Controllers and gsp files you'll use Composers and zul files. It doesn't mean that you can't use Controllers nor gsp anymore you can mix both without problems. From a gsp page you can go to a zul page, and there is no secret just link one to another with an tag, for example. And it's possible to share objects between the pages as well, using Services, zkgrails plugin's Facade or with your own spring bean.

This is the first of a series of articles I'll write about my experience working with Grails and ZK. Now I'll show a very simple example of how to start using both and what we gain using both in the same project. First of all create a new grails project and install zk plugin:

$ cd 
$ grails create-app grails-and-zk-app1
    ...
    Created Grails Application at /grails-and-zk-app1
$ cd grails-and-zk-app1
$ grails install-plugin zk 0.7.4
    ....
    Plugin zk-0.7.4 installed
    Plug-in provides the following new scripts:
    ------------------------------------------
    grails create-composer
    grails create-facade
    grails create-zul

Your project is now created and configured to use ZK. Now I'll show you how easy is to build an rich interface with ZK and Grails, create the zul file:

$ grails create-zul myFirstZkPage

This will create two files the page and it's Composer, remember the composer is the ZK controller.

Created by create-zul myFirstZkPage command

The plugin creates the files with a Hello World page ready to work. Execute it to see it running:

$ grails run-app

Open this url in your browser http://localhost:8080/grails-and-zk-app1/myFirstZkPage.zul. Write a text inside the text box and click on "Hello" button and a greeting text will be show. This is very simple but the implementation shows some cool features, let's see them.

This is the page grails-and-zk/web-app/myFirstZkPage.zul, the language is called ZUML it's a markup language to build rich interfaces every component (some tags) here has it's own Java class so you can use them in your code without any problems:

On line 11, the apply attribute tells ZK which class is the Composer of the Window component it expects the class' full qualified name. Hum, what is being passed to apply doesn't look like any full qualified name. Yes it isn't, apply="${myFirstZkPageComposer}" is an EL expression which is resolved to the Spring Bean named "myFirstZkPageComposer" and this bean is, as you can easily guess: grails-app/composers/MyFirstZkPageComposer.groovy, cool eh. Every class in composers directory which ends with "Composer" will be automatically a spring bean.

Inside the window we've three components with an id setted (lines 17, 21 and 26), looking the composer's code we can see that for each of this three components there's one attribute with the same name:

import org.zkoss.zkgrails.*

class MyFirstZkPageComposer extends GrailsComposer {

    def txtName
    def btnHello
    def lstResult

    def myFirstZkPageFacade

    def onClick_btnHello() {
        lstResult.clear()
        lstResult.append {
            listitem { listcell { label(value: "Hello, ${txtName.value} !") } }
        }
    }

    def afterCompose = { c ->
        // initialize component here
    }
}

This mean you've full access of this components own's attributes you can read and write it's values. For example, try to add this new line at the end of onClick_btnHello method and save it:

btnHello.label = "Hello There!"

Run the app an see what happens when you click the Hello button. Play with the code to see what more you can do. To learn more about ZK I recommend you to read the documentation page specially the Developer's Guide and Developer's Reference. Use your curiosity to make great things

In the next articles I'll enter in more details.

# Update 1

ZK with Grails: Where are my controllers? Learn what is and how to use ZK Composers.

Tweak ZK to make event processing call groovy’s invokeMethod

Felipe Cypriano — Mon, 26 Oct 2009 11:32:50 +0000

My current project needs a very dynamic and fast pages without refreshs, or using the buzz word ajax, to accomplish this requirement I'm using ZK Direct RIA. As ZK heavily uses ajax requests with unpredictable url I need another way to protect the controller's actions (composer's method) instead of url. Using @Secured and groovy's invokeMethod I was able to protect each method of any class (please read the post to get a better picture of what I'll discuss) which works fines if the method call is from a groovy code, ZK is fully implemented in java though.

When a user clicks on a button, or does anything that generates events, zk process it and call the corresponding method in the composer class. ZK events processing executes this code when it find the method to call:

mtd.invoke(controller, new Object[] {evt});

This uses Java Reflection API and completely bypass groovy's invokeMethod, what we need to do is use groovy's InvokerHelper class instead of direct calling the method using reflection.

InvokerHelper.invokeMethod(controller, mtd.getName(), new Object[] {params});

Now that we know how to do it for any kind of java code let's dig into the problem with ZK event and find out where we should use InvokerHelper.

Implementing InvokerHelper in GrailsComposer

The GrailsComposer in ZKGrails plugin is a subclass of GenericForwardComposer that changes the default char separator from '$' to '_', because groovy already uses the '$' with another meaning, and allows the use of a closure as the doAfterCompose method. So when you create a new composer using grails create-composer your new class extends GrailsComposer. Let's create a composer and protect two of it's buttons.

import org.springframework.security.annotation.Secured
class MainAreaComposer extends GrailsComposer {
    private Button btnEditText // automatically wired from the zul file
    private Button btnSaveText
    private Button btnCancelText

    def afterCompose = {
        // loads the current text
    }

    @Secured("mainArea_editText")
    public void onClick_btnEditText() {
        // shows the rich text editor to edit the text
        btnSaveText.visible = true
        btnCancelText.visible = btnSaveText.visible
        btnEditText.visible = false
    }

    @Secured("mainArea_editText")
    public void onClick_btnSaveText() {
        // saves the text, hide the editor and load the new text
         btnSaveText.visible = false
         btnCancelText.visible = btnSaveText.visible
         btnEditText.visible = true
    }

    public void onClick_btnCancelText(){
         // hide the editor and loads the text without any modifications
    }
}

The idea here is that only some users have access to edit the text. ZK is fully ajax based and every event cames from client through javascript request. Because of this even if the btnEditText is invisible a malicious users could forge a request to call the method - not easy, but possible - the use of @Secured is to assure that an attempt to call this method from an unauthorized user will fail.

If you run your app using ZKGrails 0.7.5, the current version for Grails 1.1.1, and test if an unauthorized user fails when call the method - just make the button always visible to test - you will see that nothing is blocked no AccessDeniedException is thrown, and of course this isn't good. Humm, and how could we solve this? How to make zk event handling aware of the dynamic methods?

My first thought was "ZK is open source, what about reading it's code to understand the event system?" and there I go, downloaded the source and start reading how ZK maps the methods name to components event, in other words how it does this magic:

public void onClick_btnCancelText() {// event code}

The above method is the same as the not so nice:

btnCancelText.addEventListener("onClick", {// event code} as EventListener)

Reading the source code I find out that this kind of event is a ForwardEvent but I couldn't find where the original method is called until I look the class diagram for GrailsComposer:

GrailsComposer class hierarchy

And there was the solution GenericEventListener onEvent method, I've finally found where the original method (onClick_componentId) is invoked and now we just need to override onEvent in GrailsComposer, this is the implementation:
org/zkoss/zkgrails/GrailsComposer.java

    /**
     * Overrides GenericEventListener to use InvokerHelper to call methods. Because of this the events are now
     * part of groovy's dynamic methods, e.g. metaClass.invokeMethod works for event methods.
     * @param evt
     * @throws Exception
     */
    @Override
	public void onEvent(Event evt) throws Exception {
		final Object controller = getController();
		final Method mtd =	ComponentsCtrl.getEventMethod(controller.getClass(), evt.getName());
		if (mtd != null) {
			if (mtd.getParameterTypes().length == 0) {
                InvokerHelper.invokeMethod(controller, mtd.getName(), null);
            } else if (evt instanceof ForwardEvent) { //ForwardEvent
				final Class paramcls = (Class) mtd.getParameterTypes()[0];
				//paramcls is ForwardEvent || Event
				if (ForwardEvent.class.isAssignableFrom(paramcls)
				|| Event.class.equals(paramcls)) {
                    InvokerHelper.invokeMethod(controller, mtd.getName(), new Object[] {evt});
				} else {
					do {
						evt = ((ForwardEvent)evt).getOrigin();
					} while(evt instanceof ForwardEvent);
                    InvokerHelper.invokeMethod(controller, mtd.getName(), new Object[] {evt});
				}
			} else {
                InvokerHelper.invokeMethod(controller, mtd.getName(), new Object[] {evt});
            }
		}
	}

Just replacing method.invoke to InvokerHelper.invokeMethod (lines 13, 19, 24 and 27) is enough to make the methods actually secured. Open your GrailsComposer class and add this method to the class, this is all you need to do. If you don't understand how the @Secured is now working, read the previous post which is about the implementation of @Secured.

I've submitted this as a patch to Chanwit, the plugin's maintainer, and ZKGrails 1.0 will have this overridin onEvent out-of-the-box. No need to change the plugin source code anymore, great news.

Enable @Secured annotation with Grails Spring Security plugin

Felipe Cypriano — Mon, 19 Oct 2009 20:46:15 +0000

How could I protect each method of my classes? Using Spring Security it should be easy, right? After a quick search I realize that the best way is to use @Secured annotation, good! Another issue fixed. But as life isn't fun without problems to solve it didn't work as expected.

The problem started because grails acegi plugin, in version 0.5.2, doesn't support this annotation.Talking about this in grail user mailing list Benjamin Doerr gave me a nice idea: use groovy's invokeMethod to add the support that I needed.

The idea is to use groovy meta magic to add behavior to the classes that have at least one method annotated, we well override the metaClass.invokeMethod of the class we want to enable the annotation. To keep things organized I create a new boot strap file in grail-app/conf/SecurityBootStrap.groovy and all the related code is place in this file.

First off all let's create a closure that can be used to override invokeMethod of any class:

    def verifyMethodAccess = {String name, args ->
        def method = delegate.metaClass.getMetaMethod(name, args)
        def logMsg = new StringBuilder("invoking ${method}, ")
        if (method) {
            def annotation = method.cachedMethod.getAnnotation(Secured)
            logMsg += "is @Secured ${annotation != null}"
            if (annotation) {
                def annotationValue = annotation.value()?.toString()?.replaceAll(~/[\[-\]]/, '') // remove [ and ]
                logMsg += " by ${annotationValue}"
                if (!authenticateService?.ifAnyGranted(annotationValue)) {
                    log.debug logMsg.toString()
                    throw new AccessDeniedException("Access denied to ${delegate.class.simpleName}.${name} from user ${authenticateService.principal()?.username}")
                }
            }
            log.debug logMsg.toString()
            return method.invoke(delegate, args)
        }

        log.error "Method ${delegate.class.simpleName}.${name} not found"
        return null
    }

In a glance this closure gets the method that is been invoked and verifies if this method is annotated with @Secured annotation, if it does then the granted authorities passed to the annotation's value is obtained - line 8 - and is passed to the authenticationService if the current user has access the method is invoked otherwise an AccessDeniedException is thrown.

To active this behavior in a class we only need to override it's metaClass.invokeMethod:

import org.springframework.security.annotation.Secured
import org.springframework.security.AccessDeniedException

public class SecurityBootStrap {
    def init = {servletContext ->
        ClassifiedClass.metaClass.invokeMethod = verifyMethodAccess
    }
    // verifyMethodAccess declaration and body goes here
}

To complete the example this is the ClassifiedClass:

public class ClassifiedClass {
    @Secured("ROLE_PRESIDENT")
    String protectedMethod() {
        "I'm a top classified information!"
    }

    def ordinaryMethod() {
        "Anyone can call me."
    }
}

Every time a groovy code calls any method of ClassifiedClass it's metaClass.invokeMethod will be executed before the actual method. Just pay attention to use the same Secured annotation in your class and in SecurityBootStrap.

Unfortunately this solution only works if the call came from groovy code, if any java code calls classifiedObj.protectedMethod() it will succeed even without permission. Java code completely ignores the invokeMethod. Now stop thinking that you read all of this for nothing, because on next post I'll talk about using InvokerHelper class to make java code obey the law.

# Update 1

Read this post to see how to make java code be aware of groovy's dynamic method, including invokeMethod.

Customizing SpringSecurity to protect each button of a page using Grails Acegi plugin

Felipe Cypriano — Wed, 14 Oct 2009 22:36:57 +0000

I'm very happy with grails acegi plugin, aka Spring Security Plugin, but on my newest project I needed a finner grained way to do control access than using simple urls filters and roles.

I wanted a way to control which button, link, action of the current page the user can access. If the user has only read access to a page than the page is shown but edit action isn't, because of this requirement using only roles to grant access isn't enough and could easily became a mess if I create one role per action. Use urls filters won't work because most urls are generated by ZK framework and hence are non predictable.

The solution is fully based on SpringSecurity capabilities and should work on every project that uses it independent of plugins or frameworks that I use. Since spring security plugin does the hard work for us, we just need to create two more classes besides acegi's default user and role and extends UserDetailsService interface. This is based on zk_sample project and is a database implementation of this article by Oleg Zhurakousky.

The database schema

The plugin needs User and Role class by default, to extend (not meaning inheritance) them I create two new classes to add more control over which resource can be accessed namely: Group and Access. The Group class purpose is only to organize the Access, since there will be a lot of them. It's important to notice that the access' name and the role's authority must be unique.

User, Role, Group and Access class diagram

With this classes we can create roles that contains a list of granted accesses, for instance:

ROLE_ADMIN
- pagePolicy.btnNew
- pagePolicy.btnSave
- pagePolicy.btnDelete
ROLE_ORDINARY
- pagePolicy.btnNew

With our granted access setup in database we need to teach spring security how to authorize an access based on the access name:

authenticateService.ifAllGranted "ROLE_ADMIN" //  works out of the box
authenticateService.ifAllGranted "pagePolicy.btnNew" //  don't work

The goal is to make both options works, to do this we need to provide a custom implementation of UserDetailsService which will load to the UserDetails object both roles and accesses as GrantedAuthority. Let's customize spring security and extend GrailsDAOImpl to add our logic:

src/groovy/HierachyUserDetailsService.groovy

public class HierachyUserDetailsService extends GrailsDaoImpl {
    protected GrantedAuthority[] loadAuthorities(user, String username, boolean loadRoles) {
        if (!loadRoles) {
        	return []
        }

        def accessCriteria = Access.createCriteria()
        // get all the accesses for this user
        def accesses = accessCriteria.list {
            authorizedGroups {
                authorizedRoles {
                    users {
                        eq("login", username)
                    }
                }
            }
        }

        // now we iterate over the accesses to get the roles associated to each access
        def allAuthorities = [] as Set
        accesses.each { access ->
            def roles = [] as Set
            access. authorizedGroups*. authorizedRoles*.each { role ->
                roles << new GrantedAuthorityImpl(role.authorityValue)
            }

            allAuthorities.addAll(roles)
            allAuthorities << new AccessGrantedAuthority(access.name, roles)
        }
        log.debug "Authorities for user ${username}: ${allAuthorities}"

        return allAuthorities as GrantedAuthority[]
    }
}

GrailsDaoImpl already implements UserDetailsService interface and provide a very good set of methods we just need to override one of them to achieve our goal. Great.

The AccessGrantedAuthority (line 28) is just to make it easier to debug from which role the access came from. See the log debug output using this class:

Authorities for user admin: [ROLE_ADMIN, ROLE_ORDINARY, pagePolicy.btnNew[ROLE_ADMIN, ROLE_ORDINARY], pagePolicy.btnSave[ROLE_ADMIN], pagePolicy.btnDelete[ROLE_ADMIN]]

If don't want this information you could use the default implementation, GrantedAuthorityImpl as in line 24.

Now that we have our implementation the last step is to configure our implementation as the current implementation used by Spring Security:

grails-app/conf/spring/resources.groovy

import org.codehaus.groovy.grails.plugins.springsecurity.AuthorizeTools
beans = {
    // Spring Security
    def securityConf = AuthorizeTools.securityConfig.security
    userDetailsService(br.com.litoraltextil.vc.springsecurity.AuthorityHierachyUserDetailsService) {
        usernameFieldName = securityConf.userName
        passwordFieldName = securityConf.password
        enabledFieldName = securityConf.enabled
        authorityFieldName = securityConf.authorityField
        loginUserDomainClass = securityConf.loginUserDomainClass
        relationalAuthoritiesField = securityConf.relationalAuthorities
        authoritiesMethodName = securityConf.getAuthoritiesMethod
        sessionFactory = ref('sessionFactory')
        authenticateService = ref("authenticateService")
    }
}

As a full configuration of spring security plugin isn't the focus of this post I suggest you to read how to customize the plugin using SecurityConfig.

Finally we can use all the artifacts using both the role name or the access name, some examples:

secure stuff here
secure stuff using both

Solving Grails/GORM data truncation error on blob column using Java

Felipe Cypriano — Fri, 09 Oct 2009 21:33:27 +0000

Today GORM was in a bad mood and refuses to insert a text in a blob (clob) column. If a set a non null value in the attribute which was mapped to a blob field I end up with this strange error:

Caused by: java.sql.DataTruncation: Data truncation

Data truncation for a blob column makes no sense since blobs are made to handle large amount of data, as far as I know the limit is your storage space.

What I needed was an improved version of the Setting class that cames with settings plugin, I wanted to store large texts in some settings, larger the 100 characters which is the current limit, so I create a new attribute to store large texts, this new attribute is a blob in the dabase.

Here is the new grails domain class that I created:

grails-app/domain/Setting.groovy

class Setting {
    String code
    String content
    String largeText

    static constraint {
        code(length: 100)
        content(length: 255)
    }
    static mapping {
         largeText type: “text”
    }

    public static final String LARGE_TEXT = “large_text”
    public String getContent(){
       content != LARGE_TEXT ? content : largeText
    }

    public void setContent(String value) {
        if (value && value.size() > 255) {
            this.content = LARGE_TEXT
            largeText = value
        } else {
            this.content = value
            largeText = null
        }
    }
}

This is the logic behind the class, very simple and effective. The problem begun when I set a content bigger than 255 characters and call save()... boom java.sql.DataTruncation.

After searching for a solution, and asking in the mailing list, I don’t find an answer. So I decide to make the mapping the way I was sure it works: using annotations and POJO. Then I create a java class instead of a groovy one, obvious parts are omitted:

src/java/entity/Setting.java

package entity;
// don’t forget the imports
@Entity
public class Setting implements Serializable {
    @Column(length = 100, unique = true)
    private String code;
    @Column(length = 255)
    private String content;
    @Lob
    private String largeText;

    // Getters and setters, the ones for content are identical the groovy version
}

Ok, the POJO is here but how will it work with grails and all its great features, like dynamic finders?

It’s very simple just tell Hibernate, which is under the hood in Grails, that you want to map the Setting class. Open the file grails-app/conf/hibernate/hibernate.cfg.xml and configure it like this:

And voilà your POJO is now a full-blown Grails domain class. For now on you can call the dynamic finders, save method and everything:

Setting.findByCode(“your.setting”)
settingObj.save()

This is how I solved a problem with GORM and blob columns. I belive that I need to do all this because of the database I'm using in this project, which is Firebid 2.1. After all what matters is how great is groovy/grails integration with plain java.