001/*
002 * CREDIT SUISSE IS WILLING TO LICENSE THIS SPECIFICATION TO YOU ONLY UPON THE
003 * CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS AGREEMENT.
004 * PLEASE READ THE TERMS AND CONDITIONS OF THIS AGREEMENT CAREFULLY. BY
005 * DOWNLOADING THIS SPECIFICATION, YOU ACCEPT THE TERMS AND CONDITIONS OF THE
006 * AGREEMENT. IF YOU ARE NOT WILLING TO BE BOUND BY IT, SELECT THE "DECLINE"
007 * BUTTON AT THE BOTTOM OF THIS PAGE.
008 * 
009 * Specification: JSR-354 Money and Currency API ("Specification")
010 * 
011 * Copyright (c) 2012-2013, Credit Suisse All rights reserved.
012 */
013package org.javamoney.moneta.format;
014
015import java.io.IOException;
016import java.text.ParseException;
017import java.util.Locale;
018
019import javax.money.MonetaryAmount;
020
021/**
022 * Formats instances of {@code T} to a {@link String} or an {@link Appendable}.
023 * Instances of {@link FormatToken} can be added to a {@link ItemFormatBuilder}
024 * to assemble a complex input/output {@link ItemFormat} using a programmatic
025 * fluent API. Hereby each {@link FormatToken} instance represent a part of the
026 * overall formatted String. Similarly when parsing an input by calling
027 * {@link ItemFormat#parse(CharSequence, Locale)} each {@link FormatToken} can
028 * read and forward the current {@link ParseContext}, or through an error, if
029 * the input does not provide a parseable input for the given
030 * {@link FormatToken}.
031 * <p>
032 * Classes implementing this interface are required to be thread-safe and
033 * immutable.
034 * 
035 * @author Anatole Tresch
036 */
037public interface FormatToken {
038
039        /**
040         * Prints an item value to an {@code Appendable}.
041         * <p>
042         * Example implementations of {@code Appendable} are {@code StringBuilder},
043         * {@code StringBuffer} or {@code Writer}. Note that {@code StringBuilder}
044         * and {@code StringBuffer} never throw an {@code IOException}.
045         * 
046         * @param appendable
047         *            the appendable to add to, not null
048         * @param item
049         *            the item to print, not null
050         * @param locale
051         *            the {@link Locale} to be used, not null.
052         * @throws UnsupportedOperationException
053         *             if the formatter is unable to print
054         * @throws IOException
055         *             if an IO error occurs
056         */
057        public void print(Appendable appendable, MonetaryAmount amount)
058                        throws IOException;
059
060        /**
061         * Parses an item from the given {@link ParseContext}. Any parsed item can
062         * be added to the {@link ParseContext} using
063         * {@link ParseContext#addParseResult(Object, Object)} as results. At the
064         * end of the parsing process an instance of {@link ItemFactory} is
065         * transferring the results parsed into the target item to be parsed.
066         * 
067         * @param context
068         *            the parse context
069         * @param locale
070         *            the {@link Locale} to be used, not null.
071         * @param style
072         *            the {@link LocalizationStyle} to be used.
073         * @throws ParseException
074         *             thrown, if parsing fails.
075         */
076        public void parse(ParseContext context)
077                        throws ParseException;
078
079}