<jsptutorial />

Die fmt-Bibliothek


Die fmt-Bibliothek unterstützt die JSP-Entwicklerin bei der Internationalisierung der Maske. Diese Bibliothek sieht Tags zum Zugriff auf ResourceBundle-Keys oder zum Formatieren lokalisierbarer Daten wie bspw. Datums- und Zahlwerten vor. Die grundlegenden Konzepte der Internationalisierung haben wir zusammen mit möglichen Fallstricken, die bei internationalisierten Webanwendungen in Java auftreten können, im entsprechenden Kapitel beschrieben.
Die nachstehende Übersicht listet alle Tags der fmt-Bibliothek auf und enthält einen kurzen Hinweis zur Nutzungsmöglichkeit des Tags. Detailliert werden die Tags in den nachfolgenden Abschnitten erläutert.

TagBodyBedeutung
setLocaleleerSetzt die Locale für die gewünschte Lokalisierung
bundleJSPLegt für den Body des Tags das zu nutzende ResourceBundle fest
setBundleleerLegt fest, welches ResourceBundle die folgenden fmt-Tags nutzen sollen
messageJSPGibt einen formatierten und lokalisierten Text aus
paramJSPSetzt Parameter für umschließende message-Tags
requestEncodingleerSetzt das Character-Encoding des Requests
timeZoneJSPLegt die Zeitzone fest, die für die fmt-Tags innerhalb des Body dieses Tags gilt
setTimeZoneleerLegt die Zeitzone fest, die für die folgenden Tags gilt
formatNumberJSPFormatiert eine Nummer entsprechend der gewählten Lokalisierung
parseNumberJSPWertet einen String als Nummer entsprechend der gewählten Lokalisierung aus
formatDateJSPFormatiert ein Datum entsprechend der gewählten Lokalisierung und Zeitzone
parseDateJSPWertet einen String als Datum entsprechend der gewählten Lokalisierung und Zeitzone aus


Die Tags der Bibliothek haben wir der Spezifikation folgend sortiert. Demzufolge stellen wir zunächst Tags vor, die der Internationalisierung von Texten dienen, bevor wir auf die Tags zur Formatierung von Zahl- und Datumswerten zu sprechen kommen.
&lt;fmt:setLocale&gt;

AttributPflichtfeldBedeutung
valuejaEine String-Repräsentation eines Locale-Wertes
variantneinVariante der Locale
scopeneinDer Gültigkeitsbereich der Locale-Konfigurationsvariablen


Legt die Lokalisierung aller Folge-Tags fest. Die Platzierung des Tags ist entscheidend. Dieser Tag muss bspw. noch vor dem Tag <fmt:setBundle> genutzt werden, wenn das richtige lokalisierte ResouceBundle genutzt werden soll.
Das Attribut "value" enthält eine String-Repräsentation eines java.util.Locale-Objektes. Dieses muss zumindest das Sprachkürzel, das aus zwei Großbuchstaben besteht, enthalten. Optional kann auch, durch einen Unter- oder Bindestrich abgetrennt, ein Länderkürzel aus zwei Kleinbuchstaben folgen. Das Attribut "variant" kann noch eine spezielle herstellerspezifische Ergänzung enthalten, allerdings ist die Nutzung eines Variant-Elements eher bei Desktop-Anwendungen üblich; die Nutzung dieses Attributs dürfte also selten nötig sein. Die genauen Regeln für die String-Repräsentation von Locale-Objekten können in der API zu java.util.Locale nachgelesen werden.

Zum SeitenanfangZum Seitenanfang

<fmt:bundle>

AttributPflichtfeldBedeutung
basenamejaDer Basisname zum Auffinden des Locale-spezifischen ResourceBundles
prefixneinEin Präfix, der allen Keys der geschachtelten <fmt:message>-Tag-Anfragen vorangestellt wird


