Session objects
The Java objects declared in controllers.xml have session scope; that is, they are objects that are created for a user and exist during his session. It's syntax is:<object
name="objectName" <!-- 1 -->
class="objectType" <!-- 2 -->
value="initialValue" <!-- 3 -->
scope="module|global" <!-- 4 New in v2.1 -->
/>- name (required): Name of the object, usually you use the application name as prefix to avoid name collision in large projects.
- class (required): Full qualified Java class for this object.
- value (optional): Initial value for the object.
- scope (optional): (New in v2.1) The default value is module. If you use module scope each module will have its own copy of this object. If you use global scope the same object will be shared by all modules of all OpenXava applications (running in the same .war).
<object name="xava_view" class="org.openxava.view.View"/>
<object name="xava_referenceSubview" class="org.openxava.view.View"/>
<object name="xava_tab" class="org.openxava.tab.Tab"/>
<object name="xava_mainTab" class="org.openxava.tab.Tab"/>
<object name="xava_row" class="java.lang.Integer" value="0"/>
<object name="xava_language" class="org.openxava.session.Language"/>
<object name="xava_newImageProperty" class="java.lang.String"/>
<object name="xava_currentReferenceLabel" class="java.lang.String"/>
<object name="xava_activeSection" class="java.lang.Integer" value="0"/>
<object name="xava_previousControllers" class="java.util.Stack"/>
<object name="xava_previousViews" class="java.util.Stack"/>The controller and its actions
The syntax of controller is:<controller
name="name" <!-- 1 -->
>
<extends ... /> ... <!-- 2 -->
<action ... /> ... <!-- 3 -->
<subcontroller .../> ... <!-- 4 New in v4.8 -->
</controller>- name (required): Name of the controller.
- extends (several, optional): Allows to use multiple inheritance, to do this the controller inherits all actions from other controller(s). Add the excluded-actions (new in v5.8) attribute to prevent certain actions to be inherited.
- action (several, required): Implements the logic to execute when the final user clicks a button or link.
- subcontroller (several, optional): (New in v4.8) Allows grouping several actions that are shown in a drop-down button.
The controllers consist of actions, and actions are the main things. Here is the syntax:
<action
name="name" <!-- 1 -->
label="label" <!-- 2 -->
description="description" <!-- 3 -->
mode="detail|list|ALL" <!-- 4 -->
icon="icon" <!-- 5 New in v5.4 -->
image="image" <!-- 6 -->
class="class" <!-- 7 -->
hidden="true|false" <!-- 8 -->
on-init="true|false" <!-- 9 -->
on-each-request="true|false" <!-- 10 New in v2.1.2 -->
before-each-request="true|false" <!-- 11 New in v2.2.5 -->
after-each-request="true|false" <!-- 12 New in v4.0.1 -->
by-default="never|almost-never (new in v4m6)|
if-possible|almost-always|always" <!-- 13 -->
takes-long="true|false" <!-- 14 -->
confirm="true|false" <!-- 15 -->
keystroke="keystroke" <!-- 16 New in v2.0.1 -->
show-dialog="true|false" <!-- 17 Only in v4m1 -->
hide-dialog="true|false|default" <!-- 18 Only in v4m1 -->
in-each-row="true|false" <!-- 19 New in v4m4 -->
process-selected-items="true|false" <!-- 20 New in v5.7 -->
available-on-new="true|false" <!-- 21 New in v5.8 -->
loses-changed-data="true|false" <!-- 22 New in v6.3 -->
>
<set ... /> ... <!-- 23 -->
<use-object ... /> ... <!-- 24 -->
</action>- name (required): Action name that must be unique within its controller, but it can be repeated in other controllers. When you reference an action always use the format ControllerName.actionName.
- label (optional): Button label or link text. It's much better to use i18n files.
- description (optional): Description text of the action. It's much better to use i18n files.
- mode (optional): Indicates in which mode the action has to be visible. The default value is ALL, that means that this action is always visible.
- icon (optional): (New in v5.4) Icon id from Material Design Icons. For example, if you write icon="bell" a bell will be used as icon for you action and you don't need to include any image. Since v5.4 this is the preferred way to define an icon instead of image.
- image (optional): URL of the image associated with this action. In the current implementation if you specify an image, it is shown to user in link format. Until v4.1.x the root for the URL was xava, it was needed to use images/ as prefix. Since v4.2 the root depend on the style and in the default style it is xava/images, so it is not longer needed to use the images/ as prefix, though it is still supported for not breaking backward compatibility. If you define both image and icon, icon has preference over image, though you can change this behavior with useIconsInsteadOfImages=false in xava.properties. Inside portals image has always preference.
- class (optional): Implements the logic to execute. Must implement IAction interface.
- hidden (optional): A hidden action is not shown in the button bar, although it can be used in all other places, for example to associate it to an event, as action of a property, in collections, etc. The default is false.
- on-init (optional): If you set this property to true, then the action will be executed automatically on initiating the module. The default is false.
- on-each-request (optional): (New in v2.1.2) If you set this property to true, then the action will be executed automatically on each request of the user, that is, on first module execution and before each user action execution. In the moment of execution all OpenXava session objects are setup and ready to use. That is, from this action you can use xava_view and xava_tab. The default is false. Using in conjunction with mode you can discriminate the execution of this action for a concrete mode (list or detail) (new in v3.0.2).
- before-each-request (optional): (New in v2.2.5) If you set this property to true, then the action will be executed automatically before each request of the user, that is, on first module execution and before each user action execution, but before the OpenXava session objects are setup and ready to use. That is, from this action you cannot use xava_view or xava_tab. The default is false. Using in conjunction with mode you can discriminate the execution of this action for a concrete mode (list or detail) (new in v3.0.2).
- after-each-request (optional): (New in v4.0.1) If you set this property to true, then the action will be executed automatically after each request of the user, that is, on first module execution and before each user action execution. The default is false. Using in conjunction with mode you can discriminate the execution of this action for a concrete mode (list or detail).
- by-default (optional): Indicates the weight of this action on choosing the action to execute as the default one. The default action is executed when the user presses ENTER. The default is almost-never (until v4m5 was never).
- takes-long (optional): If you set it to true, then you are indicating that this action takes long time in executing (minutes or hours). In the current implementation OpenXava shows a progress bar. The default is false.
- confirm (optional): If you set it to true, then before executing the action a dialog is shown to the user to ask if he is sure to execute it. The default is false.
- keystroke (optional): (New in v2.0.1) Defines a keystroke that the user can press for executing this action. The possible values are the same as for javax.swing.KeyStroke. Examples: "control A", "alt x", "F7".
- show-dialog (optional): (Only in v4m1, not available since v4m2) If true after the action execution the current user interface will be show inside a modal dialog. The default is false.
- hide-dialog (optional): (Only in v4m1, not available since v4m2) If true then if currently there is a modal dialog shown then it will be hidden. The default value is default, it means that the dialog will be hidden only when the action name is "cancel" or it is the default action.
- in-each-row (optional): (New in v4m4) If true and this action is shown in list mode or in a collection the action will be shown in each row. The action must have an int row property (TabBaseAction and CollectionBaseAction already have the row property). The default is false.
- process-selected-items (optional): (New in v5.7) If true this action processes the selected rows in the list. In this way OpenXava can hide this action if selecting items is not available. The default is false.
- available-on-new (optional): (New in v5.8) If false this action is not available when the user is creating a new entity (when he clicks on New). The default is true.
- loses-changed-data (optional): (New in v6.3) If true it means that when executed all the data changed by the user in the view since the last saving will be lost. This can be used by OpenXava in order to ask for confirmation before executing the action The default is false.
- set (several, optional): Sets a value of action properties. Thus the same action class can be configured in different ways and it can be used in several controllers.
- use-object (several, optional): Assigns a session object to an action property just before executing the action. After the execution the property value is put back into the context again (update the session object, thus you can update even immutable objects).
A plain controller might look like this:
<controller name="Remarks">
<action name="hideRemarks"
class="org.openxava.test.actions.HideShowPropertyAction">
<set property="property" value="remarks" />
<set property="hide" value="true" />
<use-object name="xava_view"/> <!-- Not needed since v4m2 -->
</action>
<action name="showRemarks" mode="detail"
class="org.openxava.test.actions.HideShowPropertyAction">
<set property="property" value="remarks" />
<set property="hide" value="false" />
<use-object name="xava_view"/> <!-- Not needed since v4m2 -->
</action>
<action name="setRemarks" mode="detail"
class="org.openxava.test.actions.SetPropertyValueAction">
<set property="property" value="remarks" />
<set property="value" value="Hell in your eyes" />
<use-object name="xava_view"/> <!-- Not needed since v4m2 -->
</action>
</controller><module name="Deliveries">
<model name="Delivery"/>
<controller name="Typical"/>
<controller name="Remarks"/>
</module>
And the bottom button bar:
Note that actions with image/icon are located at the top of the page, and actions without image/icon are located at the bottom of the page.
You can write the code for hideRemarks like this:
package org.openxava.test.actions;
import org.openxava.actions.*;
/**
* @author Javier Paniza
*/
public class HideShowPropertyAction extends ViewBaseAction { // 1
private boolean hide;
private String property;
public void execute() throws Exception { // 2
getView().setHidden(property, hide); // 3
}
public boolean isHide() {
return hide;
}
public void setHide(boolean b) {
hide = b;
}
public String getProperty() {
return property;
}
public void setProperty(String string) {
property = string;
}
}<use-object name="xava_view"/> <!-- Not needed since v4m2 -->The <use-object /> gets the session object xava_view and assigns it to the property view (removing the prefix xava_, in general removes the prefix myapplication_ before assigning object to property) of your action just before calling execute(). Though since v4m2 is not needed to use <use-object /> to inject xava_view because ViewBaseAction already inject it using @Inject.
Now inside the execute() method you can use getView() as you want (3), in this case for hiding a property. You can see all View possibilities in the JavaDoc of org.openxava.view.View.
With...
<set property="property" value="remarks" />
<set property="hide" value="true" />Subcontroller (new in v4.8)
With the subcontroller we can grouping several actions and show them in a drop-down button.Here is its syntax:
<subcontroller
controller="controllerName" <!-- 1 -->
image="image" <!-- 2 -->
icon="icon" <!-- 3 New in v5.4 -->
mode="detail|list|ALL" /> <!-- 4 -->- controller: (required) Controller's name that we reference
- image: (optional) URL of the image associated with this subcontroller
- icon: (optional): (New in v5.4) Icon id from Material Design Icons. For example, if you write icon="bell" a bell will be used as icon for you subcontroller and you don't need to include any image. Since v5.4 this is the preferred way to define an icon instead of image.
- mode: (optional) The default value is ALL. Indicates in which mode the action has to be visible.
<controllers>
<controller name="Color">
<action name="seeMessage"
class="org.openxava.test.actions.SeeMessageAction"/>
<subcontroller
controller="ColorSub" <!-- 1 -->
icon="menu"/>
</controller>
</controllers>
You can put the controller name in i18n files.
Dependency injection
Using Dependency injection the value of a field or property is set by the framework, not by the developer.@Inject (JSR-330) (new in v4m2)
Since v4m2 OpenXava supports JSR-330, the Java standard for dependency injection. In order to inject a session object in an action you only have to annotate a field with @javax.inject.Inject . Thas is, if you have a session object and an action in your controllers.xml as following:<controllers>
<object name="xavatest_activeYear" class="java.lang.Integer" value="2010" scope="global"/>
<controller name="ActiveYear">
<action name="change"
class="org.openxava.test.actions.ChangeActiveYearAction"/>
</controller>
</controllers>
public class ChangeActiveYearAction extends ViewBaseAction {
@Inject
private int activeYear; // Getter and setter are not needed
public void execute() throws Exception {
assert activeYear == 2010; // The value from session object
activeYear = 2012; // It changes the value of session object
}
}As you see, the default name of the session object to inject is the name of the attribute ignoring the prefix (ignoring xavatest_ in this case). Although you can use @Named (also JSR-330 standard) to specify a different name for session object and field:
public class ChangeActiveYearAction extends ViewBaseAction {
@Inject @Named("xavatest_activeYear")
private int year; // getter and setter are not needed
public void execute() throws Exception {
assert year == 2010; // The value from xavatest_actionYear session object
year = 2012; // It changes the value of xavatest_actionYear
}
}Using <use-object /> for dependency injection
Dependency injection has been in OpenXava since its very beginning. The traditional way to inject session objects in an action is by means of <use-object /> in <action/> declaration. If you are using a version previous to v4m2, you must write the above example in using <use-object/> in controllers.xml:<controllers>
<object name="xavatest_activeYear" class="java.lang.Integer" value="2010" scope="global"/>
<controller name="ActiveYear">
<action name="change"
class="org.openxava.test.actions.ChangeActiveYearAction">
<use-object name="xavatest_activeYear"/>
</action>
</controller>
</controllers>public class ChangeActiveYearAction extends ViewBaseAction {
private int activeYear; // No @Inject, we are using <use-object/>
public void execute() throws Exception {
assert activeYear == 2010; // The value from session object
activeYear = 2012; // It changes the value of session object
}
public void setActiveYear(int activeYear) { // Setter and...
this.activeYear = activeYear;
}
public int getActiveYear() { // getter are needed
return activeYear;
}
}<action name="change"
class="org.openxava.test.actions.ChangeActiveYearAction">
<use-object name="xavatest_activeYear" action-property="year"/>
</action>public class ChangeActiveYearAction extends ViewBaseAction {
private int year; // No @Inject, we are using <use-object/>
public void execute() throws Exception {
assert year == 2010; // The value from xavatest_actionYear session object
year = 2012; // It changes the value of xavatest_actionYear
}
public void setYear(int year) { // Setter and...
this.year = year;
}
public int getYear() { // getter are needed
return year;
}
}You can use both <use-object/> and @Inject for dependency injection, but given that JSR-330 is the Java standard it's the favorite one.
(New in v4.7) If the session object to be injected has a property named request, this property is populated with the current HttpServletRequest before injecting the object in the action. It works in this way for objects injected using <use-object/> or @Inject.
Controllers inheritance
You can create a controller that inherits all actions from one or more controllers. An example of this is the generic controller called Typical, this controller is in openxava/src/main/resources/xava/default-controllers.xml (in OpenXava/xava/default-controllers.xml for v6 or older):<controller name="Typical">
<extends controller="Print"/>
<extends controller="CRUD"/>
</controller>You can use inheritance to refine the way a standard controller works, e. g. like this:
<controller name="Family">
<extends controller="Typical" excluded-actions="refresh, delete"/>
<action name="new" icon="library-plus"
class="org.openxava.test.actions.CreateNewFamilyAction">
<use-object name="xava_view"/> <!-- Not needed since v4m2 -->
</action>
</controller>List mode actions
You can write actions that apply to several objects. These actions are usually shown in list mode only and normally have effects on the objects chosen by user only.An example can be:
<action name="deleteSelected" mode="list" <!-- 1 -->
confirm="true" <!-- 2 -->
class="org.openxava.actions.DeleteSelectedAction">
</action>The action source code:
package org.openxava.actions;
import java.util.*;
import org.openxava.model.*;
import org.openxava.validators.*;
/**
* @author Javier Paniza
*/
public class DeleteSelectedAction extends TabBaseAction implements IModelAction { // 1
private String model;
public void execute() throws Exception {
// int [] selectedOnes = getTab().getSelected(); // 2
// int [] selectedOnes = getSelected(); // New in v4m4. Deprecated in v4.7 // 2
Map [] selectedOnes = getSelectedKeys(); // New in 4.7 // 2
if (selectedOnes != null) {
for (int i = 0; i < selectedOnes.length; i++) {
Map key = selectedOnes[i];
try {
MapFacade.remove(model, key); // 3
}
catch (ValidationException ex) {
addError("no_delete_row", new Integer(i), key); // 4
addErrors(ex.getErrors());
}
catch (Exception ex) {
addError("no_delete_row", new Integer(i), key);
}
}
getTab().deselectAll(); // 5
resetDescriptionsCache(); // 6
}
}
public void setModel(String modelName) { // 7
this.model = modelName;
}
}You can access to the Tab using the getTab() method (2); this method is implemented in TabBaseAction and it allows you to access to the xava_tab session object. By means of getTab() you are allowed to manage the list of displayed objects. For example, with getTab().getSelected() (2) you obtain the indexes of selected rows, though since v4m4 is better to use getSelected() instead which is a method from TabBaseAction. Since v4.7 getSelected() is deprecated instead we use getSelectedKeys() that returns the keys map. With getTab().getTableModel() a table model to access to data, and with getTab().deselectAll() you deselect the rows. You can take a look of org.openxava.tab.Tab JavaDoc for more details on its possibilities.
Something very interesting you can see in this example is the use of MapFacade (3). MapFacade allows you to access the data model using Java maps (java.util.Map). This is useful, if you get data from Tab or View in Map format and you want to update the model (and therefore the database) with it, or vice versa. All generic classes of OpenXava use MapFacade to manage the model and you also can use MapFacade. As general design tip: working with maps is useful in the case of generic logic, but if you need to program specific things it is better to use directly the object of model layer. For more details have a look at the JavaDoc of org.openxava.model.MapFacade.
You see here how to display messages to the user with addError(). The addError() method receives the id of an entry in your i18n files and the argument to send to the message. The added messages are displayed to the user as errors. If you want to add warning or informative messages you can use addMessage(), addInfo() (new in v4.3) or addWarning() (new in v4.3) whose behavior is like addError(). The i18n files that hold errors and messages must be called MyProject-messages.properties and the language sufix (_en, _ca, _es, _it, etc). You can see the examples in openxavatest/src/main/resources/i18n (in OpenXavaTest/i18n for v6 or older). All not caught exceptions produces a generic error messages, except if the not caught exception is of the type ValidationException. In this case the message exception is displayed.
The resetDescriptionsCache() (6) method deletes all cache entries used by OpenXava to display descriptions list (combos). It's a good idea to call it whenever data is updated.
You can see more possibilities in org.openxava.actions.BaseAction and org.openxava.actions.TabBaseAction JavaDoc.
Since v2.1.4 this type of actions can also be used as @ListAction for @OneToMany and @Condition collections, but not for calculated collections, @ManyToMany or @OrderColumn lists.
Optional actions (new in v5.9)
You can create actions that are available or hidden based on a programmatic condition. These actions implement the IAvailableAction interface, which defines a method isAvailable() that returns a boolean indicating if the action should be displayed or not.The IAvailableAction interface can be implemented by any type of action (detail, list, collection, etc.). When OpenXava is about to display an action, it checks if the action implements IAvailableAction and if so, it calls the isAvailable() method. If the method returns false, the action is not displayed.
Let's see an example of a list action that is only available for specific rows depending on their content. In this case, the action will only be displayed for rows where the carrier's name is not already in uppercase:
package org.openxava.test.actions;
import java.util.*;
import org.apache.commons.logging.*;
import org.openxava.actions.*;
import org.openxava.model.*;
import org.openxava.test.model.*;
/**
* Action to convert the selected items in a list to uppercase.
* @author Javier Paniza
*/
public class CarrierToUpperCaseAction extends TabBaseAction implements IAvailableAction { // 1
private static Log log = LogFactory.getLog(CarrierToUpperCaseAction.class);
@Override
@SuppressWarnings("unchecked")
public void execute() throws Exception {
Map[] selectedOnes = getSelectedKeys();
for (int i = 0; i < selectedOnes.length; i++) {
Carrier carrier = (Carrier) MapFacade.findEntity("Carrier", selectedOnes[i]);
carrier.setName(carrier.getName().toUpperCase());
}
}
@Override
@SuppressWarnings("unchecked")
public boolean isAvailable() { // 2
try {
if (getRow() < 0) return false; // 3
Map key = getSelectedKeys()[0];
Carrier carrier = (Carrier) MapFacade.findEntity("Carrier", key);
return !carrier.getName().equals(carrier.getName().toUpperCase()); // 4
}
catch (Exception ex) {
log.error("Error checking if CarrierToUpperCaseAction is available", ex);
return false;
}
}
} Note that from the isAvailable() method you have access to the same resources as from the execute() method, such as getRow() or getSelectedKeys(), which allows you to implement complex logic to determine when an action should be available.
Overwriting default search
When a module is shown in list mode and the user clicks to display a detail, then OpenXava searches the corresponding object and displays it in detail. Now, if in detail mode the user fills the key fields and clicks on search (the binoculars), it also does the same. And when the user navigates by the records clicking the next or previous buttons then it does the same search. How can you customize this search? Let's see that:You only need to define the module in src/main/resources/xava/application.xml (just in xava folder for v6 or older) this way:
<module name="Deliveries">
<env-var name="XAVA_SEARCH_ACTION" value="Deliveries.search"/>
<model name="Delivery"/>
<controller name="Typical"/>
<controller name="Remarks"/>
<controller name="Deliveries"/>
</module><controller name="Deliveries">
<action name="search" mode="detail"
by-default="if-possible" hidden="true"
class="org.openxava.test.actions.SearchDeliveryAction"
keystroke="F8">
<use-object name="xava_view"/> <!-- Not needed since v4m2 -->
</action>
...
</controller>package org.openxava.test.actions;
import java.util.*;
import org.openxava.actions.*;
import org.openxava.util.*;
/**
* @author Javier Paniza
*/
public class SearchDeliveryAction extends SearchByViewKeyAction { // 1
public void execute() throws Exception {
super.execute(); // 2
if (!Is.emptyString(getView().getValueString("employee"))) {
getView().setValue("deliveredBy", new Integer(1));
getView().setHidden("carrier", true);
getView().setHidden("employee", false);
}
else {
Map carrier = (Map) getView().getValue("carrier");
if (!(carrier == null || carrier.isEmpty())) {
getView().setValue("deliveredBy", new Integer(2));
getView().setHidden("carrier", false);
getView().setHidden("employee", true);
}
else {
getView().setHidden("carrier", true);
getView().setHidden("employee", true);
}
}
}
}OpenXava comes with 3 predefined search actions:
- CRUD.searchByViewKey: This is the default one. It does a search using the key values in the view, it executes no event.
- CRUD.searchExecutingOnChange: Works as searchByViewKey but it executes the @OnChange/on-change actions after search data.
- CRUD.searchReadOnly: Works as searchByViewKey but it set the detail view to not editable state on searching. Useful for creating read only modules.
<module name="Products3ChangeActionsOnSearch">
<env-var name="XAVA_SEARCH_ACTION" value="CRUD.searchExecutingOnChange"/>
<model name="Product3"/>
<view name="WithDescriptionsList"/>
<controller name="Typical"/>
<controller name="Products3"/>
</module>Initialize a module with an action
By setting on-init=”true” when you define an action, you configure that this action will be executed automatically when the module is executed for the first time. This is a chance to initialize the module. Let's see an example. In your controllers.xml you write:<controller name="Invoices2002">
<action name="init" on-init="true" hidden="true"
class="org.openxava.test.actions.InitDefaultYearTo2002Action">
<!-- <use-object name="xavatest_defaultYear"/>
Since v4m2 you can use @Inject instead -->
<!-- <use-object name="xava_tab"/>
Since v4m2 you can use @Inject instead -->
</action>
...
</controller>package org.openxava.test.actions;
import javax.inject.*;
import org.openxava.actions.*;
import org.openxava.tab.*;
/**
* @author Javier Paniza
*/
public class InitDefaultYearTo2002Action extends BaseAction {
@Inject // Since 4m2, if you do not use <use-object />
private int defaultYear;
@Inject // Since 4m2, if you do not use <use-object />
private Tab tab;
public void execute() throws Exception {
setDefaultYear(2002); // 1
tab.setTitleVisible(true); // 2
tab.setTitleArgument(new Integer(2002)); // 3
}
public int getDefaultYear() {
return defaultYear;
}
public void setDefaultYear(int i) {
defaultYear = i;
}
public Tab getTab() {
return tab;
}
public void setTab(Tab tab) {
this.tab = tab;
}
}Calling another module
Sometimes it's convenient to call programmatically one module from another one. For example, imagine that you want to show a list of customers and when the user clicks on one customer, then a list of its invoices is displayed and the user can choose an invoice to edit. One way to obtain this effect is to have a module with only list mode and when the user clicks on a detail, the user is directed to an invoices module that shows only the invoices of the chosen customer. Let's see it. First you need to define the module in application.xml this way:<module name="InvoicesFromCustomers">
<env-var name="XAVA_LIST_ACTION" value="Invoices.listOfCustomer"/> <!-- 1 -->
<model name="Customer"/>
<controller name="Print"/>
<controller name="ListOnly"/> <!-- 2 Not needed since v6.0 -->
<mode-controller name="Void"/> <!-- 3 Not needed since v6.0 -->
</module>