Entries in jimage are expressed as one of three {@link Node} types; * resource nodes, directory nodes and link nodes. * *
When remapping jimage entries, jimage location names (e.g. {@code * "/java.base/java/lang/Integer.class"}) are prefixed with {@code "/modules"} * to form the names of resource nodes. This aligns with the naming of module * entries in jimage (e.g. "/modules/java.base/java/lang"), which appear as * directory nodes in {@code ImageReader}. * *
Package entries (e.g. {@code "/packages/java.lang"} appear as directory * nodes containing link nodes, which resolve back to the root directory of the * module in which that package exists (e.g. {@code "/modules/java.base"}). * Unlike other nodes, the jimage file does not contain explicit entries for * link nodes, and their existence is derived only from the contents of the * parent directory. * *
While similar to {@code BasicImageReader}, this class is not a conceptual
* subtype of it, and deliberately hides types such as {@code ImageLocation} to
* give a focused API based only on nodes.
*
* @implNote This class needs to maintain JDK 8 source compatibility.
*
* It is used internally in the JDK to implement jimage/jrtfs access,
* but also compiled and delivered as part of the jrtfs.jar to support access
* to the jimage file provided by the shipped JDK by tools running on JDK 8.
*/
public final class ImageReader implements AutoCloseable {
private final SharedImageReader reader;
private volatile boolean closed;
private ImageReader(SharedImageReader reader) {
this.reader = reader;
}
/**
* Opens an image reader for a jimage file at the specified path, using the
* given byte order.
*/
public static ImageReader open(Path imagePath, ByteOrder byteOrder) throws IOException {
Objects.requireNonNull(imagePath);
Objects.requireNonNull(byteOrder);
return SharedImageReader.open(imagePath, byteOrder);
}
/**
* Opens an image reader for a jimage file at the specified path, using the
* platform native byte order.
*/
public static ImageReader open(Path imagePath) throws IOException {
return open(imagePath, ByteOrder.nativeOrder());
}
@Override
public void close() throws IOException {
if (closed) {
throw new IOException("image file already closed");
}
reader.close(this);
closed = true;
}
private void ensureOpen() throws IOException {
if (closed) {
throw new IOException("image file closed");
}
}
private void requireOpen() {
if (closed) {
throw new IllegalStateException("image file closed");
}
}
/**
* Finds the node with the given name.
*
* @param name a node name of the form {@code "/modules/ This is equivalent to:
* This is equivalent to:
* Note that there is no reentrant calling back to this method from within
* the node handling code.
*
* @param name an absolute, {@code /}-separated path string, prefixed with either
* "/modules" or "/packages".
*/
synchronized Node findNode(String name) {
Node node = nodes.get(name);
if (node == null) {
// We cannot get the root paths ("/modules" or "/packages") here
// because those nodes are already in the nodes cache.
if (name.startsWith(MODULES_ROOT + "/")) {
// This may perform two lookups, one for a directory (in
// "/modules/...") and one for a non-prefixed resource
// (with "/modules" removed).
node = buildModulesNode(name);
} else if (name.startsWith(PACKAGES_ROOT + "/")) {
node = buildPackagesNode(name);
}
if (node != null) {
nodes.put(node.getName(), node);
}
} else if (!node.isCompleted()) {
// Only directories can be incomplete.
assert node instanceof Directory : "Invalid incomplete node: " + node;
completeDirectory((Directory) node);
}
assert node == null || node.isCompleted() : "Incomplete node: " + node;
return node;
}
/**
* Returns a resource node in the given module, or null if no resource of
* that name exists.
*
* Note that there is no reentrant calling back to this method from within
* the node handling code.
*/
Node findResourceNode(String moduleName, String resourcePath) {
// Unlike findNode(), this method makes only one lookup in the
// underlying jimage, but can only reliably return resource nodes.
if (moduleName.indexOf('/') >= 0) {
throw new IllegalArgumentException("invalid module name: " + moduleName);
}
String nodeName = MODULES_ROOT + "/" + moduleName + "/" + resourcePath;
// Synchronize as tightly as possible to reduce locking contention.
synchronized (this) {
Node node = nodes.get(nodeName);
if (node == null) {
ImageLocation loc = findLocation(moduleName, resourcePath);
if (loc != null && isResource(loc)) {
node = newResource(nodeName, loc);
nodes.put(node.getName(), node);
}
return node;
} else {
return node.isResource() ? node : null;
}
}
}
/**
* Returns whether a resource exists in the given module.
*
* This method is expected to be called frequently for resources
* which do not exist in the given module (e.g. as part of classpath
* search). As such, it skips checking the nodes cache and only checks
* for an entry in the jimage file, as this is faster if the resource
* is not present. This also means it doesn't need synchronization.
*/
boolean containsResource(String moduleName, String resourcePath) {
if (moduleName.indexOf('/') >= 0) {
throw new IllegalArgumentException("invalid module name: " + moduleName);
}
// If the given module name is 'modules', then 'isResource()'
// returns false to prevent false positives.
ImageLocation loc = findLocation(moduleName, resourcePath);
return loc != null && isResource(loc);
}
/**
* Builds a node in the "/modules/..." namespace.
*
* Called by {@link #findNode(String)} if a {@code /modules/...} node
* is not present in the cache.
*/
private Node buildModulesNode(String name) {
assert name.startsWith(MODULES_ROOT + "/") : "Invalid module node name: " + name;
// Returns null for non-directory resources, since the jimage name does not
// start with "/modules" (e.g. "/java.base/java/lang/Object.class").
ImageLocation loc = findLocation(name);
if (loc != null) {
assert name.equals(loc.getFullName()) : "Mismatched location for directory: " + name;
assert isModulesSubdirectory(loc) : "Invalid modules directory: " + name;
return completeModuleDirectory(newDirectory(name), loc);
}
// Now try the non-prefixed resource name, but be careful to avoid false
// positives for names like "/modules/modules/xxx" which could return a
// location of a directory entry.
loc = findLocation(name.substring(MODULES_ROOT.length()));
return loc != null && isResource(loc) ? newResource(name, loc) : null;
}
/**
* Builds a node in the "/packages/..." namespace.
*
* Called by {@link #findNode(String)} if a {@code /packages/...} node
* is not present in the cache.
*/
private Node buildPackagesNode(String name) {
// There are only locations for the root "/packages" or "/packages/xxx"
// directories, but not the symbolic links below them (the links can be
// entirely derived from the name information in the parent directory).
// However, unlike resources this means that we do not have a constant
// time lookup for link nodes when creating them.
int packageStart = PACKAGES_ROOT.length() + 1;
int packageEnd = name.indexOf('/', packageStart);
if (packageEnd == -1) {
ImageLocation loc = findLocation(name);
return loc != null ? completePackageDirectory(newDirectory(name), loc) : null;
} else {
// We cannot assume that the parent directory exists for a link node, since
// the given name is untrusted and could reference a non-existent link.
// However, if the parent directory is present, we can conclude that the
// given name was not a valid link (or else it would already be cached).
String dirName = name.substring(0, packageEnd);
if (!nodes.containsKey(dirName)) {
ImageLocation loc = findLocation(dirName);
// If the parent location doesn't exist, the link node cannot exist.
if (loc != null) {
nodes.put(dirName, completePackageDirectory(newDirectory(dirName), loc));
// When the parent is created its child nodes are created and cached,
// but this can still return null if given name wasn't a valid link.
return nodes.get(name);
}
}
}
return null;
}
/** Completes a directory by ensuring its child list is populated correctly. */
private void completeDirectory(Directory dir) {
String name = dir.getName();
// Since the node exists, we can assert that its name starts with
// either "/modules" or "/packages", making differentiation easy.
// It also means that the name is valid, so it must yield a location.
assert name.startsWith(MODULES_ROOT) || name.startsWith(PACKAGES_ROOT);
ImageLocation loc = findLocation(name);
assert loc != null && name.equals(loc.getFullName()) : "Invalid location for name: " + name;
// We cannot use 'isXxxSubdirectory()' methods here since we could
// be given a top-level directory (for which that test doesn't work).
// The string MUST start "/modules" or "/packages" here.
if (name.charAt(1) == 'm') {
completeModuleDirectory(dir, loc);
} else {
completePackageDirectory(dir, loc);
}
assert dir.isCompleted() : "Directory must be complete by now: " + dir;
}
/**
* Completes a modules directory by setting the list of child nodes.
*
* The given directory can be the top level {@code /modules} directory,
* so it is NOT safe to use {@code isModulesSubdirectory(loc)} here.
*/
private Directory completeModuleDirectory(Directory dir, ImageLocation loc) {
assert dir.getName().equals(loc.getFullName()) : "Mismatched location for directory: " + dir;
List The given directory can be the top level {@code /packages} directory,
* so it is NOT safe to use {@code isPackagesSubdirectory(loc)} here.
*/
private Directory completePackageDirectory(Directory dir, ImageLocation loc) {
assert dir.getName().equals(loc.getFullName()) : "Mismatched location for directory: " + dir;
// The only directories in the "/packages" namespace are "/packages" or
// "/packages/ Note: This cannot be used for package subdirectories as they have
* child offsets stored differently to other directories.
*/
private List A resource must have a valid module associated with it, so its
* module offset must be non-zero, and not equal to the offsets for
* "/modules/..." or "/packages/..." entries.
*/
private boolean isResource(ImageLocation loc) {
int moduleOffset = loc.getModuleOffset();
return moduleOffset != 0
&& moduleOffset != modulesStringOffset
&& moduleOffset != packagesStringOffset;
}
/**
* Determines if an image location is a directory in the {@code /modules}
* namespace (if so, the location name is the node name).
*
* In jimage, every {@code ImageLocation} under {@code /modules/} is a
* directory and has the same value for {@code getModule()}, and {@code
* getModuleOffset()}.
*/
private boolean isModulesSubdirectory(ImageLocation loc) {
return loc.getModuleOffset() == modulesStringOffset;
}
/**
* Creates an "incomplete" directory node with no child nodes set.
* Directories need to be "completed" before they are returned by
* {@link #findNode(String)}.
*/
private Directory newDirectory(String name) {
return new Directory(name, imageFileAttributes);
}
/**
* Creates a new resource from an image location. This is the only case
* where the image location name does not match the requested node name.
* In image files, resource locations are NOT prefixed by {@code /modules}.
*/
private Resource newResource(String name, ImageLocation loc) {
assert name.equals(loc.getFullName(true)) : "Mismatched location for resource: " + name;
return new Resource(name, loc, imageFileAttributes);
}
/**
* Creates a new link node pointing at the given target name.
*
* Note that target node is resolved each time {@code resolve()} is called,
* so if a link node is retained after its reader is closed, it will fail.
*/
private LinkNode newLinkNode(String name, String targetName) {
return new LinkNode(name, () -> findNode(targetName), imageFileAttributes);
}
/** Returns the content of a resource node. */
private byte[] getResource(Node node) throws IOException {
// We could have been given a non-resource node here.
if (node.isResource()) {
return super.getResource(node.getLocation());
}
throw new IOException("Not a resource: " + node);
}
}
/**
* A directory, resource or symbolic link.
*
* Furthermore, since a {@link ImageReader} provides "perfect" caching of
* nodes, equality of nodes from the same reader is equivalent to instance
* identity.
*/
public abstract static class Node {
private final String name;
private final BasicFileAttributes fileAttrs;
/**
* Creates an abstract {@code Node}, which is either a resource, directory
* or symbolic link.
*
* This constructor is only non-private so it can be used by the
* {@code ExplodedImage} class, and must not be used otherwise.
*/
protected Node(String name, BasicFileAttributes fileAttrs) {
this.name = Objects.requireNonNull(name);
this.fileAttrs = Objects.requireNonNull(fileAttrs);
}
// A node is completed when all its direct children have been built.
// As such, non-directory nodes are always complete.
boolean isCompleted() {
return true;
}
// Only resources can return a location.
ImageLocation getLocation() {
throw new IllegalStateException("not a resource: " + getName());
}
/**
* Returns the name of this node (e.g. {@code
* "/modules/java.base/java/lang/Object.class"} or {@code
* "/packages/java.lang"}).
*
* Note that for resource nodes this is NOT the underlying jimage
* resource name (it is prefixed with {@code "/modules"}).
*/
public final String getName() {
return name;
}
/**
* Returns file attributes for this node. The value returned may be the
* same for all nodes, and should not be relied upon for accuracy.
*/
public final BasicFileAttributes getFileAttributes() {
return fileAttrs;
}
/**
* Resolves a symbolic link to its target node. If this code is not a
* symbolic link, then it resolves to itself.
*/
public final Node resolveLink() {
return resolveLink(false);
}
/**
* Resolves a symbolic link to its target node. If this code is not a
* symbolic link, then it resolves to itself.
*/
public Node resolveLink(boolean recursive) {
return this;
}
/** Returns whether this node is a symbolic link. */
public boolean isLink() {
return false;
}
/**
* Returns whether this node is a directory. Directory nodes can have
* {@link #getChildNames()} invoked to get the fully qualified names
* of any child nodes.
*/
public boolean isDirectory() {
return false;
}
/**
* Returns whether this node is a resource. Resource nodes can have
* their contents obtained via {@link ImageReader#getResource(Node)}
* or {@link ImageReader#getResourceBuffer(Node)}.
*/
public boolean isResource() {
return false;
}
/**
* Returns the fully qualified names of any child nodes for a directory.
*
* By default, this method throws {@link IllegalStateException} and
* is overridden for directories.
*/
public Stream Directory nodes have two distinct states:
* When a directory node is returned by {@link ImageReader#findNode(String)}
* it is always complete, but this DOES NOT mean that its child nodes are
* complete yet.
*
* To avoid users being able to access incomplete child nodes, the
* {@code Node} API offers only a way to obtain child node names, forcing
* callers to invoke {@code findNode()} if they need to access the child
* node itself.
*
* This approach allows directories to be implemented lazily with respect
* to child nodes, while retaining efficiency when child nodes are accessed
* (since any incomplete nodes will be created and placed in the node cache
* when the parent was first returned to the user).
*/
private static final class Directory extends Node {
// Monotonic reference, will be set to the unmodifiable child list exactly once.
private List Resources are leaf nodes referencing an underlying image location. They
* are lightweight, and do not cache their contents.
*
* Unlike directories (where the node name matches the jimage path for the
* corresponding {@code ImageLocation}), resource node names are NOT the same
* as the corresponding jimage path. The difference is that node names for
* resources are prefixed with "/modules", which is missing from the
* equivalent jimage path.
*/
private static class Resource extends Node {
private final ImageLocation loc;
private Resource(String name, ImageLocation loc, BasicFileAttributes fileAttrs) {
super(name, fileAttrs);
this.loc = loc;
}
@Override
ImageLocation getLocation() {
return loc;
}
@Override
public boolean isResource() {
return true;
}
@Override
public long size() {
return loc.getUncompressedSize();
}
@Override
public long compressedSize() {
return loc.getCompressedSize();
}
@Override
public String extension() {
return loc.getExtension();
}
}
/**
* Link node (a symbolic link to a top-level modules directory).
*
* Link nodes resolve their target by invoking a given supplier, and do
* not cache the result. Since nodes are cached by the {@code ImageReader},
* this means that only the first call to {@link #resolveLink(boolean)}
* could do any significant work.
*/
private static class LinkNode extends Node {
private final Supplier{@code
* findNode("/modules/" + moduleName + "/" + resourcePath)
* }
* but more performant, and returns {@code null} for directories.
*
* @param moduleName The module name of the requested resource.
* @param resourcePath Trailing module-relative resource path, not starting
* with {@code '/'}.
*/
public Node findResourceNode(String moduleName, String resourcePath)
throws IOException {
ensureOpen();
return reader.findResourceNode(moduleName, resourcePath);
}
/**
* Returns whether a resource exists in the given module.
*
* {@code
* findResourceNode(moduleName, resourcePath) != null
* }
* but more performant, and will not create or cache new nodes.
*
* @param moduleName The module name of the resource being tested for.
* @param resourcePath Trailing module-relative resource path, not starting
* with {@code '/'}.
*/
public boolean containsResource(String moduleName, String resourcePath)
throws IOException {
ensureOpen();
return reader.containsResource(moduleName, resourcePath);
}
/**
* Returns a copy of the content of a resource node. The buffer returned by
* this method is not cached by the node, and each call returns a new array
* instance.
*
* @throws IOException if the content cannot be returned (including if the
* given node is not a resource node).
*/
public byte[] getResource(Node node) throws IOException {
ensureOpen();
return reader.getResource(node);
}
/**
* Returns the content of a resource node in a newly allocated byte buffer.
*/
public ByteBuffer getResourceBuffer(Node node) {
requireOpen();
if (!node.isResource()) {
throw new IllegalArgumentException("Not a resource node: " + node);
}
return reader.getResourceBuffer(node.getLocation());
}
private static final class SharedImageReader extends BasicImageReader {
private static final MapNode Equality
*
* Nodes are identified solely by their name, and it is not valid to attempt
* to compare nodes from different reader instances. Different readers may
* produce nodes with the same names, but different contents.
*
*
*
*
*