This is version 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 . It is not the current version, and thus it cannot be edited.

Back to current version Restore this version

JSF Ext oder JSF Extensions ist nun die dritte Auflage unserer beliebten Erweiterungen für JSF. Nach den Versionen Intersult Taglib für JSF 1.2, JSF Desktop für JSF 2.0 ist nun JSF Ext für JSF 2.0 bis 2.2 verfügbar. JSF Ext ist eine Erweiterung von JSF 2 (2.0, 2.1, 2.2) um einige grundlegende Features, die man für saubere, funktionale AJAX-Applikationen braucht.

JSF Ext wurde weiter vereinfacht, sodass eine hohe Geschwindigkeit der Web-Seiten erreicht werden kann. JSF Ext wurde optimiert, sodass höchst mögliche Kompatibilität mit anderen Produkten sichergestellt ist. Sollten Sie Fragen, Bugs oder Feature-Requests haben, so nutzen sie bitte die Issue List.

Übersicht der Features:

• Dynamik: Echtes dynamisches Laden von Teilen großer Views
• Scopes: Component-Scopes mit komfortabler Load-/Unload-Funktion
• Messages: Vereinfachte Fehlerbehandlung
• Events: Einfach nutzbare Events und automatisches Rendering
• Push: AJAX-Push unabhängig von verwendeten Framework
• Kompatibilität: Arbeitet zusammen mit Primefaces, Richfaces, Spring etc.
• Fertigstellung/Fixes: Multipart-Requests (Submit/AJAX), View State Fix, Compatibility, AJAX Insert und Delete etc.
• Persistence: JSF Ext läuft auch ohne Hibernate, diese Funktionalität befindet sich in JPA Support.

Folgende Inhalte befinden sich auf eigenen Wiki-Seiten:

• JSF Ext Tags
• JSF Ext Scopes
• JSF Ext Events
• JSF Ext Push
• JSF Ext Functions
• Faces Filter

Inhalt#

Overview#

The main features of the JSF Ext (formerly JSF Desktop) are:

• Events: Event sources and registration. Java beans and components can produce events, other beans and components can consume them. This includes rendering and updating components, even using AJAX requests.
• Messages: Clean message handling. Exceptions are converted to faces messages, using normal or AJAX requests. An event is raised, thus you can update your message components.
• Dynamic Includes: Clean component tree and small network traffic. Facelets can dynamically are loaded from XHTML sources when needed through AJAX requests. No more overloaded component trees, no waiting for loading all the megabytes to your browser. You can include as much popups, tabs and other elements in your page without slowing it down. Everything is just loaded when needed. And much better, its also can be unloaded when finished. Both DOM and component tree stays clean.
• Custom Scopes: Use custom scopes within your loaded facelets, they are cleaned up when finished. No more manual clearing of data from popups. Nice memory footprint and save data.
• Integration: JSF Ext works perfectly together with Richfaces, Primefaces and other component libraries.

Konfiguration#

JSF Ext kann von Central bezogen werden:

In der pom.xml für den Maven-Build wird angegeben:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	...
	<dependencies>
		<dependency>
			<groupId>com.intersult</groupId>
			<artifactId>jsf-ext</artifactId>
			<version>2.2.0.1</version>
		</dependency>
                ...
	</dependencies>
</project>

JSF Ext includes namespaces e and ext. There are two namespaces, because JSF Ext contains both classic tags and on-the-fly facelet tags. In your XHTML-Pages, include the namespaces:

	xmlns:e="http://java.sun.com/jsf/ext"
	xmlns:ext="http://java.sun.com/jsf/composite/ext"

Kompatibilität#

Demo unserer Desktop-Plattform auf der Basis von JSF v2, die auch auf GAE lauffähig ist:

Damit setzen Sie komplexe, interaktive Applications im Handumdrehen auf.

Annotations und InjectionProvider#

JSF Ext ist darauf ausgelegt, ohne größere Konfiguration benutzt werden zu können. Viele Features können Out-of-the-Box verwendet werden, sobald sich das jsf-ext.jar in der Web-Application in /WEB-INF/lib befindet.

Bei einigen Features und Konstellationen ist es von Vorteil, bestimmte Konfigurationen vorzunehmen. Wie bereits in JSF2 erwähnt, werden in einigen Servlet-Containern die Annotations nicht verarbeitet. JSF Ext registriert einen sogenannten InjectionProvider, was im Normalfall transparent funktioniert.

Falls man feststellt, dass die Events im JSF Ext nicht arbeiten, Oberflächenelemente nicht aktualisiert werden und Messages nicht angezeigt werden, dann arbeiten vermutlich auch übliche JSF-Annotations @ManagedBean oder @SessionScoped nicht. Abhilfe schafft dann:

	<context-param>
		<param-name>com.sun.faces.injectionProvider</param-name>
		<param-value>com.intersult.jsf.event.EventInjectionProvider</param-value>
	</context-param>

AJAX-Queue#

