javax.faces.convert.Converter Maven / Gradle / Ivy
Show all versions of jakarta.faces Show documentation
/*
* Copyright (c) 1997, 2018 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package javax.faces.convert;
import javax.faces.component.StateHolder;
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
/**
* Converter is an
* interface describing a Java class that can perform Object-to-String
* and String-to-Object conversions between model data objects and a
* String representation of those objects that is suitable for
* rendering.
*
* {@link Converter} implementations must have a zero-arguments public
* constructor. In addition, if the {@link Converter} class wishes to have
* configuration property values saved and restored with the component tree,
* the implementation must also implement {@link StateHolder}.
*
* Starting with version 1.2 of the specification, an exception to the above
* zero-arguments constructor requirement has been introduced. If a converter has
* a single argument constructor that takes a Class instance and
* the Class of the data to be converted is
* known at converter instantiation time, this constructor
* must be used to instantiate the converter instead of the zero-argument
* version. This enables the per-class conversion
* of Java enumerated types.
*
* If any Converter implementation requires a
* java.util.Locale to perform its job, it must obtain that
* Locale from the {@link javax.faces.component.UIViewRoot}
* of the current {@link FacesContext}, unless the
* Converter maintains its own Locale as part
* of its state.
*
* If the class implementing
* Converter has a {@link
* javax.faces.application.ResourceDependency} annotation, the action
* described in ResourceDependency must be taken when
* {@link javax.faces.component.ValueHolder#setConverter} is called.
* If the class implementing Converter has a {@link
* javax.faces.application.ResourceDependencies} annotation, the
* action described in ResourceDependencies must be taken
* when {@link javax.faces.component.ValueHolder#setConverter} is called.
*
* @param The generic type of object value to convert.
*/
public interface Converter {
/**
* Convert the specified string value, which is associated with
* the specified {@link UIComponent}, into a model data object that
* is appropriate for being stored during the Process Validations
* phase of the request processing lifecycle.
*
* @param context {@link FacesContext} for the request being processed
* @param component {@link UIComponent} with which this model object
* value is associated
* @param value String value to be converted (may be null)
* @return null if the value to convert is null,
* otherwise the result of the conversion
* @throws ConverterException if conversion cannot be successfully
* performed
* @throws NullPointerException if context or
* component is null
*/
public T getAsObject(FacesContext context, UIComponent component,
String value);
/**
* Convert the specified model object value, which is associated with
* the specified {@link UIComponent}, into a String that is suitable
* for being included in the response generated during the
* Render Response phase of the request processing
* lifeycle.
*
* @param context {@link FacesContext} for the request being processed
* @param component {@link UIComponent} with which this model object
* value is associated
* @param value Model object value to be converted
* (may be null)
* @return a zero-length String if value is null,
* otherwise the result of the conversion
* @throws ConverterException if conversion cannot be successfully
* performed
* @throws NullPointerException if context or
* component is null
*/
public String getAsString(FacesContext context, UIComponent component,
T value);
/**
*
* If this param is set, and calling toLowerCase().equals("true") on a
* String representation of its value returns true,
* Application.createConverter() must guarantee that the default for the
* timezone of all javax.faces.convert.DateTimeConverter instances must
* be equal to TimeZone.getDefault() instead of "GMT".
*
*
* @since 2.0
*/
public static final String DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SYSTEM_TIMEZONE_PARAM_NAME =
"javax.faces.DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SYSTEM_TIMEZONE";
}