001/*
002 * Units of Measurement API
003 * Copyright (c) 2014-2021, Jean-Marie Dautelle, Werner Keil, Otavio Santana.
004 *
005 * All rights reserved.
006 *
007 * Redistribution and use in source and binary forms, with or without modification,
008 * are permitted provided that the following conditions are met:
009 *
010 * 1. Redistributions of source code must retain the above copyright notice,
011 *    this list of conditions and the following disclaimer.
012 *
013 * 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions
014 *    and the following disclaimer in the documentation and/or other materials provided with the distribution.
015 *
016 * 3. Neither the name of JSR-385 nor the names of its contributors may be used to endorse or promote products
017 *    derived from this software without specific prior written permission.
018 *
019 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
020 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
021 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
022 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
023 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
024 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
025 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
026 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
027 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
028 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
029 */
030package javax.measure.format;
031
032import java.io.IOException;
033import java.text.ParsePosition;
034
035import javax.measure.Unit;
036
037/**
038 * Formats instances of {@link Unit} to a {@link String} or {@link Appendable} and parses a {@link CharSequence} to a {@link Unit}.
039 *
040 * <dl>
041 * <dt><span class="strong"><a id="synchronization">Synchronization</a></span></dt>
042 * </dl> 
043 * <p>
044 * Instances of this class are not required to be thread-safe. It is recommended to use separate format instances for each thread. If multiple threads
045 * access a format concurrently, it must be synchronized externally.
046 * <p>
047 *
048 * @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
049 * @author <a href="mailto:werner@uom.technology">Werner Keil</a>
050 *
051 * @version 2.0, July 3, 2020
052 * @since 1.0
053 *
054 * @see Unit
055 */
056public interface UnitFormat {
057    /**
058     * Formats the specified {@link Unit}.
059     *
060     * @param unit
061     *            the {@link Unit} to format, not {@code null}
062     * @param appendable
063     *            the appendable destination.
064     * @return the appendable destination passed in with formatted text appended.
065     * @throws IOException
066     *             if an error occurs while writing to the destination.
067     */
068    Appendable format(Unit<?> unit, Appendable appendable) throws IOException;
069
070    /**
071     * Formats the specified {@link Unit}.
072     *
073     * @param unit
074     *            the {@link Unit} to format, not {@code null}
075     * @return the string representation using the settings of this {@link UnitFormat}.
076     */
077    String format(Unit<?> unit);
078
079    /**
080     * Attaches a system-wide label to the specified unit.
081     * <p>
082     * If the specified label is already associated to a unit the previous association can be discarded or ignored. Depending on the
083     * {@link UnitFormat} implementation, this call may be ignored if the particular unit already has a label.
084     * </p>
085     * If a {@link UnitFormat} implementation is explicitly <b>immutable</b>, similar to e.g. the result of <code>Collections.unmodifiableList()</code>,
086     * then an {@linkplain UnsupportedOperationException} may be thrown upon this call.
087     * <p>
088     * Since <code>UnitFormat</code> implementations often apply the Singleton pattern, <b>system-wide</b> means, the label applies to every instance of
089     * <code>UnitFormatA</code> implementing <code>UnitFormat</code> in this case, but not every instance of <code>UnitFormatB</code> or <code>UnitFormatC</code> both
090     * also implementing <code>UnitFormat</code>. If a <code>UnitFormat</code> #isLocaleSensitive() it is up to the implementation, whether the label is
091     * ignored, applied in a local-neutral manner (in addition to its local-sensitive information) or locale-specific.
092     * </p>
093     *
094     * @param unit
095     *            the unit being labeled.
096     * @param label
097     *            the new label for this unit.
098     * @throws IllegalArgumentException
099     *             if the label is not a valid identifier. This may include characters not supported by a particular {@link UnitFormat} implementation
100     *             (e.g. only <b>ASCII</b> characters for certain devices)
101     * @throws UnsupportedOperationException
102     *             if the <code>label</code> operation is not supported by this {@link UnitFormat}
103     */
104    void label(Unit<?> unit, String label);
105
106    /**
107     * Returns <code>true</code> if this {@link UnitFormat} depends on a <code>Locale</code> to perform its tasks.
108     * <p>
109     * In environments that do not support a <code>Locale</code>, e.g. Java ME, this usually returns <code>false</code>.
110     * </p>
111     *
112     * @return Whether this format depends on a locale.
113     */
114    default boolean isLocaleSensitive() {
115        return false;
116    }
117
118    /**
119     * Parses a portion of the specified <code>CharSequence</code> from the specified position to produce a {@link Unit}.
120     * If parsing succeeds, then the index of the <code>pos</code> argument is updated to the index after the last character used.
121     *
122     * @param csq
123     *            the <code>CharSequence</code> to parse.
124     * @param pos
125     *            a ParsePosition object holding the current parsing index and error parsing index information as described above.
126     * @return the unit parsed from the specified character sub-sequence.
127     * @throws IllegalArgumentException
128     *             if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).
129     * @since 2.0
130     */
131    Unit<?> parse(CharSequence csq, ParsePosition pos) throws IllegalArgumentException, MeasurementParseException;
132
133    /**
134     * Parses the text into an instance of {@link Unit}.
135     * <p>
136     * The parse must complete normally and parse the entire text. If the parse completes without reading the entire length of the text, an exception
137     * is thrown. If any other problem occurs during parsing, an exception is thrown.
138     * <p>
139     *
140     * @param csq
141     *            the {@code CharSequence} to parse.
142     * @return the unit parsed from the specified character sequence.
143     * @throws MeasurementParseException
144     *             if any problem occurs while parsing the specified character sequence (e.g. illegal syntax).
145     * @throws UnsupportedOperationException
146     *             if the {@link UnitFormat} is unable to parse.
147     * @since 2.0
148     */
149    Unit<?> parse(CharSequence csq) throws MeasurementParseException;
150}