archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 14:54:52 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8187443: Forest Consolidation: Move files to unified layout

Browse source 
Reviewed-by: darcy, ihse
This commit is contained in:
Erik Joelsson 2017-09-12 19:03:39 +02:00
parent 270fe13182
commit 3789983e89
56923 changed files with 3 additions and 15727 deletions
Download patch file Download diff file Expand all files Collapse all files

263
src/java.base/share/classes/java/util/spi/AbstractResourceBundleProvider.java Normal file
View file

@ -0,0 +1,263 @@
/*
* Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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 Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util.spi;
import jdk.internal.misc.JavaUtilResourceBundleAccess;
import jdk.internal.misc.SharedSecrets;
import java.io.IOException;
import java.io.InputStream;
import java.io.UncheckedIOException;
import java.security.AccessController;
import java.security.PrivilegedAction;
import java.util.Locale;
import java.util.PropertyResourceBundle;
import java.util.ResourceBundle;
import static sun.security.util.SecurityConstants.GET_CLASSLOADER_PERMISSION;
/**
* {@code AbstractResourceBundleProvider} is an abstract class that provides
* the basic support for a provider implementation class for
* {@link ResourceBundleProvider}.
*
* <p>
* Resource bundles can be packaged in one or more
* named modules, <em>bundle modules</em>. The <em>consumer</em> of the
* resource bundle is the one calling {@link ResourceBundle#getBundle(String)}.
* In order for the consumer module to load a resource bundle
* "{@code com.example.app.MyResources}" provided by another module,
* it will use the {@linkplain java.util.ServiceLoader service loader}
* mechanism. A service interface named "{@code com.example.app.MyResourcesProvider}"
* must be defined and a <em>bundle provider module</em> will provide an
* implementation class of "{@code com.example.app.MyResourcesProvider}"
* as follows:
*
* <pre><code>
* import com.example.app.MyResourcesProvider;
* class MyResourcesProviderImpl extends AbstractResourceBundleProvider
* implements MyResourcesProvider
* {
* protected String toBundleName(String baseName, Locale locale) {
* // return the bundle name per the naming of the resource bundle
* :
* }
*
* public ResourceBundle getBundle(String baseName, Locale locale) {
* // this module only provides bundles in french
* if (locale.equals(Locale.FRENCH)) {
* return super.getBundle(baseName, locale);
* }
* return null;
* }
* }</code></pre>
*
* @see <a href="../ResourceBundle.html#bundleprovider">
* Resource Bundles in Named Modules</a>
* @see <a href="../ResourceBundle.html#RBP_support">
* ResourceBundleProvider Service Providers</a>
*
* @since 9
* @spec JPMS
*/
public abstract class AbstractResourceBundleProvider implements ResourceBundleProvider {
private static final JavaUtilResourceBundleAccess RB_ACCESS =
SharedSecrets.getJavaUtilResourceBundleAccess();
private static final String FORMAT_CLASS = "java.class";
private static final String FORMAT_PROPERTIES = "java.properties";
private final String[] formats;
/**
* Constructs an {@code AbstractResourceBundleProvider} with the
* "java.properties" format. This constructor is equivalent to
* {@code AbstractResourceBundleProvider("java.properties")}.
*/
protected AbstractResourceBundleProvider() {
this(FORMAT_PROPERTIES);
}
/**
* Constructs an {@code AbstractResourceBundleProvider} with the specified
* {@code formats}. The {@link #getBundle(String, Locale)} method looks up
* resource bundles for the given {@code formats}. {@code formats} must
* be "java.class" or "java.properties".
*
* @param formats the formats to be used for loading resource bundles
* @throws NullPointerException if the given {@code formats} is null
* @throws IllegalArgumentException if the given {@code formats} is not
* "java.class" or "java.properties".
*/
protected AbstractResourceBundleProvider(String... formats) {
this.formats = formats.clone(); // defensive copy
if (this.formats.length == 0) {
throw new IllegalArgumentException("empty formats");
}
for (String f : this.formats) {
if (!FORMAT_CLASS.equals(f) && !FORMAT_PROPERTIES.equals(f)) {
throw new IllegalArgumentException(f);
}
}
}
/**
* Returns the bundle name for the given {@code baseName} and {@code
* locale} that this provider provides.
*
* @apiNote
* A resource bundle provider may package its resource bundles in the
* same package as the base name of the resource bundle if the package
* is not split among other named modules. If there are more than one
* bundle providers providing the resource bundle of a given base name,
* the resource bundles can be packaged with per-language grouping
* or per-region grouping to eliminate the split packages.
*
* <p>For example, if {@code baseName} is {@code "p.resources.Bundle"} then
* the resource bundle name of {@code "p.resources.Bundle"} of
* <code style="white-space:nowrap">Locale("ja", "", "XX")</code>
* and {@code Locale("en")} could be <code style="white-space:nowrap">
* "p.resources.ja.Bundle_ja_&thinsp;_XX"</code> and
* {@code "p.resources.Bundle_en"} respectively.
*
* <p> This method is called from the default implementation of the
* {@link #getBundle(String, Locale)} method.
*
* @implNote The default implementation of this method is the same as the
* implementation of
* {@link java.util.ResourceBundle.Control#toBundleName(String, Locale)}.
*
* @param baseName the base name of the resource bundle, a fully qualified
* class name
* @param locale the locale for which a resource bundle should be loaded
* @return the bundle name for the resource bundle
*/
protected String toBundleName(String baseName, Locale locale) {
return ResourceBundle.Control.getControl(ResourceBundle.Control.FORMAT_DEFAULT)
.toBundleName(baseName, locale);
}
/**
* Returns a {@code ResourceBundle} for the given {@code baseName} and
* {@code locale}.
*
* @implNote
* The default implementation of this method calls the
* {@link #toBundleName(String, Locale) toBundleName} method to get the
* bundle name for the {@code baseName} and {@code locale} and finds the
* resource bundle of the bundle name local in the module of this provider.
* It will only search the formats specified when this provider was
* constructed.
*
* @param baseName the base bundle name of the resource bundle, a fully
* qualified class name.
* @param locale the locale for which the resource bundle should be instantiated
* @return {@code ResourceBundle} of the given {@code baseName} and
* {@code locale}, or {@code null} if no resource bundle is found
* @throws NullPointerException if {@code baseName} or {@code locale} is
* {@code null}
* @throws UncheckedIOException if any IO exception occurred during resource
* bundle loading
*/
@Override
public ResourceBundle getBundle(String baseName, Locale locale) {
Module module = this.getClass().getModule();
String bundleName = toBundleName(baseName, locale);
ResourceBundle bundle = null;
for (String format : formats) {
try {
if (FORMAT_CLASS.equals(format)) {
bundle = loadResourceBundle(module, bundleName);
} else if (FORMAT_PROPERTIES.equals(format)) {
bundle = loadPropertyResourceBundle(module, bundleName);
}
if (bundle != null) {
break;
}
} catch (IOException e) {
throw new UncheckedIOException(e);
}
}
return bundle;
}
/*
* Returns the ResourceBundle of .class format if found in the module
* of this provider.
*/
private static ResourceBundle loadResourceBundle(Module module, String bundleName)
{
PrivilegedAction<Class<?>> pa = () -> Class.forName(module, bundleName);
Class<?> c = AccessController.doPrivileged(pa, null, GET_CLASSLOADER_PERMISSION);
if (c != null && ResourceBundle.class.isAssignableFrom(c)) {
@SuppressWarnings("unchecked")
Class<ResourceBundle> bundleClass = (Class<ResourceBundle>) c;
return RB_ACCESS.newResourceBundle(bundleClass);
}
return null;
}
/*
* Returns the ResourceBundle of .property format if found in the module
* of this provider.
*/
private static ResourceBundle loadPropertyResourceBundle(Module module,
String bundleName)
throws IOException
{
String resourceName = toResourceName(bundleName, "properties");
if (resourceName == null) {
return null;
}
PrivilegedAction<InputStream> pa = () -> {
try {
return module.getResourceAsStream(resourceName);
} catch (IOException e) {
throw new UncheckedIOException(e);
}
};
try (InputStream stream = AccessController.doPrivileged(pa)) {
if (stream != null) {
return new PropertyResourceBundle(stream);
} else {
return null;
}
} catch (UncheckedIOException e) {
throw e.getCause();
}
}
private static String toResourceName(String bundleName, String suffix) {
if (bundleName.contains("://")) {
return null;
}
StringBuilder sb = new StringBuilder(bundleName.length() + 1 + suffix.length());
sb.append(bundleName.replace('.', '/')).append('.').append(suffix);
return sb.toString();
}
}

