To better understand the presentation layer, we consider the Web Application Bundle as well, even it is part of the backend tier. Let's start with some details about the architecture of the presentation layer, most important for Project Engineers who setup and customize the system. On the upper right side in Figure 2.1, “Architecture - Presentation Tier” we identify our client-side application logic in form of Flex MXML components and ActionScript classes. Both of these artifacts are compiled into ActionScript classes together with the GraniteDS Service Declaration that is a MXML component as well. It's a simple Flex component that solely includes GraniteDS RemoteObject declarations. Each declared object refers to a Flex Service, configured in the standard Flex Service Configuration file (on the upper left side). In turn a Flex Service definition consits of several Destinations with unique identifiers which are mapped to an AMF Channel. This Channel is the port to the backend application and is configured with an endpoint on the server (URL).

Figure 2.1. Architecture - Presentation Tier

Because we are talking about a web application it is more as natural that a Servlet is mapped to a particular URL pattern on the server side. Two Servlet Filters are registered to scan incoming requests before the GraniteDS Servlet does handle them. The first Servlet Filter is responsible for the integration of Spring Security and delegates to a chain of standard Spring Security handler beans for authentication and authorization purpose. The second Filter in the chain is the GraniteDS context filter which handles deserialization of incoming AMF3 requests, context population and serialization of the response respectively. Afterwards the request can be processed by GraniteDS' Servlet that resolves a proper Service Invoker from its Service Factory and delegates processing accordingly. We don't go into the details of GraniteDS here hence we pursue with the OSGi service binding. At all, GraniteDS knows about the Flex Service Configuration and the configured Destinations and tries to reference a Spring bean within the Spring ApplicationContext by name. The name of the bean is part of the Destination configuration and must match an injected OSGi service reference. There is no explicit bean instantiation done in the Spring XML bean configuration, all services are imported from the OSGi service registry exclusively.

As already mentioned in the main concept on the website as well as in the overview section we strongly rely on the traditional layering architecture, splitting the business tier into a service and a data access layer and bundling domain objects together to be used in all layers. Persistent Domain Objects like Users, Modules, TransportUnits or Orders are part of the cross-cutting Business Domain Object layer. Each Module comes with a set of it's own domain classes suitable for the Module's domain. Splitting technical layers into domain Modules is a trade-off between high cohesion and lose coupling, thats why each set of domain classes is specific to it's Module.

Figure 3.1. Architecture - Backend Tier

Configuration Services on the right side are used in all layers to access global configuration data. A global scope spans all layers in all Modules, not only the Core Framework Module. It is a central service that comes with the framework. Providing an access point to the persistent storage is part of the Infrastructure Service layer that is arranged at the bottom of Figure 3.1, “Architecture - Backend Tier” and exists only once in the whole application - but can be referenced by all other Modules not only the framework.

The Service Layer (on top of Figure 3.1, “Architecture - Backend Tier”) provides functionality regarding the business requirements - corse grained services with transactional behavior. These services interact with other services within the same Module or with the underlying Repository Layer (Data Access Layer) to perform data access operations. A common goal is to minimize dependencies between services, also it is not always possible to eliminate them at all. Services offer their business functionality via a thin interface layer to outer clients (e.g. the web application) and shield the interal implementation. In the past we implemented two different service implementations, one with the Spring Framework and a second in EJB technology. It was quite convenient to switch between both service layer implementations without the need to change something on the client application. Note that Figure 3.1, “Architecture - Backend Tier” does not reflect the deployment concept and does not suggest different Bundles for both parts of the Business Service Layer even if it is so. It is up to you how you structure your new Modules, probably it is more feasable for you to combine service interface and implementation. However it's a good practise to implement against interfaces. No matter how you build your deliverables later on.

The Data Access Layer, or more fashioned the Repository Layer is a so called Integration Layer because it encapsulates the actual data access operations from the Service Layer and thus increases robustness of the implemented business logic. In former days it was essential to cut-off this functionality from the intrinsic business logic. Lately we already have an abstraction with the standardized Java Persistence API, so you could argue to remove this layer. Our suggestion is, if you feel you write duplicated code or code that just delegates to JPA's EntityManager, then you can omit this layer in your own Modules without doubts. Like in the Business Service Layer we code against an interface definition (Repository) to offer data access functionality. The implementation itself (JPA DAO Implementation) is specific to the JPA standard specification and does not depend on y particular JPA provider (like Hibernate or Eclipselink). But at runtime we need to have an underlying JPA provider, that's why there is another part in the Repository Layer - the JPA Provider. This is always a 3rd party library that comes with OpenWMS.org - by default we are using Hibernate as provider. But it shall also be possible to switch to Eclipselink or another JPA compliant implementation.

