org.apache.myfaces.trinidad.convert
Class DateTimeConverter

java.lang.Object
  extended by javax.faces.convert.DateTimeConverter
      extended by org.apache.myfaces.trinidad.convert.DateTimeConverter
All Implemented Interfaces:
javax.faces.component.PartialStateHolder, javax.faces.component.StateHolder, javax.faces.convert.Converter

@JSFConverter(configExcluded=true)
public class DateTimeConverter
extends javax.faces.convert.DateTimeConverter
implements javax.faces.convert.Converter, javax.faces.component.StateHolder

Converter implementation for java.util.Date values. Converts an strings to and from java.util.Date objects.

The converter has additonal features than standard JSF DateTimeConverter. New dateStyle shortish has been introduced. Shortish is identical to short but forces the year to be a full four digits. If dateStyle is not set, then dateStyle defaults to shortish.

Timezone can be set per web-app in trinidad-config.xml configuration file. If timeZone is not set on the converter, then timezone will be defaulted to the value set in trinidad-config.xml configuration file. If it is not set in the configuration file, then it will be defaulted to GMT.

The converter always allows a level of leniency while converting user input value to date to the following extent.

For example:
When pattern on the converter is set to "MMM/d/yyyy" the following inputs are tolerated as valid by the converter.

Jan/4/2004
Jan-4-2004
Jan.4.2004
01/4/2004
01-4-2004
01.4.2004
1/4/2004
1-4-2004
1.4.2004

The detail part of faces message,for conversion errors can be customized by overriding the message associated with each CONVERT_[TYPE]_MESSAGE_ID.

The methods used for customizing the detail message associated with each id is given below:

  1. CONVERT_DATE_MESSAGE_ID - setMessageDetailConvertDate(String)
  2. CONVERT_TIME_MESSAGE_ID - setMessageDetailConvertTime(String)
  3. CONVERT_BOTH_MESSAGE_ID - setMessageDetailConvertBoth(String)
The custom messages can contain placeholders, which will be replaced with values as specified in its corresponding message id.

The getAsObject() method parses a String into a java.util.Date, according to the following algorithm:

The getAsString() method expects a value of type java.util.Date (or a subclass), and creates a formatted String according to the following algorithm:

