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

• aXSL is now dependent on Java Standard Edition 6.
• 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.
• The rather bulky Language, Country, and Script classes that used to be in Common have been moved to FOray, and replaced in aXSL with interfaces of the same name. The primary purpose for this change is to reduce the footprint of Common, but also provides a way for additional items of each of these types to be added by implementations. We still like having these in typesafe containers. In addition, a new Orthography interface has been added, which is simply the combination of a Language, Country, and Script. Instances of Orthography are now passed to Hyphenation and Font methods.
• Hyphenation and Font interfaces are now more word-oriented instead of char-oriented. We think this will eventually increase performance of line- and page-breaking code.

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.

The build and dependency management has been converted to Apache Maven.

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.
• Added new FontOptions interface, which is intended to convey the user's intent regarding which font features should and should not be used, specifically the OpenType features that may be available. For example, the user may wish for the "liga" ligatures to be processed, but to ignore the "dlig" discretionary ligatures. Additional granularity may be added to this interface in the future, for example to allow the "ffl" ligature to be used, but to disallow the "ffi" ligature from being used. There is uncertainty about how this information should be conveyed to the font system. We assume for now that it should come from the XSL-FO document itself. The other possibility is that it should come from the font-configuration, so that if a user wanted to include certain features in one place and not in another, they would actually reference different registered fonts that point to the same actual font. The font registration would then convey the configuration to the font during processing. So the former option required something like FontOption, and the latter does not.

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.