1 /* 2 * Copyright (c) 2007-present, Stephen Colebourne & Michael Nascimento Santos 3 * 4 * All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions are met: 8 * 9 * * Redistributions of source code must retain the above copyright notice, 10 * this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright notice, 13 * this list of conditions and the following disclaimer in the documentation 14 * and/or other materials provided with the distribution. 15 * 16 * * Neither the name of JSR-310 nor the names of its contributors 17 * may be used to endorse or promote products derived from this software 18 * without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 23 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 27 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 28 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 29 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 package org.threeten.bp.format; 33 34 import java.util.Iterator; 35 import java.util.Locale; 36 import java.util.Map.Entry; 37 import java.util.concurrent.atomic.AtomicReference; 38 39 import org.threeten.bp.temporal.TemporalField; 40 41 /** 42 * The Service Provider Interface (SPI) to be implemented by classes providing 43 * the textual form of a date-time field. 44 * 45 * <h3>Specification for implementors</h3> 46 * This interface is a service provider that can be called by multiple threads. 47 * Implementations must be thread-safe. 48 * Implementations should cache the textual information. 49 * <p> 50 * This class has been made pubilc primarily for the benefit of Android. 51 */ 52 public abstract class DateTimeTextProvider { 53 54 private static final AtomicReference<DateTimeTextProvider> MUTABLE_PROVIDER = new AtomicReference<DateTimeTextProvider>(); 55 56 /** 57 * Gets the provider. 58 * 59 * @return the provider, not null 60 */ getInstance()61 static DateTimeTextProvider getInstance() { 62 return ProviderSingleton.PROVIDER; 63 } 64 65 /** 66 * Sets the provider to use. 67 * <p> 68 * This can only be invoked before {@link DateTimeTextProvider} class is used for formatting/parsing. 69 * Invoking this method at a later point will throw an exception. 70 * 71 * @param provider the provider to use 72 * @throws IllegalStateException if initialization has already occurred or another provider has been set 73 */ setInitializer(DateTimeTextProvider provider)74 public static void setInitializer(DateTimeTextProvider provider) { 75 if (!MUTABLE_PROVIDER.compareAndSet(null, provider)) { 76 throw new IllegalStateException("Provider was already set, possibly with a default during initialization"); 77 } 78 } 79 80 //----------------------------------------------------------------------- 81 /** 82 * Gets the text for the specified field, locale and style 83 * for the purpose of printing. 84 * <p> 85 * The text associated with the value is returned. 86 * The null return value should be used if there is no applicable text, or 87 * if the text would be a numeric representation of the value. 88 * 89 * @param field the field to get text for, not null 90 * @param value the field value to get text for, not null 91 * @param style the style to get text for, not null 92 * @param locale the locale to get text for, not null 93 * @return the text for the field value, null if no text found 94 */ getText(TemporalField field, long value, TextStyle style, Locale locale)95 public abstract String getText(TemporalField field, long value, TextStyle style, Locale locale); 96 97 /** 98 * Gets an iterator of text to field for the specified field, locale and style 99 * for the purpose of parsing. 100 * <p> 101 * The iterator must be returned in order from the longest text to the shortest. 102 * <p> 103 * The null return value should be used if there is no applicable parsable text, or 104 * if the text would be a numeric representation of the value. 105 * Text can only be parsed if all the values for that field-style-locale combination are unique. 106 * 107 * @param field the field to get text for, not null 108 * @param style the style to get text for, null for all parsable text 109 * @param locale the locale to get text for, not null 110 * @return the iterator of text to field pairs, in order from longest text to shortest text, 111 * null if the field or style is not parsable 112 */ getTextIterator(TemporalField field, TextStyle style, Locale locale)113 public abstract Iterator<Entry<String, Long>> getTextIterator(TemporalField field, TextStyle style, Locale locale); 114 115 //----------------------------------------------------------------------- 116 // use JVM class initializtion to lock the singleton without additional synchronization 117 static class ProviderSingleton { 118 static final DateTimeTextProvider PROVIDER = initialize(); 119 120 // initialize the provider initialize()121 static DateTimeTextProvider initialize() { 122 // Set the default initializer if none has been provided yet 123 MUTABLE_PROVIDER.compareAndSet(null, new SimpleDateTimeTextProvider()); 124 return MUTABLE_PROVIDER.get(); 125 } 126 } 127 128 } 129