Использование стандартных конвертеров

JavaServer Faces предоставляет набор реализаций Converter, которые можно использовать для конвертации данных компонента. Цель конвертации — взять строковые данные, поступающие из Servlet API, и преобразовать их в строго типизированные объекты Java, которые можно использовать в компонентах бизнес-логики. Для получения дополнительной информации о концептуальных деталях модели этих преобразований см. Модель конвертации.

Стандартные реализации Converter находятся в пакете javax.faces.convert. Обычно конвертеры присваиваются неявно в зависимости от типа выражения EL, на которое указывает значение компонента. Однако к этим конвертерам также можно получить доступ по идентификатору конвертера. Таблица 11-1 показывает классы конвертеров и связанные с ними идентификаторы конвертеров.

Таблица 11-1 Классы конвертеров и их идентификаторы

Класс в пакете javax.faces.convert

Идентификатор конвертера

BigDecimalConverter

javax.faces.BigDecimal

BigIntegerConverter

javax.faces.BigInteger

BooleanConverter

javax.faces.Boolean

ByteConverter

javax.faces.Byte

CharacterConverter

javax.faces.Character

DateTimeConverter

javax.faces.DateTime

DoubleConverter

javax.faces.Double

EnumConverter

javax.faces.Enum

FloatConverter

javax.faces.Float

IntegerConverter

javax.faces.Integer

LongConverter

javax.faces.Long

NumberConverter

javax.faces.Number

ShortConverter

javax.faces.Short

Стандартное сообщение об ошибке связано с каждым из этих конвертеров. Если вы зарегистрировали какой-либо из этих конвертеров в компоненте на своей странице, и конвертер не может конвертировать значение компонента, на странице появится сообщение об ошибке конвертера. Например, следующее сообщение об ошибке появляется, если BigIntegerConverter не может преобразовать значение:

{0} должен быть числом, состоящим из одной или нескольких цифр

В этом случае параметр замещения {0} будет заменён именем компонента ввода, на котором зарегистрирован конвертер.

Два стандартных конвертера DateTimeConverter и NumberConverter имеют собственные теги, которые позволяют настраивать формат данных компонента с помощью атрибутов тега. Для получения дополнительной информации об использовании DateTimeConverter см. Использование DateTimeConverter. Для получения дополнительной информации об использовании NumberConverter см. Использование NumberConverter. В следующем разделе объясняется, как преобразовать значение компонента, в том числе как зарегистрировать другие стандартные конвертеры в компоненте.

Конвертация значения компонента

Чтобы использовать конкретный конвертер для преобразования значения компонента, необходимо зарегистрировать конвертер в компоненте. Вы можете зарегистрировать любой из стандартных конвертеров одним из следующих способов.

Вложите один из стандартных тегов конвертера в тег компонента. Так можно поступить с f:convertDateTime и f:convertNumber, которые описаны в Использование DateTimeConverter и Использование NumberConverter соответственно.
Свяжите значение компонента со свойством Managed-бина того же типа, что и конвертер. Эта техника наиболее распространена.
Обратитесь к конвертеру из атрибута converter тега компонента, указав идентификатор класса конвертера.
Вложите тег f:converter внутрь тега компонента и используйте либо атрибут converterId тега f:converter, либо его атрибут binding для ссылки на конвертер.

В качестве примера второго метода, когда вы хотите преобразовать данные компонента в Integer, вы можете просто привязать значение компонента к свойству Managed-бина. Вот пример:

Integer age = 0;
public Integer getAge(){ return age;}
public void setAge(Integer age) {this.age = age;}

Данные из тега h:inputText в этом примере будут преобразованы в значение java.lang.Integer. Тип Integer поддерживается типом конвертера NumberConverter. Если не требуется указывать какие-либо инструкции форматирования с помощью атрибутов тега f:convertNumber, и если одного из стандартных конвертеров будет достаточно, можно просто ссылаться на этот конвертер с помощью атрибута converter.

Вы также можете вложить тег f:converter в тег компонента и использовать атрибут converterId тега конвертера или его атрибут binding для ссылки на конвертер.

Атрибут converterId должен ссылаться на идентификатор конвертера. Вот пример, который использует один из идентификаторов конвертера, перечисленных в таблице 11-1:

<h:inputText value="#{loginBean.age}">
    <f:converter converterId="javax.faces.Integer" />
</h:inputText>

Вместо использования атрибута converterId тег f:converter может использовать атрибут binding. Атрибут binding должен разрешать свойство бина, которое принимает и возвращает соответствующий объект Converter.

Вы также можете создавать собственные конвертеры и регистрировать их в компонентах, используя тег f:converter. Подробнее см. Создание и использование кастомного конвертера.

Использование DateTimeConverter

Вы можете преобразовать данные компонента в java.util.Date, вложив тег convertDateTime в тег компонента. Тег convertDateTime имеет несколько атрибутов, которые позволяют вам указать формат и тип данных. Таблица 11-2 перечисляет атрибуты.

Вот простой пример тега convertDateTime:

<h:outputText value="#{cashierBean.shipDate}">
    <f:convertDateTime type="date" dateStyle="full" />
</h:outputText>

При связывании DateTimeConverter с компонентом убедитесь, что свойство Managed-бина, с которым связан компонент, имеет тип java.util.Date. В предыдущем примере cashierBean.shipDate должен иметь тип java.util.Date.

Тег примера может отображать следующий вывод:

Saturday, September 21, 2013

Вы также можете отобразить ту же дату и время, используя следующий тег, в котором указан формат даты:

<h:outputText value="#{cashierBean.shipDate}">
    <f:convertDateTime pattern="EEEEEEEE, MMM dd, yyyy" />
</h:outputText>

