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}