[AXIOM-387] Deprecate getChildrenWithName and introduce a replacement method

• Type: Task
• Status: Resolved
• Priority: Minor
• Resolution: Won't Fix
• Component/s: API
• Assignee: Unassigned
• Reporter: Andreas Veithen
• Created: 05/Sep/11 09:34
• Updated: 20/Feb/16 15:51
• Resolved: 20/Feb/16 15:51

Description

The behavior of OMElement#getChildrenWithName is somewhat ill defined for QNames without namespace. In earlier Axiom versions, for such QNames, the returned iterator would only match the local name and return child elements with any namespace. This was changed in r522259, but the legacy behavior was later restored by AXIOM-11 to avoid breaking existing code. However, this legacy behavior is only supported by LLOM. DOOM always uses strict QName matching. It should also be noted that none of this is properly documented in the Javadoc of the getChildrenWithName method.

To enable us to eventually get rid of this legacy code, we should

(1) deprecate OMElement#getChildrenWithName
(2) introduce a replacement method (getChildrenWithQName) with a well defined behavior (i.e. that always uses strict QName matching)
(3) update the documentation to recommend users to migrate to getChildrenWithQName or getChildrenWithLocalName depending on the use case