Skip to first unread message
admin
Dec 4, 2019, 5:01:57 PM12/4/19
to css4j
New release 2.0.0 is now available from two download sites:
Highlights
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 or 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.
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 or 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.
admin
Dec 5, 2019, 12:47:56 PM12/5/19
to css4j
A few figures about css4j 2.0.0:
Lines of code in css4j's Github repositories, counted with tokei:
-------------------------------------------------------------------------------
Language Files Lines Code Comments Blanks
-------------------------------------------------------------------------------
CSS 24 1955 1336 455 164
HTML 11 1863 1846 5 12
Java 629 170450 130983 22222 17245
JavaScript 7 204 174 30 0
Markdown 7 112 112 0 0
Shell 3 109 76 33 0
SVG 9 1231 1213 9 9
Plain Text 15 1631 1631 0 0
XML 8 1301 1267 31 3
-------------------------------------------------------------------------------
Total 713 178856 138638 22785 17433
-------------------------------------------------------------------------------
Excluding the css4j.github.io website:
-------------------------------------------------------------------------------
Language Files Lines Code Comments Blanks
-------------------------------------------------------------------------------
CSS 21 1524 977 454 93
HTML 8 1223 1213 4 6
Java 629 170450 130983 22222 17245
Markdown 7 112 112 0 0
Shell 2 73 57 16 0
Plain Text 12 1398 1398 0 0
XML 8 1301 1267 31 3
-------------------------------------------------------------------------------
Total 687 176081 136007 22727 17347
-------------------------------------------------------------------------------
- About 45% of the code is test-related (unit tests, integration and benchmarks).
- 82.3% unit test coverage in the core module (81.9% from core tests, 0.4% from css4j-dom4j tests).
- 140 real-world high volume websites being integration-tested to check for possible issues.
Reply all
Reply to author
Forward
0 new messages