81
src/java.base/share/classes/java/util/spi/CalendarDataProvider.java Normal file
View file

@ -0,0 +1,81 @@
/*
* Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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 Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util.spi;
import java.util.Calendar;
import java.util.Locale;
/**
* An abstract class for service providers that provide locale-dependent {@link
* Calendar} parameters.
*
* @author Masayoshi Okutsu
* @since 1.8
* @see CalendarNameProvider
*/
public abstract class CalendarDataProvider extends LocaleServiceProvider {
/**
* Sole constructor. (For invocation by subclass constructors, typically
* implicit.)
*/
protected CalendarDataProvider() {
}
/**
* Returns the first day of a week in the given {@code locale}. This
* information is required by {@link Calendar} to support operations on the
* week-related calendar fields.
*
* @param locale
* the desired locale
* @return the first day of a week; one of {@link Calendar#SUNDAY} ..
* {@link Calendar#SATURDAY},
* or 0 if the value isn't available for the {@code locale}
* @throws NullPointerException
* if {@code locale} is {@code null}.
* @see java.util.Calendar#getFirstDayOfWeek()
* @see <a href="../Calendar.html#first_week">First Week</a>
*/
public abstract int getFirstDayOfWeek(Locale locale);
/**
* Returns the minimal number of days required in the first week of a
* year. This information is required by {@link Calendar} to determine the
* first week of a year. Refer to the description of <a
* href="../Calendar.html#first_week"> how {@code Calendar} determines
* the first week</a>.
*
* @param locale
* the desired locale
* @return the minimal number of days of the first week,
* or 0 if the value isn't available for the {@code locale}
* @throws NullPointerException
* if {@code locale} is {@code null}.
* @see java.util.Calendar#getMinimalDaysInFirstWeek()
*/
public abstract int getMinimalDaysInFirstWeek(Locale locale);
}

301
src/java.base/share/classes/java/util/spi/CalendarNameProvider.java Normal file
View file

