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