Üblicher Weise werden AJAX-Aufrufe serialisiert. Generell macht dies Sinn, da es sonst zu Problemen mit dem View-State kommt. Aktiviert wird das Parallelisieren von AJAX-Aufrufen durch das Setzen der JavaScript-Variable "jsf.ajaxQueue":

	<script type="text/javascript">
		jsf.ajaxQueue = 2;
	</script>

Warnung: Aus gutem Grund werden die AJAX-Requests üblicher Weise serialisiert. Beim Verwenden paralleler AJAX-Requests besteht die Gefahr, einen veralteten View-State an den Server zu senden. Parallele Requests werden nur korrekt arbeiten, wenn ausgeschlossen wird, dass ein Formular mehrere Abfragen gleichzeitig abschickt.

Tag-Support#

JSF Ext bietet eine Reihe von Features, die den Bau von eigenen Tags unterstützen.

Composite Tags sind ein mächtiges und zugleich einfach zu handhabendes Instrument zum Erstellen eigener Taglibs. Durch einige zusätzliche Instrumente werden Composite Tags noch vielseitiger. Damit kann vielfach auf die Entwicklung von nativen Tags verzichtet werden, inklusive aufwändiger Compile, Redeploy und Restart-Zyklen. Durch die erweiterten Möglichkeiten steigt gleichzeitig der Anreiz zu Composite Tags.

Composite Behaviors#

Beim Bau von Composite-Tags möchte man in einigen Fällen auf den darüberliegenden Tag zugreifen.

Hintergrund: Die EL-Expression #{component.parent.parent.parent} (dazwischen zwei UINamingContainer und UIPanel die Facelets einfügt) würde normaler Weise den Parent-Tag liefern, evaluiert jedoch zu null. Zum einen ist zu dieser Zeit die Tag-Hierarchie noch nicht aufgebaut, zum anderen wird der UINamingContainer aus der Facelet-Hierarchie herausgenommen, da der Tag durch einen speziellen Mechanismus gerendert wird.

Lösung:

Zugriff über jsf, also #{jsf.tag.composite.parent.component}. Folgendes Beispiel zeigt eine Composite-Component für ein Mouse-Behavior:

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml"
	xmlns:ui="http://java.sun.com/jsf/facelets"
	xmlns:h="http://java.sun.com/jsf/html"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:c="http://java.sun.com/jsp/jstl/core"
	xmlns:cc="http://java.sun.com/jsf/composite"
	xmlns:e="http://java.sun.com/jsf/ext"
	xmlns:ext="http://java.sun.com/jsf/composite/ext"
>
	<cc:interface>
	</cc:interface>
	<cc:implementation>
		<e:behavior id="mouseover" event="mouseover" for="#{jsf.tag.composite.parent.component}" script="focus();"/>
		<e:behavior id="mouseout" event="mouseout" for="#{jsf.tag.composite.parent.component}" script="blur();"/>
	</cc:implementation>
</html>

Dieser Tag ist bereits Bestandteil des JSF-Ext unter <ext:mouse-focus>. Er kann zusammen mit jedem ClientBehaviorHolder, wie dem <e:div> angewendet werden.

Forms und AJAX#

Wird eine Komponente durch AJAX neu gerendered, die eine FORM enthält, geht der View-State der FORM verloren. In einigen Fällen kann dies verhindert werden, in dem die Form explizit im Render-Attribut eines AJAX-Tags angegeben wird. Im Zusammenhang mit Include-Anweisungen, wie auch den Scopes ist dies nur bedingt möglich.

JSF Ext löst dieses Problem durch zusätzlichen Java-Script Code. Durch das Einbinden der JAR-Bibliothek ist das Problem transparent gelöst. Der enthaltene Java-Script Code wird immer dann eingebunden, wenn auch der JSF-AJAX-Code eingebunden wird. Er fügt den ViewState in enthaltenenen FORM-Tags ein, sodass keine zusätzlichen Render-Anweisungen benötigt werden.

Der ExtResponseWriter#

JSF-Behaviors bestehen aus einer Klasse die von Behavior oder ClientBehavior abgeleitet sind. Im Wesentlichen ist eine Methode getScript enthalten, mit der ein Fragment des entsprechenden event-Attribut des entsprechenden HTML-Tags gerendert wird, also zum Beispiel onclick="...". Bei komplexeren Behaviors braucht man zusätzlichen HTML-Code, der kann an dieser Stelle nicht geschrieben werden. Ursache ist dass der HTML-Writer sich gerade innerhalb des geöffneten Tags befindet und startElement ungültiges HTML erzeugen würde.

Der ExtResponseWriter von JSF Ext stellt eine statische Methode getEndElementWriter(ResponseWriter responseWriter) bzw. getEndElementWriter() zur Verfügung. Damit bekommt man einen ResponseWriter, mit dem geschrieben werden kann. Der HTML-Code wir dann effektiv vor dem Schließen des End-Tags ausgegeben:

	ResponseWriter writer = ExtResponseWriter.getEndElementWriter();
	writer.startElement("div", component);
	writer.writeAttribute("id", component.getClientId(behaviorContext.getFacesContext()), null);
	writer.writeAttribute("style", "display: none;", null);
	writer.endElement("div");

