Introduction to plugin development#
This page covers basic notions required for Gluu Casa plugin development. In practice, writing plugins is easy but requires understanding of some key concepts. If you skip the background part and proceed straight to Writing your first plugin, it is quite likely you will get bounced here very soon.
Requirements and tools#
A Gluu Server VM#
For development, you need a virtual machine with Gluu Server installed as well as the client software that may allow you to run (play) the machine. Recall Gluu Server installation is constrained to a number of Linux distributions. The Gluu server version used should match that of the machines you are targetting for production environment.
Ideally, you should populate your Gluu Server with data (e.g. users/groups) to somewhat resemble a testing or production server of your organization. Writing a plugin to be run on a server with no users other than admin will lead to very poor testing scenarios.
Ask your administrator for help on preparing your virtual machine. It is likely they already have one available for immediate use. Check the CE docs for instructions on how to install Gluu Server from scratch if you need to do so.
Ensure you have credentials for a user with administrator privileges in your Gluu Server as well as in the VM (e.g root). Ensure you can connect to that VM via SSH with a client and that your can transfer files.
A running Gluu Casa installation#
Once you are up and running with a Gluu Server VM proceed to install Gluu Casa. Ensure you can log in to Casa when finished.
Change file check period#
By default .zul templates are cached for a very long period, however, for development we need to change this. Do the following:
- Connect to your VM and log in to Gluu chroot (e.g.
service gluu-server-3.1.6 login)
- Extract ZK descriptor:
# cd /opt/gluu/jetty/casa/webapps # jar -xf casa.war WEB-INF/zk.xml
- Locate XML tag
file-check-periodand remove it including its surrounding parent
- Save the file and patch application war:
# jar -uf casa.war WEB-INF/zk.xml
- Restart Casa (
service casa restart)
The above guarantees changes in .zul files are picked very often (5 seconds is default ZK cache refresh time).
Find a graphical LDAP client#
Ensure you can use a GUI client in order to connect to your LDAP. While all sort of operations on the directory can be achieved with the tools already bundled in the Gluu Server chroot container, the only means to have an agile development experience is leveraging a point-and-click tool.
Two graphical clients worth mentioning are LDAP Admin and Apache DS. Ask your administrator how to setup a connection from the client running on your desktop to Gluu container's LDAP or follow these instructions.
In case you cannot establish the tunnel mentioned in the docs you can do this:
If your Gluu Server is backed by OpenLDAP:
- Open port 1636 in your VM firewall
- Restart LDAP (
service solserver restart)
If your Gluu Server is backed by OpenDJ:
/opt/opendj/bin/dsconfig -h localhost -p 4444 -D "cn=directory manager" -w PASSWORD -n set-connection-handler-prop --handler-name="LDAPS Connection Handler" --set listen-address:0.0.0.0 -Xin chroot
- Open port 1636 in your VM firewall
- Restart LDAP (
service opendj restart)
It is advisable to get some basic acquaintance with the structure of Gluu's LDAP. We suggest doing a quick introductory reading about LDAP (you'll find many articles in the Internet) if your plugins needs to access or store information from the directory. Ensure you get the basic grasp of the following concepts:
- DN and RDN
- Search filters (optional)
Java coding skills are a must and basic-to-intermediate knowledge of web applications is desirable. Previous knowledge of the UI framework or the plugin framework are not required but readers will likely need to glance at both when the time for coding comes.
In theory, any other language supported in the JVM such as Scala or Groovy may work, however at Gluu we haven't experimented with those. Feel free to create a Github project and share with us.
IDE and building tools#
You can use the tools of your choosing as long as you can produce fat (Uber) jars, which is the from in which Gluu Casa plugins are delivered. In the following pages, we will use command line interface (CLI) and Maven 3 as build tool.
LDAP SDK For Java#
Plugins will likely require reading and writing data from and to the underlying Gluu Server lightweight directory. There is one Java library (part of Gluu casa project) called
casa-shared at developers disposal which abstracts and simplifies access to LDAP (basically CRUD operations). Manipulation of this abstraction requires you to create simple classes and POJOs that can be mapped to actual LDAP entries.
For this purposes the UnboundID LDAP SDK Persistence Framework is used. Of particular interest is the
generate-source-from-schema tool which allows you to automate generation of classes so that you don't have to write the mapping annotations manually.
generate-source-from-schema and the persistence framework is bundled in the UnboundID LDAP SDK. It is recommended to download the full release package which brings the automation tools, Java libs (jar files), and plenty of documentation and examples. Internally, Gluu Casa uses version 4.0.4 of this project.
For more background on these topics you may like checking this website.
- Get ZK Up and Running with MVVM (glance at it now if possible)
- ZK MVVM Reference
- ZK Developers' Reference
- ZK ZUML Reference
- ZK Component Reference
The api-docs are also a good source of low-level details.
There is no need to get into the installation details of ZK since plugins will just leverage the ZK 8.6 libraries available in Gluu Casa at runtime.
In ZK, you use ZUML (ZK User Interface Markup Language) which is an XML-formatted language to describe UIs. The default extension file name for ZUML pages is .zul. In zul files, components are represented as XML tags (elements) and each component's style and behavior is configured by setting XML element's attributes.
ZK provides many ready-to-use UI components, but it also allows to use pure HTML code which is universally known by designers and developers in the field of web applications.
You can use any of the resources listed above to get an idea of how typical zul files look. Additionally you may check the code of Gluu Casa project where you'll find many zul files. In the Writing your first plugin page you will have the opportunity to view and edit a .zul file your own.
Particularly in Gluu Casa code, the amount of zul components used is very small to favor plain HTML5 tags. This allows to reduce the time it takes to incorporate a UI design handed by a third party into a project. Additionally it helps reducing the time to learn ZK by focusing only on the relevant components that make the interaction with the backend possible.
Besides ZUML, ViewModels are an important concept. ZK MVVM Reference contains a great introduction to the topic. By now it suffices to say the View is the user interface, i.e. the zul page which contains ZK components, and the ViewModel is a type of View abstraction which contains a View's state and behavior. Physically, it is a POJO that contains no direct references to UI components but fields (with getters and setters) that store data state of the view, for instance, the text being entered in a text box, the enabled status of a button, the selected item of list. With regard to behaviour, it may contain the methods that will be called when something interesting happens (e.g. a button was clicked or checkbox was ticked, etc.)
ZK framework takes charge of handling the communication and state synchronization between the View and its associate ViewModel. While you don't normally reference UI components in ViewModels, if you need to manipulate those in your POJO, account that there is a Java class in the framework for every possible ZK component (e.g. Button, CheckBox, etc.) and they reside in package
The process of synchronizing data between the View and ViewModel is called binding. ZK uses a set of Java-like annotations to drive this mechanism. We will see some of those when Writing our first plugin. ZK binder is also responsible for hooking up a UI component's event such as a button's onClick to a method defined in a ViewModel. In this case Java annotations are used.
Gluu Casa only accepts plugins packaged in jar files. See the constraints section for more information.
The following is a summary of relevant concepts (somewhat tailored to the particular case of Gluu Casa):
- A plugin contains zero or more extensions
- An extension implements one extension point
- Extension points are Java interfaces defining a set of methods of interest (this way behavior is added/overriden in a host application)
- Extension points are declared in external projects (i.e. in shared libraries - not in the plugin itself or the host application)
- Extension points must extend the interface
In PF4J there are a handful of concepts such as the Plugin manager and others but they are of use for developers of the main application only, not for plugin developers. Just knowing about the concepts above will let you focus on the real deal: writing the extensions (the classes that implement the logic declared in extension point interfaces).
In addition to the plugin (which is represented by a class that extends
Casa shared module#
There is an important Java artifact called
casa-shared. It's a small jar file that exposes a number of interfaces and utility classes instrumental in doing plugin development.
casa-shared in plugins by adding the following to your maven project:
You can find the physical artifact here.
Note that "provided" scope is used because classes of this library are available at runtime in Gluu Casa already, thus you don't have to make them part of your plugin jar.
Extension points for Gluu Casa#
casa-shared defines a couple of extension points that you may like your plugins to implement for your extension classes:
Navigation menu (
org.gluu.casa.extension.navigation.NavigationMenu): Implementing an extension of this kind allows adding one or more menu items to a specific navigation menu found in Gluu Casa: user menu, admin dashboard menu, or drop down menu (the one shown on the top right of the app UI).
Authentication method (
org.gluu.casa.extension.AuthnMethod): Implementing an extension of this kind allows adding (or overriding) and authentication mechanism used in Gluu Casa (with regards to enrolling capabilities only). Adding a method requires some planning. There is a dedicated section around this.
The existence of this two extension points means that you can tweak menus or authentication method behaviors. These are core aspects of the application, specially the later. However, if your plugin is not related to any of those, you can pack your plugin with no extensions and still provide assets like UI pages, ViewModels, etc.
org.gluu.casa.ui.CustomDateConverter: This is an instance of
org.zkoss.bind.Convertervery handful for date formatting in your .zul templates.
org.gluu.casa.ui.UIUtils: A class containing static methods to show auto-dismiss notification success/error ZK notification boxes. You can call these methods from within your ViewModels.
org.gluu.casa.misc.Utils: A class containing a handful of static miscelaneous methods. There are good chances that you'll leverage some methods of
Utilswhen writing plugins, specially
org.gluu.casa.misc.WebUtils: Provides web-related utility methods. Most of them inspect the
javax.servlet.ServletRequestunder the hood. You may call these methods specially from within your ViewModels.
The following are some classes which help represent remarkable entities:
org.gluu.casa.credential.BasicCredential: A class that represents the basic info about an enrolled credential (authentication device).
org.gluu.casa.core.pojo.BrowserInfo: A class that holds basic information about a user's browser.
org.gluu.casa.core.pojo.User: Represents the current logged in user. It holds the most common attributes, e.g. given name, last name, etc.
Actual instances of
User are obtained by interacting with an instance of
org.gluu.casa.service.ISessionContext. See below.
casa-shared provides a couple of interfaces that used in combination with method
Utils.managedBean opens access to key features or information:
ISessionContext: It allows you to obtain information about the current user session: who the logged-in
Useris, and which their
ILdapService: Obtain an instance of this class (via
managedBeanmethod) and you are ready to start performing CRUD operations in local LDAP!. Recall that objects and classes passed here are supposed to follow the rules of persistence framework. This interface also contains some methods that allows you to quickly obtain the DN (distinguished name) of the most important branches of Gluu's LDAP tree.
When obtaining your ILdapService reference there is no need to worry about connecting to LDAP. You are ready to go.
casa-shared already provides some persistence-framework compatible POJOs that you can reuse or extend when writing plugins. The following are the most prominent:
org.gluu.casa.core.ldap.BaseLdapPerson represents an entry in the people LDAP branch, that is, one with
objectClass=gluuPerson. It only exposes LDAP attributes
uid so you might extend this class and add the attributes your plugin needs to handle. Note that field attributes, getter and setter methods may require annotations so that the framework automatically populates and/or persists values appropriately and also execute searches successfully.
For an example on
BaseLdapPerson derivation, check Gluu Casa Person class which in addition to
BaseLdapPerson fields, handles
memberOf attributes. This class is not available in
org.gluu.casa.core.ldap.oxCustomScript models an entry in the scripts LDAP branch, in other words, a representation of a Gluu custom interception script. This class is useful for plugins working with authentication methods since those are parameterized via the configuration properties of scripts. You will find method
Utils.scriptConfigPropertiesAsMap useful for easily reading a script properties set.
Anatomy of a plugin#
In this section we will explore the layout of a plugin - more exactly how Gluu Casa expects your plugins to be structured.
A Gluu Casa valid plugin is a jar-packaged PF4J plugin resembling the following structure:
| +-- zk-label.properties
| +-- zk-label_en.properties
| +-- zk-label_de.properties
| +-- ...
| +-- extensions.idx
| +-- MANIFEST.MF
assetsdirectory contains static resources (images, stylesheets, .js files, etc.) and Views (.zul files). This directory is optional and can be composed of arbitrarily nested subdirectories.
labelsis an optional directory and is expected to contain your plugin resource bundle (ZK internationalization labels files). The resource bundle name is required to be
zk-label. ZK rules for looking up labels is followed. For example, if user's locale is
de_DEthe first place to search for a label is
zk-label_de_DE.properties, if the file does not exist or the label is not found,
zk-label_de.propertiesis tried; a final attempt is made with
META-INFis mandatory and should contain at least the two files shown in the figure above.
MANIFEST.MFis the jar manifest file and should contain the metadata entries for your plugin (e.g. id, version, description, etc.). Check this page to learn more.
extensions.idxis automatically generated by PF4J at compile time so there is no need to craft this by hand. It contains references to all the extensions found in your plugin.
Directories remaining should contain java classes and any other type of resource needed. Note that your plugin must have exactly one class (anywhere) extending
org.pf4j.Plugin. Also you can can bundle zero or more classes annotated with
There are no explicit requirements about package naming or where to place plugin classes, extensions, or supporting classes. We suggest the following:
<pluginID> is the ID of the plugin you are writing. Here we assume you are a developer at
Extension classes can be declared inside the plugin class itself (nested static classes) as seen in the PF4J examples and demos, or as regular classes in their own files as depicted in the figure above. Such classes must implement methods declared in extension point interfaces.
In Gluu Casa extension classes are instantiated only once (singletons), so keep this in mind for your plugins development.
It is likely you will reuse other libraries in your plugin. Unless such dependencies are already part of those Gluu Casa provides at runtime, you have to provide them in your project. This means you will generate a fat jar (a jar-with-dependencies).
To know about the dependencies already available at runtime, you can to do the following:
clone Gluu casa (
git clone https://github.com/GluuFederation/casa.git)
switch to a proper branch (e.g.
git checkout version_3.1.6)
cd to application's project (
Alternatively, you may extract the file
/opt/gluu/jetty/casa/webapps/casa.war inside your Gluu Server container and inspect subdirectory
WEB_INF/lib. To do so you can use
jar -xf casa.war WEB-INF/lib.
If you are already using in your project dependencies found in Casa, you should skip those in your jar file to get a lighter plugin. To do so you can set the
scope of the artifact to
provided in your maven's pom descriptor.
If you are using maven as build tool, the Assembly Plugin will help you to easily generate your jar-with-dependencies and also get the manifest file as needed. The sample plugin we will study later uses this approach for your reference.
A manifest file example#
This is how a typical Gluu Casa plugin
MANIFEST.MF looks like:
Plugin-Description: This plugin adds a link to users menu which takes
you to a page where you are asked to fill a form with your credit
card data and SSN. The information is sent to a hacker's inbox.
Plugin-License: Available under the MIT License. See http://opensource
.org/licenses/MIT for full text
Plugin-Provider: My Company
Created-By: Apache Maven 3.2.5
Built-By: you developer
Logger-Name entry allows you to include logging statements your project generates to
casa.log when they belong to the prefix supplied. We will revisit this later.
Casa plugins lifecycle#
PF4J plugins have a lifecycle, where basically they go through a number of "states" (see class
org.pf4j.PluginState). In Gluu Casa, we present a simplified version of this through the admin dashboard. Here are the driving rules:
A plugin is considered to be started or stopped - no other intermediate states.
When a plugin is just uploaded, it is considered stopped (internally the plugin is actually resolved).
When the admin decides to add the plugin (this is prompted in a screen where the full plugin description is shown), the
startPluginmethod of class
org.pf4j.PluginManageris called. If the call is successful, it is deemed as started.
A started plugin can only be transitioned to stopped (this is attempted by a call to
org.pf4j.PluginManager). Once stopped, the plugin is considered to be "down" (not serving any functionality).
A stopped plugin can transition to started state only.
The admin can delete a plugin only if it's already stopped. When this occurs, internally a call to
The configuration file of Gluu Casa stores a mapping of started/stopped plugins and their location. That way, when the app is starting, it tries to load all plugins (issuing
loadPlugin calls). Up to this point those successfully loaded are considered stopped. The failed ones are removed from the configuration file. Afterwards,
startPlugin is called on plugins which are supposed to be started.
If the location of a plugin is not valid (e.g. jar file is not found), its entry is automatically removed from the file, no loading attempt occurs in this case.
The following are some important considerations to account:
Earlier we mentioned the usage of Weld for contexts and dependency injection. While Weld 3.0 API is available in
casa-shared module, you cannot include managed beans, producer methods, or producer fields in your plugins. Weld is only aware of the beans discovered in the scanning phase at startup of Gluu Casa, while your classes are added dynamically at a later stage. Also injection simply won't take place.
To be obtain references of already defined services objects, use
Simultaneous plugin versions#
Gluu Casa does not allow to upload a plugin whose plugin ID is already found in the system - whether started or stopped - even when plugin versions do not match.
As required by PF4J, a plugin version must be compliant with Semantic Versioning.
PF4J supports zip-based, jar-based, and directory-based plugins (the last one in PF4J development mode). Gluu Casa runs in deployment mode and only accepts plugins in jar form.
PF4J allows a plugin to depend on other plugins. This feature is not supported in Gluu Casa yet.
If you reached this part of the document, you already have the background required to start. Congratulations!.
The following is a generic suggested flow for developing plugins once the requirements presented in the beginning of this document are met. It is assumed the goals to fulfil with your development are already clear for you:
Create a simple project in your development environment. Include
casa-shareddependency (this will give you access to UI and plugin framework as well as other utilities). Create an empty resource bundle (labels file).
Create a plugin class and write your plugin metadata (i.e. all descriptive elements that will appear in the plugin's manifest file).
Create the extension classes you need (don't forget the
@Extension- a common mistake -).
Code the body of your extension classes (i.e. implement the methods that the extension interfaces may be requiring).
Create blank documents for the UI pages you may need. For every page add a minimal amount of markup code to start: for instance add a title and a heading text (probably you'll add the actual text to your labels file and reference the entries in your UI page via EL expressions).
Create the controller classes for your UI pages. We strongly encourage you to use the MVVM approach. Attach the controllers to your pages.
Code your ViewModel or controller classes with the logic required for page initialization. Add some logging statements here.
Build your plugin artifact. For your first artifact, ensure the jar complies with the expected structure. Check your manifest file contains the entries you expect and that the
extensions.idxwas bundled alongside with the manifest.
Login to your Gluu Casa testing application and upload the plugin in the admin dashboard. Check your
casa.log: while the application provides you with some visual feedback, there might be some warnings generated under the hood that may result interesting to you.
Click the button that adds (starts) the plugin. Check the log once more.
In a browser hit the page(s) you want to visualize in order to test your achievement so far. For the first attempts there is good likelihood of errors appearing. These are normally due to some misreference in URLs, class names, or label names. Some errors can be fixed without even regenerating and reuploading your plugins while others many need you to get back to your IDE. See this page for more information.
Apply error fixing as per the previous step if needed. If a new jar file needs to be built, before uploading it, stop and delete the current running plugin via the admin dashboard of Gluu Casa.
Add more logic to your plugin. This may require you to do some of the following:
Generate Java classes intended for LDAP data manipulation (e.g by using
generate-source-from-schemaor writing those by hand)
Adding elements to Gluu's LDAP schema
Add more code to your ViewModel classes (e.g. to handle interactions such as pressing a button or to bind data from UI components)
Add service classes (classes to concentrate business logic aspects) and use those in your ViewModels.
Add JAX-RS resource classes
Generate a new plugin artifact and repeat the upload/test/fix/add logic loop.
Once you are confident with your results, review and polish your manifest file.
Test your plugin on a realistic Gluu Server instance (pre-production environment of your organization). Once approved give the plugin its final version (e.g. 1.0.0), generate the final jar file, and deploy in production.
Neither Gluu Casa nor Gluu Server requires to be restarted when you are developing plugins. In case you need to alter the directory schema, only the LDAP service needs a restart.