[Yanel-dev] SitetreeDOMImpl or rather NodeDOMImpl has an issue re isCollection

[Guillaume Déflache]

Michael Wechner schrieb:
> Guillaume Déflache wrote:
>> Hi!
>>
>> Michael Wechner schrieb:
>>>  [...]
>>> I have fixed this now by changing appendChild(Node) to 
>>> appendChild(Node, int)
>>>
>>> whereas int is for example Node.COLLECTION or Node.RESOURCE
>>
>> Why use an int instead of an enum?
> 
> because src/core/java/org/wyona/yarep/core/Node.java also uses an int 
> and to be honest I didn't think much about it ;-)
> 
> What would be the advantage of enum? (Since we broke the backwards 
> compatibility yesterday I would say we can break
> it once again today if there is a good reason to use enum)

Mainly more type safety, hence more guidance for the developer, see 
<http://java.sun.com/j2se/1.5.0/docs/guide/language/enums.html>:
> In prior releases, the standard way to represent an enumerated type was the int Enum pattern:
> 
>     // int Enum Pattern - has severe problems!
>     public static final int SEASON_WINTER = 0;
>     public static final int SEASON_SPRING = 1;
>     public static final int SEASON_SUMMER = 2;
>     public static final int SEASON_FALL   = 3;
> 
> This pattern has many problems, such as:
> 
>     * Not typesafe - Since a season is just an int you can pass in any other int value where a season is required, or add two seasons together (which makes no sense).
>     * No namespace - You must prefix constants of an int enum with a string (in this case SEASON_) to avoid collisions with other int enum types.
>     * Brittleness - Because int enums are compile-time constants, they are compiled into clients that use them. If a new constant is added between two existing constants or the order is changed, clients must be recompiled. If they are not, they will still run, but their behavior will be undefined.
>     * Printed values are uninformative - Because they are just ints, if you print one out all you get is a number, which tells you nothing about what it represents, or even what type it is. 
> 
> So when should you use enums? Any time you need a fixed set of constants. That includes natural enumerated types (like the planets, days of the week, and suits in a card deck) as well as other sets where you know all possible values at compile time, such as choices on a menu, rounding modes, command line flags, and the like. It is not necessary that the set of constants in an enum type stay fixed for all time. The feature was specifically designed to allow for binary compatible evolution of enum types. 

Also instead of C-style bitmasks to encode capabilities, e.g. if 
(VERSIONABLEV1 & MODIFIABLEV2) {...} ;) one should likewise use 
http://java.sun.com/javase/6/docs/api/java/util/EnumSet.html instead.


>> In case you wondered binary backward-compatibility rules of enums and 
>> their values are the same as those of classes and their methods, cf. 
>> http://java.sun.com/docs/books/jls/third_edition/html/binaryComp.html#78657 
>>
> 
> I am not sure I understand. Can you explain this?

To sum it up you can add new values, reorder them without breaking 
backward-compatibility.


I also stumbled upon a nice and more summarized reference: 
http://wiki.eclipse.org/Evolving_Java-based_APIs_2 (non-normative 
contrary to the Java Language Specification link given above)

The rest of the series is IMHO also a nice-to-read about the other 
aspects of compatibility:
Part I:
>     * 1 API Java Elements
>     * 2 API Prime Directive
>     * 3 Achieving API Contract Compatibility
>           o 3.1 Example 1 - Changing a method postcondition
>           o 3.2 Example 2 - Changing a method precondition
>           o 3.3 Example 3 - Changing a field invariant
>           o 3.4 Example 4 - Adding an API method
>           o 3.5 General Rules for Contract Compatibility
>     * 4 Achieving API Binary Compatibility
>     * 5 Other Notes
http://wiki.eclipse.org/Evolving_Java-based_APIs
Part III:
>     * 1.1 Data Compatibility
>     * 1.2 Standard Workarounds
>           o 1.2.1 Deprecate and Forward
>           o 1.2.2 Start over in a New Package
>           o 1.2.3 Adding an Argument
>           o 1.2.4 "2" Convention
>           o 1.2.5 COM Style
>           o 1.2.6 Making Obsolete Hook Methods Final
>     * 1.3 Defective API Specifications
>     * 1.4 A Word about Source Code Incompatibilities
>     * 1.5 Java Reflection
http://wiki.eclipse.org/Evolving_Java-based_APIs_3

HTH