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

[Michael Wechner]

Guillaume Déflache wrote:
> 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

sounds very reasonable to me. Thanks very much for this information. 
Will try to improve it shortly.

Cheers

Michi