@ -0,0 +1,301 @@
/*
* Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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 Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util.spi;
import java.util.Calendar;
import java.util.Locale;
import java.util.Map;
/**
* An abstract class for service providers that provide localized string
* representations (display names) of {@code Calendar} field values.
*
* <p><a id="calendartypes"><b>Calendar Types</b></a>
*
* <p>Calendar types are used to specify calendar systems for which the {@link
* #getDisplayName(String, int, int, int, Locale) getDisplayName} and {@link
* #getDisplayNames(String, int, int, Locale) getDisplayNames} methods provide
* calendar field value names. See {@link Calendar#getCalendarType()} for details.
*
* <p><b>Calendar Fields</b>
*
* <p>Calendar fields are specified with the constants defined in {@link
* Calendar}. The following are calendar-common fields and their values to be
* supported for each calendar system.
*
* <table class="striped">
* <caption style="display:none">Field values</caption>
* <thead>
* <tr>
* <th scope="col">Field</th>
* <th scope="col">Value</th>
* <th scope="col">Description</th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <th scope="row" style="vertical-align:top">{@link Calendar#MONTH}</th>
* <td style="vertical-align:top">{@link Calendar#JANUARY} to {@link Calendar#UNDECIMBER}</td>
* <td>Month numbering is 0-based (e.g., 0 - January, ..., 11 -
* December). Some calendar systems have 13 months. Month
* names need to be supported in both the formatting and
* stand-alone forms if required by the supported locales. If there's
* no distinction in the two forms, the same names should be returned
* in both of the forms.</td>
* </tr>
* <tr>
* <th scope="row" style="vertical-align:top">{@link Calendar#DAY_OF_WEEK}</th>
* <td style="vertical-align:top">{@link Calendar#SUNDAY} to {@link Calendar#SATURDAY}</td>
* <td>Day-of-week numbering is 1-based starting from Sunday (i.e., 1 - Sunday,
* ..., 7 - Saturday).</td>
* </tr>
* <tr>
* <th scope="row" style="vertical-align:top">{@link Calendar#AM_PM}</th>
* <td style="vertical-align:top">{@link Calendar#AM} to {@link Calendar#PM}</td>
* <td>0 - AM, 1 - PM</td>
* </tr>
* </tbody>
* </table>
*
* <p style="margin-top:20px">The following are calendar-specific fields and their values to be supported.
*
* <table class="plain">
* <caption style="display:none">Calendar type and field values</caption>
* <thead>
* <tr>
* <th scope="col">Calendar Type</th>
* <th scope="col">Field</th>
* <th scope="col">Value</th>
* <th scope="col">Description</th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <th scope="row"rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@code "gregory"}</th>
* <th scope="row" rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@link Calendar#ERA}</th>
* <th scope="row" style="font-weight:normal">0</th>
* <td>{@link java.util.GregorianCalendar#BC} (BCE)</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">1</th>
* <td>{@link java.util.GregorianCalendar#AD} (CE)</td>
* </tr>
* <tr>
* <th scope="row" rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@code "buddhist"}</th>
* <th scope="row" rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@link Calendar#ERA}</th>
* <th scope="row" style="font-weight:normal">0</th>
* <td>BC (BCE)</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">1</th>
* <td>B.E. (Buddhist Era)</td>
* </tr>
* <tr>
* <th scope="row" rowspan="6" style="font-weight:normal; text-align:left; vertical-align:top">{@code "japanese"}</th>
* <th scope="row" rowspan="5" style="font-weight:normal; text-align:left; vertical-align:top">{@link Calendar#ERA}</th>
* <th scope="row" style="font-weight:normal">0</th>
* <td>Seireki (Before Meiji)</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">1</th>
* <td>Meiji</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">2</th>
* <td>Taisho</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">3</th>
* <td>Showa</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">4</th>
* <td >Heisei</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal; text-align:left; vertical-align:top">{@link Calendar#YEAR}</th>
* <th scope="row" style="font-weight:normal">1</th>
* <td>the first year in each era. It should be returned when a long
* style ({@link Calendar#LONG_FORMAT} or {@link Calendar#LONG_STANDALONE}) is
* specified. See also the <a href="../../text/SimpleDateFormat.html#year">
* Year representation in {@code SimpleDateFormat}</a>.</td>
* </tr>
* <tr>
* <th scope="row" rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@code "roc"}</th>
* <th scope="row" rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@link Calendar#ERA}</th>
* <th scope="row" style="font-weight:normal">0</th>
* <td>Before R.O.C.</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">1</th>
* <td>R.O.C.</td>
* </tr>
* <tr>
* <th scope="row" rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@code "islamic"}</th>
* <th scope="row" rowspan="2" style="font-weight:normal; text-align:left; vertical-align:top">{@link Calendar#ERA}</th>
* <th scope="row" style="font-weight:normal">0</th>
* <td>Before AH</td>
* </tr>
* <tr>
* <th scope="row" style="font-weight:normal">1</th>
* <td>Anno Hijrah (AH)</td>
* </tr>
* </tbody>
* </table>
*
* <p>Calendar field value names for {@code "gregory"} must be consistent with
* the date-time symbols provided by {@link java.text.spi.DateFormatSymbolsProvider}.
*
* <p>Time zone names are supported by {@link TimeZoneNameProvider}.
*
* @author Masayoshi Okutsu
* @since 1.8
* @see CalendarDataProvider
* @see Locale#getUnicodeLocaleType(String)
*/
public abstract class CalendarNameProvider extends LocaleServiceProvider {
/**
* Sole constructor. (For invocation by subclass constructors, typically
* implicit.)
*/
protected CalendarNameProvider() {
}
/**
* Returns the string representation (display name) of the calendar
* <code>field value</code> in the given <code>style</code> and
* <code>locale</code>. If no string representation is
* applicable, <code>null</code> is returned.
*
* <p>{@code field} is a {@code Calendar} field index, such as {@link
* Calendar#MONTH}. The time zone fields, {@link Calendar#ZONE_OFFSET} and
* {@link Calendar#DST_OFFSET}, are <em>not</em> supported by this
* method. {@code null} must be returned if any time zone fields are
* specified.
*
* <p>{@code value} is the numeric representation of the {@code field} value.
* For example, if {@code field} is {@link Calendar#DAY_OF_WEEK}, the valid
* values are {@link Calendar#SUNDAY} to {@link Calendar#SATURDAY}
* (inclusive).
*
* <p>{@code style} gives the style of the string representation. It is one
* of {@link Calendar#SHORT_FORMAT} ({@link Calendar#SHORT SHORT}),
* {@link Calendar#SHORT_STANDALONE}, {@link Calendar#LONG_FORMAT}
* ({@link Calendar#LONG LONG}), {@link Calendar#LONG_STANDALONE},
* {@link Calendar#NARROW_FORMAT}, or {@link Calendar#NARROW_STANDALONE}.
*
* <p>For example, the following call will return {@code "Sunday"}.
* <pre>
* getDisplayName("gregory", Calendar.DAY_OF_WEEK, Calendar.SUNDAY,
* Calendar.LONG_STANDALONE, Locale.ENGLISH);
* </pre>
*
* @param calendarType
* the calendar type. (Any calendar type given by {@code locale}
* is ignored.)
* @param field
* the {@code Calendar} field index,
* such as {@link Calendar#DAY_OF_WEEK}
* @param value
* the value of the {@code Calendar field},
* such as {@link Calendar#MONDAY}
* @param style
* the string representation style: one of {@link
* Calendar#SHORT_FORMAT} ({@link Calendar#SHORT SHORT}),
* {@link Calendar#SHORT_STANDALONE}, {@link
* Calendar#LONG_FORMAT} ({@link Calendar#LONG LONG}),
* {@link Calendar#LONG_STANDALONE},
* {@link Calendar#NARROW_FORMAT},
* or {@link Calendar#NARROW_STANDALONE}
* @param locale
* the desired locale
* @return the string representation of the {@code field value}, or {@code
* null} if the string representation is not applicable or
* the given calendar type is unknown
* @throws IllegalArgumentException
* if {@code field} or {@code style} is invalid
* @throws NullPointerException if {@code locale} is {@code null}
* @see TimeZoneNameProvider
* @see java.util.Calendar#get(int)
* @see java.util.Calendar#getDisplayName(int, int, Locale)
*/
public abstract String getDisplayName(String calendarType,
int field, int value,
int style, Locale locale);
/**
* Returns a {@code Map} containing all string representations (display
* names) of the {@code Calendar} {@code field} in the given {@code style}
* and {@code locale} and their corresponding field values.
*
* <p>{@code field} is a {@code Calendar} field index, such as {@link
* Calendar#MONTH}. The time zone fields, {@link Calendar#ZONE_OFFSET} and
* {@link Calendar#DST_OFFSET}, are <em>not</em> supported by this
* method. {@code null} must be returned if any time zone fields are specified.
*
* <p>{@code style} gives the style of the string representation. It must be
* one of {@link Calendar#ALL_STYLES}, {@link Calendar#SHORT_FORMAT} ({@link
* Calendar#SHORT SHORT}), {@link Calendar#SHORT_STANDALONE}, {@link
* Calendar#LONG_FORMAT} ({@link Calendar#LONG LONG}), {@link
* Calendar#LONG_STANDALONE}, {@link Calendar#NARROW_FORMAT}, or
* {@link Calendar#NARROW_STANDALONE}. Note that narrow names may
* not be unique due to use of single characters, such as "S" for Sunday
* and Saturday, and that no narrow names are included in that case.
*
* <p>For example, the following call will return a {@code Map} containing
* {@code "January"} to {@link Calendar#JANUARY}, {@code "Jan"} to {@link
* Calendar#JANUARY}, {@code "February"} to {@link Calendar#FEBRUARY},
* {@code "Feb"} to {@link Calendar#FEBRUARY}, and so on.
* <pre>
* getDisplayNames("gregory", Calendar.MONTH, Calendar.ALL_STYLES, Locale.ENGLISH);
* </pre>
*
* @param calendarType
* the calendar type. (Any calendar type given by {@code locale}
* is ignored.)
* @param field
* the calendar field for which the display names are returned
* @param style
* the style applied to the display names; one of
* {@link Calendar#ALL_STYLES}, {@link Calendar#SHORT_FORMAT}
* ({@link Calendar#SHORT SHORT}), {@link
* Calendar#SHORT_STANDALONE}, {@link Calendar#LONG_FORMAT}
* ({@link Calendar#LONG LONG}), {@link Calendar#LONG_STANDALONE},
* {@link Calendar#NARROW_FORMAT},
* or {@link Calendar#NARROW_STANDALONE}
* @param locale
* the desired locale
* @return a {@code Map} containing all display names of {@code field} in
* {@code style} and {@code locale} and their {@code field} values,
* or {@code null} if no display names are defined for {@code field}
* @throws NullPointerException
* if {@code locale} is {@code null}
* @see Calendar#getDisplayNames(int, int, Locale)
*/
public abstract Map<String, Integer> getDisplayNames(String calendarType,
int field, int style,
Locale locale);
}

