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

Merge

Browse source
This commit is contained in:
Lana Steuck 2018-01-04 04:22:28 +00:00
commit c8c8cd7238
121 changed files with 2574 additions and 913 deletions
Download patch file Download diff file Expand all files Collapse all files

1
src/java.base/share/classes/java/util/Arrays.java
View file

@ -26,6 +26,7 @@
package java.util;
import jdk.internal.HotSpotIntrinsicCandidate;
import jdk.internal.util.ArraysSupport;
import java.lang.reflect.Array;
import java.util.concurrent.ForkJoinPool;

545
src/java.base/share/classes/java/util/ArraysSupport.java
View file

@ -1,545 +0,0 @@
/*
* Copyright (c) 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;
import jdk.internal.HotSpotIntrinsicCandidate;
import jdk.internal.misc.Unsafe;
/**
* Utility methods to find a mismatch between two primitive arrays.
*
* <p>Array equality and lexicographical comparison can be built on top of
* array mismatch functionality.
*
* <p>The mismatch method implementation, {@link #vectorizedMismatch}, leverages
* vector-based techniques to access and compare the contents of two arrays.
* The Java implementation uses {@code Unsafe.getLongUnaligned} to access the
* content of an array, thus access is supported on platforms that do not
* support unaligned access. For a byte[] array, 8 bytes (64 bits) can be
* accessed and compared as a unit rather than individually, which increases
* the performance when the method is compiled by the HotSpot VM. On supported
* platforms the mismatch implementation is intrinsified to leverage SIMD
* instructions. So for a byte[] array, 16 bytes (128 bits), 32 bytes
* (256 bits), and perhaps in the future even 64 bytes (512 bits), platform
* permitting, can be accessed and compared as a unit, which further increases
* the performance over the Java implementation.
*
* <p>None of the mismatch methods perform array bounds checks. It is the
* responsibility of the caller (direct or otherwise) to perform such checks
* before calling this method.
*/
class ArraysSupport {
static final Unsafe U = Unsafe.getUnsafe();
private static final boolean BIG_ENDIAN = U.isBigEndian();
private static final int LOG2_ARRAY_BOOLEAN_INDEX_SCALE = exactLog2(Unsafe.ARRAY_BOOLEAN_INDEX_SCALE);
private static final int LOG2_ARRAY_BYTE_INDEX_SCALE = exactLog2(Unsafe.ARRAY_BYTE_INDEX_SCALE);
private static final int LOG2_ARRAY_CHAR_INDEX_SCALE = exactLog2(Unsafe.ARRAY_CHAR_INDEX_SCALE);
private static final int LOG2_ARRAY_SHORT_INDEX_SCALE = exactLog2(Unsafe.ARRAY_SHORT_INDEX_SCALE);
private static final int LOG2_ARRAY_INT_INDEX_SCALE = exactLog2(Unsafe.ARRAY_INT_INDEX_SCALE);
private static final int LOG2_ARRAY_LONG_INDEX_SCALE = exactLog2(Unsafe.ARRAY_LONG_INDEX_SCALE);
private static final int LOG2_ARRAY_FLOAT_INDEX_SCALE = exactLog2(Unsafe.ARRAY_FLOAT_INDEX_SCALE);
private static final int LOG2_ARRAY_DOUBLE_INDEX_SCALE = exactLog2(Unsafe.ARRAY_DOUBLE_INDEX_SCALE);
private static final int LOG2_BYTE_BIT_SIZE = exactLog2(Byte.SIZE);
private static int exactLog2(int scale) {
if ((scale & (scale - 1)) != 0)
throw new Error("data type scale not a power of two");
return Integer.numberOfTrailingZeros(scale);
}
private ArraysSupport() {}
/**
* Find the relative index of the first mismatching pair of elements in two
* primitive arrays of the same component type. Pairs of elements will be
* tested in order relative to given offsets into both arrays.
*
* <p>This method does not perform type checks or bounds checks. It is the
* responsibility of the caller to perform such checks before calling this
* method.
*
* <p>The given offsets, in bytes, need not be aligned according to the
* given log<sub>2</sub> size the array elements. More specifically, an
* offset modulus the size need not be zero.
*
* @param a the first array to be tested for mismatch, or {@code null} for
* direct memory access
* @param aOffset the relative offset, in bytes, from the base address of
* the first array to test from, otherwise if the first array is
* {@code null}, an absolute address pointing to the first element to test.
* @param b the second array to be tested for mismatch, or {@code null} for
* direct memory access
* @param bOffset the relative offset, in bytes, from the base address of
* the second array to test from, otherwise if the second array is
* {@code null}, an absolute address pointing to the first element to test.
* @param length the number of array elements to test
* @param log2ArrayIndexScale log<sub>2</sub> of the array index scale, that
* corresponds to the size, in bytes, of an array element.
* @return if a mismatch is found a relative index, between 0 (inclusive)
* and {@code length} (exclusive), of the first mismatching pair of elements
* in the two arrays. Otherwise, if a mismatch is not found the bitwise
* compliment of the number of remaining pairs of elements to be checked in
* the tail of the two arrays.
*/
@HotSpotIntrinsicCandidate
static int vectorizedMismatch(Object a, long aOffset,
Object b, long bOffset,
int length,
int log2ArrayIndexScale) {
// assert a.getClass().isArray();
// assert b.getClass().isArray();
// assert 0 <= length <= sizeOf(a)
// assert 0 <= length <= sizeOf(b)
// assert 0 <= log2ArrayIndexScale <= 3
int log2ValuesPerWidth = LOG2_ARRAY_LONG_INDEX_SCALE - log2ArrayIndexScale;
int wi = 0;
for (; wi < length >> log2ValuesPerWidth; wi++) {
long bi = ((long) wi) << LOG2_ARRAY_LONG_INDEX_SCALE;
long av = U.getLongUnaligned(a, aOffset + bi);
long bv = U.getLongUnaligned(b, bOffset + bi);
if (av != bv) {
long x = av ^ bv;
int o = BIG_ENDIAN
? Long.numberOfLeadingZeros(x) >> (LOG2_BYTE_BIT_SIZE + log2ArrayIndexScale)
: Long.numberOfTrailingZeros(x) >> (LOG2_BYTE_BIT_SIZE + log2ArrayIndexScale);
return (wi << log2ValuesPerWidth) + o;
}
}
// Calculate the tail of remaining elements to check
int tail = length - (wi << log2ValuesPerWidth);
if (log2ArrayIndexScale < LOG2_ARRAY_INT_INDEX_SCALE) {
int wordTail = 1 << (LOG2_ARRAY_INT_INDEX_SCALE - log2ArrayIndexScale);
// Handle 4 bytes or 2 chars in the tail using int width
if (tail >= wordTail) {
long bi = ((long) wi) << LOG2_ARRAY_LONG_INDEX_SCALE;
int av = U.getIntUnaligned(a, aOffset + bi);
int bv = U.getIntUnaligned(b, bOffset + bi);
if (av != bv) {
int x = av ^ bv;
int o = BIG_ENDIAN
? Integer.numberOfLeadingZeros(x) >> (LOG2_BYTE_BIT_SIZE + log2ArrayIndexScale)
: Integer.numberOfTrailingZeros(x) >> (LOG2_BYTE_BIT_SIZE + log2ArrayIndexScale);
return (wi << log2ValuesPerWidth) + o;
}
tail -= wordTail;
}
return ~tail;
}
else {
return ~tail;
}
}
// Booleans
// Each boolean element takes up one byte
static int mismatch(boolean[] a,
boolean[] b,
int length) {
int i = 0;
if (length > 7) {
i = vectorizedMismatch(
a, Unsafe.ARRAY_BOOLEAN_BASE_OFFSET,
b, Unsafe.ARRAY_BOOLEAN_BASE_OFFSET,
length, LOG2_ARRAY_BOOLEAN_INDEX_SCALE);
if (i >= 0)
return i;
i = length - ~i;
}
for (; i < length; i++) {
if (a[i] != b[i])
return i;
}
return -1;
}
static int mismatch(boolean[] a, int aFromIndex,
boolean[] b, int bFromIndex,
int length) {
int i = 0;
if (length > 7) {
int aOffset = Unsafe.ARRAY_BOOLEAN_BASE_OFFSET + aFromIndex;
int bOffset = Unsafe.ARRAY_BOOLEAN_BASE_OFFSET + bFromIndex;
i = vectorizedMismatch(
a, aOffset,
b, bOffset,
length, LOG2_ARRAY_BOOLEAN_INDEX_SCALE);
if (i >= 0)
return i;
i = length - ~i;
}
for (; i < length; i++) {
if (a[aFromIndex + i] != b[bFromIndex + i])
return i;
}
return -1;
}
// Bytes
/**
* Find the index of a mismatch between two arrays.
*
* <p>This method does not perform bounds checks. It is the responsibility
* of the caller to perform such bounds checks before calling this method.
*
* @param a the first array to be tested for a mismatch
* @param b the second array to be tested for a mismatch
* @param length the number of bytes from each array to check
* @return the index of a mismatch between the two arrays, otherwise -1 if
* no mismatch. The index will be within the range of (inclusive) 0 to
* (exclusive) the smaller of the two array lengths.
*/
static int mismatch(byte[] a,
byte[] b,
int length) {
// ISSUE: defer to index receiving methods if performance is good
// assert length <= a.length
// assert length <= b.length
int i = 0;
if (length > 7) {
i = vectorizedMismatch(
a, Unsafe.ARRAY_BYTE_BASE_OFFSET,
b, Unsafe.ARRAY_BYTE_BASE_OFFSET,
length, LOG2_ARRAY_BYTE_INDEX_SCALE);
if (i >= 0)
return i;
// Align to tail
i = length - ~i;
// assert i >= 0 && i <= 7;
}
// Tail < 8 bytes
for (; i < length; i++) {
if (a[i] != b[i])
return i;
}
return -1;
}
/**
* Find the relative index of a mismatch between two arrays starting from
* given indexes.
*
* <p>This method does not perform bounds checks. It is the responsibility
* of the caller to perform such bounds checks before calling this method.
*
* @param a the first array to be tested for a mismatch
* @param aFromIndex the index of the first element (inclusive) in the first
* array to be compared
* @param b the second array to be tested for a mismatch
* @param bFromIndex the index of the first element (inclusive) in the
* second array to be compared
* @param length the number of bytes from each array to check
* @return the relative index of a mismatch between the two arrays,
* otherwise -1 if no mismatch. The index will be within the range of
* (inclusive) 0 to (exclusive) the smaller of the two array bounds.
*/
static int mismatch(byte[] a, int aFromIndex,
byte[] b, int bFromIndex,
int length) {
// assert 0 <= aFromIndex < a.length
// assert 0 <= aFromIndex + length <= a.length
// assert 0 <= bFromIndex < b.length
// assert 0 <= bFromIndex + length <= b.length
// assert length >= 0
int i = 0;
if (length > 7) {
int aOffset = Unsafe.ARRAY_BYTE_BASE_OFFSET + aFromIndex;
int bOffset = Unsafe.ARRAY_BYTE_BASE_OFFSET + bFromIndex;
i = vectorizedMismatch(
a, aOffset,
b, bOffset,
length, LOG2_ARRAY_BYTE_INDEX_SCALE);
if (i >= 0)
return i;
i = length - ~i;
}
for (; i < length; i++) {
if (a[aFromIndex + i] != b[bFromIndex + i])
return i;
}
return -1;
}
// Chars
static int mismatch(char[] a,
char[] b,
int length) {
int i = 0;
if (length > 3) {
i = vectorizedMismatch(
a, Unsafe.ARRAY_CHAR_BASE_OFFSET,
b, Unsafe.ARRAY_CHAR_BASE_OFFSET,
length, LOG2_ARRAY_CHAR_INDEX_SCALE);
if (i >= 0)
return i;
i = length - ~i;
}
for (; i < length; i++) {
if (a[i] != b[i])
return i;
}
return -1;
}
static int mismatch(char[] a, int aFromIndex,
char[] b, int bFromIndex,
int length) {
int i = 0;
if (length > 3) {
int aOffset = Unsafe.ARRAY_CHAR_BASE_OFFSET + (aFromIndex << LOG2_ARRAY_CHAR_INDEX_SCALE);
int bOffset = Unsafe.ARRAY_CHAR_BASE_OFFSET + (bFromIndex << LOG2_ARRAY_CHAR_INDEX_SCALE);
i = vectorizedMismatch(
a, aOffset,
b, bOffset,
length, LOG2_ARRAY_CHAR_INDEX_SCALE);
if (i >= 0)
return i;
i = length - ~i;
}
for (; i < length; i++) {
if (a[aFromIndex + i] != b[bFromIndex + i])
return i;
}
return -1;
}
// Shorts
static int mismatch(short[] a,
short[] b,
int length) {
int i = 0;
if (length > 3) {
i = vectorizedMismatch(
a, Unsafe.ARRAY_SHORT_BASE_OFFSET,
b, Unsafe.ARRAY_SHORT_BASE_OFFSET,
length, LOG2_ARRAY_SHORT_INDEX_SCALE);
if (i >= 0)
return i;
i = length - ~i;
}
for (; i < length; i++) {
if (a[i] != b[i])
return i;
}
return -1;
}
static int mismatch(short[] a, int aFromIndex,
short[] b, int bFromIndex,
int length) {
int i = 0;
if (length > 3) {
int aOffset = Unsafe.ARRAY_SHORT_BASE_OFFSET + (aFromIndex << LOG2_ARRAY_SHORT_INDEX_SCALE);
int bOffset = Unsafe.ARRAY_SHORT_BASE_OFFSET + (bFromIndex << LOG2_ARRAY_SHORT_INDEX_SCALE);
i = vectorizedMismatch(
a, aOffset,
b, bOffset,
length, LOG2_ARRAY_SHORT_INDEX_SCALE);
if (i >= 0)
return i;
i = length - ~i;
}
for (; i < length; i++) {
if (a[aFromIndex + i] != b[bFromIndex + i])
return i;
}
return -1;
}
// Ints
static int mismatch(int[] a,
int[] b,
int length) {
int i = 0;
if (length > 1) {
i = vectorizedMismatch(
a, Unsafe.ARRAY_INT_BASE_OFFSET,
b, Unsafe.ARRAY_INT_BASE_OFFSET,
length, LOG2_ARRAY_INT_INDEX_SCALE);
if (i >= 0)
return i;
i = length - ~i;
}
for (; i < length; i++) {
if (a[i] != b[i])
return i;
}
return -1;
}
static int mismatch(int[] a, int aFromIndex,
int[] b, int bFromIndex,
int length) {
int i = 0;
if (length > 1) {
int aOffset = Unsafe.ARRAY_INT_BASE_OFFSET + (aFromIndex << LOG2_ARRAY_INT_INDEX_SCALE);
int bOffset = Unsafe.ARRAY_INT_BASE_OFFSET + (bFromIndex << LOG2_ARRAY_INT_INDEX_SCALE);
i = vectorizedMismatch(
a, aOffset,
b, bOffset,
length, LOG2_ARRAY_INT_INDEX_SCALE);
if (i >= 0)
return i;
i = length - ~i;
}
for (; i < length; i++) {
if (a[aFromIndex + i] != b[bFromIndex + i])
return i;
}
return -1;
}
// Floats
static int mismatch(float[] a,
float[] b,
int length) {
return mismatch(a, 0, b, 0, length);
}
static int mismatch(float[] a, int aFromIndex,
float[] b, int bFromIndex,
int length) {
int i = 0;
if (length > 1) {
int aOffset = Unsafe.ARRAY_FLOAT_BASE_OFFSET + (aFromIndex << LOG2_ARRAY_FLOAT_INDEX_SCALE);
int bOffset = Unsafe.ARRAY_FLOAT_BASE_OFFSET + (bFromIndex << LOG2_ARRAY_FLOAT_INDEX_SCALE);
i = vectorizedMismatch(
a, aOffset,
b, bOffset,
length, LOG2_ARRAY_FLOAT_INDEX_SCALE);
// Mismatched
if (i >= 0) {
// Check if mismatch is not associated with two NaN values
if (!Float.isNaN(a[aFromIndex + i]) || !Float.isNaN(b[bFromIndex + i]))
return i;
// Mismatch on two different NaN values that are normalized to match
// Fall back to slow mechanism
// ISSUE: Consider looping over vectorizedMismatch adjusting ranges
// However, requires that returned value be relative to input ranges
i++;
}
// Matched
else {
i = length - ~i;
}
}
for (; i < length; i++) {
if (Float.floatToIntBits(a[aFromIndex + i]) != Float.floatToIntBits(b[bFromIndex + i]))
return i;
}
return -1;
}
// 64 bit sizes
// Long
static int mismatch(long[] a,
long[] b,
int length) {
if (length == 0) {
return -1;
}
int i = vectorizedMismatch(
a, Unsafe.ARRAY_LONG_BASE_OFFSET,
b, Unsafe.ARRAY_LONG_BASE_OFFSET,
length, LOG2_ARRAY_LONG_INDEX_SCALE);
return i >= 0 ? i : -1;
}
static int mismatch(long[] a, int aFromIndex,
long[] b, int bFromIndex,
int length) {
if (length == 0) {
return -1;
}
int aOffset = Unsafe.ARRAY_LONG_BASE_OFFSET + (aFromIndex << LOG2_ARRAY_LONG_INDEX_SCALE);
int bOffset = Unsafe.ARRAY_LONG_BASE_OFFSET + (bFromIndex << LOG2_ARRAY_LONG_INDEX_SCALE);
int i = vectorizedMismatch(
a, aOffset,
b, bOffset,
length, LOG2_ARRAY_LONG_INDEX_SCALE);
return i >= 0 ? i : -1;
}
// Double
static int mismatch(double[] a,
double[] b,
int length) {
return mismatch(a, 0, b, 0, length);
}
static int mismatch(double[] a, int aFromIndex,
double[] b, int bFromIndex,
int length) {
if (length == 0) {
return -1;
}
int aOffset = Unsafe.ARRAY_DOUBLE_BASE_OFFSET + (aFromIndex << LOG2_ARRAY_DOUBLE_INDEX_SCALE);
int bOffset = Unsafe.ARRAY_DOUBLE_BASE_OFFSET + (bFromIndex << LOG2_ARRAY_DOUBLE_INDEX_SCALE);
int i = vectorizedMismatch(
a, aOffset,
b, bOffset,
length, LOG2_ARRAY_DOUBLE_INDEX_SCALE);
if (i >= 0) {
// Check if mismatch is not associated with two NaN values
if (!Double.isNaN(a[aFromIndex + i]) || !Double.isNaN(b[bFromIndex + i]))
return i;
// Mismatch on two different NaN values that are normalized to match
// Fall back to slow mechanism
// ISSUE: Consider looping over vectorizedMismatch adjusting ranges
// However, requires that returned value be relative to input ranges
i++;
for (; i < length; i++) {
if (Double.doubleToLongBits(a[aFromIndex + i]) != Double.doubleToLongBits(b[bFromIndex + i]))
return i;
}
}
return -1;
}
}

