AribaWeb 101: The Setup (Part 2)

In Part 1 I covered all you need to know in order to setup and run the AW application using standard AW tools. Now we will go to the next step that is setting up AW project completely inside your IDE without including any AW tools.

The reasons you might want to do this are:

• It's fun & useful to figure out how get "under the covers" of how AribaWeb is deployed, especially if you're using AW in a larger project
• Speed: you can squeeze the turnaround-time some if you unbundle the ANT deployment scripts -- useful when you're doing a lot of restarts of the app server during intense development
• You may want to change the defaults on what goes where in the folder structure
• Hey, maybe you want to "gradle-ize" your AW installation?

Read on to find out the details!

First time setup and Project Layout

The first thing we will start with is the layout of the project. I think you do not want to have everything in one directory but you want to have layout that gives you flexibility on where you put resources, java files, test files and others.

When I said that we would work with the IDE I meant IntelliJ IDEA but I think eclipse users can do something similar as well. The first setup is manual but once it’s done you will appreciate the speed.

Create New java project

I expect that you are already IntelliJ IDEA user because I am skipping some of the steps here. This article is not guide how to use this IDE rather how to develop AW application in this IDE.

Select that you want to create new project from the scratch:

Initial Setup

Once your project is created this should be your initial setup:

Simple project created - nothing else

And now lets get back to the layout. As you know each real project has it’s own specific structure that lets you well organize your resources. In IDEA please create following layout:

Initial setup

This is something we can start with. No more one-directory layout but structured project that is divided into two areas main and test. I think the names describe themselves. 

Directory	Description
ariba	Here I put all the ariba resources directories where the locales are stores. The reason for this is that you need to be able to work with these files maybe change or fix translations or even extend it (override it). You do not want dig all this inside jar files and all the time rebuilding the AW distribution. This is something, which needs to be available.
config	This directory plays two roles: Place to put all your application settings . Extension directory. AW is great at branding and extending and there is already build-in behavior that lets you override what is inside ariba directory. E.g. If you have under ariba resources some localization csv file and you want to change some translated value you simply place the file with the same structure under config directory and AW takes your modifies version instead of the one which came with AW the distribution
java	Here are your java files.
webapp	Into web app I put web.xml

This simple layout lets you organize your files well. Since AW relies on specific structure as I already mentioned in Part 1 so the next thing you need to do is to extend AWServletApplication and specify where to look for files. 

But before we do some programming we need to add some libraries into the project so AW classes are recognized.

Adding AW library. I already created global library so I do not have to do this for every single project

You can add individual files or create global library from $AW_HOME/lib

Finish the awl application

Let’s create several java files that are needed for this setup.

First thing to do: extend the servlet and AW application

FILE	Description
MainDispatcherServlet	This is your custom servlet file that returns reference into your custom application.
WebApplication	This is the heart of your application. Here we need register our custom directory structure so the RapidTurnaround works even for this setup. Also we are overriding method to retrieve application name. Now the URL will be: http://<host>:8080/example/Main instead of /example/AribaWeb
java	Here are your java files.
webapp	Into web app I put web.xml that refers to our custom servlet.
docroot	This is directory containing your static web resources. Here you have your css files and branding images if you need to.  The only thing you need to do is to take already assembled docroot directory from one of the examples. This is one time operation.

After little coding we have created little project, which looks like this:

IDE Project pane showing created files as well as how files are organized

Create Artifact

Now it is time to create thing called artifact. Basically we tell the IDE how to build and pack the application for our development purposes. Artifacts are created inside your IDEA project settings.

We are starting with directory structure:

Selecting exploded web app

Once you are done the artifact might look like this:

Final directory structure for the deployment 

Do not forget to update your resource patterns for compiler. Otherwise your .oss or .awl file would not be moved to the output directory.

IDE settings where we have extra extensions needed by AW

Tomcat Setup

The only thing that is left is to setup Tomcat application runner, which needs know what artifact to use, and we are done.

Selecting tomcat configuration: Local

Here is the tomcat configuration:

Select that artifact + what context path should be applied for this webapp

We can also enable RapidTurnaround by adding ARIBA_AW_SEARCH_PATH variable.

Setting up Tomcat with extra env. variables. 

Run and Debug

Now the final run or debug.

Once we have everything configured we can simply click on Run/Debug just in any java application

Using AW tools you are able to run your application as external process and then you used remote debugger to connect to the application. 

In this method (Without AW tools) you are running IDEA tomcat process, which is all built-in and what is more important you have full control over the application now.

Idea out window

Do not be mistaken I still use build scripts (we are using currently grandle) that manages the process for the continuous integration server but for the development it is only IDE. 

In this article I tried to show you different ways how you can structure and develop your real AW application where the key points are: 

• Full control over the application not the other way. 
• You need to know all the magic behind. Not rely on high-level tool. 
• Directory layout for real application. 
• You need to understand if you rely on the ant script you always run the full cycle (clean, compile, build, war, start, etc…) and if you have really large application this can be time consuming. In my case you really focus on the development because you do not have to wait if you changed something for the whole build cycle in order to startup the application again. 
• If you look at the project you can see one file called pom.xml, which I use as a library loader and checker. You do not have to use maven only for building project. In Idea you can use maven to monitor dependencies between your libraries and it can also automatically update your project settings with jars from the pom.xml.

Other areas to investigate:

Once again to finish up this article here are some points that you can check out in order to extends the capabilities of this project. 

AWConcreteServerApplication. registerResourceDirectories():
This one is responsible for scanning all of your directories and jar files and registering all your resources.  

JRebel: 

If you want to really speed up the development process you can integrate JRebel. This little tool let you do hotswap even on classes where you add or remove methods or properties and even more. 

ResourceService. getStringsForLocale(): 

We created ariba and config directory for specific reason that is to support extension of the application and branding. When you check out this method you will better understand how AW lookups its resources. 

Also try to understand how the AW is initialized, how are jar files scanned, from where all files are loaded, how ant build scripts assembles the docroot directly.


When I mentioned that I am using the grandle please have look how such build file might look like to  compile & build whole AW project:

build.grandle example

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:

AWServletApplication.init():

• 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.

AWClasspathResourceDirectory.autoRegisterJarResources():

• 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.

 AWConcreteApplication.setSessionValidator():

• 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. .