Components referenzieren#

In JSF gibt es drei Arten von Referenz-Ausdrücken in render und execute Ausdrücken, relative, absolute und meta:

• Absolute: Beispielsweise :form:panel:input-text
• Relative: panel:input-Text
• Meta: @this, @component, @form, @all

Meist arbeitet man soweit es geht mit relativen Ausdrucken und wechselt notfalls zu absoluten. Um die allgemeine Verwendbarkeit von absoluten Ausdrücken in Composite Components zu gewährleisten, beginnt man diese etwa mit :#{cc.clientId}:input-Text. Das funktioniert leider nicht immer, insbesondere wenn Tabellen, For-Tags oder andere dynamische Elemente darüber liegen.

Dazu führt JSF Ext die Syntax ".." ein, die man bereits von relativen Pfadangaben im Dateisystem kennt. Damit ist es nun möglich innerhalb einer Composite Component einen oder einige Components nach oben zu gehen und von dort ab etwas zu selektieren. Also die Kombination von relativen Angaben und Erreichbarkeit der Components:

<e:ajax render="..:#{cc.id}:panel"/>

Hinweis: Jede Angabe von ".." geht eine Naming-Container nach oben. Components die kein Naming Container sind, werden dabei übersprungen, ebenso wie beim ursprünglichen Absteigen im Component Tree mit x:y:z.

Internationalisierung#

JSF Ext enthält einige Erweiterungen, die den Umgang mit Sprach- und Länderunterstützung erleichtern. Es sind SelectItems für Sprachen, Länder und Währungen vorhanden, damit können unter anderem Drop-Down-Menüs befüllt werden:

<h:selectOneMenu id="country" value="#{bean.country}">
	<f:selectItems value="#{locales.countrySelectItems}"/>
</h:selectOneMenu>
<h:selectOneMenu id="language" value="#{bean.language}">
	<f:selectItems value="#{locales.languageSelectItems}"/>
</h:selectOneMenu>
<h:selectOneMenu id="currency" value="#{bean.currency}">
	<f:selectItems value="#{locales.currencySelectItems}"/>
</h:selectOneMenu>

Zusätzlich befindet sich noch ein Getter für localeSelectItems. Dies liefert Liste vollwertiger Locale-Elemente aus Locale.getAvailableLocales() in einer auf der Oberfläche darstellbaren Form.

Des Weiteren befindet sich ein Feld für eine User-Locale in der Session-Scoped Bean. Dadurch kann ein einfaches Auswählen der Locale erreicht werden:

<h:selectOneMenu id="language" value="#{locales.locale}" converter="intersult.String">
	<f:selectItems value="#{locales.localeSelectItems}"/>
</h:selectOneMenu>

Der Converter "intersult.String" konvertiert ein Locale-Element in einen Sprach-String und zurück, damit das Locale-Objekt mit dem selectOneMenu verwendet werden kann.

Properties Resources#

In JSF können Properties-Dateien definiert werden, die entsprechend der Endung im Namen für die Internationalisierung verwendet werden können. Um auch aus dem Java-Code darauf zugreifen zu können, gibt es die Klasse com.intersult.jsf.messages.Resource:

Methode	Beschreibung
getString	Den Resource-String zurückgeben. Falls nicht vorhanden, wird ein Dummy zurückgegeben.
getStringNull	Den Resource-String zurückgeben. Falls nicht vorhanden, wird null zurückgegeben.
getStringVariant	Eine Variante eines Resource-Strings zurückgeben.
getFormatVariant	Eine formatierte Variante eines Resource-Key zurückgeben.
getFormat	Einen formatierten Resource-String zurückgeben.
addMessage	Eine globale Faces-Message aus einem Resource-Key hinzufügen.
addMessageToComponent	Eine Faces-Message aus einem Resource-Key zu einer Komponente hinzufügen.
getMessage	Eine Faces-Message aus einem Ressource-Key erzeugen
enumFormat	Einen formatierten Resource-String für ein Enum zurückgeben.
enumFormatVariant	Eine Variante eines formatierten Resource-String für ein Enum zurückgeben.
enumString	Einen Resource-String für ein Enum zurückgeben.
enumList	Eine Liste mit Enums zurückgeben.
enumStringList	Eine Liste mit Enum-Strings zurückgeben.
enumStringListVariant	Eine Liste mit Varianten von Enum-Stringe zurückgeben.
enumSelectItems	SelectItems für das Befüllen von JSF-Elementen (Dropdowns etc.) zurückgeben
enumSelectItemsType	SelectItems für einen Enum-Type zurückgeben.
enumSelectItemsTypeVariant	SelectItems für Varianten eines Enum-Types zurückgeben.
enumSelectItem	Ein einzelnes SelectItem erzeugen.
abbreviate	Einen String für die Oberfläche abkürzen.
replaceHtml	HTML-Sonderzeichen ersetzen.

