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

Upgrade to CSS4J 2.0.4

    XMLWordPrintable

    Details

    • Type: Task
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: 12.5
    • Fix Version/s: 12.6
    • Component/s: Dependency Upgrades
    • Labels:
      None
    • Difficulty:
      Unknown
    • Documentation:
      N/A
    • Similar issues:

      Description

                                  CSS4J RELEASE NOTES
                                  ===================
      
      Release 2.0.4 - July 8, 2020
      ----------------------------
      
      Highlights
      ----------
       Bugfixes, and the nu.validator htmlparser artifact is used instead of the (very
      similar) nu.validator.htmlparser's.
      
      
      Upgrading from 1.0
      ------------------
       The 2.0 branch 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.
      
       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()).
      
       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, the source-level compatibility is now for Java SE version 8 instead of
      7: be sure that you are able to use Java 8 or higher.
      
      
      Description
      -----------
       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.
      
      
      Packaging
      ---------
       This project is divided in several modules:
      
      - Core module: file css4j-<version>.jar
      - User agent module: file css4j-agent-<version>.jar
      - Dom4j backend module: file css4j-dom4j-<version>.jar
      - AWT module, with AWT helper classes: file css4j-awt-<version>.jar
      
       Depending on your use case, you may just need the core module, the core module
      plus the dom4j one, or all four modules.
      
      
      Java(tm) Runtime Environment requirements
      -----------------------------------------
       All the classes in the binary package have been compiled with a Java SE 
      compiler set to 1.8 compiler compliance level, except the module-info files.
      
       Building the library requires JDK 12 or higher, although the resulting jar
      files can be run with a 1.8 JRE.
      
      
      W3C Compliance
      --------------
       Some parts of the code may throw DOMExceptions that are not covered by the 
      CSS Object Model specification. Those cases are documented in the code.
      
       The behaviour of the documents and sheets varies according to the 'compliance
      mode' of the associated document (DTD-less documents are in 'quirks' mode).
      
       If your use case is broken due to non-conformant behaviour, please report.
      
      
      CSS3 Support
      ------------
       CSS3 is partially supported by the base CSS interfaces, and is not supported 
      by the experimental visual formatting model. The following table summarizes 
      the basic support for setting/retrieving the main CSS level 3/4 features (other
      specifications are also supported):
        ___________________________________________
       |    CSS3 Spec Name           |   Support   |
       |-----------------------------|-------------|
       | Background / Border         | Yes         |
       | Color                       | Yes         |
       | Media Queries               | Partial (1) |
       | Selectors                   | Yes         |
       | Transitions                 | Yes         |
       | Values                      | Yes         |
       | Grid / Template / Alignment | Partial (2) |
       |_____________________________|_____________|
      Notes:
       1) Event handling with addListener/removeListener is not supported, given that
      the library's user is supposed to be in control of the CSSCanvas instances where
      the information about such events should be available.
       2) Legacy gap properties (grid-row-gap, grid-column-gap, and grid-gap) are not
      supported, although the longhands can be used if declared explicitly).
      
      
      Using CSS4J
      -----------
       The usage guide at the website and the Javadoc overviews of the different
      packages can be a starting point for users. Unit tests may also be useful
      in showing different uses of the library. Generally, the library will be used in
      the context of a document object model tree, but stand-alone use of style
      declarations and style sheets is also possible.
      
      
      Software dependencies
      =====================
      
       To build this library you need:
      
      - The JCLF package. Version 4.0.4 or higher is required. Go to
        https://sourceforge.net/projects/jclf for downloads.
      
      - The SLF4J package, which is a logging package. See http://www.slf4j.org/ 
        for more information.
      
      To build the dom4j module the following is required:
      
      - The dom4j JAR package (tested with 2.1.1).
        URL: https://github.com/dom4j
      
      - The XPP3 Pull Parser (which is supported by this library but beware that it
        does not support entities). See:
        http://www.extreme.indiana.edu/dist/java-repository/xpp3/distributions/
      
       Optional packages:
      
      To run the unit tests you need a recent version of JUnit 4. Tests and the agent
      module also require the validator.nu html5 parser:
          https://about.validator.nu/htmlparser/
      
      - Dom4j module: unit tests require Jaxen (https://github.com/jaxen-xpath/jaxen).
        This software was tested with 1.2.0.
      
       A Maven build (which requires Java 12 or higher) is provided. The dom4j module
      requires dom4j 2.x to build, although you should be able to run the resulting
      jar file with dom4j 1.6 if you are stuck with it.
      
      
      Project Sites
      =============
      Project home: https://css4j.github.io/
      Development site: https://github.com/css4j
      
      

        Attachments

          Activity

            People

            Assignee:
            vmassol Vincent Massol
            Reporter:
            vmassol Vincent Massol
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved: