AW Talk is the official development team blog for AribaWeb, the Open Source component-based web application development framework for creating rich, AJAX-enabled applications with the absolute minimum of code (and no hand-coded Javascript).

AribaWeb 101: The Setup (Part 1)

When you start with some new framework like this you need to spend some time trying to really understand it. First you try to rely on high level tools which makes the development little bit easier but at the end you need to make sure you control the application and not other way around. And in this article and the next one I will try to show you two ways how you can setup your application in order to get maximum out of it.

AW ant building tools

When you look into the AribaWeb distribution or one of the first screencast you can see how easily you create new project where everything will be created for you, even the IntelliJ IDEA or Eclipse project.

As you know already there is a command called aw under the $AW_HOME/bin folder that let’s you create different types of application:


This is a helper tool based on the ant, which simplifies the creation of the project. It can be really useful if you do some initial setup or prototyping where you need to create quickly several projects. Since it’s only the ant script you can modify the type of the project anytime during your development process. 


Ant script structure

When you check out the $AW_HOME/tools/ directory for the ant file the first thing you notice there is not a one ant script which you can use but there are five. Yes five ant build scripts and each used for different type of the application (there is a common but it counts too ;-) ).

build-common.xml

This ant script is the main one because it contains all necessary properties and targets used by other scripts in order to build, deploy and even run your AribaWeb application.

Properties: 
You can override existing ant properties using well known .properties files which should be located in one of the following locations or directly inside your project’s build.xml script:

  • ${user.home}/aribaweb.build.properties
  • ${user.home}/build.properties
  • ${basedir}/build.properties
There many properties but those in this stage that you probably care about are:

Name
Description
servlet.port
Port on which your servlet container is listening
jpda.address
Debugging port on which your application listening
aw.search.path
If you try to run your AribaWeb application in debug mode and you want to have Rapid Turnaround enabled this property must be set and point to your src directory.
This can be also set by env. Variable called:
ARIBA_AW_SEARCH_PATH



build-widgets-app.xml




This ant script is usually included inside your generated AW Widget application. This script imports the common one from above. As you can see on the picture each generated ant script, which is part of your application, contains only import tag which points to this ant script.



Let’s pretend that we have created our first widgets application and inside of this build.xml you will only see these 4 tags.
What you probably might want to do is to change your debugging port on which your Tomcat is listening. In my case some other process occupied this port so I had to changed it (I think it was Skype)

In this case my tomcat will listen on this debugging port 5678. 

Properties:
In this stage you can also override some ant properties because by default this ant will generate a file called aribaweb.properties that is used by AribaWeb to correctly load and initialize your application.

Name
Description
aw.namespaceIdentifier
Since this is widget app you can also define your own widgets and if you are going to use them you will need to prefix them with some namespace. This is defined by this property. By default AW put "x"
aw.packagedResourceExtensions
Each application has many files that needs to be included for the deployment and in this property you specify what all file extensions to select.

So the project’s aribaweb.properties might look like this:




build-metaui-app.xml 

The same what we said earlier applies also for this type of application. The only difference you will find is this type of application includes some extra jar files related to meta-ui

Properties: 

Here you can also override some ant properties besides the ones we have described earlier: 

Name
Description
dependsOn.jar
Jar dependency declaration for your application. You specify the list of jars this application depends on. For this type of app it can be ariba.metaui
aw.packagedResourceExtensions
The same as in the widgets app but in this case you need to include also oss files.
Inlined-jars
You can also embed some file libraries as part of this jar
Pre-initializer
Name of the of the class file along with the method name you want to call during initialization process



build-jpa-app.xml

This type of build file you usually include in database-like applications or it is already included if you use the aw command and metaui-jpa.

Besides common tasks to build, package or deploy your application this one also contains necessary targets to initialize the configuration for your DB or O/R Mapping tool as well as starting build-in InMemory database.

Properties:

The most important properties in this type of application you care about are the ones that let you connect to the underling database through your O/R Mapping tool.

  •  hibernate.connection.driver_class
  •  hibernate.dialect
  •  hibernate.connection.username
  •  hibernate.connection.password
  •  hibernate.connection.url
  •  hibernate.hbm2ddl.auto
For the full list of properties please check the session configuration.

Application structure

When your project is generated it does not contains much but for simple prototype it’s probably ok. 


In real world you usually need to have everything under the control. So what else is there you need to be aware of in order to include other files into the project?

By default AW expects certain directory structure so it can properly register all the resources. This structure is important for the initialization process as well as for the build scripts, which expect names and specific folder layout.

Let’s start with the aribaweb.properties :

Example of aribaweb.properties
The first thing you want to do is to include aribaweb.properties file and not let the ant task to   generate it for you. Because when you are building real application these properties does not change much and became more or less static. Of course you might prefer to declare all this properties in your ant script.

