Uploaded image for project: 'XWiki Platform'
  1. XWiki Platform
  2. XWIKI-16905

Upgrade to CSS4J 2.0.0



    • Task
    • Resolution: Fixed
    • Major
    • 12.0-rc-1
    • 11.10
    • Dependency Upgrades
    • None
    • Unknown
    • N/A
    • Pull Request accepted


                                  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
      different licensing).
       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.


        Issue Links



              carlosame Carlos Amengual
              vmassol Vincent Massol
              0 Vote for this issue
              2 Start watching this issue