Dieser Tag legt das zu verwendende ResourceBundle für die eingeschlossenen Tags fest. Zudem kann man damit ein gemeinsames Präfix für die enthaltenen Anfragen setzen. Dies ist v.a. praktisch, wenn man seine Keys systematisch mit Formular- oder View-Präfixe benennt, wie im Kapitel Einführung ins erste Beispiel beschrieben. Im Unterschied zum folgenden Tag wird hier das zu nutzende ResourceBundle ausschließlich für die umschlossenen Tags definiert.

Zum SeitenanfangZum Seitenanfang

<fmt:setBundle>

AttributPflichtfeldBedeutung
basenamejaDer Basisname zur Auffindung des Locale-spezifischen RersourceBundles
varneinEin Name, unter dem das ResourceBundle abgelegt werden soll. Die exportierte Variable ist vom Typ javax.servlet.jsp.jstl.fmt.LocalizationContext
scopeneinDer Gültigkeitsbereich, unter dem das ResourceBundle abgelegt werden soll


Setzt das ResourceBundle, das für die Tags der fmt-Bibliothek gelten sollen. Der Unterschied zum vorherigen Tag ist der, dass das ResourceBundle mit diesem Tag für alle Folge-Tags gilt. Der <fmt:setBundle>-Tag selber hat keinen Body. Ein allgemeines Präfix kan mit diesem Tag nicht gesetzt werden.

Zum SeitenanfangZum Seitenanfang

<fmt:message>

AttributPflichtfeldBedeutung
keyneinDer Key, der den zu holenden Text bezeichnet
bundleneinEine Variable vom Typ javax.servlet.jsp.jstl.fmt.LocalizationContext, die das ResourceBundle mit dem gewünschten Key enthält
varneinEin Name, unter dem der gefundene Text abgelegt werden soll
scopeneinDer Gültigkeitsbereich, unter dem der Text abgelegt werden soll


Mit diesem Tag greift man auf Werte aus einem ResourceBundle zu. Dazu muss das RessourceBundle zuvor mit einem der beiden Tags <fmt:setBundle> oder <fmt:bundle> gesetzt worden sein oder direkt im Tag mitgegeben werden.
Es gibt drei mögliche Arten, den Tag zu nutzen, wovon wir zwei vorstellen. Die beiden gebräuchlichen Nutzungsarten sehen wie folgt aus:


  1. Es wird ein einzelner Key ausgegeben, der keine Parameter benötigt:
    <fmt:message key="messageKey" />

  2. Es wird ein parametrisierter Text ausgegeben. Bei dieser Art werden Platzhalter des ResourceBundles entsprechend den Regeln der Klasse java.text.MessageFormat durch Laufzeitparameter ersetzt. Die Nutzung des Tags ist in dem Fall wie folgt:
    <fmt:message key="messageKey">
       <fmt:param value="messageParameter" />
       <%-- mögliche weitere <fmt:param>-Tags --%>
    </fmt:message>

Die letzte in der Spezifikation genannte Nutzungsart ist - gelinde gesagt - misslungen. Wir weisen hier nur darauf hin, dass man noch als dritte Möglichkeit, den Key zusammen mit Parametern im Body des Tags angeben kann. Bisher ist uns dies noch nicht in Projekten begegnet, so dass wir hier nicht weiter darauf eingehen.
Ist der Key nicht bekannt oder ist das RessourceBundle nicht gesetzt, so wird dies mit ???usedKey??? gekennzeichnet, wobei usedKey für den nicht gefundenen Key steht. Ist der verwendete Key null, so wird stattdessen ?????? ausgegeben.

Zum SeitenanfangZum Seitenanfang

<fmt:param>

AttributPflichtfeldBedeutung
valueneinDer Wert, der anstelle des aktuellen Platzhalters in den Text eingesetzt werden soll


Die Nutzung dieses Tags ist schon beim Tag <fmt:message> vorgestellt worden. Der <fmt:param>-Tag kann ausschließlich innerhalb des <fmt:message>-Tags eingesetzt werden und dient dazu, die Werte für parametrisierte Texte zu ergänzen.
Hat man bspw. im RessourceBundle folgendes Key-Value-Paar, so ist dieser Tag nötig, um den ersten Parameter, der durch den Platzhalter {0} repräsentiert wird, mit einem Wert zu füllen.