122
src/java.base/share/classes/java/util/spi/CurrencyNameProvider.java Normal file
View file

@ -0,0 +1,122 @@
/*
* Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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 Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util.spi;
import java.util.Arrays;
import java.util.Currency;
import java.util.List;
import java.util.Locale;
import java.util.ResourceBundle.Control;
/**
* An abstract class for service providers that
* provide localized currency symbols and display names for the
* {@link java.util.Currency Currency} class.
* Note that currency symbols are considered names when determining
* behaviors described in the
* {@link java.util.spi.LocaleServiceProvider LocaleServiceProvider}
* specification.
*
* @since 1.6
*/
public abstract class CurrencyNameProvider extends LocaleServiceProvider {
/**
* Sole constructor. (For invocation by subclass constructors, typically
* implicit.)
*/
protected CurrencyNameProvider() {
}
/**
* Gets the symbol of the given currency code for the specified locale.
* For example, for "USD" (US Dollar), the symbol is "$" if the specified
* locale is the US, while for other locales it may be "US$". If no
* symbol can be determined, null should be returned.
*
* @param currencyCode the ISO 4217 currency code, which
* consists of three upper-case letters between 'A' (U+0041) and
* 'Z' (U+005A)
* @param locale the desired locale
* @return the symbol of the given currency code for the specified locale, or null if
* the symbol is not available for the locale
* @exception NullPointerException if <code>currencyCode</code> or
* <code>locale</code> is null
* @exception IllegalArgumentException if <code>currencyCode</code> is not in
* the form of three upper-case letters, or <code>locale</code> isn't
* one of the locales returned from
* {@link java.util.spi.LocaleServiceProvider#getAvailableLocales()
* getAvailableLocales()}.
* @see java.util.Currency#getSymbol(java.util.Locale)
*/
public abstract String getSymbol(String currencyCode, Locale locale);
/**
* Returns a name for the currency that is appropriate for display to the
* user. The default implementation returns null.
*
* @param currencyCode the ISO 4217 currency code, which
* consists of three upper-case letters between 'A' (U+0041) and
* 'Z' (U+005A)
* @param locale the desired locale
* @return the name for the currency that is appropriate for display to the
* user, or null if the name is not available for the locale
* @exception IllegalArgumentException if <code>currencyCode</code> is not in
* the form of three upper-case letters, or <code>locale</code> isn't
* one of the locales returned from
* {@link java.util.spi.LocaleServiceProvider#getAvailableLocales()
* getAvailableLocales()}.
* @exception NullPointerException if <code>currencyCode</code> or
* <code>locale</code> is <code>null</code>
* @since 1.7
*/
public String getDisplayName(String currencyCode, Locale locale) {
if (currencyCode == null || locale == null) {
throw new NullPointerException();
}
// Check whether the currencyCode is valid
char[] charray = currencyCode.toCharArray();
if (charray.length != 3) {
throw new IllegalArgumentException("The currencyCode is not in the form of three upper-case letters.");
}
for (char c : charray) {
if (c < 'A' || c > 'Z') {
throw new IllegalArgumentException("The currencyCode is not in the form of three upper-case letters.");
}
}
// Check whether the locale is valid
Control c = Control.getNoFallbackControl(Control.FORMAT_DEFAULT);
for (Locale l : getAvailableLocales()) {
if (c.getCandidateLocales("", l).contains(locale)) {
return null;
}
}
throw new IllegalArgumentException("The locale is not available");
}
}

144
src/java.base/share/classes/java/util/spi/LocaleNameProvider.java Normal file
View file

