The ModuleFileParser is designed to iterate over the module file using * {@code hasNext()} and {@code next()}. The section type and data can be * accessed using methods such as {@code getSectionHeader()}, * {@code getContentStream()}, and {@code getClasses()}.
* *The {@code next()} method causes the parser to read the next parse event, * and returns an {@code Event} which identifies the type of event just read. * The current event type can be determined invoking the {@code event()} * method.
* *Convenience methods, such as {@code skipToNextStartSection} and * {@code skipToNextStartSubSection}, are defined to support easy access to * (sub)section content without having to handle specific event types.
* *A minimal example for using this API may look as follows: *
* try (FileInputStream fis = new FileInputStream(jmodFile)) {
* ModuleFileParser parser = ModuleFile.newParser(fis);
* while (parser.skipToNextStartSection()) {
* SectionHeader header = parser.getSectionHeader();
* SectionType type = header.getType();
* switch (type) {
* case MODULE_INFO:
* out.format("%s section, %s%n", type, header); break;
* case SIGNATURE:
* out.format("%s section, %s%n", type, header); break;
* case CLASSES:
* out.format("%s section, %s%n", type, header); break;
* case RESOURCES:
* out.format("%s section, %s%n", type, header); break;
* case NATIVE_LIBS:
* out.format("%s section, %s%n", type, header); break;
* case NATIVE_CMDS:
* out.format("%s section, %s%n", type, header); break;
* case CONFIG:
* out.format("%s section, %s%n", type, header); break;
* default:
* throw new IOException("Unknown section type");
* }
* }
* }
*
*/
public interface ModuleFileParser {
/**
* ModuleFileParser parsing events.
*
* Events must follow the following grammar. *
* START_FILE
* START_SECTION (MODULE_INFO must be present)
* END_SECTION
* [START_SECTION (optional sections)
* [START_SUBSECTION (sections with subsections)
* END_SUBSECTION]+
* END_SECTION]+
* END_FILE
*
*/
public static enum Event {
/**
* The first event returned. The module header has been consumed.
*/
START_FILE,
/**
* The start of a section. The section header has been consumed.
*/
START_SECTION,
/**
* The start of a subsection. The subsection header has been consumed.
*/
START_SUBSECTION,
/**
* The end of a subsection. The subsection content has been consumed.
*/
END_SUBSECTION,
/**
* The end of a section. The section content has been consumed.
*/
END_SECTION,
/**
* The end of the module file. The file content has been consumed.
*/
END_FILE;
}
/**
* Returns the module file header.
*
* @return The module file header
*/
public ModuleFileHeader fileHeader();
/**
* Returns current event of the parser.
*/
public Event event();
/**
* Check if there are more events.
*
* @return true, if and only if, there are more events
*/
public boolean hasNext();
/**
* Returns the next parsing event.
*
* Skips over any unread data from a previous (sub)section.
* * @return the next parse event * * @throws NoSuchElementException * If invoked when {@code hasNext} returns false * * @throws ModuleFileParserException * If there is an error processing the underlying module file */ public Event next(); /** * Returns the header of the current section. * * @return the section header * * @throws ModuleFileParserException * If the current event is one of START_FILE or END_FILE */ public SectionHeader getSectionHeader(); /** * Returns the header of the current file subsection. * * @return the subsection header * * @throws ModuleFileParserException * If the current event is not one of START_SUBSECTION or END_SUBSECTION */ public SubSectionFileHeader getSubSectionFileHeader(); /** * Returns the hash of the module file header, current section, or file. * *Returns the hash of the module file header if the current event is * START_FILE, the section hash if the current event is END_SECTION, or the * complete file contents hash if the current event is END_FILE.
* *The specific hashes are calculated as per the module-file * specification. More specifically, the module file header hash and the * section hash exclude the follow fields from their header, the hash length * and the hash value. The complete file contents hash excludes the file * hash value in the module file header and the signature section * (if present).
* * @return the hash bytes. * * @throws ModuleFileParserException * If the current event is not one of START_FILE, END_SECTION, * or END_FILE */ public byte[] getHash(); /** * Returns an InputStream of the uncompressed content of the current * section or subsection (if the section defines a compressor), otherwise * just the raw bytes. * *For the CLASSES section ( {@code getSectionHeader.getType() == * ModuleFile.SectionType.CLASSES} ) the {@code getClasses} method should be * invoked. All other sections and subsections can invoke this method to get * the uncompressed (sub)section content.
* * @return the content stream * * @throws ModuleFileParserException * If the current event is not one of START_SECTION or * START_SUBSECTION, if {@code getSectionHeader().getType()} returns * {@code ModuleFile.SectionType.CLASSES}, or if there is an error * processing the underlying module file */ public InputStream getContentStream(); /** * Returns an Iterator over the classes in the CLASSES section. * *If this method is invoked to extract the content of the classes * section then it must be invoked in a section whose * {@code getSectionHeader.getType()} returns * {@code ModuleFile.SectionType.CLASSES}. Any other time will throw a * {@code ModuleFileParserException}.
* * @return an Iterator over the classes, where the entry key is the class * file name, e.g. java/lang/Object.class, and the value is an * input stream containing the class bytes. * * @throws ModuleFileParserException * If the current event is not START_SECTION, if * {@code getSectionHeader().getType()} does not return * {@code ModuleFile.SectionType.CLASSES}, or if there is an error * processing the underlying module file */ public IteratorIf the (sub)section data is compressed then this method simply * returns the compressed bytes, and the invoker is responsible for * decompressing.
* * @return The raw (sub)section data * * @throws ModuleFileParserException * If the current event is not one of START_SECTION or START_SUBSECTION */ public InputStream getRawStream(); /** * Skips to the start of the next section. * *Skips over any unread data, and consumes events until START_SECTION * or END_FILE is encountered.
* * @return true, if and only if, the next event is START_SECTION * * @throws ModuleFileParserException * If there is an error processing the underlying module file */ public boolean skipToNextStartSection(); /** * Skips to the start of the next subsection. * *Skips over any unread data, and consumes events until END_SECTION * is encountered.
* * @return true, if and only if, the current event is START_SUBSECTION * * @throws ModuleFileParserException * If not within a section that contains subsections, or if there is * an error processing the underlying module file */ public boolean skipToNextStartSubSection(); }