The resource directories

As already mentioned for your development you need to layout your resources into structure that AW understands specifically the AWConcreteServerApplication.

In your source directory you need to create layout like this:



When AW is registering your resources directories the first thing it tries to lookup if you are in debugging mode and you want to utilize all the RapidTurnaround features:



In this branding folder (resource/webserver/branding) you store your own look and feel. Meaning that you can change each component’s style as well as images. Everything is brandable.

As you can see I put it in the source directory also aribaweb.properties, which will be taken by ant task.

There is something else you can see and it is your resource bundle files. The (resource/<locale>/strings) directory let you store your string translations. You might ask why there is another directory level or why the resource csv files are not directly under the locale?
Well the answer is simple. Not only resource files (the actually text) you want to have locale specific. There are other things like:

  • You can have images per locale
  • Maybe some other files used for templating that needs to be layout per locale. For example image that you have your Signup page and you need to send out confirmation email. Of course you do not want to use one template you want to use as many templates as many locales you will support in your application.

In this case your application can ask give me localized template so I can include it in my multipart email message, which I want to send out to user. And the only thing you do in your application is to ask for this localized file:


Code Example:
ResourceService.getService().findResourceURL("email/ConfirmationEmail.html",<user’s locale>);

And once you deploy your application the final result might look like this:



docroot:
  • This is your directory where you have your web server static resource. You can see that what we had under resource/webserver is now under docroot/config/.
  • You can also configure AW in the way so these web resources are on different server and mapped for example by your apache server.

                                                                     
Other areas to investigate:

To finish this part for you it is also worth to check how AW application is initialized. Therefore I recommend check out following:

  • Here everything starts. Once your application is created this method is called in order setup everything. 
AWConcreteServerApplication. registerResourceDirectories():
  • This one is responsible for scanning and all your directories and jar files and registering all your resources.

  • I think you can already guess from its name. This method that is executed inside registerResourceDirectories() will scan all your jar files and register all your images, oss  and everything what is in its way.


  • You want to call this method and set your own session validator if you want to have your custom authentization and authorization logic.

This is pretty much it and the next time in the part 2 I will show you different way how you can manage your build and application. If you are intellij Idea user you might be interested in this one. .



(Meta UI - JPA) Context Binding Explained !

Hello everyone, 
Almost all of you who have explored AW at any depth will have encountered the ObjectContext and will probably have realized that its function is to bind the persistence-layer session to the AW-layer. The observant amongst you may have noticed that the ObjectContext appears to be per page and that additionally the context is thread-locally bound. When I first saw this I was confused. As I move through the app from page to page, it seems like I would be creating lots of ObjectContexts which may or may not have been committed or flushed and I may lose uncommitted edits; additionally, there's no guarantee that I will rendezvous with the same thread across request potentially causing more memory bloat and / or lost edits. If you are building really enterprise application and you care about a performance the earlier or the later you will want to know more. So what's going on? Read on and I'll tell you.

Class diagram showing relation between the AWPage and ObjectContext



We know that in simple scenario ObjectContext is used to complete your transaction and save the data into the DB, but on the other side do we know what is happening on the background? Is this even so important? 


Yes this is important because this will influence your future performance of the application. I am starting with this because we have decided long time ago to re-implement whole persistence stack with our own API to support our requirements and this week we did some refactoring and discovered several points that we think it should be addressed and clarified by anyone going the same direction as we do.


Here is what's going on: 

1) Every time there is a new request from the Servlet Container and handled by our AWDispatcherServlet it does not have to be the same thread all the time. 

2) When you are playing with AribaWeb you will probably do not notice but from the time you login till the end you logout from the Application you are probably using the same thread. But this is only a coincidence. With big load you might get different thread every time. (But this is common behavior and I am mentioning it just for the completeness). 
So have you even try to understand your hibernate session or ObjectContext? How it is created and how it is destroyed or even propagated over several pages?



3) Every time your page with your content is about to be rendered then new AWPage is created and gets new ObjectContext (or existing is reused from previous thread). All this using ContextBinder and its method pageWillAwake(). ObjectContext is nothing else than in the default implementation the HibernateContext that holds its HibernateSession.