welcome=Willkommen, {0}!

Wir nehmen an, dass RessourceBundle hieße "vocabs" und der Name sei als Request-Attribut unter dem Bezeichner "name" abgelegt. Dann kann man, wie in der Beispielanwendung gezeigt, den Text mit folgendem Code-Fragment innerhalb der JSP ausgeben:

<%-- usage of core tags in /WEB-INF/jsp/showResults.jsp  --%>
<fmt:message key="showResultsPage.textAnswered">
   <fmt:param>${numberAnswered}</fmt:param> 
   <fmt:param>${unit.numberOfWords}</fmt:param>
</fmt:message>


<%-- key and value as used in the ResourceBundle         --%>
<%-- vocabs_en.properties (english version):             --%>
<%-- showResultsPage.textAnswered=Anwered: {0} of {1}    --%>

Die Regeln für die Nutzung von parametrisierten Texten kann in der Javadoc-Dokumentation der Klasse java.text.MessageFormatnachgelesen werden.

Zum SeitenanfangZum Seitenanfang

<fmt:requestEncoding>

AttributPflichtfeldBedeutung
valueneinDas Encoding, das zum Parsen des Requests benutzt werden soll


Mit diesem Tag wird das Character-Encoding des Requests gesetzt. Eine sehr wichtige Funktion, die man aber besser mit einem Filter behandelt (sofern das Encoding auf der ganzen Webseite einheitlich ist). Zu diesem Themenkomplex sei auf das Kapitel Internationalisierung verwiesen.

Zum SeitenanfangZum Seitenanfang

<fmt:timeZone>

AttributPflichtfeldBedeutung
valuejaDer Zeitzonen-Wert, der für die Datums-bezogenen Tags im Body dieses Tags gelten sollen


Legt die Zeitzone fest, die allen Datums-bezogenen Tags innerhalb dieses Tags zugrunde gelegt werden soll.

Zum SeitenanfangZum Seitenanfang

<fmt:setTimeZone>

AttributPflichtfeldBedeutung
valuejaDer Zeitzonen-Wert, der für die Datums-bezogenen Tags im Body dieses Tags gelten sollen. Muss vom Typ java.util.timezone oder die gültige String-Repräsentation einer Zeitzone sein
varneinDer Name, unter dem die Zeitzone abgelegt werden soll
scopeneinDer Gültigkeitsbereich für die abgelegte Variable


Speichert - im Gegensatz zum vorherigen <fmt:timeZone>-Tag - die Zeitzone in einer Variablen. Sofern keine Variable im Attribut "var" angegeben ist, wird die Zeitzone unter dem Defaultnamen javax.servlet.jsp.jstl.fmt.timeZone abgelegt und ersetzt damit den vorherigen Standardwert. Der Wert des "value"-Attributs kann entweder ein Objekt vom Typ java.util.TimeZone sein oder eine String-Repräsentation einer Zeitzone. Wie gültige Werte für String-Repräsentationen von Zeitzonen aufgebaut sein müssen, wird in der Java-API zur Klasse java.util.TimeZone erläutert.

Zum SeitenanfangZum Seitenanfang

<fmt:formatNumber>

AttributPflichtfeldBedeutung
valueneinDie zu formatierende Zahl
typeneinLegt den Typ der Formatierung fest
patternneinEin frei definierbares Muster zur Formatierung der Zahl
currencyCodeneinDer dreistellige Währungscode
currencySymbolneinDas zu nutzende Währungssysmbol
groupingUsedneinGibt an, ob Tausender-Trennzeichen verwendet werden sollen oder nicht
maxIntegerDigitsneinDie maximale Anzahl von Ziffern für Ganzzahlenwerte
minIntegerDigitsneinDie minimale Anzahl von Ziffern für Ganzzahlenwerte
maxFractionDigitsneinDie maximale Anzahl von Ziffern für Nachkommastellen
minFractionDigitsneinDie minimale Anzahl von Ziffern für Nachkommastellen
varneinDer Name, unter dem der Wert abgelegt werden soll
scopeneinDer Gültigkeitsbereich für die abgelegte Variable


