aXSL: Unreleased Changes, Java

See Release Notes for other Release Notes.

Unreleased Changes are expected to be incorporated in the next release, and generally reflect the current state of the repository.

Highlights

• General change of using CharSequence for return values on text, instead of char[]. This is a more object-oriented solution, and provides two tangible benefits: 1) The possibility of making the values immutable, and 2) The possibility of more creative solutions to how the data is stored. Consideration was given to creating a special interface for this purpose, but CharSequence is sufficient for the purpose and is the only possible interface which java.lang.String can implement.
• Parameters on text-related methods now generally accept any CharSequence instead of only String. Since this change is backward-compatible, we have not noted the individual cases in the detail parts of this document.

General

The Ant build script, build.xml, now contains targets that build each individual module, and another, "all-modules" that builds all of these module jar files. This is useful for those who might want to use only a subset of aXSL. Details are in the build documentation.

Common

There are currently no unreleased changes.

PostScript

There are currently no unreleased changes.

Font

• FontServer: registerFontOutputFactory no longer throws a FontException. Any exceptional conditions here are in the nature of unchecked runtime exceptions.
• FontOutput: Unneeded convenience constants were removed.
• Removed FontOutputFactory and all related methods in other interfaces. The issue of how a FontUse instance creates a FontOutput instance is an implementation issue.
• FontUse: getFontOutput(String) no longer returns null, but instead throws an (unchecked) UnsupportedOperationException if it encounters an unknown mime type. Added method canMakeFontOutput(String) so that this condition can be tested first.
• Font: Added inner enumeration class for the baselines that can be stored in an OpenType font. This enumeration is font-based instead of XSL-FO-based, and is intended to make implementation more straightforward.
• Font: Signature of method org.axsl.common.value.Baseline baseline(Iso15924 script) was changed to org.axsl.font.Font.Baseline baseline(Iso15924 script). This cleans up some XSL-FO dependencies. The semantics of the method are unchanged.
• Font: Signature of method Font.Baseline baseline(Iso15924 script) was changed to Font.Baseline baseline(String script). Detailed documentation for the decision for this change was added to the javadoc. This does change the semantic of this method, as the script parameter now represents an OpenType script code instead of an ISO script code.
• Font: Signature of method int baselineOffset(AbsoluteAxis, org.axsl.common.value.Baseline, int) was changed to int baselineOffset(Font.WritingMode, org.axsl.font.Font.Baseline, int). This cleans up some XSL-FO dependencies. The semantics of the method are unchanged.
• The aXSL Font module no longer has any dependencies on aXSL Common, making it a bit more lightweight.
• FontServer: The method registerFontDescription(String, String, Encoding, Font.Style, Font.Weight, Font.Variant, Font.Stretch, float, float, float, float[]) has changed. Specifically, the "unset" value for the parameters indicating whether a font can be used to simulate small-caps, oblique, backslant, and the various stretch values has been changed from Float.NaN to new constants in the FontServer interface. Implementations and client applications should both use these new constants. Float.NaN was originally chosen to prevent confusion with valid numeric values and was intended to roughly mean "null". However Float.NaN is not suitable for use in comparison operations. The constants were created so that, if similar changes need to be made in the future, they can be done in the constants without disturbing code.
• FontUse: Added method to explicitly return the simulated small-caps percentage.
• FontServer: Added new small-caps constant and documentation to registerFontDescription, allowing a new value to be passed for the simulated small-caps. This new value indicates that the font should compute the small-caps percentage based on its x-height.
• Added documentation to axsl-font-config.dtd indicating that "native" is now an acceptable value for the simulate-small-caps attribute. This indicates that the font should compute the small-caps percentage based on its x-height.
• Font.width(CharSequence, int, int, int): Added boolean parameter "kern", indicating whether kerning should be considered when computing the width of the character sequence.
• Font.Style, Font.Weight, Font.Variant, and Font.Stretch: Added methods returning the CSS and XSL-FO values for each of the enumerated items. Removed methods with similar purposes from FontUtility: fontStyleName(Font.Style), fontVariantName(Font.Variant), fontStretchName(Font.Stretch).
• Moved FontUtility method foFontSelectionStrategy(String, boolean) to Font.SelectionStrategy.parseFo(String, boolean).
• Moved FontUtility method cssFontStyle(String, boolean) to Font.Style.parseCss(String, boolean), and moved foFontStyle(String, boolean) to Font.Style.parseFo(String, boolean).
• Moved FontUtility method cssFontWeight(String, boolean) to Font.Weight.parseCss(String, boolean), and moved foFontWeight(String, boolean) to Font.Weight.parseFo(String, boolean).
• Moved FontUtility method cssFontVariant(String, boolean) to Font.Variant.parseCss(String, boolean), and moved foFontVariant(String, boolean) to Font.Variant.parseFo(String, boolean).
• Moved FontUtility method cssFontStretch(String, boolean) to Font.Stretch.parseCss(String, boolean), and moved foFontStretch(String, boolean) to Font.Stretch.parseFo(String, boolean).
• Moved parsing-related constants in FontUtility to appropriate enums in Font, making most of them private.

