Skip to content

Commit aa57b6f

Browse files
carlosamecarlosame
committed
New UPGRADING.txt.
1 parent ff731be commit aa57b6f

File tree

1 file changed

+141
-0
lines changed

1 file changed

+141
-0
lines changed

‎UPGRADING.txt‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
UPGRADING FROM PREVIOUS VERSIONS
2+
================================
3+
4+
5+
Upgrading to 3.1 from 3.0
6+
-------------------------
7+
- If you process a document that has a remote documentURI (or no documentURI
8+
set), and that document includes links to sheets with 'file:' or 'jar:' URLs,
9+
you need to call document.setDocumentURI() to set a 'file:' or 'jar:' URI.
10+
Otherwise, the sheets won't be processed, and the same applies to BASE href
11+
attributes.
12+
- The method ErrorHandler.hasErrors() now returns true if there are I/O errors.
13+
Those errors were previously considered transient, and therefore weren't
14+
appearing there.
15+
- On attribute nodes, getTextContent() now returns the attribute value instead
16+
of the empty string.
17+
- ExtendedNamedNodeMap<T>.removeNamedItem() and removeNamedItemNS() methods now
18+
return a value of the parameterized type (T).
19+
- DefaultEntityResolver.resolveEntity(DocumentTypeDeclaration) is deprecated
20+
(probably nobody is using that method).
21+
22+
23+
Upgrading to 3.0 from 2.1
24+
-------------------------
25+
Three modules were split out from the css4j module in 2.x: tokenproducer,
26+
carte-util and xml-dtd. This should give more flexibility to developers that
27+
only want one of them (or want to use css4j without xml-dtd).
28+
29+
Now you can use finer-grained modules, but if you used css4j together with DTD
30+
classes, in Maven you now need to specify the xml-dtd module separately, like:
31+
32+
<dependency>
33+
<groupId>io.sf.carte</groupId>
34+
<artifactId>xml-dtd</artifactId>
35+
<version>${css4j.version}</version>
36+
<type>jar</type>
37+
<scope>compile</scope>
38+
<optional>false</optional>
39+
</dependency>
40+
<dependency>
41+
<groupId>io.sf.carte</groupId>
42+
<artifactId>css4j</artifactId>
43+
<version>${css4j.version}</version>
44+
<type>jar</type>
45+
<scope>compile</scope>
46+
<optional>false</optional>
47+
</dependency>
48+
49+
Then, there are the following API changes that you may need to address:
50+
51+
- CSSOM: moved CSSCanvas, Viewport from 'agent' to 'style.css' package. The old
52+
interfaces can still be used (they inherit from the new), but are deprecated.
53+
- Moved BooleanCondition, BooleanConditionFactory, MediaFeaturePredicate,
54+
MediaQueryFactory and MediaQueryHandler from 'parser' to 'style.css' package.
55+
The reason: 'parser' is supposed to be mostly an implementation package, and
56+
this move would allow other implementations to exist.
57+
- DOM API: introduced interface 'StringList' and two implementations of it.
58+
- CSSOM: StringList is now used in comment processing instead of List<String>,
59+
and enablePrecedingComments() was added to AbstractCSSRule.
60+
- CSSOM: removed the clone(AbstractCSSStyleSheet) method from CSSRule interface.
61+
Use AbstractCSSRule.clone(AbstractCSSStyleSheet) instead.
62+
- CSSOM: method SACErrorHandler.mapError() now takes a CSSRule instead of an
63+
AbstractCSSRule (to make it more generic and allow other implementations).
64+
65+
66+
Upgrading to 2.1 from 2.0
67+
-------------------------
68+
The changes in 2.1 vs. 2.0 are mostly about NSAC: a few new lexical types were
69+
added (including one for calc() which in 2.0 was considered a generic function).
70+
New primitive types for the cubic-bezier() and steps() easing functions were
71+
also added.
72+
73+
Also thanks to an addition to NSAC, setting a custom property to an empty value
74+
is now supported, like "--My-property:;".
75+
76+
Finally, it adds support for env() computed values by means of an addition to
77+
the StyleDatabase interface.
78+
79+
Which means that you can handle 2.1 as a drop-in replacement for 2.0 unless you
80+
were either: a) using NSAC directly, b) checking for cubic-bezier() or steps(),
81+
or c) are implementing the StyleDatabase interface.
82+
83+
84+
Upgrading to 2.0 from 1.0
85+
-------------------------
86+
The 2.0 branch features NSAC 2.0 and a new Object Model Value API; it is not
87+
backwards-compatible with 1.0, but the new 2.0 APIs are more appropriate to deal
88+
with modern CSS.
89+
90+
NSAC 2.0 no longer inherits from stuff in the org.w3c.css.sac package (provided
91+
by the -not needed anymore- sac.jar file) but is an independent API, with its
92+
methods and features being sort of an hybrid between the old SAC and newer code.
93+
Some interfaces have changed significantly, and the usage of the InputSource
94+
class was reduced and is discouraged (a Reader is being used instead).
95+
96+
Of course this means that other SAC parsers are not supported, which may seem a
97+
loss of flexibility. However, the other parsers are stuck with CSS2 (or partial
98+
support for CSS3) and weren't really usable for real-world sheets. Without the
99+
need to support other SAC parsers, code can be cleaner and is less error-prone
100+
(other parser projects would be welcome to implement NSAC 2 if they wanted to).
101+
102+
The new Value API still uses the interface names CSSValue and CSSPrimitiveValue
103+
but adds others like CSSTypedValue. In the end, its usage is somewhat different
104+
to the old (and deprecated) W3C CSSValue API, requiring almost no type casts to
105+
obtain information to make decisions about value handling (type casts are only
106+
required when retrieving the actual encapsulated value). The categorization of
107+
values is different, and the dimension units are shared with NSAC 2.0 from a
108+
common source interface. But some methods have names similar to the old API to
109+
ease the transition (for example I keep getCssValueType() to retrieve the value
110+
category, instead of a more proper getCategory()).
111+
112+
The extended CSS interfaces in 1.0 ('css' and 'nsac' packages) have now adopted
113+
the names of the interfaces that they were extending, due to the fact that they
114+
are no longer an extension but a full fork. This means that if you are using
115+
interfaces prefixed with 'Extended' or having the '2' suffix from those 'css'
116+
and 'nsac' packages, you need to remove that prefix/suffix to begin the upgrade,
117+
and then use the interfaces from css4j instead of the old W3C ones. Note that
118+
this is only for the CSS interfaces, so the 'Extended'-prefixed interfaces in
119+
the 'doc.dom' package were not changed.
120+
121+
SAC/NSAC 1.x users need to look closely at the new CSSHandler interface, and to
122+
the changes in LexicalUnit; the rest of the API changes should be easy to apply.
123+
The type identifiers in 2.0 use enumerations instead of integers (CSS unit
124+
identifiers are now separate from type identifiers and are still integer).
125+
126+
If you are using the CSSValue API, the upgrade is non-trivial and you should
127+
look at the new interfaces. In many cases where you were using the
128+
CSSPrimitiveValue interface, you should be using the new CSSTypedValue, although
129+
sometimes the renewed CSSValue type may be all that you need.
130+
131+
For example, calls to CSSPrimitiveValue.getRGBColorValue() should be changed to
132+
CSSTypedValue.toRGBColorValue(), but be sure that the type is a COLOR value in
133+
the RGB space before trying to edit the color (and you can use
134+
RGBColorValue.getRGBColorValue() to access the RGBAColor object).
135+
136+
DOM4J users should be aware that the document factory no longer automatically
137+
loads a default User Agent sheet. This backwards-incompatible change may seem
138+
gratuitous, but the old behaviour has shown to be problematic for users.
139+
140+
Finally, the source-level compatibility is now for Java SE version 8 instead of
141+
7: be sure that you are able to use Java 8 or higher.

0 commit comments

Comments
 (0)