Causes the this segment to be ignored when parsing.
Ignored segments are treated as blank spaces by the parsing mechanism, but are included as normal text in all other functions.
This method was originally the only means of preventing
TagType#isServerTag() located inside
StartTagType#NORMAL tags from interfering with the parsing of the tags
(such as where an
Attribute of a normal tag uses a server tag to dynamically set its value),
as well as preventing non-server tags from being recognised inside server tags.
It is not necessary to use this method to ignore
TagType#isServerTag() located inside normal tags,
as the attributes parser automatically ignores any server tags.
It is not necessary to use this method to ignore non-server tags inside server tags, or the contents of
HTMLElementName#SCRIPT elements,
as the parser does this automatically when performing a
Source#fullSequentialParse().
This leaves only very few scenarios where calling this method still provides a significant benefit.
One such case is where XML-style server tags are used inside
StartTagType#NORMAL tags.
Here is an example using an XML-style JSP tag:
<a href="<i18n:resource path="/Portal"/>?BACK=TRUE">back</a>
The first double-quote of
"/Portal"
will be interpreted as the end quote for the
href
attribute,
as there is no way for the parser to recognise the
il8n:resource
element as a server tag.
Such use of XML-style server tags inside
StartTagType#NORMAL tags is generally seen as bad practice,
but it is nevertheless valid JSP. The only way to ensure that this library is able to parse the normal tag surrounding it is to
find these server tags first and call the
ignoreWhenParsing
method to ignore them before parsing the rest of the document.
It is important to understand the difference between ignoring the segment when parsing and removing the segment completely.
Any text inside a segment that is ignored when parsing is treated by most functions as content, and as such is included in the output of
tools such as
TextExtractor and
Renderer.
To remove segments completely, create an
OutputDocument and call its
OutputDocument#remove(Segment) or
OutputDocument#replaceWithSpaces(int,int) method for each segment.
Then create a new source document using
Source#Source(CharSequence)and perform the desired operations on this new source object.
Calling this method after the
Source#fullSequentialParse() method has been called is not permitted and throws an IllegalStateException
.
Any tags appearing in this segment that are found before this method is called will remain in the
Source#getCacheDebugInfo(),
and so will continue to be found by the tag search methods.
If this is undesirable, the
Source#clearCache() method can be called to remove them from the cache.
Calling the
Source#fullSequentialParse() method after this method clears the cache automatically.
For best performance, this method should be called on all segments that need to be ignored without calling
any of the tag search methods in between.