Spring Framework#

JSF Ext arbeitet mit dem Spring Framework zusammen. Für die Spring-JSF-Integration ist es sinnvoll zunächst den EL-Resolver von Spring zu registrieren:

<faces-config>
	<application>
		<el-resolver>org.springframework.web.jsf.el.SpringBeanFacesELResolver</el-resolver>
	</application>
</faces-config>

Scopes#

Wenn man nicht nur JSF Managed Beans im Custom Scope von JSF Ext haben möchte, kann dieser auch in der applicationContext.xml registriert werden:

	<import resource="classpath:/META-INF/extContext.xml"/>

Hinweis: JSF Ext registriert zusätzlich den ViewScope von JSF.

Beispiel#

Zum Beispiel wäre dann folgende Konstruktion möglich:

Beim Laden des Scopes:

<e:load scopeId="rule-remove">
    <f:param name="rule" value="#{rule}"/>
</e:load>

Innerhalb des Scopes:

<h:commandButton value="#{messages['remove']}" action="#{ruleEditController.remove}">
	<f:ajax/>
	<e:unload/>
</h:commandButton>

Der Controller dazu:

@Component
@Scope(WebApplicationContext.SCOPE_REQUEST)
public class RuleEditController {
    @ScopeValue
    private Rule rule;

    @Transactional
    public void remove() {
        ...
    }
}

Erklärung: Damit ist es möglich, eine Entity- oder andere Modell-Bean innerhalb eines Scopes zu bearbeiten, dessen Lebenszyklus an ein AJAX-Popup gekoppelt ist. Es ist keine weitere Java-Bean erforderlich, die in einem Scope abgelegt werden muss. Alle parameterisierten Beans werden beim Beenden (Unload) des Scopes freigegeben.

Hinweis: Der Controller ist mit der Annotation @Scope(WebApplicationContext.SCOPE_REQUEST), damit die Injection im richtigen Scope erfolgt. Der Scope kann sich mit jedem Request ändern.

Hinweis: Statt die ineffiziente Value-Injection über EL-Expression stellt die JSF Spring Integration eine direkte Injection von Scope-Werten durch die Annotation @ScopeValue zur Verfügung.

Ablegen einer Spring-Bean im Scope#

Spring Beans können auch im Custom-Scope abgelegt werden:

@Component
@Scope(Scopes.CUSTOM_SCOPE)
public class Popup {
    ...
}

Oder im View-Scope:

@Component
@Scope(Scopes.VIEW_SCOPE)
public class Popup {
    ...
}

Events#

Um die Annotation @Listener auch in Spring-Beans verwenden zu können, kann man den EventBeanProcessor in Spring registrieren:

    <bean class="com.intersult.jsf.spring.EventBeanProcessor"/>

Beispiel#

Der Listener kann verwendet werden, um Inhalte von Ergebnislisten bei bedarf neu zu generieren:

@Component
@Scope(WebApplicationContext.SCOPE_REQUEST)
public class QueryController {
    @Transactional
    @Listener(Rule.EVENT_CHANGED)
    public void execute() {
        ...
    }

Hinweis: Es ist darauf zu achten, dass betreffende Spring-Beans mit einem entsprechenden Scope versehen werden, wie zum Beispiel @Scope(WebApplicationContext.SCOPE_REQUEST). Die Events können nicht während der Startphase der Applikation gebunden werden, da hier JSF noch nicht initialisiert ist.

Primefaces#

JSF Ext integriert sich mit einer Reihe von Frameworks und liefert dafür Tools, die teilweise transparent ablaufen.

• Richfaces: Zusätzlich zu dem Form-Submit Problemen bei JSF selbst, treten zusätzliche Render-Probleme im Zusammenhang mit dem AJAX und Richfaces Popups auf. Diese werden durch das in JSF Ext enthaltene Javascript ajax.js transparent gelöst. Es können alls Popups und Elemente, die Forms enthalten neu gerendert werden, ohne dass die Submit-Funktionalität von Command-Buttons udn anderen Steuerelementen verloren geht.
• Spring: Wie bereits im Abschnitt über Scopes beschrieben, können auch Spring-Beans für Scopes und andere JSF Ext Elemente verwendet werden.
• Primefaces: Primefaces Dialogs <p:dialog> können zusammen mit <e:scope> verwendet werden, um ganz unabhängige Dialoge zu realisieren. Zusätzlich liefert JSF Ext eine Lösung zum Anpassen anderer Buttons an das Primefaces Layout.

Primefaces Buttons#

Beim Verwenden von Primefaces werden <h:inputCommand> und native HTML-Buttons nicht im Primefaces-Style dargestellt. Folgende Einträge korrigieren dies (zumindest für Primefaces 3.3):

1. Im pom.xml die jsf-ext eintragen, wie in JSF Ext beschrieben.

1. Ins Page-Template folgenden Eingrag am Ende des Body-Tags vornehmen:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
	xmlns:h="http://java.sun.com/jsf/html"
	...
	<h:head id="head">
            ...
	</h:head>
	<h:body id="body">
            ...
		<h:outputStylesheet name="primefaces.css" library="css"/>
		<h:outputScript name="primefaces.js" library="ext-js"/>
	</h:body>
</html>

Danach erscheinen alle <h:commandButton> und andere Buttons im Primefaces Style.

Validieren#

Die Validierung von Eingabewerten ist von der Idee her eine gute Sache, die Konfiguration ist allerdings nicht ganz so leicht. Spätestens wenn in den Faces-Messages die ClientId der betreffenden Komponenten beim Benutzer am Bildschirm erscheinen, hat man das Gefühl es fehlt noch etwas.

Mit JSF Ext kann das Ganze so aussehen:

Die JSF-Validators werden direkt im Frontend angebracht, also in den XHTML-Dateien. Damit können Felder unterschiedlich validiert werden und Situations abhängige Logik implementiert werden. Zum Beispiel kann gesprüft werden, ob zwei Felder gleich sein müssen. Eine Sonderrolle spielt das Attribut required bei vielen UIInput-Elementen, mit dem eine Eingabe erzwungen werden kann.

Bean-Validators werden in Application Support behandelt.

Unique-Validator#

Mit dem Unique-Validator kann ein Property geprüft werden, ob es nur einmal in der Datenbank existiert. Der Unique-Validator braucht den Application Support als Abhängigkeit, da auf das Spring-Entity-Management zugegriffen werden muss.

<h:outputLabel for="name" value="Name"/>
<h:inputText id="name" value="#{userEdit.user.name}" required="true"
    validator="intersult.Unique"/>

Erklärung: Der Unique-Validator holt sich die Entity-Klasse und Property über die EL-Expression für das Attribut "value" und prüft ob dieser bereits in der Datenbank vorhanden ist. Falls die Bean bereits persistent ist, wird der betreffende Wert außgenommen, sodass die Bean auch mit demselben Wert für das Property geupdatet werden kann.

Input-Wrapper#

Der Input-Wrapper ist ein Composite-Tag der um ein Input-Element gelegt werden kann. Dadurch werden FacesMessages hinzugefügt und AJAX-Submit ausgeführt, wenn der Wert geändert wird. Das Layout von Eingabeelementen wird dabei vereinheitlicht.

Dabei kann man wählen, welche Teile man benutzen möchte. Ganz bequem geht es mit dem Tag <ext:input>. Damit gewrappte Eingabe-Steuerelemente werden automatisch AJAX-Validiert und mit Faces Messages versehen.

<h:form id="some-form">
    <h:outputLabel for="name:name" value="Name"/>
    <ext:input id="name">
        <h:inputText id="name" value="#{userEdit.user.name}" required="true"/>
    </ext:input>
</h:form>

Der Input-Wrapper-Tag ist eine Composite-Component, die man so verwenden kann wie sie ist. Oder man benutzt den Code als Vorlage für ein eigenes Projekt-Layout:

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html"
	xmlns:c="http://java.sun.com/jsp/jstl/core"
	xmlns:ui="http://java.sun.com/jsf/facelets"
        xmlns:cc="http://java.sun.com/jsf/composite"
	xmlns:e="http://java.sun.com/jsf/ext"
	xmlns:ext="http://java.sun.com/jsf/composite/ext"