Wandelt eine Zahl entsprechend der Regeln der derzeit gültigen Locale in einen Währungsbetrag, eine Prozentzahl oder eine formatierte Zahl um. Aufgrund seiner Möglichkeiten hat dieser Tag eine Vielzahl Attribute, die allerdings allesamt optional sind. Die umzuwandelnde Zahl muss allerdings entweder aus dem Body des Tags oder aus dem Attribut "value" kommen.
Das Attribut "type" bestimmt die Art der Umwandlung. Der Default-Wert ist "number" und bezeichnet eine Umwandlung in einen Zahlstring. Die beiden anderen möglichen Werte sind "currency" und "percent". Die beiden Attribute "currencyCode" und "currencySymbol" werden nur ausgewertet, wenn unter "type" "currency" eingetragen ist. "currencySymbol" ist ein frei vergebbarer String, der als Währungsbezeichner verwendet wird, wohingegen "currencyCode" ein dreibuchstabiger ISO 4217 Währungskode ist.
Die Angaben zur Anzahl der zu nutzenden Ziffern sind in der Übersicht der Attribute selbsterklärend. Interessant hingegen ist das Attribut "groupingUsed ". Mit diesem boolschen Flag kann festgelegt werden, ob die Tausender-Trennzeichen bei großen Zahlen ausgegeben werden sollen oder nicht. Läßt man das Attribut weg, so werden sie ausgegeben.
Das Attribut "pattern" ermöglicht zudem eine freie Formatierungsdefinition gemäß den Regeln, die in der Dokumentation zur Klasse java.text.DecimalFormat beschrieben sind. Ist das Attribut "pattern" gesetzt, werden möglicherweise gesetzte Attribute "type", "dateStyle" und "timeStyle" ignoriert.

Zum SeitenanfangZum Seitenanfang

<fmt:parseNumber>

AttributPflichtfeldBedeutung
valueneinDer zu parsende String
typeneinLegt den Typ fest, der dem Parsen zugrunde gelegt wird
patternneinEin Muster, das dem Parsen des Zahlstrings zugrunde gelegt wird
parseLocaleneinDie zum Parsen zu nutzende Locale
integerOnlyneinGibt an, ob nur der Ganzzahlwert zum Parsen herangezogen werden soll
varneinDer Name der Variablen, unter der das Parse-Ergebnis abgelegt werden soll
scopeneinDer Gültigkeitsbereich für die abgelegte Variable


Dieser Tag stellt das direkte Gegenstück zu dem vorhergehenden Tag dar. Wandelte der vorherige eine Zahl in einen String um, so wird nun ein formatierter Zahlstring genommen, geparst und in eine Zahl umgewandelt. Dies macht vor allem dann Sinn, wenn man in der JSP die Eingaben von Nutzerinnen verarbeitet.
Einige Attribute sind die Gegenstücke zu entsprechenden Attributen des vorherigen <fmt:formatNumber>-Tags. Das "type"-Attribut dient wieder dazu, zwischen Zahlstrings, Prozentzahlen und Währungsangaben zu unterscheiden, und akzeptiert erneut die Werte "number", "currency" und "percent". "number" ist wieder der Default, so dass bei Zahlstrings dieses Attribut weggelassen werden kann.
Mit "pattern" kann auch zum Parsen ein frei definierbares Muster entsprechend der Regeln der java.text.DecimalFormat-Klasse verwendet werden.
Neu hingegen ist das Attribut "parseLocale", mit der zum Parsen eine von der derzeitigen Standard-Locale abweichende Einstellung vorgenommen werden kann. Auch "integerOnly" ist ein Attribut, das beim Tag <fmt:formatNumber> nicht vorkommt. Es entspricht der Methode setParseIntegerOnly() der Klasse java.text.NumberFormat.

Zum SeitenanfangZum Seitenanfang