Если вы хотите отобразить пример даты на испанском языке, вы можете использовать атрибут locale:

<h:outputText value="#{cashierBean.shipDate}">
    <f:convertDateTime dateStyle="full"
                       locale="es"
                       timeStyle="long" type="both" />
</h:outputText>

Этот тег будет отображать следующий вывод:

jueves 24 de octubre de 2013 15:07:04 GMT

Обратитесь к уроку «Customizing Formats» учебного руководства по Java http://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html с информацией о том, как форматировать вывод, используя атрибут pattern тега convertDateTime.

Таблица 11-2 Атрибуты для тега f:convertDateTime

Атрибут

Тип

Описание

binding

DateTimeConverter

Используется для привязки конвертера к свойству Managed-бина.

dateStyle

String

Определяет формат, указанный в java.text.DateFormat, даты или части даты строки date. Применяется, только если type равен date или both и если pattern не определён. Допустимые значения: default, short, medium, long и full. Если значение не указано, используется default.

for

String

Используется с составными компонентами. Относится к одному из объектов в составном компоненте, внутрь которого этот тег вложен.

locale

String или Locale

Locale, чьи предопределённые стили для дат и времени используются во время форматирования или анализа. Если не указано, будет использоваться Locale, возвращаемый FacesContext.getLocale.

pattern

String

Пользовательский шаблон форматирования, который определяет, как строка даты/времени должна быть отформатирована и проанализирована. Если этот атрибут указан, атрибуты dateStyle и timeStyle игнорируются.

Смотрите таблицу 11-3 для значений по умолчанию, когда pattern не указан.

timeStyle

String

Определяет формат, указанный в java.text.DateFormat, time или части времени строки date. Применяется, только если type имеет значение time и pattern не определён. Допустимые значения: default, short, medium, long и full. Если значение не указано, используется default.

timeZone

String или TimeZone

Часовой пояс, в котором можно интерпретировать любую информацию о времени в строке date.

type

String

Указывает, будет ли строковое значение содержать дату, время или оба. Допустимые значения: date, time, both, LocalDate, LocalTime, LocalDateTime, OffsetTime, OffsetDateTime или ZonedDateTime. Если значение не указано, используется date.

Смотрите таблицу 11-3 для дополнительной информации.

Таблица 11-3 Тип атрибута и значения шаблона по умолчанию

Тип атрибута

Класс

По умолчанию, когда шаблон не указан

both

java.util.Date

DateFormat.getDateTimeInstance(dateStyle, timeStyle)

date

java.util.Date

DateFormat.getDateTimeInstance(dateStyle)

time

java.util.Date

DateFormat.getDateTimeInstance(timeStyle)

localDate

java.time.LocalDate

DateTimeFormatter.ofLocalizedDate(dateStyle)

localTime

java.time.LocalTime

DateTimeFormatter.ofLocalizedTime(dateStyle)

localDateTime

java.time.LocalDateTime

DateTimeFormatter.ofLocalizedDateTime(dateStyle)

offsetTime

java.time.OffsetTime

DateTimeFormatter.ISO_OFFSET_TIME

offsetDateTime

java.time.OffsetDateTime

DateTimeFormatter.ISO_OFFSET_DATE_TIME

zonedDateTime

java.time.ZonedDateTime

DateTimeFormatter.ISO_ZONED_DATE_TIME

Использование NumberConverter

Вы можете преобразовать данные компонента в java.lang.Number, вложив тег convertNumber в тег компонента. Тег convertNumber имеет несколько атрибутов, которые позволяют вам указать формат и тип данных. Таблица 11-4 перечисляет атрибуты.

В следующем примере тег convertNumber используется для отображения общей цены содержимого корзины покупок:

<h:outputText value="#{cart.total}">
    <f:convertNumber currencySymbol="$" type="currency"/>
</h:outputText>

При связывании NumberConverter с компонентом убедитесь, что свойство Managed-бина, с которым связан компонент, имеет примитивный тип или имеет тип java.lang.Number. В предыдущем примере cart.total имеет тип double.

Вот пример числа, которое может отображать этот тег:

$934

Этот результат также можно отобразить с помощью следующего тега, в котором указан шаблон валюты:

<h:outputText id="cartTotal" value="#{cart.total}">
    <f:convertNumber pattern="$####" />
</h:outputText>

См. «Customizing Formats» учебного руководства по Java http://docs.oracle.com/javase/tutorial/i18n/format/decimalFormat.html для получения дополнительной информации о форматировании вывода, используя атрибут pattern тега convertNumber.

Таблица 11-4 Атрибуты для тега f:convertNumber

Атрибут

Тип

Описание

binding

NumberConverter

Используется для привязки конвертера к свойству Managed-бина.

currencyCode

String

Код валюты ISO 4217, используется только при форматировании валют.

currencySymbol

String

Символ валюты, применяется только при форматировании валют.

for

String

groupingUsed

Boolean

Указывает, содержит ли отформатированный вывод разделители группировки.

integerOnly

Boolean

Указывает, будет ли анализироваться только целая часть значения.

locale

String или Locale

Locale, число стилей которого используется для форматирования или анализа данных.

maxFractionDigits

int

Максимальное количество цифр, отформатированных в дробной части вывода.

maxIntegerDigits

int

Максимальное количество цифр, отформатированных в целочисленной части вывода.

minFractionDigits

int

Минимальное количество цифр, отформатированных в дробной части вывода.

minIntegerDigits

int

Минимальное количество цифр, отформатированных в целочисленной части вывода.

pattern

String

Пользовательский шаблон форматирования, определяющий способ форматирования и синтаксического анализа числовой строки.

type

String

Указывает, анализируется ли строковое значение и форматируется ли он как number, currency или percentage. Если не указано, используется number.