Collect this node and its child nodes (if-applicable) into the collection parameter, provided the node satisfies the filtering criteria.
This mechanism allows powerful filtering code to be written very easily, without bothering about collection of embedded tags separately. e.g. when we try to get all the links on a page, it is not possible to get it at the top-level, as many tags (like form tags), can contain links embedded in them. We could get the links out by checking if the current node is a form tag, and going through its contents. However, this ties us down to specific tags, and is not a very clean approach.
Using collectInto(), programs get a lot shorter. Now, the code to extract all links from a page would look like :
NodeList collectionList = new NodeList(); Node node; String filter = LinkTag.LINK_TAG_FILTER; for (NodeIterator e = parser.elements(); e.hasMoreNodes();) { node = e.nextNode(); node.collectInto (collectionVector, filter); } Thus, collectionList will hold all the link nodes, irrespective of how deep the links are embedded. This of course implies that tags must fulfill their responsibilities toward honouring certain filters.
Important: In order to keep performance optimal,
do not create you own filter strings, as the internal matching occurs with the pre-existing filter string object (in the relevant class). i.e. do not make calls like :
collectInto(collectionList,"-l"), instead, make calls only like :
collectInto(collectionList,LinkTag.LINK_TAG_FILTER).
To find out if your desired tag has filtering support, check the API of the tag.