@ -0,0 +1,144 @@
/*
* Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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 Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util.spi;
import java.util.Locale;
/**
* An abstract class for service providers that
* provide localized names for the
* {@link java.util.Locale Locale} class.
*
* @since 1.6
*/
public abstract class LocaleNameProvider extends LocaleServiceProvider {
/**
* Sole constructor. (For invocation by subclass constructors, typically
* implicit.)
*/
protected LocaleNameProvider() {
}
/**
* Returns a localized name for the given <a href="http://www.rfc-editor.org/rfc/bcp/bcp47.txt">
* IETF BCP47</a> language code and the given locale that is appropriate for
* display to the user.
* For example, if <code>languageCode</code> is "fr" and <code>locale</code>
* is en_US, getDisplayLanguage() will return "French"; if <code>languageCode</code>
* is "en" and <code>locale</code> is fr_FR, getDisplayLanguage() will return "anglais".
* If the name returned cannot be localized according to <code>locale</code>,
* (say, the provider does not have a Japanese name for Croatian),
* this method returns null.
* @param languageCode the language code string in the form of two to eight
* lower-case letters between 'a' (U+0061) and 'z' (U+007A)
* @param locale the desired locale
* @return the name of the given language code for the specified locale, or null if it's not
* available.
* @exception NullPointerException if <code>languageCode</code> or <code>locale</code> is null
* @exception IllegalArgumentException if <code>languageCode</code> is not in the form of
* two or three lower-case letters, or <code>locale</code> isn't
* one of the locales returned from
* {@link java.util.spi.LocaleServiceProvider#getAvailableLocales()
* getAvailableLocales()}.
* @see java.util.Locale#getDisplayLanguage(java.util.Locale)
*/
public abstract String getDisplayLanguage(String languageCode, Locale locale);
/**
* Returns a localized name for the given <a href="http://www.rfc-editor.org/rfc/bcp/bcp47.txt">
* IETF BCP47</a> script code and the given locale that is appropriate for
* display to the user.
* For example, if <code>scriptCode</code> is "Latn" and <code>locale</code>
* is en_US, getDisplayScript() will return "Latin"; if <code>scriptCode</code>
* is "Cyrl" and <code>locale</code> is fr_FR, getDisplayScript() will return "cyrillique".
* If the name returned cannot be localized according to <code>locale</code>,
* (say, the provider does not have a Japanese name for Cyrillic),
* this method returns null. The default implementation returns null.
* @param scriptCode the four letter script code string in the form of title-case
* letters (the first letter is upper-case character between 'A' (U+0041) and
* 'Z' (U+005A) followed by three lower-case character between 'a' (U+0061)
* and 'z' (U+007A)).
* @param locale the desired locale
* @return the name of the given script code for the specified locale, or null if it's not
* available.
* @exception NullPointerException if <code>scriptCode</code> or <code>locale</code> is null
* @exception IllegalArgumentException if <code>scriptCode</code> is not in the form of
* four title case letters, or <code>locale</code> isn't
* one of the locales returned from
* {@link java.util.spi.LocaleServiceProvider#getAvailableLocales()
* getAvailableLocales()}.
* @see java.util.Locale#getDisplayScript(java.util.Locale)
* @since 1.7
*/
public String getDisplayScript(String scriptCode, Locale locale) {
return null;
}
/**
* Returns a localized name for the given <a href="http://www.rfc-editor.org/rfc/bcp/bcp47.txt">
* IETF BCP47</a> region code (either ISO 3166 country code or UN M.49 area
* codes) and the given locale that is appropriate for display to the user.
* For example, if <code>countryCode</code> is "FR" and <code>locale</code>
* is en_US, getDisplayCountry() will return "France"; if <code>countryCode</code>
* is "US" and <code>locale</code> is fr_FR, getDisplayCountry() will return "Etats-Unis".
* If the name returned cannot be localized according to <code>locale</code>,
* (say, the provider does not have a Japanese name for Croatia),
* this method returns null.
* @param countryCode the country(region) code string in the form of two
* upper-case letters between 'A' (U+0041) and 'Z' (U+005A) or the UN M.49 area code
* in the form of three digit letters between '0' (U+0030) and '9' (U+0039).
* @param locale the desired locale
* @return the name of the given country code for the specified locale, or null if it's not
* available.
* @exception NullPointerException if <code>countryCode</code> or <code>locale</code> is null
* @exception IllegalArgumentException if <code>countryCode</code> is not in the form of
* two upper-case letters or three digit letters, or <code>locale</code> isn't
* one of the locales returned from
* {@link java.util.spi.LocaleServiceProvider#getAvailableLocales()
* getAvailableLocales()}.
* @see java.util.Locale#getDisplayCountry(java.util.Locale)
*/
public abstract String getDisplayCountry(String countryCode, Locale locale);
/**
* Returns a localized name for the given variant code and the given locale that
* is appropriate for display to the user.
* If the name returned cannot be localized according to <code>locale</code>,
* this method returns null.
* @param variant the variant string
* @param locale the desired locale
* @return the name of the given variant string for the specified locale, or null if it's not
* available.
* @exception NullPointerException if <code>variant</code> or <code>locale</code> is null
* @exception IllegalArgumentException if <code>locale</code> isn't
* one of the locales returned from
* {@link java.util.spi.LocaleServiceProvider#getAvailableLocales()
* getAvailableLocales()}.
* @see java.util.Locale#getDisplayVariant(java.util.Locale)
*/
public abstract String getDisplayVariant(String variant, Locale locale);
}

224
src/java.base/share/classes/java/util/spi/LocaleServiceProvider.java Normal file
View file