Version:
$Name: $ ($Revision: adfrt/faces/adf-faces-api/src/main/java/oracle/adf/view/faces/convert/DateTimeConverter.java#0 $) $Date: 10-nov-2005.19:09:11 $
See Also:
CONVERT_DATE_MESSAGE_ID, CONVERT_TIME_MESSAGE_ID, CONVERT_BOTH_MESSAGE_ID, DateFormat, SimpleDateFormat

Field Summary
static String CONVERT_BOTH_MESSAGE_ID
          The message identifier of the FacesMessage to be created if the value cannot be converted to a date when type is set to 'both' and pattern is either null or not set.
static String CONVERT_DATE_MESSAGE_ID
          The message identifier of the FacesMessage to be created if the value cannot be converted to a date, when pattern is null or not set and type is set to 'date'.
static String CONVERT_TIME_MESSAGE_ID
          The message identifier of the FacesMessage to be created if the value cannot be converted date time object, when type is set to 'time' and pattern is null or not set.
static String CONVERTER_ID
          Standard converter id for this converter.
 
Fields inherited from class javax.faces.convert.DateTimeConverter
DATE_ID, DATETIME_ID, STRING_ID, TIME_ID
 
Constructor Summary
DateTimeConverter()
          Creates a DateTimeConverter
DateTimeConverter(String pattern)
          Creates a DateTimeConverter with the specified SimpleDateFormat format pattern
DateTimeConverter(String pattern, String secondaryPattern)
          Creates a DateTimeConverter with the specified SimpleDateFormat format pattern and a secondary pattern.
 
Method Summary
 boolean equals(Object object)
          Compares this DateTimeConverter with the specified Object for equality.
 Object getAsObject(javax.faces.context.FacesContext context, javax.faces.component.UIComponent component, String value)
          Convert the specified string value, which is associated with the specified UIComponent, into a java.util.Date object based on the values set.
 String getAsString(javax.faces.context.FacesContext context, javax.faces.component.UIComponent component, Object value)
          Convert the model Date object value, into a String based on the pattern or styles.
protected  Date getDate(javax.faces.context.FacesContext context, javax.faces.component.UIComponent component)
          Gets the existing date from the component.
protected  DateFormat getDateFormat(javax.faces.context.FacesContext context, String pattern, boolean forParsing, Date targetDate)
           
 String getDateStyle()
          Return the style to be used to format or parse dates.
protected  String getExample(javax.faces.context.FacesContext context)
           
protected  TimeZone getFormattingTimeZone(TimeZone tZone)
          Returns the TimeZone that will be set on DateFormat for formatting and parsing the dates.
protected  TimeZone getFormattingTimeZone(TimeZone tZone, Date targetDate)
          Returns the timeZone for formatting and parsing the date.
 String getHintBoth()
          Return custom hintBoth message.
 String getHintDate()
          Return custom hintDate message.
 String getHintTime()
          Return custom hintTime message.
 Locale getLocale()
          Return the Locale that was set.
 String getMessageDetailConvertBoth()
          Return custom detail error message that was set for creating FacesMessage, for values that cannot be converted to Date when type is set to 'both'.
 String getMessageDetailConvertDate()
          Return custom detail error message that was set for creating FacesMessage, for values that cannot be converted to Date when pattern / secondary pattern is set or when type is set to 'date'.
 String getMessageDetailConvertTime()
          Return custom detail error message that was set for creating FacesMessage, for values that cannot be converted to Date when type is set to 'time'.
protected  Object getMessagePattern(javax.faces.context.FacesContext context, String key, Object[] params, javax.faces.component.UIComponent component)
           
protected  javax.faces.application.FacesMessage getParseErrorMessage(javax.faces.context.FacesContext context, javax.faces.component.UIComponent component, String pattern, Object[] params)
           
 String getPattern()
          Return the format pattern to be used when formatting and parsing dates and times.
 String getSecondaryPattern()
          Return the secondary pattern used to parse string when parsing by pattern or style fails.
 String getTimeStyle()
          Return the style to be used to format or parse times.
 TimeZone getTimeZone()
          Return the TimeZone that is used to interpret a time value.
 String getType()
          Return the type of value to be formatted or parsed.
 javax.faces.el.ValueBinding getValueBinding(String name)
          Deprecated.  
 javax.el.ValueExpression getValueExpression(String name)
          Return the ValueExpression used to calculate the value for the specified attribute name, if any.
protected  String getViolationMessageKey(String pattern)
           
 int hashCode()
          Returns the hash code for this Converter.
 boolean isDisabled()
          Return whether it is disabled.
 boolean isTransient()
           
 void restoreState(javax.faces.context.FacesContext context, Object state)
           
 Object saveState(javax.faces.context.FacesContext context)
           
 void setDateStyle(String dateStyle)
          Set the style to be used to format or parse dates.
 void setDisabled(boolean isDisabled)
          Set the value to property disabled.
 void setHintBoth(String hintBoth)
          Custom hintBoth message.
 void setHintDate(String hintDate)
          Custom hintDate message.
 void setHintTime(String hintTime)
          Custom hintTime message.
 void setLocale(Locale locale)
          Set the Locale to be used when parsing or formatting dates and times.
 void setMessageDetailConvertBoth(String convertBothMessageDetail)
          Custom error message to be used, for creating detail part of the FacesMessage, for date-time based value that cannot be converted to Date when type is set to 'both'.
 void setMessageDetailConvertDate(String convertDateMessageDetail)
          Custom error message to be used, for creating detail part of the FacesMessage, for values that cannot be converted to Date when the pattern / secondary pattern is set or when type is set to 'date'.
 void setMessageDetailConvertTime(String convertTimeMessageDetail)
          Custom error message to be used, for creating detail part of the FacesMessage, for time based value that cannot be converted to date when type is set to 'time'.
 void setPattern(String pattern)
          Set the format pattern to be used when formatting and parsing dates and times.
 void setSecondaryPattern(String secondaryPattern)
          Second pattern which will be used to parse string in getAsObject if pattern or styles fail.
 void setTimeStyle(String timeStyle)
          Set the style to be used to format or parse times.
 void setTimeZone(TimeZone timeZone)
          Set the TimeZone used to interpret a time value.
 void setTransient(boolean isTransient)
           
 void setType(String type)
          Set the type of value to be formatted or parsed.
 void setValueBinding(String name, javax.faces.el.ValueBinding binding)
          Deprecated.  
 void setValueExpression(String name, javax.el.ValueExpression expression)
          Set the ValueExpression used to calculate the value for the specified attribute if any.
 
Methods inherited from class javax.faces.convert.DateTimeConverter
clearInitialState, initialStateMarked, markInitialState
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CONVERTER_ID

public static final String CONVERTER_ID

Standard converter id for this converter.

See Also:
Constant Field Values

CONVERT_DATE_MESSAGE_ID

public static final String CONVERT_DATE_MESSAGE_ID

The message identifier of the FacesMessage to be created if the value cannot be converted to a date, when pattern is null or not set and type is set to 'date'. Or when failures occurs when value cannot be converted to a date based on the pattern set. The message format string for this message may optionally include {0}, {1}, {4} placeholdes, which will be replaced by input value, component label and example date based on the pattern or based on the style when type is set to 'date'.

See Also:
Constant Field Values

CONVERT_TIME_MESSAGE_ID

public static final String CONVERT_TIME_MESSAGE_ID

The message identifier of the FacesMessage to be created if the value cannot be converted date time object, when type is set to 'time' and pattern is null or not set. The message format string for this message may optionally include {0}, {1}, {4} placeholdes, which will be replaced by input value, component label and a time example, based on the timeStyle set in the converter.

See Also:
Constant Field Values

CONVERT_BOTH_MESSAGE_ID

public static final String CONVERT_BOTH_MESSAGE_ID

The message identifier of the FacesMessage to be created if the value cannot be converted to a date when type is set to 'both' and pattern is either null or not set. The message format string for this message may optionally include {0}, {1}, {4} placeholdes, which will be replaced by input value, component label and a date-time example, based on the dateStyle and timeStyle set in the converter.

See Also:
Constant Field Values
Constructor Detail

DateTimeConverter

public DateTimeConverter()
Creates a DateTimeConverter


DateTimeConverter

public DateTimeConverter(String pattern)
Creates a DateTimeConverter with the specified SimpleDateFormat format pattern

Parameters:
pattern - a primary pattern; this will be used to format and parser strings.

DateTimeConverter

public DateTimeConverter(String pattern,
                         String secondaryPattern)
Creates a DateTimeConverter with the specified SimpleDateFormat format pattern and a secondary pattern.

Parameters:
pattern - a primary pattern; this will be used to format and parser strings.
secondaryPattern - a second pattern, which will be used as a second attempt to parse a string if the primary pattern or styles fail, but is never used for formatting strings.
Method Detail

getAsObject

public Object getAsObject(javax.faces.context.FacesContext context,
                          javax.faces.component.UIComponent component,
                          String value)

Convert the specified string value, which is associated with the specified UIComponent, into a java.util.Date object based on the values set.

Specified by:
getAsObject in interface javax.faces.convert.Converter
Overrides:
getAsObject in class javax.faces.convert.DateTimeConverter
Parameters:
context - FacesContext for the request being processed
component - UIComponent with which this model object value is associated
value - String value to be converted (may be null)
Returns:
null if the value to convert is null, otherwise return a java.util.Date object.
Throws:
javax.faces.convert.ConverterException - if conversion cannot be successfully performed
NullPointerException - if context or component is null
IllegalArgumentException - if the value is of type other than Date, String. The value can be null.

getAsString

public String getAsString(javax.faces.context.FacesContext context,
                          javax.faces.component.UIComponent component,
                          Object value)

Convert the model Date object value, into a String based on the pattern or styles.

Specified by:
getAsString in interface javax.faces.convert.Converter
Overrides:
getAsString in class javax.faces.convert.DateTimeConverter
Parameters:
context - FacesContext for the request being processed
component - UIComponent with which this model object value is associated
value - Model object value to be converted (may be null)
Returns:
a zero-length String if value is null, otherwise the result of the conversion
Throws:
javax.faces.convert.ConverterException - if conversion cannot be successfully performed
NullPointerException - if context or component is null

setMessageDetailConvertDate

public void setMessageDetailConvertDate(String convertDateMessageDetail)

Custom error message to be used, for creating detail part of the FacesMessage, for values that cannot be converted to Date when the pattern / secondary pattern is set or when type is set to 'date'.

Overrides detail message identified by message id CONVERT_DATE_MESSAGE_ID

Parameters:
convertDateMessageDetail - custom error message.

getMessageDetailConvertDate

@JSFProperty
public String getMessageDetailConvertDate()

Return custom detail error message that was set for creating FacesMessage, for values that cannot be converted to Date when pattern / secondary pattern is set or when type is set to 'date'.

Returns:
custom error message that was set.
See Also:
setMessageDetailConvertDate(String)

setMessageDetailConvertTime

public void setMessageDetailConvertTime(String convertTimeMessageDetail)

Custom error message to be used, for creating detail part of the FacesMessage, for time based value that cannot be converted to date when type is set to 'time'.

Overrides detail message identified by message id CONVERT_TIME_MESSAGE_ID

Parameters:
convertTimeMessageDetail - custom error message.

getMessageDetailConvertTime

@JSFProperty
public String getMessageDetailConvertTime()

Return custom detail error message that was set for creating FacesMessage, for values that cannot be converted to Date when type is set to 'time'.

Returns:
custom error message that was set.

See Also:
setMessageDetailConvertTime(java.lang.String)

setMessageDetailConvertBoth

public void setMessageDetailConvertBoth(String convertBothMessageDetail)

Custom error message to be used, for creating detail part of the FacesMessage, for date-time based value that cannot be converted to Date when type is set to 'both'.

Overrides detail message identified by message id CONVERT_BOTH_MESSAGE_ID

Parameters:
convertBothMessageDetail - custom error message.
See Also:
CONVERT_BOTH_MESSAGE_ID

getMessageDetailConvertBoth

@JSFProperty
public String getMessageDetailConvertBoth()
Return custom detail error message that was set for creating FacesMessage, for values that cannot be converted to Date when type is set to 'both'.

Returns:
custom error message that was set.
See Also:
setMessageDetailConvertBoth(java.lang.String)

setHintDate

public void setHintDate(String hintDate)

Custom hintDate message.

Overrides default hint message

Parameters:
hintDate - Custom hint message.

getHintDate

public String getHintDate()

Return custom hintDate message.

Returns:
Custom hint message.
See Also:
setHintDate(String)

setHintTime

public void setHintTime(String hintTime)

Custom hintTime message.

Overrides default hint message

Parameters:
hintTime - Custom hint message.

getHintTime

public String getHintTime()

Return custom hintTime message.

Returns:
Custom hint message.
See Also:
setHintTime(String)

setHintBoth

public void setHintBoth(String hintBoth)

Custom hintBoth message.

Overrides default hint message

Parameters:
hintBoth - Custom hint message.

getHintBoth

public String getHintBoth()

Return custom hintBoth message.

Returns:
Custom hint message.
See Also:
setHintBoth(String)

getDate

protected Date getDate(javax.faces.context.FacesContext context,
                       javax.faces.component.UIComponent component)
Gets the existing date from the component. This date will be used to fill in missing portions of the new date. For example, if the new date is missing the time, the time portion from the existing date will be used.

This implementation checks to see if the component is a ValueHolder, and calls getValue() and returns the result if it is a Date instance.

Parameters:
component - The component to get the existing date from.
Returns:
null if there is no existing date.

setLocale

public void setLocale(Locale locale)

Set the Locale to be used when parsing or formatting dates and times. If set to null, the Locale stored in the UIViewRoot for the current request will be utilized.

Overrides:
setLocale in class javax.faces.convert.DateTimeConverter
Parameters:
locale - The new Locale (or null)

getLocale

@JSFProperty
public Locale getLocale()

Return the Locale that was set. If not explicitly set, the Locale stored in the UIViewRoot for the current request is used during call to getAsObject and getAsString.

Overrides:
getLocale in class javax.faces.convert.DateTimeConverter

setPattern

public void setPattern(String pattern)

Set the format pattern to be used when formatting and parsing dates and times. Valid values are those supported by java.text.SimpleDateFormat. An invalid value will cause a ConverterException when getAsObject() or getAsString() is called.

Overrides:
setPattern in class javax.faces.convert.DateTimeConverter
Parameters:
pattern - The new format pattern

getPattern

@JSFProperty
public String getPattern()

Return the format pattern to be used when formatting and parsing dates and times.

Overrides:
getPattern in class javax.faces.convert.DateTimeConverter

setTimeZone

public void setTimeZone(TimeZone timeZone)

Set the TimeZone used to interpret a time value.

Overrides:
setTimeZone in class javax.faces.convert.DateTimeConverter
Parameters:
timeZone - The new time zone

getTimeZone

@JSFProperty
public TimeZone getTimeZone()

Return the TimeZone that is used to interpret a time value. If not explicitly set or if a null value is set, then during call to getAsObject and getAsString, the time zone set for the web-app is used. If time zone is not set for the web-app then the default time zone of GMT is used.

Overrides:
getTimeZone in class javax.faces.convert.DateTimeConverter

setType

public void setType(String type)

Set the type of value to be formatted or parsed. Valid values are both, date, or time. An invalid value will cause a IllegalStateException when getAsObject() or getAsString() is called.

Overrides:
setType in class javax.faces.convert.DateTimeConverter
Parameters:
type - The new date style

getType

@JSFProperty(defaultValue="date")
public String getType()

Return the type of value to be formatted or parsed. If not explicitly set, the default type, date is returned.

Overrides:
getType in class javax.faces.convert.DateTimeConverter

setDateStyle

public void setDateStyle(String dateStyle)

Set the style to be used to format or parse dates. Valid values are default, shortish short, medium, long, and full. An invalid value will cause a IllegalStateException when getAsObject() or getAsString() is called.

Overrides:
setDateStyle in class javax.faces.convert.DateTimeConverter
Parameters:
dateStyle - The new style code

getDateStyle

@JSFProperty(defaultValue="shortish")
public String getDateStyle()

Return the style to be used to format or parse dates. If not set, the default value, shortish, is returned.

Overrides:
getDateStyle in class javax.faces.convert.DateTimeConverter
Returns:
date style
See Also:
setDateStyle(java.lang.String)

setTimeStyle

public void setTimeStyle(String timeStyle)

Set the style to be used to format or parse times. Valid values are default, short, medium, long, and full. An invalid value will cause a IllegalStateException when getAsObject() or getAsString() is called.

Overrides:
setTimeStyle in class javax.faces.convert.DateTimeConverter
Parameters:
timeStyle - The new style code

getTimeStyle

@JSFProperty(defaultValue="short")
public String getTimeStyle()

Return the style to be used to format or parse times. If not set, the default value, short, is returned.

Overrides:
getTimeStyle in class javax.faces.convert.DateTimeConverter

setSecondaryPattern

public void setSecondaryPattern(String secondaryPattern)

Second pattern which will be used to parse string in getAsObject if pattern or styles fail. But is never used for formatting to string in getAsString().

Parameters:
secondaryPattern - a second pattern which will be used as a second attempt to parse a string if the primary pattern or styles fail, but is never used for formatting strings.

getSecondaryPattern

@JSFProperty
public String getSecondaryPattern()

Return the secondary pattern used to parse string when parsing by pattern or style fails.


isTransient

public boolean isTransient()
Specified by:
isTransient in interface javax.faces.component.StateHolder
Overrides:
isTransient in class javax.faces.convert.DateTimeConverter

setTransient

public void setTransient(boolean isTransient)
Specified by:
setTransient in interface javax.faces.component.StateHolder
Overrides:
setTransient in class javax.faces.convert.DateTimeConverter

saveState

public Object saveState(javax.faces.context.FacesContext context)
Specified by:
saveState in interface javax.faces.component.StateHolder
Overrides:
saveState in class javax.faces.convert.DateTimeConverter

restoreState

public void restoreState(javax.faces.context.FacesContext context,
                         Object state)
Specified by:
restoreState in interface javax.faces.component.StateHolder
Overrides:
restoreState in class javax.faces.convert.DateTimeConverter

setValueExpression

public void setValueExpression(String name,
                               javax.el.ValueExpression expression)

Set the ValueExpression used to calculate the value for the specified attribute if any.

Parameters:
name - Name of the attribute for which to set a ValueExpression
expression - The ValueExpression to set, or null to remove any currently set ValueExpression
Throws:
NullPointerException - if name is null
IllegalArgumentException - if name is not a valid attribute of this converter

getValueExpression

public javax.el.ValueExpression getValueExpression(String name)

Return the ValueExpression used to calculate the value for the specified attribute name, if any.

Parameters:
name - Name of the attribute or property for which to retrieve a ValueExpression
Throws:
NullPointerException - if name is null
IllegalArgumentException - if name is not a valid attribute of this converter

setValueBinding

public void setValueBinding(String name,
                            javax.faces.el.ValueBinding binding)
Deprecated. 

Set the ValueBinding used to calculate the value for the specified attribute if any.

Parameters:
name - Name of the attribute for which to set a ValueBinding
binding - The ValueBinding to set, or null to remove any currently set ValueBinding
Throws:
NullPointerException - if name is null
IllegalArgumentException - if name is not a valid attribute of this converter

getValueBinding

public javax.faces.el.ValueBinding getValueBinding(String name)
Deprecated. 

Return the ValueBinding used to calculate the value for the specified attribute name, if any.

Parameters:
name - Name of the attribute or property for which to retrieve a ValueBinding
Throws:
NullPointerException - if name is null
IllegalArgumentException - if name is not a valid attribute of this converter

equals

public boolean equals(Object object)

Compares this DateTimeConverter with the specified Object for equality.

Overrides:
equals in class Object
Parameters:
object - Object to which this DateTimeConverter is to be compared.
Returns:
true if and only if the specified Object is a DateTimeConverter and if all parameters are equal.

hashCode

public int hashCode()

Returns the hash code for this Converter.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.

setDisabled

public void setDisabled(boolean isDisabled)

Set the value to property disabled. Default value is false.

Parameters:
isDisabled - true if it's disabled, false otherwise.

isDisabled

public boolean isDisabled()
Return whether it is disabled.

Returns:
true if it's disabled and false if it's enabled.

getDateFormat

protected final DateFormat getDateFormat(javax.faces.context.FacesContext context,
                                         String pattern,
                                         boolean forParsing,
                                         Date targetDate)
                                  throws javax.faces.convert.ConverterException
Throws:
javax.faces.convert.ConverterException

getFormattingTimeZone

protected TimeZone getFormattingTimeZone(TimeZone tZone)
Returns the TimeZone that will be set on DateFormat for formatting and parsing the dates. By default, this just returns the specified time zone, the one that is set on the DateTimeConverter or in the Adf-Faces config.


getFormattingTimeZone

protected TimeZone getFormattingTimeZone(TimeZone tZone,
                                         Date targetDate)
Returns the timeZone for formatting and parsing the date. TRINIDAD-1512: In some cases,timezone varies depending on the targetDate, e.g. daylight savings.


getParseErrorMessage

protected final javax.faces.application.FacesMessage getParseErrorMessage(javax.faces.context.FacesContext context,
                                                                          javax.faces.component.UIComponent component,
                                                                          String pattern,
                                                                          Object[] params)

getExample

protected final String getExample(javax.faces.context.FacesContext context)

getMessagePattern

protected Object getMessagePattern(javax.faces.context.FacesContext context,
                                   String key,
                                   Object[] params,
                                   javax.faces.component.UIComponent component)

getViolationMessageKey

protected String getViolationMessageKey(String pattern)


Copyright © 2001-2012 The Apache Software Foundation. All Rights Reserved.