4) If you leave the page or go to the new one the current ObjectContext is removed - unbound. But here might be a problem #1. 
The ObjectContext is removed from ThreadLocal but its not really destroyed meaning your HibernateContext and its HibernateSession is still active. There is no close() called. Now imagine you will have Facebook like application with allots of hits and you are ignoring these facts then you might get into trouble. Of course you might say that Hibernate supports some release strategies which allows you automatically close the database connection when you complete your work but what about session? 
There is even more you need to consider. Especially when dealing with large number of users accessing the website. If you do not have clearly defined your transaction and its demarcation and maybe do not set properly FlushMode you get into trouble. The objects in your session will grow and grow. Of course you can say but we do call flush when we save the object and hibernate specific implementation has defined several rules when the flush should occur. But this might behave differently when you have 100 users using your application or when you have 100k users using your app. If you are planning to implement your own JPA layer please consider all this because hibernate at the end if you configure it correctly might not give you so much trouble compared to your version where you will try to simulate the same behavior but instead of passing around HibernateContext you might be passing your own Context with some state. You need to be lazy meaning you should acquire connection when you really need it and when you are done just get rid of it. 


5) The persistence framework (MetaUI-JPA) allows you to have several active ObjectContext opened and bound to your session id but only one for current thread. (Valid for Nested Session)


Note: Here I want to stress that AribaWeb is mainly unique web framework on first place and then there is rest of its stack (JPA implementation and so on...). So I am showing you these points because you should be aware of it and I want make sure that we understand it and this is not something that AribaWeb (the UI) should handle. If you will have trouble with your session management then all is in your hands. As I mentioned before if you decide to use HibernateSession you need to make sure that your hibernate layer is set correctly


6) We understand now how the session management works and we can go on and focus on the actual flow of the request. So lets say we launched AltIssue Demo application where we have module tabs [Issue,Category,..] and now you simply click on the second tab the Category.


The actual flow can be described like this:


Once you click on the new tab the first phase is executed. Since every click can be from different thread we need to transfer ObjectContext if any to the current thread. 




#1: pageWillAwake() is called on Issue page (the page we are exiting) and current ObjectContext if any is taken from the page context and bound into current thread for the AWPage B. You can see the ThreadLocal does not make any sense anymore for the AWPage A




#2: pageWillAwake() is called again and this time for the new Category page. It will take newly added ObjectContext from current thread and attaches it into the current Page Context that is associated with the AWPage B.




#3, #4: Then content is rendered and pageWillSleep() is called on both AWPages A and B, which releases the ObjectContext from current thread.

Now we get some idea how ObjectContext is transferred between pages and threads. Maybe now you are asking why it is so important to transfer object context from one page to another. The answer is simple. Every time you create a new object this object is associated with current and active EntityManager and this EntityManager is part of your ObjectContext. Typical use case for this might be a Wizard where you are managing a long conversation over several pages for one specific entity. On the picture you can see how the execution is triggered. First is called awake for the model.Issue tab, then the awake for the model.Category and when everything is rendered we remove the ObjectContext from the current thread.



Other areas to investigate:

While we are are still in the persistence layer I think it is worth to check out all classes which are involved in this whole process: 
ObjectContext: 
  • This is your link between persistence layer and the UI layer. This object is responsible for all DAO operation as well is creation of the objects. 
  • Any class using this ObjectContext API might wish to monitor all the changes on a object which happen in the other ObjectContext (for example if a nested context is created) 
  • Use to group ObjectContexts (currently by sessionId). Valid only for the nested context where you need to propagate all the changes to parent context. 
  • This is specific implementation of the ObjectContext based on the java persistence API. 
  • Implements create() method which provides new context in this case HibernateContext when ContextBinder.pageWillAwake() is trying to bind new context to AWPage and ThreadLocal

AribaWeb 101: The Basic (File Types)

Welcome to one of the first but I hope not the last AribaWeb 101 session where I will show you all the necessary details you need in order to build and run an AribaWeb application. This article assumes that you have already read all AribaWeb documentation and watched all related screencasts.

When I asked myself what is the most important thing to start with, I went through a few different rather complex scenarios in my mind in order to show you the power of AribaWeb; but, every time I ended up concluding: “We are missing the basics!” Plus when reading our Google discussion group I can see the concept is clear for most of us but there are still some elementary details that we can’t simply connect together. 


File Types

When building an AribaWeb application you come across several file extensions which all together form the application and here I will guide you quickly through the most important ones: 

*.awl (AribaWeb Language )
This is the most important file that you will use when building your UI application layer. Inside this file you see HTML - like syntax to define your user interface. Usually this file is used for templating as well as component definition.  
           


Templating can be used directly from the .awl file or in more advanced usage from .oss files (but we will get to that in a second). On the picture bellow you can see two components <a:IncludeComponent> tags -- HeaderPage and FooterPage -- which are just additional .awl pages that you can add to your existing page. 



You can also define new component like in this case where we created a component for rendering captcha code. You can then attach it in your page (please see java file type section):

Defining new component that renders captcha code
Each .awl component can have its own java class with the same name, which can hold the state and can act as a controller.