OpenWMS.org is dedicated to run on SpringSource dmServer™ application server (for simplification called dmServer from now). This server guarantees a stable and reliable environment to run OSGi applications on. It makes life easier when you have to identify OSGi dependency problems and it comes with sophisticated tracing and failure capture (FFDC) mechanism. It is delivered as a pre-configured OSGi container that saves your time compared to setting up a base OSGi implementation like Eclipse Equinox or Knopplerfish. All necessary bundles are already included, like Apache Tomcat web container, Spring Dynamic Modules for OSGi and obviously the Spring Framework itself. SpringSource dmServer™ support different application deployment formats like PAR, Plans and Library Definition files that are mandatory to run OpenWMS.org and will hopefully become a standard in the next OSGi specification.

OpenWMS.org is currently tested on version 2.0.5.RELEASE.

$ export $SERVER_HOME=<PATH TO UNZIPPED DM SERVER>

$ cd $SERVER_HOME/bin
$ ./startup.sh

PostgreSQL Database Server is the one we have chosen to develop OpenWMS.org. Of course OpenWMS.org is database independent so you can switch to a database of your choice. We have chosen PostgreSQL DB because it is a mature and proven database server formerly branched from IngresDB, that is now opensource and comes with a proper administration tool. Installation and running the server is described in the PostgreSQL documentation . Simply download the latest version (9.x) and install it on your machine.

$ ./createuser -Upostgres -W -P OPENWMS

$ ./createdb -Upostgres -W -OOPENWMS OPENWMS

By default OpenWMS.org is configured to connect to a PostgreSQL Database Server. Other databases are supported as well but have to be configured in the OSGi Configuration Service properties file that is shipped with the application. All application properties are stored in one Java properties file ($SERVER_HOME/repository/usr/org.openwms.common.infrastructure.configuration-x.y.z.properties). Properties regarding the database connectivity are prefixed with 'jdbc.'.

jdbc.driverClassName=org.postgresql.Driver
jdbc.url=jdbc:postgresql:OPENWMS
jdbc.username=OPENWMS
jdbc.password=OPENWMS
jdbc.dialect=org.hibernate.dialect.PostgreSQLDialect
jdbc.database=POSTGRESQL
jdbc.properties=hibernate.connection.compatible=7.1
jdbc.persistenceUnit=OpenWMS-test-durable

...

Detailed information about the intention of each property can you find in the developer manual.