<fmt:formatDate>

AttributPflichtfeldBedeutung
valueneinDas zu formatierende Datum. Muss vom Typ java.util.Date sein
typeneinLegt den Typ der Formatierung fest
dateStyleneinDefiniert die Art der Darstellung bei Datumswerten
timeStyleneinDefiniert die Art der Darstellung bei Zeitangaben
patternneinEin frei definierbares Muster zur Formatierung des Date-Objekts
timeZoneneinDie Zeitzone für die zu formatierende Zeitangabe
varneinDer Name, unter dem der Wert abgelegt werden soll
scopeneinDer Gültigkeitsbereich für die abgelegte Variable


Analog zum <fmt:formatNumber>-Tag wandelt der <fmt:formatDate>-Tag ein java.util.Date-Objekt in einen lokalisierten Datums- oder Zeitstring um. Allerdings muss beim <fmt:formatDate>-Tag das zu formatierende Datum mit dem Pflichtattribut "value" gesetzt werden und kann nicht wie bei <fmt:formatNumber>-Tag aus dem Body des Tags kommen.
Das Attribut "type" bestimmt die Art der Umwandlung. Mögliche Werte sind "date", "time" und "both". Der Default-Wert ist "date". Das Attribut "dateStyle" wird nur ausgewertet, wenn unter "type" entweder "date" oder "both" eingetragen ist. Entsprechend das Attribut "timeStyle" nur bei "time" oder "both". Die dort jeweils gültigen Stile sind "default", "short", "medium", "long" und "full". Die Semantik dieser Stile entspricht den entsprechenden Konstanten der Klasse java.text.DateFormat.
Das Attribut "pattern " ermöglicht zudem eine freie Formatierungsdefinition, gemäß den Regeln, die in der Dokumentation zur Klasse java.text.SimpleDateFormat beschrieben sind. Ist das Attribut "pattern" gesetzt, wird ein mögliches Attribut "type" ignoriert.

Zum SeitenanfangZum Seitenanfang

<fmt:parseDate>

AttributPflichtfeldBedeutung
valueneinDer zu parsende String.
typeneinLegt den Typ fest, der dem Parsen zugrunde gelegt wird.
dateStyleneinDefiniert die Art, einen Datumswert zu parsen.
timeStyleneinDefiniert die Art, eine Zeitangabe zu parsen.
patternneinEin Muster, das dem Parsen der Datums- bzw. Zeitangabe zugrunde gelegt wird.
timeZoneneinDie Zeitzone für die zu parsende Zeitangabe.
parseLocaleneinDie zum Parsen zu nutzende Locale.
varneinDer Name der Variablen, unter der das Parse-Ergebnis abgelegt werden soll.
scopeneinDer Gültigkeitsbereich für die abgelegte Variable.


Wie bei Zahlen ist es auch bei formatierten Datums- und Zeitangaben möglich, diese zu parsen und in ein java.util.Date-Objekt umzuwandeln.
Die meisten Attribute sind Gegenstücke zu entsprechenden Attributen des Tags <fmt:formatDate>. Das "type"-Attribut dient wieder dazu, zwischen Datums-, Zeit- oder kombinierten Werten zu unterscheiden, und akzeptiert entsprechend die Werte "date", "time" und "both". "date" ist wieder der Default, so dass bei Datumsangaben dieses Attribut weggelassen werden kann.
Mit "pattern" kann auch zum Parsen ein frei definierbares Muster entsprechend der Regeln der java.text.SimpleDateFormat-Klasse verwendet werden. Auch die "dateStyle"- und "timeStyle"-Attribute finden sich wieder und akzeptieren die in den Konstanten der Klasse java.text.DateFormat definierten Stile "default", "short", "medium", "long" und "full".
Wie schon beim Tag <fmt:parseNumber> kann mit dem Attribut "parseLocale" eine von der derzeitigen Standard-Locale abweichende Einstellung vorgenommen werden.

Zum SeitenanfangZum Seitenanfang


www.jsptutorial.org
© 2005, 2006, 2007