Location of files:
Probably the most important locations to remember while discovering details of this framework are these 3 directories:
1.       ariba core: src/aribaweb: 
          Here are core components and every time you see something prefixed with the <a:* name space you know it’s from this source path 
2.       ariba widgets: src/widgets: 
         This directory contains widgets that you are using when building your UI. 
          The <w:* namespace means widgets and it’s from this source path 
3.       ariba MetaUI: src/metaui:
          This directory contains everything related to meta context. 
          When you see the <m:* name space you know it’s from this directory

Hint: If you are not sure or you get stuck, always remember that you can search these directories for possible examples or usages. There are plenty of examples.


For more information please see: AribaWeb Documentation 

*.awz, *.afr (Wizard files)
Each well behaved application that requires some flow usually use wizards. And to accomplish this in AribaWeb you use followings:

*.awz (Wizard definition)
This is the main wizard definition file where you describe the flow. Developers do not have to worry about too many details and can focus on the logic. 


As you can see in the example above we define what action we support in the wizard navigation bar, number of steps and exit frame. 
The source of each step refers to the wizard frame (the *.afr file) which provides the content for the step. And the content for each wizard frame is specified by the source of the content tag in that frame (please see the afr section).

Each step can have number of sub-steps:


*.afr (Wizard frame)
This file defines the wizard frame for actual content, which is then defined by awl file.
In this example we are referring to the Information.awl in the package wizard.



Location of files:
The first location you should look for is the directory where the Wizard.dtd and Frame.dtd are located. Once you look inside here, you will learn how your .awz and .afr files should look like:
  • Frame.dtd:
    •   $AW_HOME/src/widgets/resource/global/dtd/Wizard.dtd
  • Wizard.dtd:
    •  $AW_HOME/src/widgets/resource/global/dtd/Frame.dtd

When you deploy your application these files are located inside the ariba.widgets.jar under ${ariba.widgets.jar}/ariba/resource/global/dtd/

Wizard Extension:
When you check these directories you will find something else besides files above:
  • WizardExtension.dtd
  •  FrameExtension.dtd
These files you probably want to use if you are developing enterprise-like applications and you know your Customer would like to extend it. They can change the flow, modify what frame to show or maybe add extra frames, etc. 
You might ask why not to use Wizard.dtd and Frame.dtd directly? Well you could but usually you have a core product and you do not want the Customer to modify your core code, rather only extending it. 
This is something like your config directory in the docroot where you can override CSS styles, images and other resource. Or another example we have BrandingComponents. This is all made and prepared for extending or branding an application. 
As you can see AribaWeb is a brandable platform from its heart and you as a developer do not have to think how to hack this when something small needs to tweaked. In other words, all this makes AribaWeb a really killer platform for the enterprise.


For more information please see: Wizard documentation


*.java 
I do not have to tell you what java files are for but I just wanted to mention that besides the obvious, you use java files to define your component and to give it some behavior.

For example you can have the file AWCaptcha.awl from above example that defines the actual component and then AWCaptcha.java for holding a state and handling all the events.

Your java file must be inherited from the AWComponent:



Rendered control might look like this:

And used like this: 



*.groovy 
AribaWeb supports the groovy language and basically it has the same purpose as the above java file.


*.oss ( object style sheet)
Probably the most interesting part you will work with when developing an AribaWeb application. The .oss file is a key element in the rule-driven UI. The UI is generated based on this rules file. 





This will require an additional article because this is a pretty complex topic. The only thing you need to know for now is the .oss files contain rules in the CSS like syntax and based on them you can declaratively create your UI. 


Location of files:
As a good start and a way to try to learn more about .oss files, it’s probably best to look directly into core files defined by AribaWeb.
  • WidgetsRules.oss
    • Main MetaUI definition where you can find all out of box rules
    • $AW_HOME/src/metaui/ariba/ui/meta/layouts/WidgetsRules.oss
  • PersistenceRules.oss
    • MetaUI definition for the persistence layer. Here you find all the definition for rendering data in the table, search details and others.
    • $AW_HOME/src/metaui/ariba/ui/meta/persistence/PersistenceRules.oss
  • Application.oss
    • This is your main application MetaUI rules definition. Here you usually put details about modules, defining main layout of your application, maybe extending out of box rules (WidgetsRules, PersistentRules)
      • $AW_HOME/examples/**/Application.oss
  • rules.oss
    • In this rules files you usually declare rules related to your domain model. For every package in which is your POJO class you put one rules.oss file.
    • Again to find out more please have a look at: $AW_HOME/examples/**/Application.oss

For more information please see: MetaUI Documentation 

 So that's about it for now, the next time you see another 101 article we will focus on the setting up of a project, build script and getting AribaWeb under control.  Until then!