	<cc:interface>
		<cc:attribute name="inputId" default=":#{cc.children[0].clientId}"/>
		<cc:attribute name="styleClass"/>
		<cc:attribute name="style"/>
	</cc:interface>
	<cc:implementation>
		<h:panelGrid cellpadding="0" cellspacing="0" style="#{cc.attrs.style}" styleClass="#{cc.attrs.styleClass}">
			<e:insert component="#{cc.children[0]}">
				<e:ajax event="change"/>
			</e:insert>
			<ext:message id="message" for="#{cc.attrs.inputId}"/>
		</h:panelGrid>
	</cc:implementation>
</html>

Der entsprechende Messages-Tag:

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html"
	xmlns:c="http://java.sun.com/jsp/jstl/core"
	xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:cc="http://java.sun.com/jsf/composite"
	xmlns:e="http://java.sun.com/jsf/ext"
	xmlns:ext="http://java.sun.com/jsf/composite/ext"
	xmlns:p="http://primefaces.org/ui"
>
	<cc:interface>
		<cc:attribute name="for"/>
	</cc:interface>
	<cc:implementation>
		<h:outputStylesheet name="faces-messages.css" library="css"/>
		<h:message id="message" for="#{cc.attrs.for}" infoClass="msg-info" warnClass="msg-warn" errorClass="msg-error">
			<e:render event="#{cc.attrs.for}"/>
		</h:message>
	</cc:implementation>
</html>

Die Styles befinden sich im JSF Ext und werden automatisch in den Header geladen.

Validation Messages#

Die ValidationException von JSF nimmt den String direkt. JSF Ext stellt eine Ableitung davon zur Verfügung, mit der ein Resource-Key übergeben werden kann. Damit ist eine Internationalisierung möglich:

throw new ValidatorResourceException("user.unique.name");

Converter#

SelectOneMenu und SelectItem#

Das SelectOneMenu und andere Auswahlelemente können nicht direkt mit Objekten umgehen. Eine generische Lösung bietet der intersult.SelectItemConverter:

<h:selectOneMenu id="start" value="#{workflowEdit.workflow.start}" converter="intersult.SelectItemConverter">
	<f:selectItem itemLabel="#{messages['select']}" noSelectionOption="true"/>
	<f:selectItems value="#{transitionList.stateList}" var="state" itemLabel="#{state.name}" itemValue="#{state}"/>
</h:selectOneMenu>

Erklärung: Der SelectItemConverter nummeriert die SelectItems durch, nutzt dann hashCode- und equals-Methoden um diese wiederzufinden. Bei den Elementen <f:selectItem> kann nun für itemValue die vollwertige Java-Bean angegeben werden, die auch beim Element <h:selectOneMenu> bei value verwendet wird.

Bemerkung: Da für den Browser jedes Element eine Nummer bekommt und nur diese an den Server zurückgeschickt wird, kann es beim zwischenzeitlichen Verändern der Liste zur Auswahl es falschen Elements kommen. Im Regelfall befindet sich die korrekte Liste noch im Component-Tree, sodass der Fehler nicht auftritt.

String-Constructor#

Der Converter intersult.String ist ein allgemeiner Converter für Objekte, die einen Constructor mit einem String-Argument besitzen und toString implementiert ist. Typischer Weise implementiert man einfache Datentypen auf diese Weise, dazu gehört auch Locale.

Language und Country#

Die beiden Converter intersult.Language konvertiert ein Locale-Objekt nach dem Language-Anteil als String. Der Converter intersult.Country benutzt den Country-Anteil. Ein Converter für den kompletten Anteil ist nicht erforderlich, da hierfür der Converter intersult.String herangezogen werden kann.

Display-Language und -Country#

Im Gegensatz zu Language- und Country-Converter konvertieren diese Converter einen Language- oder Country-String zu einem lesbaren String.

Files und Resources#

File Upload#

File Upload und Multipart-Requests war schon immer ein wenig behandeltes Thema in JSF. In JSF 2.2 hat man zwar im Zusammenhang mit dem Servlet Standard 3 einen File Upload. Allerdings funktioniert dieser nur ab Tomcat 7 und nicht zusammen mit AJAX.

Das JSF Ext ermöglicht Multipart-Requests und damit auch File Uploads mit Servlet Standard 2. Darüber hinaus ist auch ein Submit mit AJAX möglich. Folgendes Beispiel zeigt die Anwendung:

	<h:form id="form" enctype="multipart/form-data">
		<h:inputText id="text" value="#{fileUpload.text}"/>
		<e:inputFile id="file" value="#{fileUpload.file}" filename="#{fileUpload.filename}"
			mimeType="#{fileUpload.mimeType}"/>
		<h:commandButton value="Save" action="#{fileUpload.save}">
			<f:ajax execute="@form"/>
		</h:commandButton>
	</h:form>

Der Tag <e:inputFile> hat folgende EL-Parameter:

Name	Jave-Typ	Beschreibung
value	byte	Enthält den Inhalt der Datei. Bei Bedarf wird noch eine Stream-Lösung geliefert.
filename	String	Enthält den Filenamen der Datei.
mimeType	String	Enthält den vom Browser gesendeten Mime-Type.

Resource Provider#

Ab JSF 2 ist es zwar möglich Resource Handler von dem Interface ResourceHandler abzuleiten. Allerdings erfordert die Implementierung weitere Klassen und eine Vielzahl von Methoden, einen Faces Wrapper und das Registrieren im Faces Context.

Eleganter geht es mit der Annotation @ResourceProvider, diese verwandelt die Methode einer Spring-Bean zu einem Resource Handler:

	@ResourceProvider("file")
	public boolean handleResourceRequest(String resourceName) throws IOException {
		if (file == null)
			return false;
		FacesContext context = FacesContext.getCurrentInstance();
		context.getExternalContext().getResponseOutputStream().write(file);
		context.getExternalContext().setResponseContentType(mimeType);
		context.getExternalContext().setResponseContentLength(file.length);
		context.responseComplete();
		return true;
	}

Erklärung: Hier wirde explizit der Library-Name "file" angegeben, da die Methode nur auszugsweise gezeigt wird. Dieser Wert kann weggelassen werden, dann wird der Name der Spring-Bean verwendet. Dies vereinfacht auch das Wiederfinden eines Resource Providers.

Hinweis: Dieses Features verwendet zusätzlich Application Support und JSF Spring Integration. In der Regel wird es sich um ein Singleton (SCOPE_SINGLETON) handeln, also dem Default-Scope für eine Spring-Bean. Es können allerdings auch andere Scopes verwendet werden, wie Session Scope, beispielsweise um Nutzer spezifische Daten vorhalten zu können.

Achtung: Es gibt Servlet-Filter, welche den InputStream des HttpServletRequest nicht korrekt durchreichen. Sie sollten diese Filter ausschalten, sonst kann der File-Upload nicht an die entsprechende Datei herankommen.

Utilities und Tools#

JSF Ext enthält einige Instrumente zur Unterstützung der Entwicklung von weiteren Tool- und Component-Bibliotheken für JSF.

Document Writer#

JSF bietet die Möglichkeit zum Einsatz von Render-Kits, also eine alternative Darstellung der XHTML-Seiten. Der Standard-Writer schreibt allerdings HTML-Code direkt als Stream. Für Anwendung wie z.B. PDF generieren wäre sinnvoll, auf den Document-Tree zuzugreifen. Dafür kann der Document Writer eingesetzt werden:

DocumentWriter writer = new DocumentWriter(context.getResponseWriter(), "application/pdf");
context.setResponseWriter(writer);

Hinweis: Für die Integration in den JSF Lifecycle sind noch einige andere Dinge zu beachten. Dies zu erklären wäre zu umfangreich für diese Dokumentation, dies kann in der Dokumentation für JSF nachgelesen werden.

XML Rendering#

Soll die Seite direkt als XML gerendert werden, bietet JSF Ext noch eine weitere Kapselung des Document Writer an. Die Methode Jsf.renderViewXml kann direkt aus einem HTTP-Request ein XHTML-Document rendern, ohne über das JSF-Servlet zu gehen.

Dies kann nützlich sein, wenn der Document-Tree weiter verarbeitet werden soll, zum Beispiel zum Generieren anderer Ansichten.

Hinweis: Für PDF steht das PDF Renderkit zur Verfügung. Andere Browser- und Download-Ansichten sollten generell in der Form eines Renderkit zur Verfügung gestellt werden. Für weitere Unterstützung beraten wir Sie gerne.

Unwrapping FacesWrapper#

Vor allem seit JSF 2 wurde die faces-config.xml weiter ausgebaut. JSF-Komponenten können viele JSF-Klassen wrappen, indem sie das Interface FacesWrapper implementieren. Einige Klassen haben diesen Wrapper bereits implementiert, sodass sie nur noch abgeleitet werden brauchen. JSF Ext enthält noch weitere Wrapper im Package com.intersult.jsf.wrapper.*, wie zum Beispiel ViewRootWrapper oder ValueExpressionWrapper, die das Implementieren von Komponenten unterstützen können.

Dahinter liegender Sinn ist das Zusammenspiel mehrerer Faces-Erweiterungen nebenher. Die Wrapper werden in unbestimmter Reihenfolge aufgerufen, sodass jede betroffene Klasse prüfen kann, ob sie etwas zu tun hat. Falls nicht, gibt sie den Aufruf einfach an die Wrapped Instance weiter.

Einen Nachteil gibt es bei der Sache: Hat man FacesWrapper erst einmal abgeleitet, kommt man meist nur mehr sehr schwierig an die eigene Klasse ran. Abhilfe schafft die Methode Jsf.unwrap, mit der man seine eigenen (oder auch fremde) Klassen in der Wrapper-Kette findet:

ExtFacesContext extContext = Jsf.unwrap(parent, ExtFacesContext.class);

Expression Analyzer#

Methoden um Referenzen auf EL-Expressions zu bekommen, Expressions umzuwandeln. Wird gebraucht, um Validierungen an der Oberfläche vornehmen zu können.

ValueReference reference = ExpressionAnalyzer.getReference(expression, context.getELContext());
Object base = reference.getBase();

Interpolator#

Mit dem Interpolator können EL-Expressions innerhalb eines Strings ersetzt werden.

Methode	Bedeutung
interpolate	Einen String interpolieren.
evaluate	Eine Expression evaluieren.
create	Eine neue EL-Expression anlegen.
createMethodExpression	Eine Method-Expression erzeugen.
createValueExpression	Eine Value-Expression erzeugen.
createLiteral	Eine Literal-Expression erzeugen.
coerce	Eine Typumwandlung vornehmen.
setVariable	Eine Variable setzen.
restoreVariable	Eine Variable wiederherstellen.
action	Eine Action-Expression ausführen.
converterFor	Einen Converter für eine bestimmte Klasse holen.

IO Utils#

Methoden für das Schreiben, Lesen und Kopieren von Streams:

IOUtils.copy(binaryStream, outputStream);

Navigation#

JSF Ext enthält eine transparente Lösung für das Redirect-After-Submit-Pattern. Am besten arbeitet diese Lösung mit web.xml 3.0 und Application-Servern, wie Tomcat 7, die diesen Standard unterstützen.

Hintergrund: Ohne Redirect-After-Submit wird nach der Navigation auf eine andere Seite in der Browser-URL-Zeile die vorhergehende Seite angezeigt. Des Weiteren wird bei einem Seiten-Request die für den Benutzer oft unverständliche Meldung angezeigt, ob die Seite nochmal abgeschickt werden soll. Ziel des Redirect-After-Submit-Pattern ist beides zu vermeiden.

Redirect-After-Submit wird aktiv, wenn man JSF Ext einbindet und web.xml 3.0 verwendet. Alle Page-Submits mit <h:commandButton>, <h:commandLink> etc. werden mit einem Redirect abgeschlossen.

Ergebnis: Nach der Navigation wird die aktuelle URL im Browser angezeigt. Refresh der Seite im Browser kann ohne Rückfrage durchgeführt werden.

Hinweis: Bei einem Redirect geht üblicher Weise der Zustand der Seite verloren. JSF Ext nutzt den sogenannten Flash-Scope von JSF, um dieses Hindernis zu überwinden und auch Faces-Messages über den Redirect zu retten. Daher ist web.xml 3.0 und Tomcat 7 für das saubere Arbeiten erforderlich.

Bei web.xml 2.x und Tomcat 6 kann ein Fallback-Mechanismus verwendet werden, der die View-Id als GET-Parameter an die URL hängt. Dies ist zwar problemlos möglich, jedoch können dann keine "sauberen" URLs mehr produziert werden. Dieses Verhalten kann mit einem Konfigurations-Parameter in der web.xml aktiviert werden:

