Access to external links

The following properties can be used to configure the way external links are accessed during the generation:

• checkLinks: to specify that the presence of all external links must be checked (default is true)
• checkHTTPLinks: to specify that the presence of HTTP external links must be checked (default is true. Note that if checkLinks is false, checkHTTPLinks will be set to false regaldless on how the user has set its value
• forceHTTPLinksInvalid: set to true if you want all the HTTP links check to fail (default is false). Note that if checkHTTPLinks is false, then this property will not be used
• checkHTTPLinksThreaded specifies if HTTP links must be checked in a Thread pool (true by default)
• checkHTTPLinksTimeOut set the timeout of the Thread pool used for checking URL links with the "http" protocol, if the check is performed in background Threads
• checkHTTPLinksPool set the number of Threads in the Thread pool used for checking URL links with the "http" protocol, if the check is performed in background Threads
• "forkParser": specifies if the parsing will be performed in background threads. See also forkParser parameter for more information
• defaultHTTPTimeout set the timeout for checking the availability of an http link (300 ms by default)
• urlExceptions: specifies the XML files for which URLs won't be checked
• timeouts: specifies the XML file setting specific timeouts for URLs
• userAgent: specifies the user agent used when accessing external links
• proxy.host: specifies the host for a proxy when accessing external links
• proxy.port: specifies the port for a proxy when accessing external links
• proxy.authentication: specifies that the proxy must be authenticated (default is false)

checkHTTPLinks

The "checkHTTPLinks" property specifies that the presence of HTTP external links must be checked^[1]

for html pages, the presence of anchors if the "#" tag is found in the link construction is also checked

:

• For the a tag
• For the cite tag
• For the javadoc tag
• For the qtdoc tag
• For the doxygen tag
• For the wikipedia tag
• For the mediawiki tag

checkLinks

The "checkLinks" property specifies that the presence of all external links must be checked, regardless of the fact that they are linking to an HTTP resource or on the local network.

urlExceptions

The "urlExceptions" property specifies the XML file which will define URLs won't be checked (useful only if the "checkLinks" property is set to true).

UrlExceptions grammar

See The URLExceptions Schema.

The format of this XML file is very simple:

   <xs:element name="urlExceptions">
      <xs:complexType>
         <xs:sequence maxOccurs="unbounded" minOccurs="0">
            <xs:element ref="urlException" />
         </xs:sequence>
      </xs:complexType>
   </xs:element>
   <xs:element name="urlException">
      <xs:complexType>
         <xs:attribute name="url" type="xs:anyURI" use="required" />
      </xs:complexType>
   </xs:element>

All the children URLs of the URLs specified in this file won't be checked. It avoid to return warnings in the case where some URLs are not allowed on the Network where the docJGenerator tool is used (black list or white list).

UrlExceptions XML file example

   <urlExceptions>
      <urlException url="http://docs.oracle.com/javase/8/docs/api/" />
   </urlExceptions>

timeouts

The "urlExceptions" property specifies the XML file which will define URLs won't be checked (useful only if the "checkLinks" property is set to true).

Timeouts grammar

See The timeouts Schema.

This file specifies specific timeouts in ms for children URLs of specified URLs.

Timeouts XML file example

   <timeouts timeout="300">
      <url url="http://docs.oracle.com/javase/8/docs/api/" timeout="500" />
   </timeouts>

Here the default timeout is 300ms, but the timeout for the javadoc API website is 500ms.

userAgent

This property specifies which user agent will be send when retrieving the URLs on the Network (for http URLs).:

• The value "ie9" will set an IE9 user agent
• Other values will specify directly the user agent
• By default if not specified a Firefox 10 user agent will be assumed

Proxy

A proxy to access external URLs can be specified with the threee following properties:

• "proxy.host": specifies the host for a proxy when accessing external links
• "proxy.port": specifies the port for a proxy when accessing external links
• "proxy.authentication": specifies that the proxy must be authenticated (default is false)

Note that:

• If the "proxy.authentication" property is set, the docJGenerator will ask for a user name and password at start. These properties will be used to configure the authentication context of the tool, but won't be memorized
• The two "proxy.host" and "proxy.port" must be set to effectively use a Proxy