@ -0,0 +1,224 @@
/*
* Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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 Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util.spi;
import java.util.Locale;
/**
* <p>
* This is the super class of all the locale sensitive service provider
* interfaces (SPIs).
* <p>
* Locale sensitive service provider interfaces are interfaces that
* correspond to locale sensitive classes in the <code>java.text</code>
* and <code>java.util</code> packages. The interfaces enable the
* construction of locale sensitive objects and the retrieval of
* localized names for these packages. Locale sensitive factory methods
* and methods for name retrieval in the <code>java.text</code> and
* <code>java.util</code> packages use implementations of the provider
* interfaces to offer support for locales beyond the set of locales
* supported by the Java runtime environment itself.
*
* <h3>Packaging of Locale Sensitive Service Provider Implementations</h3>
* Implementations of these locale sensitive services can be made available
* by adding them to the application's class path. A provider identifies itself with a
* provider-configuration file in the resource directory META-INF/services,
* using the fully qualified provider interface class name as the file name.
* The file should contain a list of fully-qualified concrete provider class names,
* one per line. A line is terminated by any one of a line feed ('\n'), a carriage
* return ('\r'), or a carriage return followed immediately by a line feed. Space
* and tab characters surrounding each name, as well as blank lines, are ignored.
* The comment character is '#' ('\u0023'); on each line all characters following
* the first comment character are ignored. The file must be encoded in UTF-8.
* <p>
* If a particular concrete provider class is named in more than one configuration
* file, or is named in the same configuration file more than once, then the
* duplicates will be ignored. The configuration file naming a particular provider
* need not be in the same jar file or other distribution unit as the provider itself.
* The provider must be accessible from the same class loader that was initially
* queried to locate the configuration file; this is not necessarily the class loader
* that loaded the file.
* <p>
* For example, an implementation of the
* {@link java.text.spi.DateFormatProvider DateFormatProvider} class should
* take the form of a jar file which contains the file:
* <pre>
* META-INF/services/java.text.spi.DateFormatProvider
* </pre>
* And the file <code>java.text.spi.DateFormatProvider</code> should have
* a line such as:
* <pre>
* <code>com.foo.DateFormatProviderImpl</code>
* </pre>
* which is the fully qualified class name of the class implementing
* <code>DateFormatProvider</code>.
* <h4>Invocation of Locale Sensitive Services</h4>
* <p>
* Locale sensitive factory methods and methods for name retrieval in the
* <code>java.text</code> and <code>java.util</code> packages invoke
* service provider methods when needed to support the requested locale.
* The methods first check whether the Java runtime environment itself
* supports the requested locale, and use its support if available.
* Otherwise, they call the {@link #isSupportedLocale(Locale) isSupportedLocale}
* methods of installed providers for the appropriate interface to find one that
* supports the requested locale. If such a provider is found, its other
* methods are called to obtain the requested object or name. When checking
* whether a locale is supported, the <a href="../Locale.html#def_extensions">
* locale's extensions</a> are ignored by default. (If locale's extensions should
* also be checked, the {@code isSupportedLocale} method must be overridden.)
* If neither the Java runtime environment itself nor an installed provider
* supports the requested locale, the methods go through a list of candidate
* locales and repeat the availability check for each until a match is found.
* The algorithm used for creating a list of candidate locales is same as
* the one used by <code>ResourceBundle</code> by default (see
* {@link java.util.ResourceBundle.Control#getCandidateLocales getCandidateLocales}
* for the details). Even if a locale is resolved from the candidate list,
* methods that return requested objects or names are invoked with the original
* requested locale including {@code Locale} extensions. The Java runtime
* environment must support the root locale for all locale sensitive services in
* order to guarantee that this process terminates.
* <p>
* Providers of names (but not providers of other objects) are allowed to
* return null for some name requests even for locales that they claim to
* support by including them in their return value for
* <code>getAvailableLocales</code>. Similarly, the Java runtime
* environment itself may not have all names for all locales that it
* supports. This is because the sets of objects for which names are
* requested can be large and vary over time, so that it's not always
* feasible to cover them completely. If the Java runtime environment or a
* provider returns null instead of a name, the lookup will proceed as
* described above as if the locale was not supported.
* <p>
* The search order of locale sensitive services can
* be configured by using the "java.locale.providers" system property.
* This system property declares the user's preferred order for looking up
* the locale sensitive services separated by a comma. It is only read at
* the Java runtime startup, so the later call to System.setProperty() won't
* affect the order.
* <p>
* Java Runtime Environment provides the following four locale providers:
* <ul>
* <li> "CLDR": A provider based on Unicode Consortium's
* <a href="http://cldr.unicode.org/">CLDR Project</a>.
* <li> "COMPAT": represents the locale sensitive services that is compatible
* with the prior JDK releases up to JDK8 (same as JDK8's "JRE").
* <li> "SPI": represents the locale sensitive services implementing the subclasses of
* this {@code LocaleServiceProvider} class.
* <li> "HOST": A provider that reflects the user's custom settings in the
* underlying operating system. This provider may not be available, depending
* on the Java Runtime Environment implementation.
* <li> "JRE": represents a synonym to "COMPAT". This name
* is deprecated and will be removed in the future release of JDK.
* </ul>
* <p>
* For example, if the following is specified in the property:
* <pre>
* java.locale.providers=SPI,CLDR,COMPAT
* </pre>
* the locale sensitive services in the SPI providers are looked up first. If the
* desired locale sensitive service is not available, then the runtime looks for CLDR,
* COMPAT in that order.
* <p>
* The default order for looking up the preferred locale providers is "CLDR,COMPAT",
* so specifying "CLDR,COMPAT" is identical to the default behavior. Applications which
* require implementations of the locale sensitive services must explicitly specify
* "SPI" in order for the Java runtime to load them from the classpath.
*
* @since 1.6
*/
public abstract class LocaleServiceProvider {
private static Void checkPermission() {
SecurityManager sm = System.getSecurityManager();
if (sm != null) {
sm.checkPermission(new RuntimePermission("localeServiceProvider"));
}
return null;
}
private LocaleServiceProvider(Void ignore) { }
/**
* Initializes a new locale service provider.
*
* @throws SecurityException
* If a security manager has been installed and it denies
* {@link RuntimePermission RuntimePermission("localeServiceProvider")}
*/
protected LocaleServiceProvider() {
this(checkPermission());
}
/**
* Returns an array of all locales for which this locale service provider
* can provide localized objects or names. This information is used to
* compose {@code getAvailableLocales()} values of the locale-dependent
* services, such as {@code DateFormat.getAvailableLocales()}.
*
* <p>The array returned by this method should not include two or more
* {@code Locale} objects only differing in their extensions.
*
* @return An array of all locales for which this locale service provider
* can provide localized objects or names.
*/
public abstract Locale[] getAvailableLocales();
/**
* Returns {@code true} if the given {@code locale} is supported by
* this locale service provider. The given {@code locale} may contain
* <a href="../Locale.html#def_extensions">extensions</a> that should be
* taken into account for the support determination.
*
* <p>The default implementation returns {@code true} if the given {@code locale}
* is equal to any of the available {@code Locale}s returned by
* {@link #getAvailableLocales()} with ignoring any extensions in both the
* given {@code locale} and the available locales. Concrete locale service
* provider implementations should override this method if those
* implementations are {@code Locale} extensions-aware. For example,
* {@code DecimalFormatSymbolsProvider} implementations will need to check
* extensions in the given {@code locale} to see if any numbering system is
* specified and can be supported. However, {@code CollatorProvider}
* implementations may not be affected by any particular numbering systems,
* and in that case, extensions for numbering systems should be ignored.
*
* @param locale a {@code Locale} to be tested
* @return {@code true} if the given {@code locale} is supported by this
* provider; {@code false} otherwise.
* @throws NullPointerException
* if the given {@code locale} is {@code null}
* @see Locale#hasExtensions()
* @see Locale#stripExtensions()
* @since 1.8
*/
public boolean isSupportedLocale(Locale locale) {
locale = locale.stripExtensions(); // throws NPE if locale == null
for (Locale available : getAvailableLocales()) {
if (locale.equals(available.stripExtensions())) {
return true;
}
}
return false;
}
}