	<context-param>
		<param-name>javax.faces.REDIRECT_AFTER_SUBMIT</param-name>
		<param-value>true</param-value>
	</context-param>

Fehler und Exceptions#

JSF Ext enthält mehrere Mechanismen für das Handling von Exceptions. Grundlage dazu ist der ExtExceptionHandler und eine speziell Ableitung, der AjaxExceptionHandler.

AJAX Exception Handler#

Der Handler ist dafür verantwortlich, dass Exceptions während eines AJAX-Requests nicht die komplette Seite lahm legen. Eine derartige Exception wird ins Logfile eingetragen und eine Faces-Message dafür generiert.

Dabei existieren zwei Konfigurationsparameter:

Parameter	Bedeutung
javax.faces.IGNORE_EXCEPTIONS	Eine durch Kommata separierte Liste von voll qualifizierten Exception-Klassen-Namen, die ignoriert werden sollen. Diese tauchen nicht als Fehler auf. Damit sollte sehr vorsichtig umgegangen werden, weil es zu versteckten Fehlfunktionen in der Applikation führen kann, die später sehr schwer zu finden sein können.
javax.faces.PASS_EXCEPTIONS	Diese Exceptions werden an den nächsten Exception-Handler durchgelassen. Dies ist für Exceptions sinnvoll, für die man einen eigenen Exception-Handler schreiben möchte oder eine Dritt-Software hat, die diese handeln möchte.

Full Request Exception Handler#

Wenn kein AJAX-Request vorliegt oder die Exception in javax.faces.PASS_EXCEPTIONS konfiguriert wurde und von keinem anderen Exception-Handler verarbeitet wurde, erreicht sie den ExtExceptionHandler.

Dieser erlaubt das Definieren von Exception-Navigationen in der faces-config.xml:

	<navigation-rule>
		<navigation-case>
			<from-outcome>org.springframework.security.access.AccessDeniedException</from-outcome>
			<to-view-id>/security/login.xhtml</to-view-id>
		</navigation-case>
	</navigation-rule>
	<navigation-rule>
		<navigation-case>
			<from-outcome>java.lang.Throwable</from-outcome>
			<to-view-id>/error.xhtml</to-view-id>
		</navigation-case>
	</navigation-rule>

Erklärung: Die erste Navigationsregel leitet alle Fälle von AccessDeniedException auf die View /security/login.xhtml um. Die zweite Regel für Throwable leitet alle Exceptions, die nicht von vorherigen Regeln erfasst wurden auf die View /error.xhtml um.

Die aufgetretene Exception wird dabei in einer Bean namens pageError erfasst:

Property oder Methode	Bedeutung
exception	Hier ist die aufgetretene Instanz von java.lang.Throwable enthalten. Dadurch können genauere Informationen über den Fehler angezeigt werden.
viewId	Hier ist die View-Id gespeichert, bei Bedarf kann diese ebenfalls angezeigt werden.
init()	Diese Methode kann vor dem Aufbau der Error-Page aufgerufen werden und check ob ein Fehler vorliegt.
back()	Navigiert zurück auf die Seite auf der der Fehler aufgetreten war, damit der Benutzer weiter arbeiten kann.

Rechliches#

JSF ist eine Wort- und Bildmarke, auf die keinerlei Anspruch erhoben wird. Die Nennung dieser Marke dient ausschließlich der Referenz und Zuordnung dieses Produkts.