org.nuiton.util.converter.FormatConverter Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of nuiton-utils Show documentation
Library of usefull class to be used in any project.
There is a newer version: 3.1
/*
 * #%L
 * Nuiton Utils
 * 
 * $Id: FormatConverter.java 2360 2012-06-11 10:24:36Z tchemit $
 * $HeadURL: http://svn.nuiton.org/svn/nuiton-utils/tags/nuiton-utils-2.6.10/nuiton-utils/src/main/java/org/nuiton/util/converter/FormatConverter.java $
 * %%
 * Copyright (C) 2004 - 2010 CodeLutin
 * %%
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as 
 * published by the Free Software Foundation, either version 3 of the 
 * License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Lesser Public License for more details.
 * 
 * You should have received a copy of the GNU General Lesser Public 
 * License along with this program.  If not, see
 * .
 * #L%
 */

/* *
 * FormatConverter.java
 *
 * Created: 14 septembre 2005 00:55:19 CEST
 *
 * @author Benjamin POUSSIN 
 * @version $Revision: 2360 $
 *
 * Last update: $Date: 2012-06-11 12:24:36 +0200 (Mon, 11 Jun 2012) $
 * by : */

package org.nuiton.util.converter;

import org.nuiton.util.converter.FormatMap.Format;

/**
 * Un converter est un objet qui permet de passé d'une representation d'un
 * objet vers une autre representation. Le mininum que converter doit savoir
 * faire, est de converter une representation Java vers le format qu'il
 * gère et inversement. Pour des raisons d'optimisation, il est possible
 * qu'un converter sache passé d'un autre type que java vers sa representation
 * pour eviter une conversion supplémentaire qui pourrait-etre couteuse.
 *
 * @param  le type de l'objet a convertir
 */
public interface FormatConverter { // FormatConverter

    Format FORMAT_JAVA = new Format("Format Java");

    /**
     * Convertie une valeur vers la representation FORMAT géré par cette classe
     *
     * @param factory la factory utilisable pour rechercher d'autre converter
     *                si la representation Java n'est pas presente dans values et que l'on
     *                en a besoin
     * @param format  le format souhaité en sortie
     * @param values  une map contenant les différentes representation de la
     *                meme valeur. Les cles de la map sont les valeurs retournés par la
     *                methode getFormat().
     * @param args    des arguments qui peuvent-être utile pour la conversion.
     *                par exemple si dans une application on a construit son propre
     *                converter et que pour la conversion, on a besoin d'un Context applicatif
     *                il peut-etre passé dans les args. Si le converter a besoin d'autre
     *                converter les memes args lui seront passé.
     * @return l'objet dans la representation demandés par type
     * @throws IllegalArgumentException si auncun moyen n'est trouve pour
     *                                  convertir une des valeurs de values dans le format géré par cette classe.
     *                                  Ou s'il manque dans les args des objets utils pour la conversion.
     */
    A convert(FormatConverterFactory factory,
              Format format, FormatMap values, Object... args);

    /**
     * Convertie une valeur vers le Java
     *
     * @param factory la factory utilisable pour rechercher d'autre converter
     *                si la representation Java n'est pas presente dans values et que l'on
     *                en a besoin
     * @param format  le format à utiliser comme valeur d'entré
     * @param values  une map contenant les différentes representation de la
     *                meme valeur. La valeur interessante dans la map pour cette methode
     *                est celle retournée par values.get(getFormat()) si cet appel, ne
     *                retourne pas quelque chose de valid, la methode doit lever une exception
     * @param args    des arguments qui peuvent-être utile pour la conversion.
     *                par exemple si dans une application on a construit son propre
     *                converter et que pour la conversion, on a besoin d'un Context applicatif
     *                il peut-etre passé dans les args. Si le converter a besoin d'autre
     *                converter les memes args lui seront passé.
     * @return la valeur java
     * @throws IllegalArgumentException si le format géré par cette classe n'est
     *                                  pas trouvé dans les values. Ou s'il manque dans les args des objets utils
     *                                  pour la conversion.
     */
    Object unconvert(FormatConverterFactory factory,
                     Format format, FormatMap values, Object... args);

} // FormatConverter