67
src/java.base/share/classes/java/util/spi/ResourceBundleControlProvider.java Normal file
View file

@ -0,0 +1,67 @@
/*
* Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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 Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util.spi;
import java.util.ResourceBundle;
/**
* An interface for service providers that provide implementations of {@link
* java.util.ResourceBundle.Control}. The <a
* href="../ResourceBundle.html#default_behavior">default resource bundle loading
* behavior</a> of the {@code ResourceBundle.getBundle} factory methods that take
* no {@link java.util.ResourceBundle.Control} instance can be modified with {@code
* ResourceBundleControlProvider} implementations.
*
* <p>Provider implementations are loaded from the application's class path
* using {@link java.util.ServiceLoader} at the first invocation of the
* {@code ResourceBundle.getBundle} factory method that takes no
* {@link java.util.ResourceBundle.Control} instance.
*
* <p>All {@code ResourceBundleControlProvider}s are ignored in named modules.
*
* @author Masayoshi Okutsu
* @since 1.8
* @revised 9
* @spec JPMS
* @see ResourceBundle#getBundle(String, java.util.Locale, ClassLoader, ResourceBundle.Control)
* ResourceBundle.getBundle
* @see java.util.ServiceLoader#load(Class)
*/
public interface ResourceBundleControlProvider {
/**
* Returns a {@code ResourceBundle.Control} instance that is used
* to handle resource bundle loading for the given {@code
* baseName}. This method must return {@code null} if the given
* {@code baseName} isn't handled by this provider.
*
* @param baseName the base name of the resource bundle
* @return a {@code ResourceBundle.Control} instance,
* or {@code null} if the given {@code baseName} is not
* applicable to this provider.
* @throws NullPointerException if {@code baseName} is {@code null}
*/
public ResourceBundle.Control getControl(String baseName);
}

78
src/java.base/share/classes/java/util/spi/ResourceBundleProvider.java Normal file
View file

@ -0,0 +1,78 @@
/*
* Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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 Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util.spi;
import java.util.Locale;
import java.util.ResourceBundle;
/**
* {@code ResourceBundleProvider} is a provider interface that is used for
* loading resource bundles for named modules. Implementation classes of
* this interface are loaded with {@link java.util.ServiceLoader ServiceLoader}
* during a call to the
* {@link ResourceBundle#getBundle(String, Locale, ClassLoader)
* ResourceBundle.getBundle} method. The provider service type is determined by
* {@code <package name> + ".spi." + <simple name> + "Provider"}.
*
* <p>
* For example, if the base name is "com.example.app.MyResources",
* {@code com.example.app.spi.MyResourcesProvider} will be the provider service type:
* <pre>{@code
* public interface MyResourcesProvider extends ResourceBundleProvider {
* }
* }</pre>
*
* <p>
* This providers's {@link #getBundle(String, Locale) getBundle} method is called
* through the resource bundle loading process instead of {@link
* java.util.ResourceBundle.Control#newBundle(String, Locale, String, ClassLoader, boolean)
* ResourceBundle.Control.newBundle()}. Refer to {@link ResourceBundle} for
* details.
*
* @see <a href="../ResourceBundle.html#bundleprovider">
* Resource Bundles in Named Modules</a>
* @see <a href="../ResourceBundle.html#RBP_support">
* ResourceBundleProvider Service Providers</a>
* @since 9
* @spec JPMS
*/
public interface ResourceBundleProvider {
/**
* Returns a {@code ResourceBundle} for the given bundle name and locale.
* This method returns {@code null} if there is no {@code ResourceBundle}
* found for the given parameters.
*
*
* @param baseName
* the base bundle name of the resource bundle, a fully
* qualified class name
* @param locale
* the locale for which the resource bundle should be loaded
* @return the ResourceBundle created for the given parameters, or null if no
* {@code ResourceBundle} for the given parameters is found
*/
public ResourceBundle getBundle(String baseName, Locale locale);
}

110
src/java.base/share/classes/java/util/spi/TimeZoneNameProvider.java Normal file
View file

