Package org.apache.wiki.parser

# Class LinkParser

java.lang.Object
org.apache.wiki.parser.LinkParser

public class LinkParser extends Object
Parses JSPWiki-style "augmented" link markup into a Link object containing the link text, link reference, and any optional link attributes (as JDOM Attributes).

The parser recognizes three link forms:

1. `[Text]`
2. `[Text | Link]`
3. `[Text | Link | attributes]`

where the attributes are space-delimited, each in the form of

          name1='value1' name2='value2' name3='value3' (etc.)

If the attribute parsing fails, the parser will still return the basic link, writing a warning to the log.

### Permitted Attributes

Attributes that aren't declared on `<a>` or those that permit scripting in HTML (as this is a security risk) are ignored and have no effect on parsing, nor show up in the resulting attribute list). The 'href' and 'name' attributes are also ignored as spurious. The permitted list is: 'accesskey', 'charset', 'class', 'hreflang', 'id', 'lang', 'dir', 'rel', 'rev', 'style' , 'tabindex', 'target' , 'title', and 'type'. The declared attributes that will be ignored are: 'href', 'name', 'shape', 'coords', 'onfocus', 'onblur', or any of the other 'on*' event attributes.

The permitted attributes and target attribute values are static String arrays (`PERMITTED_ATTRIBUTES` and `PERMITTED_TARGET_VALUES` resp.) that could be compile-time modified (i.e., predeclared).

### Permitted Values on Target Attribute

The following target names are reserved in HTML 4 and have special meanings. These are the only values permitted by the parser.

_blank
  The user agent should load the designated document in a new, unnamed window.
_self
  The user agent should load the document in the same frame as the element that refers to this target.
_parent
  The user agent should load the document into the immediate FRAMESET parent of the current frame. This value is equivalent to _self if the current frame has no parent.
_top
  The user agent should load the document into the full, original window (thus canceling all other frames). This value is equivalent to _self if the current frame has no parent.

### Returned Value

This returns a Link object, a public inner class with methods:

- `getText()` returns the link text.
- `getReference()` returns the link reference value.
- `attributeCount()` returns the number of declared attributes.
- `getAttributes()` returns an iterator over any validated XHTML-compliant attributes, returned as JDOM Attributes.

The `attributeCount()` method can be used to circumvent calling `getAttributes()`, which will create an empty Iterator rather than return a null.

### Example: Link Form 1

From an incoming wikitext link of:

         [Acme]

returns:

        getText():         "Acme"
        getReference():    "Acme"
        attributeCount():  0
        getAttributes():   an empty Iterator

### Example: Link Form 2

From an incoming wikitext link of:

         [Acme | http://www.acme.com/]

returns:

        getText():         "Acme"
        getReference():    "http://www.acme.com/"
        attributeCount():  0
        getAttributes():   an empty Iterator

### Example: Link Form 3

From an incoming wikitext link of:

        [Acme | http://www.acme.com/ | id='foo' rel='Next']

returns:

        getText():         "Acme"
        getReference():    "http://www.acme.com/"
        attributeCount():  2
        getAttributes():   an Iterator containing:
          JDOM Attribute:  id="foo"
          JDOM Attribute:  rel="Next"

Since:
  2.5.10

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`LinkParser.Link`
Inner class serving as a struct containing the parsed components of a link.

## Constructor Summary

Constructors
Constructor
Description
`LinkParser()`

## Method Summary

Modifier and Type
Method
Description
`static final boolean`
`isSpace(char c)`
Returns true if char `c` is a member of `S` (space) [XML 1.1 production 3].
`static final boolean`
`isSpace(String s)`
Returns true if the String `s` is completely composed of whitespace.
`LinkParser.Link`
`parse(String linktext)`
Processes incoming link text, separating out the link text, the link URI, and then any specified attributes.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### LinkParser

public LinkParser()

## Method Details

### parse

public LinkParser.Link parse(String linktext) throws ParseException
Processes incoming link text, separating out the link text, the link URI, and then any specified attributes.

Parameters:
  `linktext` - the wiki link text to be parsed
Returns:
  a Link object containing the link text, reference, and any valid Attributes
Throws:
  `ParseException` - if the parameter is null

### isSpace

public static final boolean isSpace(String s)
Returns true if the String `s` is completely composed of whitespace.

Parameters:
  `s` - The string to check
Returns:
  True, if "s" is all XML whitespace.

### isSpace

public static final boolean isSpace(char c)
Returns true if char `c` is a member of `S` (space) [XML 1.1 production 3].

Parameters:
  `c` - Character to check.
Returns:
  True, if the character is an XML space.