Graphic

• Create new "output" package, which is essentially the same concept as is used in aXSL Font. Each output type can have its own factory, which is used to create output helpers for that output type.
• Moved GraphicPdfContext to the new output package, and renamed it GraphicOutputContext, as it can be used for more output types than just PDF.
• SvgGraphic: Moved output-specific methods to the interfaces in the output package. Moved method awtPaint to GraphicJava2d, and renamed it drawGraphic. Moved method drawPdfStreamContent to GraphicPdf, and renamed it drawVectorContent. Moved method drawPs to GraphicPs, and renamed it drawVectorContent. Parameters were added to the methods in GraphicPdf and GraphicPs to make the signatures more similar, thus having the same features. The methods in GraphicJava2d and GraphicPs may now throw a GraphicException.
• SvgGraphic: Removed method drawPdfDocument. This is an unnecessary burden on a Graphics package.
• GraphicJava2d: Removed clipRectangle parameter from drawGraphic method. Any clipping should be done by the client application. Also removed the pageHeight parameter. The purpose of this parameter was to assist in converting the given contentRectangle, assumed to be in a coordinate system whose origin is in the lower left corner of the page, to the Java2D user space, whose origin is in the upper left corner of the page. This conversion should now be done before submitting the rectangle to this method, and the documentation has been clarified to indicate that the contentRectangle is in Java2D user space.
• Added MathGraphic interface, making MathML a first-class graphic type. Also added methods makeMathDocument and makeMathGraphic to GraphicServer.

Hyphenation

• HyphenBreak: all methods now return CharSequence instead of String.
• Methods in AbstractTestHyphenationServer now throw HyphenationException instead of Exception, in accordance with best practices.

Text

• org.axsl.text.line.LineText: Add method to get optimum word spacing.
• org.axsl.text.line.LineText.inlineText() now returns CharSequence instead of char[].

Speech

There are currently no unreleased changes.

FO Tree

• org.axsl.fo.fo.BookmarkTitle: Removed specialized getChildAt method in favor of new getText() method.
• org.axsl.fo.Fo: Added isValid method, allowing an implementation to mark an object as invalid for warning-type problems that should not halt processing, and allowing downstream applications to ignore them.
• org.axsl.fo.fo.PageSequence: Added traitFormat method with a javadoc comment indicating the need for the exposure of this trait. Also added getPageNumberFormatter method so that downstream applications can know what general formatting scheme was used. Added getFolioPrefix and getFolioSuffix methods.
• org.axsl.fo.fo.FolioPrefix and org.axsl.fo.fo.FolioSuffix: Added method getContentAsText.
• org.axsl.fo.FoLineText: Add method to get optimum word spacing.
• Renamed package org.axsl.fo.svg to org.axsl.fo.foreign to make it more generally useful.
• Added interface org.axsl.fo.foreign.MathElement to allow implementations to associate a graphic element with a parsed MathML Document.
• FoLineText.inlineText(FoContext) now returns CharSequence instead of char[].
• CharacterPa.getAreaTreeText(FoContext) now returns CharSequence instead of char[].
• Method getContentAsText() in FolioPrefix and FolioSuffix now returns CharSequence instead of String.
• Method getFolioString(int) in PageNumber, PageNumberCitation, and PageNumberCitationLast now returns CharSequence instead of String.
• PageSequence.formatPageNumber(int) now returns CharSequence instead of String.
• ScalingValueCitation.getAppliedScaleFactorString(int) now returns CharSequence instead of String.

Area Tree

There are currently no unreleased changes.

Galley

• Page: getParent method now returns the more specific PageCollection.
• PageCollection: Added getPageNumberFormatter method so that downstream applications can know what general formatting scheme was used. Also added methods getPageNumberPrefix and getPageNumberSuffix for similar reasons.
• Added interface org.axsl.galley.foreign.ForeignContentMath to handle inline MathML content.
• LeaderArea.dotLeaderText() now returns CharSequence instead of char[].
• TextArea.getText() now returns CharSequence instead of char[].
• Page.getFormattedNumber() now returns CharSequence instead of String.
• PageCollection: Methods getPageNumberPrefix() and getPageNumberSuffix() now return CharSequence instead of String.
• Added new GalleyVisitorException class, and added a "throws" for it to each method in RenderVisitor. Also added "throws" for it to the render method in AreaNode.

Output

• Renderer: Changed Exception thrown by "render" method from OutputException to GalleyVisitorException.

PDF

• PdfDocument: Added method addPageLabelRange, which allows client applications to specify the appearance of page labels in the PDF document itself.
• PdfContentStream.drawText(String, boolean) has been changed to drawText(CharSequence, boolean).
• PdfDocument.addPageLabelRange(int, PdfPageLabelStyle, String, int) has been changed. The third parameter is now CharSequence instead of String.
• PdfContentStream: Added "throws PdfException" to all methods.