package.html revision b72c5c2e5482cf10117b2b25f642f7616b2326c3
1<body> 2This package contains interfaces and classes for processing class files from 3the <code>{@link proguard.classfile proguard.classfile}</code> package using 4the <i>visitor pattern</i>. Cfr., for instance, "Design Patterns, Elements of 5Reusable OO Software", by Gamma, Helm, Johnson, and Vlissider. 6<p> 7Why the visitor pattern? Class files frequently contain lists of elements of 8various mixed types: class items, constant pool entries, attributes,... 9These lists and types are largely fixed; they won't change much in future 10releases of the Java class file specifications. On the other hand, the kinds 11of operations that we may wish to perform on the class files may change and 12expand. We want to separate the objects and the operations performed upon them. 13This is a good place to use the visitor pattern. 14<p> 15Visitor interfaces avoid having to do series of <code>instanceof</code> tests 16on the elements of a list, followed by type casts and the proper operations. 17Every list element is a visitor accepter. When its <code>accept</code> method 18is called by a visitor, it calls its corresponding <code>visitX</code> method 19in the visitor, passing itself as an argument. This technique is called 20double-dispatch. 21<p> 22As already mentioned, the main advantage is avoiding lots of 23<code>instanceof</code> tests and type casts. Also, implementing a visitor 24interface ensures you're handling all possible visitor accepter types. Each 25type has its own method, which you simply have to implement. 26<p> 27A disadvantage is that the visitor methods always get the same names, specified 28by the visitor interface. These names aren't descriptive at all, making code 29harder to read. It's the visitor classes that describe the operations now. 30<p> 31Also, the visitor methods always have the same parameters and return values, as 32specified by the visitor interfaces. Passing additional parameters is done by 33means of extra fields in the visitor, which is somewhat of a kludge. 34<p> 35Because objects (the visitor accepters) and the operations performed upon them 36(the visitors) are now separated, it becomes harder to associate some state 37with the objects. For convenience, we always provide an extra <i>visitor 38info</i> field in visitor accepters, in which visitors can put any temporary 39information they want. 40</body> 41