CSS4J RELEASE NOTES
Release 2.0.0 - December 4, 2019
This new major release features NSAC 2.0 and a new Object Model Value API; it
is not backwards-compatible with 1.0, but the new 2.0 APIs are more appropriate
to deal with modern CSS. Any new development should use the 2.0 API.
NSAC 2.0 no longer inherits from stuff in the org.w3c.css.sac package (provided
by the -not needed anymore- sac.jar file) but is an independent API, with its
methods and features being sort of an hybrid between the old SAC and newer code.
Some interfaces have changed significantly, and the usage of the InputSource
class was reduced and is discouraged (a Reader is being used instead).
Of course this means that other SAC parsers are not supported, which may seem a
loss of flexibility. However, the other parsers are stuck with CSS2 (or partial
support for CSS3) and weren't really usable for real-world sheets. Without the
need to support other SAC parsers, code can be cleaner and is less error-prone
(other parser projects would be welcome to implement NSAC 2 if they wanted to).
The new Value API still uses the interface names CSSValue and CSSPrimitiveValue
but adds others like CSSTypedValue. In the end, its usage is somewhat different
to the old (and deprecated) W3C CSSValue API, requiring almost no type casts to
obtain information to make decisions about value handling (type casts are only
required when retrieving the actual encapsulated value). The categorization of
values is different, and the dimension units are shared with NSAC 2.0 from a
common source interface. But some methods have names similar to the old API to
ease the transition (for example I keep getCssValueType() to retrieve the value
category, instead of a more proper getCategory()).
Another important change is that the source-level compatibility is now for Java
SE version 8 instead of 7. Comments about the new APIs are welcome.
Many 2.0 patches do not apply to 1.0 which makes it difficult to maintain. As a
consequence, the end of life for 1.0 shall happen in March 5, 2020 unless
somebody volunteers for maintaining it (which would probably be a waste of time).
Upgrading from 1.0
The extended CSS interfaces in 1.0 ('css' and 'nsac' packages) have now adopted
the names of the interfaces that they were extending, due to the fact that they
are no longer an extension but a full fork. This means that if you are using
interfaces prefixed with 'Extended' or having the '2' suffix from those 'css'
and 'nsac' packages, you need to remove that prefix/suffix to begin the upgrade,
and then use the interfaces from css4j instead of the old W3C ones. Note that
this is only for the CSS interfaces, so the 'Extended'-prefixed interfaces in
the 'doc.dom' package were not changed.
SAC/NSAC 1.x users need to look closely at the new CSSHandler interface, and to
the changes in LexicalUnit; the rest of the API changes should be easy to apply.
The type identifiers in 2.0 use enumerations instead of integers (CSS unit
identifiers are now separate from type identifiers and are still integer).
If you are using the CSSValue API, the upgrade is non-trivial and you should
look at the new interfaces. In many cases where you were using the
CSSPrimitiveValue interface, you should be using the new CSSTypedValue, although
sometimes the renewed CSSValue type may be all that you need.
For example, calls to CSSPrimitiveValue.getRGBColorValue() should be changed to
CSSTypedValue.toRGBColorValue(), but be sure that the type is a COLOR value in
the RGB space before trying to edit the color (and you can use
RGBColorValue.getRGBColorValue() to access the RGBAColor object).
DOM4J users should be aware that the document factory no longer automatically
loads a default User Agent sheet. This backwards-incompatible change may seem
gratuitous, but the old behaviour has shown to be problematic for users.
Finally, be sure that you are able to use Java SE 8 or higher.
This software contains Java(tm) classes covering CSS document style formatting.
Unless otherwise noted, this software is provided under a BSD-style licence
(see the LICENSE.txt file, and also LICENSES.txt for included files that have a
The functionality in this library can be divided in the following areas:
- A CSSOM API very similar to the standard W3C CSS Object Model API, that allows
accessing the CSS information (style sheets, inline styles, etc.) in a DOM
Document, as well as getting computed styles for its elements.
- A CSS-enabled native DOM implementation.
- A DOM wrapper that can be used with an external DOM implementation.
- A DOM4J backend (module css4j-dom4j) which uses documents and elements that
extend those of dom4j (for those who are comfortable with dom4j).
- A device profile API to encapsulate target device-specific information.
- A few AWT helper classes (AWT module).
- Some helper XML-DTD classes.