All versions of OpenWMS.org can you find here (http://www.openwms.org/docs/downloads.html)

Please visit the download page and download the latest version of OpenWMS.org.

Unzip the downloaded file to your harddrive.

Inside the unzipped folder you find two directories containing all the bundles that have to be installed in dmServer. Please copy all files of the bundles directory to dmServer's user repository (usually to $SERVER_HOME/repository/usr ). Within the pickup directory you find the OpenWMS.org web application that has to be copied to dmServer's hot-deployment directory (usually to $SERVER_HOME/pickup ).

$ cp bundles/* $SERVER_HOME/repository/usr

$ cp pickup/* $SERVER_HOME/pickup

In a third directory you find the license agreement files of all third party libraries that are shipped with OpenWMS.org. Please read and accepts the license agreements before using OpenWMS.org.

Last but not least, you have to tell dmServer to start all bundles listed in the OSGi Plan file org.openwms.app.plan. Therefor you must add this plan to the list of plans in dmServers config file com.springsource.kernel.userregion.properties.

Open $SERVER_HOME/config/com.springsource.kernel.userregion.properties

Scroll down to the last line in this file where the initialArtifacts are listed and add the org.openwms.app.plan file. It should looks like:

initialArtifacts=..., repository:plan/org.openwms.app.plan, ...

Without this entry dmServer will not start our bundles in the repository directory, but will start the Web Application. Due to the lack of backend services the OSGi container won't be able to resolve the service dependencies of the frontend application and will throw an exception.

If you've completed all steps successfully you should now be able to start SpringSource dmServer™ with the installed OpenWMS.org application.

$ ./$SERVER_HOME/bin/startup.sh

(We assume that you have installed the server and the database with default configuration).

After dmServer's Kernel is loaded, all application specific bundles are installed and shall come up without any errors. When everything is started correctly you should see at least the line:

Started bundle 'org.openwms.zz.client.flex.wrapper' version 'x.y.z'

This means, dmServer was able to install and start the web application bundle correctly. Open a web browser and switch to http://localhost:8080/openwms to verify that your installation is successful. The login dialog of OpenWMS.org should appear now.

Figure 6.1. Application Login Dialog

After you have successfully logged in the application you see some vertical oriented buttons in the header part of the portal. These buttons will not change, doesn't matter which screen you open. The 'Logout' button is used to logout the currently logged in User from the application. All screens are closed, non-saved data is discarded and the User is logged out and forwarded to the Login screen (Figure 6.1, “Application Login Dialog”) again. Another way to leave the application is to just lock the application for other Users. In this place, an opened screen closes as well, but you can continue your work when logging in again. Unsaved data is still there after login. Notice, that only the User who locked the screen can unlock it again, other Users can not login to a locked application.

Figure 6.2. Application Header

From the main application actions bar open Application->Modules to display the Module Management view. On this screen a System Operator or Project Engineer defines all Modules of the project. One of the most important requirements on OpenWMS.org is modularization. That's why we often talk about modules either in the frontend part of the application or in the service layer (backend). An Application Module is a defined set of views, services and domain objects that belong logically together. Some modules have dependencies to other modules where they operate on.

Figure 7.1. Module Management View

On the main Module Management View press the button New to define a new Application Module. Now you have to enter a minimum set of information that is necessary to locate and run the Application Module. Required fields like the Modulename and the URL are marked with a red asterisk and must be provided to start up the module correctly. After you have done your changes click Save to save the entries in the database.

In the same view you can do changes on existing module definitions. Just choose the Application Module you want to change and the detail information of the chosen module is shown in the text fields next to the list of modules. Change the properties and press Save to write the information to the persistent storage. Be aware of uniqueness of the Modulename and the URL identifier.

Removing an existing module can be done that way too, just choose the module to delete and press the Delete button.

Your Changes will take effect the next time you reload the application.

To try out if a module is able to be loaded on startup, you should try to load it manually before. Just select the Module you want to load and press the Load button. If the module was already loaded, the buttons icon changed and is used to Unload. Pressing the Unload button unloads the current selected module. After an Application Module was successfully loaded into the application domain you should notice that the main application actions bar is populated with a couple of menu items provided by the new module. What you can't recognize so far is that the list of views was updated, too. After unloading a module, the main application actions bar is reorganized and only show the menu items of all currently loaded modules.

From the main application actions bar choose Application->Users to open the User Management View. After the view is loaded a list of Users appears on the left-hand side. In the right panel all details of a selected User are shown. In a completely new installation no Users are defined, hence the list and the detail form are both empty. The User Management is used to add new Users and to modify or delete existing ones. Furthermore you can set User details (UserDetails), change a User's password, or add an image to an User.

Figure 8.1. User Management View

Table 8.1. Actions bar of the User Management View

Icon	Description
	Add a new User.
	Delete an existing User, or an User entry that was created but not saved before.
	After changing an User's data you can save your changes by pressing the save button.
	Reload and refresh all Users from the persistent storage.
	Change the password of an existing User. The operation cannot be done on an unsaved User.
	Change the image of an existing User.

By default some detail information can be attached to each User profile. Required fields are marked with a red asterisk and must be set to successfully save the changes in the persistent storage. The Username is a system-wide unique identifier that can be changed at any time but must be set initially.

After clicking the Change Button () a popup window appears and your are prompted to enter a valid path to an image file, that is uploaded to the server afterwards. When the upload succeeds the new image file is directly assigned to the selected User, there is no need to save the User anymore. The width of the image is resized to max. 100 pixel and a height to max. 150 pixel.

Figure 8.2. Changing the Users image

To change the Users password, select an User and choose Change Password () from the actions bar. In the dialogue Figure 8.3, “Changing the Users password” reset the password and click on Change.

Figure 8.3. Changing the Users password

A System User account exists by default. This particular User profile is especially dedicated to Project Engineers and shall only be used for installation and maintenance purpose. The System User has full access to the application without any security restrictions. By default Username and password of the System User are both set to OPENWMS. How to change these credentials is described in the Developer Manual.

Once you have logged in the application, your username is displayed in the upper right corner of the application header. Click on your username to open a dialogue with your personal user settings (Figure 8.4, “Change User Preferences”). All Users, beside the SystemUser, can manage their own settings, like setting a default language or change the UserDetails. Changing the current password to login is possible as well.

Figure 8.4. Change User Preferences

Generally the term Role is a synonym for a group of Users. Having some Roles in each project is always recommended. For example, you could define a separate Role for Operators, System Operators and Project Engineers. Doing so you could assign Users to Roles and afterwards assign Security Objects, like Grants to each Role. Doing it that way is much more convenient and requires less administration than assigning each Grant to each User. New User accounts can easily tied to already existing Roles. Defining a set of Grants to a Role is done once per Role. This is standard security management in multi-user enterprise applications.

The Grants in Table 9.1, “Table of Grants regarding Role Management” determine the actions an User can perform on Roles. All Grants are stored in the secured-objects.xml file of the main Flex Application Module.

From the main application actions bar click Application->Roles to open the Role Management view. Purpose of this management view is to declare security Roles and assign individual Grants and Users to each of them.

Figure 9.1. Role Management View

Table 9.2. Actions bar of the Role Management View

Icon	Description
	Open a dialogue to create a new Role with name and description.
	Delete an existing Role.
	After double-clicking a Role you can change data and press Save to save your changes.
	Reload and refresh Role information from the persistent storage.
	Assign Users to a selected Role. Opens a dialogue to add Users to the Role.
	Select already assigned Users you want to remove from the selected Role and press this button to remove their Role membership immediately.
	Select a Role and press this button to assign one or more Grants to the Role. An dialogue opens to assign or remove Grants from a Role.

To create a new Role press the 'Create' button of the actions bar (). In a simple dialogue, you have to provide the name of the new Role and an optional descriptive text. After the Role is created the roleName is prefixed with 'ROLE_'.

Figure 9.2. Create a Role

Existing Roles can also be modified. To change the role name or description, just double click the Role to open a dialogue, like shown in Figure 9.3, “Modify a Role”, where you can change the values as desired.

Figure 9.3. Modify a Role

If you already have a Role defined, you are now able to assign Grants to this Role. Just select the Role and press the 'Assign Grants' button (). A dialogue opens that lists all non-assigned Grants on the left side and all currently assigned Grants on the right side. Choose the Grants you want to add or remove to a Role and press one of the shift buttons in the middle. After you confirm the dialogue you have to save the Role. Your changes do not take affect without saving the Role explicitely, because you could have done changes to the Role before.

Figure 9.4. Assign Grants to a Role

Role Management does only make sense when you assign Users to Roles and manage access control through Roles. So go ahead and add some Users to a defined Role. Press the 'Assign Users' button () and do it like you did before. Nearly the same dialogue opens where you can add or remove one or more Users from a selected Role.

Figure 9.5. Assign Users to a Role

All enterprise applications have some kind of configurable application preferences or settings, nevertheless whether they come from a file, a database or somewhere else. In OpenWMS.org we call these setting parameters Preferences. A Preference is always in a certain scope, valid for a particular part of the application. So far, we have defined four different types of Preferences:

An authorized User is able to create new Preferences, modify or delete existing ones. The Grants in Table 10.1, “Table of Grants regarding Preferences Management” determine the actions an User can perform. All Grants are stored in the secured-objects.xml file of the main Flex Application Module.

From the main application actions bar click Application->Preferences to open the Preference Management view. On the left-hand side of the sreen all Preferences are grouped by their type in an accordion container. Details of a selected Preference are shown right beside.

Figure 10.1. Preference Management View

Table 10.2. Actions bar of the Preference Management View

Icon	Description
	Open a dialogue to create a new Preference with all the required information like the preference key, a value and an owner (like Application, Module, Role or User).
	Delete an existing Preference.
	Save changes you did on the currently chosen Preference.
	Reload and refresh all Preferences from the persistent storage.

Each Preference must have at least a key and a type assigned. Preferences of type ModulePreference, RolePreference and UserPreference additionally need to have an owner. The key and owner fields are unique along all defined Preferences and cannot declared twice - be aware of that. For example, it is not allowed to define two Preferences with a key 'defaultLanguage' within the same Module 'CORE', but it is still allowed to have this Preference defined for two separate Modules 'CORE' and 'Common'.

Clicking the button to create a new Preference () opens the dialogue shown in Figure 10.2, “Create a Preference” to add a Preference and store it in the database. Actually the same fields can be set like in the details page of the overview screen Figure 10.1, “Preference Management View”.

Figure 10.2. Create a Preference

To make changes on an existing Preference, select that one from list on the left side of the screen. On the details page you can modify the values of the selected Preference. Notice that the key of an existing Preference cannot be changed after it is created. To save your work back to the system click on the 'Save' button () in the upper actions bar.

Removing an existing Preference is simple as well. Just select the Preference to remove and click on the 'Remove' button (). No confirmaton will be shown, hence be careful with deletion of existing entries.