@ -0,0 +1,110 @@
/*
* Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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 Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util.spi;
import java.util.Locale;
/**
* An abstract class for service providers that
* provide localized time zone names for the
* {@link java.util.TimeZone TimeZone} class.
* The localized time zone names available from the implementations of
* this class are also the source for the
* {@link java.text.DateFormatSymbols#getZoneStrings()
* DateFormatSymbols.getZoneStrings()} method.
*
* @since 1.6
*/
public abstract class TimeZoneNameProvider extends LocaleServiceProvider {
/**
* Sole constructor. (For invocation by subclass constructors, typically
* implicit.)
*/
protected TimeZoneNameProvider() {
}
/**
* Returns a name for the given time zone ID that's suitable for
* presentation to the user in the specified locale. The given time
* zone ID is "GMT" or one of the names defined using "Zone" entries
* in the "tz database", a public domain time zone database at
* <a href="ftp://elsie.nci.nih.gov/pub/">ftp://elsie.nci.nih.gov/pub/</a>.
* The data of this database is contained in a file whose name starts with
* "tzdata", and the specification of the data format is part of the zic.8
* man page, which is contained in a file whose name starts with "tzcode".
* <p>
* If <code>daylight</code> is true, the method should return a name
* appropriate for daylight saving time even if the specified time zone
* has not observed daylight saving time in the past.
*
* @param ID a time zone ID string
* @param daylight if true, return the daylight saving name.
* @param style either {@link java.util.TimeZone#LONG TimeZone.LONG} or
* {@link java.util.TimeZone#SHORT TimeZone.SHORT}
* @param locale the desired locale
* @return the human-readable name of the given time zone in the
* given locale, or null if it's not available.
* @exception IllegalArgumentException if <code>style</code> is invalid,
* or <code>locale</code> isn't one of the locales returned from
* {@link java.util.spi.LocaleServiceProvider#getAvailableLocales()
* getAvailableLocales()}.
* @exception NullPointerException if <code>ID</code> or <code>locale</code>
* is null
* @see java.util.TimeZone#getDisplayName(boolean, int, java.util.Locale)
*/
public abstract String getDisplayName(String ID, boolean daylight, int style, Locale locale);
/**
* Returns a generic name for the given time zone {@code ID} that's suitable
* for presentation to the user in the specified {@code locale}. Generic
* time zone names are neutral from standard time and daylight saving
* time. For example, "PT" is the short generic name of time zone ID {@code
* America/Los_Angeles}, while its short standard time and daylight saving
* time names are "PST" and "PDT", respectively. Refer to
* {@link #getDisplayName(String, boolean, int, Locale) getDisplayName}
* for valid time zone IDs.
*
* <p>The default implementation of this method returns {@code null}.
*
* @param ID a time zone ID string
* @param style either {@link java.util.TimeZone#LONG TimeZone.LONG} or
* {@link java.util.TimeZone#SHORT TimeZone.SHORT}
* @param locale the desired locale
* @return the human-readable generic name of the given time zone in the
* given locale, or {@code null} if it's not available.
* @exception IllegalArgumentException if <code>style</code> is invalid,
* or <code>locale</code> isn't one of the locales returned from
* {@link LocaleServiceProvider#getAvailableLocales()
* getAvailableLocales()}.
* @exception NullPointerException if <code>ID</code> or <code>locale</code>
* is {@code null}
* @since 1.8
*/
public String getGenericDisplayName(String ID, int style, Locale locale) {
return null;
}
}

169
src/java.base/share/classes/java/util/spi/ToolProvider.java Normal file
View file

@ -0,0 +1,169 @@
/*
* Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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 Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util.spi;
import java.io.PrintStream;
import java.io.PrintWriter;
import java.security.AccessController;
import java.security.PrivilegedAction;
import java.util.Objects;
import java.util.Optional;
import java.util.ServiceLoader;
import java.util.stream.StreamSupport;
/**
* An interface for command-line tools to provide a way to
* be invoked without necessarily starting a new VM.
*
* <p>Tool providers are normally located using the service-provider
* loading facility defined by {@link ServiceLoader}.
* Each provider must provide a name, and a method to run
* an instance of the corresponding tool. When a tool is run,
* it will be provided with an array of string arguments, and a
* pair of streams: one for normal (or expected) output and the other
* for reporting any errors that may occur.
* The interpretation of the string arguments will normally be defined by
* each individual tool provider, but will generally correspond to the
* arguments that could be provided to the tool when invoking the tool
* from the command line.
*
* @since 9
*/
public interface ToolProvider {
/**
* Returns the name of this tool provider.
*
* @apiNote It is recommended that the name be the same as would be
* used on the command line: for example, "javac", "jar", "jlink".
*
* @return the name of this tool provider
*/
String name();
/**
* Runs an instance of the tool, returning zero for a successful run.
* Any non-zero return value indicates a tool-specific error during the
* execution.
*
* Two streams should be provided, for "expected" output, and for any
* error messages. If it is not necessary to distinguish the output,
* the same stream may be used for both.
*
* @apiNote The interpretation of the arguments will be specific to
* each tool.
*
* @param out a stream to which "expected" output should be written
*
* @param err a stream to which any error messages should be written
*
* @param args the command-line arguments for the tool
*
* @return the result of executing the tool.
* A return value of 0 means the tool did not encounter any errors;
* any other value indicates that at least one error occurred
* during execution.
*
* @throws NullPointerException if any of the arguments are {@code null},
* or if there are any {@code null} values in the {@code args}
* array
*/
int run(PrintWriter out, PrintWriter err, String... args);
/**
* Runs an instance of the tool, returning zero for a successful run.
* Any non-zero return value indicates a tool-specific error during the
* execution.
*
* Two streams should be provided, for "expected" output, and for any
* error messages. If it is not necessary to distinguish the output,
* the same stream may be used for both.
*
* @apiNote The interpretation of the arguments will be specific to
* each tool.
*
* @implNote This implementation wraps the {@code out} and {@code err}
* streams within {@link PrintWriter}s, and then calls
* {@link #run(PrintWriter, PrintWriter, String[])}.
*
* @param out a stream to which "expected" output should be written
*
* @param err a stream to which any error messages should be written
*
* @param args the command-line arguments for the tool
*
* @return the result of executing the tool.
* A return value of 0 means the tool did not encounter any errors;
* any other value indicates that at least one error occurred
* during execution.
*
* @throws NullPointerException if any of the arguments are {@code null},
* or if there are any {@code null} values in the {@code args}
* array
*/
default int run(PrintStream out, PrintStream err, String... args) {
Objects.requireNonNull(out);
Objects.requireNonNull(err);
for (String arg : args) {
Objects.requireNonNull(args);
}
PrintWriter outWriter = new PrintWriter(out);
PrintWriter errWriter = new PrintWriter(err);
try {
try {
return run(outWriter, errWriter, args);
} finally {
outWriter.flush();
}
} finally {
errWriter.flush();
}
}
/**
* Returns the first instance of a {@code ToolProvider} with the given name,
* as loaded by {@link ServiceLoader} using the system class loader.
*
* @param name the name of the desired tool provider
*
* @return an {@code Optional<ToolProvider>} of the first instance found
*
* @throws NullPointerException if {@code name} is {@code null}
*/
static Optional<ToolProvider> findFirst(String name) {
Objects.requireNonNull(name);
ClassLoader systemClassLoader = ClassLoader.getSystemClassLoader();
return AccessController.doPrivileged(
(PrivilegedAction<Optional<ToolProvider>>) () -> {
ServiceLoader<ToolProvider> sl =
ServiceLoader.load(ToolProvider.class, systemClassLoader);
return StreamSupport.stream(sl.spliterator(), false)
.filter(p -> p.name().equals(name))
.findFirst();
});
}
}

31
src/java.base/share/classes/java/util/spi/package-info.java Normal file
View file

@ -0,0 +1,31 @@
/*
* Copyright (c) 2005, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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 Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
* Service provider classes for the classes in the java.util package.
*
* @since 1.6
*/
package java.util.spi;