227
src/java.base/share/classes/java/util/ResourceBundle.java
View file

@ -204,58 +204,70 @@ import static sun.security.util.SecurityConstants.GET_CLASSLOADER_PERMISSION;
* known concrete subclasses {@code ListResourceBundle} and
* {@code PropertyResourceBundle} are thread-safe.
*
* <h3><a id="bundleprovider">Resource Bundles in Named Modules</a></h3>
* <h3><a id="resource-bundle-modules">Resource Bundles and Named Modules</a></h3>
*
* When resource bundles are deployed in named modules, the following
* module-specific requirements and restrictions are applied.
* Resource bundles can be deployed in modules in the following ways:
*
* <ul>
* <li>Code in a named module that calls {@link #getBundle(String, Locale)}
* will locate resource bundles in the caller's module (<em>caller module</em>).</li>
* <li>If resource bundles are deployed in named modules separate from
* the caller module, those resource bundles need to be loaded from service
* providers of {@link ResourceBundleProvider}. The caller module must declare
* "{@code uses}" and the service interface name is the concatenation of the
* package name of the base name, string "{@code .spi.}", the simple class
* name of the base name, and the string "{@code Provider}". The
* <em>bundle provider modules</em> containing resource bundles must
* declare "{@code provides}" with the service interface name and
* its implementation class name. For example, if the base name is
* "{@code com.example.app.MyResources}", the caller module must declare
* "{@code uses com.example.app.spi.MyResourcesProvider;}" and a module containing resource
* bundles must declare "{@code provides com.example.app.spi.MyResourcesProvider
* with com.example.app.internal.MyResourcesProviderImpl;}"
* where {@code com.example.app.internal.MyResourcesProviderImpl} is an
* implementation class of {@code com.example.app.spi.MyResourcesProvider}.</li>
* <li>If you want to use non-standard formats in named modules, such as XML,
* {@link ResourceBundleProvider} needs to be used.</li>
* <li>The {@code getBundle} method with a {@code ClassLoader} may not be able to
* find resource bundles using the given {@code ClassLoader} in named modules.
* The {@code getBundle} method with a {@code Module} can be used, instead.</li>
* <li>{@code ResourceBundle.Control} is <em>not</em> supported in named modules.
* If the {@code getBundle} method with a {@code ResourceBundle.Control} is called
* in a named module, the method will throw an {@code UnsupportedOperationException}.
* Any service providers of {@link ResourceBundleControlProvider} are ignored in
* named modules.
* </li>
* </ul>
* <h4>Resource bundles together with an application</h4>
*
* <h3><a id="RBP_support">ResourceBundleProvider Service Providers</a></h3>
* Resource bundles can be deployed together with an application in the same
* module. In that case, the resource bundles are loaded
* by code in the module by calling the {@link #getBundle(String)}
* or {@link #getBundle(String, Locale)} method.
*
* The {@code getBundle} factory methods load service providers of
* {@link ResourceBundleProvider}, if available, using {@link ServiceLoader}.
* The service type is designated by
* {@code <package name> + ".spi." + <simple name> + "Provider"}. For
* example, if the base name is "{@code com.example.app.MyResources}", the service
* type is {@code com.example.app.spi.MyResourcesProvider}.
* <p>
* In named modules, the loaded service providers for the given base name are
* used to load resource bundles. If no service provider is available, or if
* none of the service providers returns a resource bundle and the caller module
* doesn't have its own service provider, the {@code getBundle} factory method
* searches for resource bundles that are local in the caller module and that
* are visible to the class loader of the caller module. The resource bundle
* formats for local module searching are "java.class" and "java.properties".
* <h4><a id="service-providers">Resource bundles as service providers</a></h4>
*
* Resource bundles can be deployed in one or more <em>service provider modules</em>
* and they can be located using {@link ServiceLoader}.
* A {@linkplain ResourceBundleProvider service} interface or class must be
* defined. The caller module declares that it uses the service, the service
* provider modules declare that they provide implementations of the service.
* Refer to {@link ResourceBundleProvider} for developing resource bundle
* services and deploying resource bundle providers.
* The module obtaining the resource bundle can be a resource bundle
* provider itself; in which case this module only locates the resource bundle
* via service provider mechanism.
*
* <p>A {@linkplain ResourceBundleProvider resource bundle provider} can
* provide resource bundles in any format such XML which replaces the need
* of {@link Control ResourceBundle.Control}.
*
* <h4><a id="other-modules">Resource bundles in other modules and class path</a></h4>
*
* Resource bundles in a named module may be <em>encapsulated</em> so that
* it cannot be located by code in other modules. Resource bundles
* in unnamed modules and class path are open for any module to access.
* Resource bundle follows the resource encapsulation rules as specified
* in {@link Module#getResourceAsStream(String)}.
*
* <p>The {@code getBundle} factory methods with no {@code Control} parameter
* locate and load resource bundles from
* {@linkplain ResourceBundleProvider service providers}.
* It may continue the search as if calling {@link Module#getResourceAsStream(String)}
* to find the named resource from a given module and calling
* {@link ClassLoader#getResourceAsStream(String)}; refer to
* the specification of the {@code getBundle} method for details.
* Only non-encapsulated resource bundles of "{@code java.class}"
* or "{@code java.properties}" format are searched.
*
* <p>If the caller module is a
* <a href="{@docRoot}/java/util/spi/ResourceBundleProvider.html#obtain-resource-bundle">
* resource bundle provider</a>, it does not fall back to the
* class loader search.
*
* <h4>Resource bundles in automatic modules</h4>
*
* A common format of resource bundles is in {@linkplain PropertyResourceBundle
* .properties} file format. Typically {@code .properties} resource bundles
* are packaged in a JAR file. Resource bundle only JAR file can be readily
* deployed as an <a href="{@docRoot}/java/lang/module/ModuleFinder.html#automatic-modules">
* automatic module</a>. For example, if the JAR file contains the
* entry "{@code p/q/Foo_ja.properties}" and no {@code .class} entry,
* when resolved and defined as an automatic module, no package is derived
* for this module. This allows resource bundles in {@code .properties}
* format packaged in one or more JAR files that may contain entries
* in the same directory and can be resolved successfully as
* automatic modules.
*
* <h3>ResourceBundle.Control</h3>
*
@ -268,6 +280,14 @@ import static sun.security.util.SecurityConstants.GET_CLASSLOADER_PERMISSION;
* {@link #getBundle(String, Locale, ClassLoader, Control) getBundle}
* factory method for details.
*
* <p> {@link ResourceBundle.Control} is designed for an application deployed
* in an unnamed module, for example to support resource bundles in
* non-standard formats or package localized resources in a non-traditional
* convention. {@link ResourceBundleProvider} is the replacement for
* {@code ResourceBundle.Control} when migrating to modules.
* {@code UnsupportedOperationException} will be thrown when a factory
* method that takes the {@code ResourceBundle.Control} parameter is called.
*
* <p><a id="modify_default_behavior">For the {@code getBundle} factory</a>
* methods that take no {@link Control} instance, their <a
* href="#default_behavior"> default behavior</a> of resource bundle loading
@ -815,14 +835,10 @@ public abstract class ResourceBundle {
/**
* Gets a resource bundle using the specified base name, the default locale,
* and the caller's class loader. Calling this method is equivalent to calling
* and the caller module. Calling this method is equivalent to calling
* <blockquote>
* <code>getBundle(baseName, Locale.getDefault(), this.getClass().getClassLoader())</code>,
* <code>getBundle(baseName, Locale.getDefault(), callerModule)</code>,
* </blockquote>
* except that <code>getClassLoader()</code> is run with the security
* privileges of <code>ResourceBundle</code>.
* See {@link #getBundle(String, Locale, ClassLoader) getBundle}
* for a complete description of the search and instantiation strategy.
*
* @param baseName the base name of the resource bundle, a fully qualified class name
* @exception java.lang.NullPointerException
@ -830,6 +846,9 @@ public abstract class ResourceBundle {
* @exception MissingResourceException
* if no resource bundle for the specified base name can be found
* @return a resource bundle for the given base name and the default locale
*
* @see <a href="#default_behavior">Resource Bundle Search and Loading Strategy</a>
* @see <a href="#resource-bundle-modules">Resource Bundles and Named Modules</a>
*/
@CallerSensitive
public static final ResourceBundle getBundle(String baseName)
@ -887,14 +906,10 @@ public abstract class ResourceBundle {
/**
* Gets a resource bundle using the specified base name and locale,
* and the caller's class loader. Calling this method is equivalent to calling
* and the caller module. Calling this method is equivalent to calling
* <blockquote>
* <code>getBundle(baseName, locale, this.getClass().getClassLoader())</code>,
* <code>getBundle(baseName, locale, callerModule)</code>,
* </blockquote>
* except that <code>getClassLoader()</code> is run with the security
* privileges of <code>ResourceBundle</code>.
* See {@link #getBundle(String, Locale, ClassLoader) getBundle}
* for a complete description of the search and instantiation strategy.
*
* @param baseName
* the base name of the resource bundle, a fully qualified class name
@ -905,6 +920,9 @@ public abstract class ResourceBundle {
* @exception MissingResourceException
* if no resource bundle for the specified base name can be found
* @return a resource bundle for the given base name and locale
*
* @see <a href="#default_behavior">Resource Bundle Search and Loading Strategy</a>
* @see <a href="#resource-bundle-modules">Resource Bundles and Named Modules</a>
*/
@CallerSensitive
public static final ResourceBundle getBundle(String baseName,
@ -922,19 +940,6 @@ public abstract class ResourceBundle {
* <code>getBundle(baseName, Locale.getDefault(), module)</code>
* </blockquote>
*
* <p> Resource bundles in named modules may be encapsulated. When
* the resource bundle is loaded from a provider, the caller module
* must have an appropriate <i>uses</i> clause in its <i>module descriptor</i>
* to declare that the module uses implementations of
* {@code <package name> + ".spi." + <simple name> + "Provider"}.
* Otherwise, it will load the resource bundles that are local in the
* given module or that are visible to the class loader of the given module
* (refer to the <a href="#bundleprovider">Resource Bundles in Named Modules</a>
* section for details).
* When the resource bundle is loaded from the specified module, it is
* subject to the encapsulation rules specified by
* {@link Module#getResourceAsStream Module.getResourceAsStream}.
*
* @param baseName the base name of the resource bundle,
* a fully qualified class name
* @param module the module for which the resource bundle is searched
@ -950,6 +955,8 @@ public abstract class ResourceBundle {
* @since 9
* @spec JPMS
* @see ResourceBundleProvider
* @see <a href="#default_behavior">Resource Bundle Search and Loading Strategy</a>
* @see <a href="#resource-bundle-modules">Resource Bundles and Named Modules</a>
*/
@CallerSensitive
public static ResourceBundle getBundle(String baseName, Module module) {
@ -963,14 +970,15 @@ public abstract class ResourceBundle {
* on behalf of the specified module.
*
* <p> Resource bundles in named modules may be encapsulated. When
* the resource bundle is loaded from a provider, the caller module
* the resource bundle is loaded from a
* {@linkplain ResourceBundleProvider service provider}, the caller module
* must have an appropriate <i>uses</i> clause in its <i>module descriptor</i>
* to declare that the module uses implementations of
* {@code <package name> + ".spi." + <simple name> + "Provider"}.
* to declare that the module uses of {@link ResourceBundleProvider}
* for the named resource bundle.
* Otherwise, it will load the resource bundles that are local in the
* given module or that are visible to the class loader of the given module
* (refer to the <a href="#bundleprovider">Resource Bundles in Named Modules</a>
* section for details).
* given module as if calling {@link Module#getResourceAsStream(String)}
* or that are visible to the class loader of the given module
* as if calling {@link ClassLoader#getResourceAsStream(String)}.
* When the resource bundle is loaded from the specified module, it is
* subject to the encapsulation rules specified by
* {@link Module#getResourceAsStream Module.getResourceAsStream}.
@ -1000,6 +1008,8 @@ public abstract class ResourceBundle {
* @return a resource bundle for the given base name and locale in the module
* @since 9
* @spec JPMS
* @see <a href="#default_behavior">Resource Bundle Search and Loading Strategy</a>
* @see <a href="#resource-bundle-modules">Resource Bundles and Named Modules</a>
*/
@CallerSensitive
public static ResourceBundle getBundle(String baseName, Locale targetLocale, Module module) {
@ -1060,28 +1070,25 @@ public abstract class ResourceBundle {
* Gets a resource bundle using the specified base name, locale, and class
* loader.
*
* <p>This method behaves the same as calling
* {@link #getBundle(String, Locale, ClassLoader, Control)} passing a
* default instance of {@link Control} unless another {@link Control} is
* provided with the {@link ResourceBundleControlProvider} SPI. Refer to the
* description of <a href="#modify_default_behavior">modifying the default
* behavior</a>.
* <p>When this method is called from a named module and the given
* loader is the class loader of the caller module, this is equivalent
* to calling:
* <blockquote><pre>
* getBundle(baseName, targetLocale, callerModule)
* </pre></blockquote>
*
* <p><a id="default_behavior">The following describes the default
* behavior</a>.
* otherwise, this is equivalent to calling:
* <blockquote><pre>
* getBundle(baseName, targetLocale, loader, control)
* </pre></blockquote>
* where {@code control} is the default instance of {@link Control} unless
* a {@code Control} instance is provided by
* {@link ResourceBundleControlProvider} SPI. Refer to the
* description of <a href="#modify_default_behavior">modifying the default
* behavior</a>. The following describes the default behavior.
*
* <p>
* Resource bundles in a named module are private to that module. If
* the caller is in a named module, this method will find resource bundles
* from the service providers of {@link java.util.spi.ResourceBundleProvider}
* if any. Otherwise, it will load the resource bundles that are visible to
* the given {@code loader} (refer to the
* <a href="#bundleprovider">Resource Bundles in Named Modules</a> section
* for details).
* If the caller is in a named module and the given {@code loader} is
* different than the caller's class loader, or if the caller is not in
* a named module, this method will not find resource bundles from named
* modules.
* <b><a id="default_behavior">Resource Bundle Search and Loading Strategy</a></b>
*
* <p><code>getBundle</code> uses the base name, the specified locale, and
* the default locale (obtained from {@link java.util.Locale#getDefault()
@ -1201,7 +1208,7 @@ public abstract class ResourceBundle {
*
* <p><b>Note:</b>The <code>baseName</code> argument should be a fully
* qualified class name. However, for compatibility with earlier versions,
* Sun's Java SE Runtime Environments do not verify this, and so it is
* Java SE Runtime Environments do not verify this, and so it is
* possible to access <code>PropertyResourceBundle</code>s by specifying a
* path name (using "/") instead of a fully qualified class name (using
* ".").
@ -1248,7 +1255,7 @@ public abstract class ResourceBundle {
*
* @apiNote If the caller module is a named module and the given
* {@code loader} is the caller module's class loader, this method is
* equivalent to {@code getBundle(baseName, locale)}; otherwise, it will not
* equivalent to {@code getBundle(baseName, locale)}; otherwise, it may not
* find resource bundles from named modules.
* Use {@link #getBundle(String, Locale, Module)} to load resource bundles
* on behalf on a specific module instead.
@ -1264,6 +1271,7 @@ public abstract class ResourceBundle {
* @since 1.2
* @revised 9
* @spec JPMS
* @see <a href="#resource-bundle-modules">Resource Bundles and Named Modules</a>
*/
@CallerSensitive
public static ResourceBundle getBundle(String baseName, Locale locale,
@ -1278,9 +1286,9 @@ public abstract class ResourceBundle {
/**
* Returns a resource bundle using the specified base name, target
* locale, class loader and control. Unlike the {@linkplain
* #getBundle(String, Locale, ClassLoader) <code>getBundle</code>
* factory methods with no <code>control</code> argument}, the given
* locale, class loader and control. Unlike the {@link
* #getBundle(String, Locale, ClassLoader) getBundle}
* factory methods with no {@code control} argument, the given
* <code>control</code> specifies how to locate and instantiate resource
* bundles. Conceptually, the bundle loading process with the given
* <code>control</code> is performed in the following steps.
@ -2365,7 +2373,14 @@ public abstract class ResourceBundle {
* the callback methods provides the information necessary for the
* factory methods to perform the <a
* href="./ResourceBundle.html#default_behavior">default behavior</a>.
* <a href="#note">Note that this class is not supported in named modules.</a>
*
* <p> {@link ResourceBundle.Control} is designed for an application deployed
* in an unnamed module, for example to support resource bundles in
* non-standard formats or package localized resources in a non-traditional
* convention. {@link ResourceBundleProvider} is the replacement for
* {@code ResourceBundle.Control} when migrating to modules.
* {@code UnsupportedOperationException} will be thrown when a factory
* method that takes the {@code ResourceBundle.Control} parameter is called.
*
* <p>In addition to the callback methods, the {@link
* #toBundleName(String, Locale) toBundleName} and {@link
@ -2501,8 +2516,8 @@ public abstract class ResourceBundle {
* }
* </pre>
*
* @apiNote <a id="note">{@code ResourceBundle.Control} is not supported
* in named modules.</a> If the {@code ResourceBundle.getBundle} method with
* @apiNote {@code ResourceBundle.Control} is not supported
* in named modules. If the {@code ResourceBundle.getBundle} method with
* a {@code ResourceBundle.Control} is called in a named module, the method
* will throw an {@link UnsupportedOperationException}. Any service providers
* of {@link ResourceBundleControlProvider} are ignored in named modules.

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

@ -45,42 +45,46 @@ import static sun.security.util.SecurityConstants.GET_CLASSLOADER_PERMISSION;
*
* <p>
* Resource bundles can be packaged in one or more
* named modules, <em>bundle modules</em>. The <em>consumer</em> of the
* named modules, <em>service provider 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}"
* mechanism. A service interface named "{@code com.example.app.spi.MyResourcesProvider}"
* must be defined and a <em>service provider module</em> will provide an
* implementation class of "{@code com.example.app.spi.MyResourcesProvider}"
* as follows:
*
* <pre><code>
* import com.example.app.MyResourcesProvider;
* <blockquote><pre>
* {@code import com.example.app.spi.MyResourcesProvider;
* class MyResourcesProviderImpl extends AbstractResourceBundleProvider
* implements MyResourcesProvider
* {
* public MyResourcesProviderImpl() {
* super("java.properties");
* }
* // this provider maps the resource bundle to per-language package
* protected String toBundleName(String baseName, Locale locale) {
* // return the bundle name per the naming of the resource bundle
* :
* return "p." + locale.getLanguage() + "." + baseName;
* }
*
* public ResourceBundle getBundle(String baseName, Locale locale) {
* // this module only provides bundles in french
* // this module only provides bundles in French
* if (locale.equals(Locale.FRENCH)) {
* return super.getBundle(baseName, locale);
* }
* // otherwise return null
* return null;
* }
* }</code></pre>
* }}</pre></blockquote>
*
* @see <a href="../ResourceBundle.html#bundleprovider">
* Resource Bundles in Named Modules</a>
* @see <a href="../ResourceBundle.html#RBP_support">
* ResourceBundleProvider Service Providers</a>
* Refer to {@link ResourceBundleProvider} for details.
*
* @see <a href="../ResourceBundle.html#resource-bundle-modules">
* Resource Bundles and Named Modules</a>
* @since 9
* @spec JPMS
*/
public abstract class AbstractResourceBundleProvider implements ResourceBundleProvider {
private static final JavaUtilResourceBundleAccess RB_ACCESS =

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

@ -29,33 +29,117 @@ 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"}.
* {@code ResourceBundleProvider} is a service provider interface for
* resource bundles. It is used by
* {@link ResourceBundle#getBundle(String) ResourceBundle.getBundle}
* factory methods to locate and load the service providers that are deployed as
* modules via {@link java.util.ServiceLoader ServiceLoader}.
*
* <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
* <h3>Developing resource bundle services</h3>
*
* A service for a resource bundle of a given <em>{@code baseName}</em> must have
* a fully-qualified class name of the form:
* <blockquote>
* {@code <package of baseName> + ".spi." + <simple name of baseName> + "Provider"}
* </blockquote>
*
* The service type is in a {@code spi} subpackage as it may be packaged in
* a module separate from the resource bundle providers.
* For example, the service for a resource bundle named
* {@code com.example.app.MyResources} must be
* {@code com.example.app.spi.MyResourcesProvider}:
*
* <blockquote><pre>
* {@code package com.example.app.spi;
* public interface MyResourcesProvider extends ResourceBundleProvider {
* }
* }</pre>
* }</pre></blockquote>
*
* <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.
* <h3>Deploying resource bundle service providers</h3>
*
* @see <a href="../ResourceBundle.html#bundleprovider">
* Resource Bundles in Named Modules</a>
* @see <a href="../ResourceBundle.html#RBP_support">
* ResourceBundleProvider Service Providers</a>
* Resource bundles can be deployed in one or more service providers
* in modules. For example, a provider for a service
* named "{@code com.example.app.spi.MyResourcesProvider}"
* has the following implementation class:
*
* <blockquote><pre>
* {@code import com.example.app.spi.MyResourcesProvider;
* class MyResourcesProviderImpl extends AbstractResourceBundleProvider
* implements MyResourcesProvider
* {
* public MyResourcesProviderImpl() {
* super("java.properties");
* }
* // this provider maps the resource bundle to per-language package
* protected String toBundleName(String baseName, Locale locale) {
* return "p." + locale.getLanguage() + "." + baseName;
* }
*
* public ResourceBundle getBundle(String baseName, Locale locale) {
* // this module only provides bundles in French
* if (locale.equals(Locale.FRENCH)) {
* return super.getBundle(baseName, locale);
* }
* // otherwise return null
* return null;
* }
* }}</pre></blockquote>
*
* This example provides "{@code com.example.app.MyResources}"
* resource bundle of the French locale. Traditionally resource bundles of
* all locales are packaged in the same package as the resource bundle base name.
* When deploying resource bundles in more than one modules and two modules
* containing a package of the same name, <em>split package</em>,
* is not supported, resource bundles in each module can be packaged in
* a different package as shown in this example where this provider packages
* the resource bundles in per-language package, i.e. {@code com.example.app.fr}
* for French locale.
*
* <p> A provider can provide more than one services, each of which is a service
* for a resource bundle of a different base name.
*
* <p>{@link AbstractResourceBundleProvider}
* provides the basic implementation for {@code ResourceBundleProvider}
* and a subclass can override the {@link
* AbstractResourceBundleProvider#toBundleName(String, Locale) toBundleName}
* method to return a provider-specific location of the resource to be loaded,
* for example, per-language package.
* A provider can override {@link #getBundle ResourceBundleProvider.getBundle}
* method for example to only search the known supported locales or
* return resource bundles in other formats such as XML.
*
* <p>The module declaration of this provider module specifies the following
* directive:
* <pre>
* provides com.example.app.spi.MyResourcesProvider with com.example.impl.MyResourcesProviderImpl;
* </pre>
*
* <h3><a id="obtain-resource-bundle">Obtaining resource bundles from providers</a></h3>
*
* The module declaration of the <em>consumer module</em> that calls one of the
* {@code ResourceBundle.getBundle} factory methods to obtain a resource
* bundle from service providers must specify the following directive:
* <pre>
* uses com.example.app.spi.MyResourcesProvider;
* </pre>
*
* {@link ResourceBundle#getBundle(String, Locale)
* ResourceBundle.getBundle("com.example.app.MyResource", locale)}
* locates and loads the providers for {@code com.example.app.spi.MyResourcesProvider}
* service and then invokes {@link #getBundle(String, Locale)
* ResourceBundleProvider.getBundle("com.example.app.MyResource", locale)} to
* find the resource bundle of the given base name and locale.
* If the consumer module is a resource bundle service provider for
* {@code com.example.app.spi.MyResourcesProvider}, {@code ResourceBundle.getBundle}
* will locate resource bundles only from service providers.
* Otherwise, {@code ResourceBundle.getBundle} may continue the search of
* the resource bundle in other modules and class path per the specification
* of the {@code ResourceBundle.getBundle} method being called.
*
* @see AbstractResourceBundleProvider
* @see <a href="../ResourceBundle.html#resource-bundle-modules">
* Resource Bundles and Named Modules</a>
* @see java.util.ServiceLoader
* @since 9
* @spec JPMS
*/