org.apache.maven.doxia.util

Class DoxiaUtils

java.lang.Object

org.apache.maven.doxia.util.DoxiaUtils

public class DoxiaUtils
extends java.lang.Object

General Doxia utility methods. The methods in this class should not assume any specific Doxia module or document format.

Since:

1.1

Version:

$Id: DoxiaUtils.java 1726411 2016-01-23 16:34:09Z hboutemy $

Field Summary

Fields

Modifier and Type	Field and Description
private static java.text.ParsePosition	DATE_PARSE_POSITION
private static java.text.SimpleDateFormat	DATE_PARSER
private static java.lang.String[]	DATE_PATTERNS
private static int	MINUS_ONE

Constructor Summary

Constructors

Modifier	Constructor and Description
private	DoxiaUtils()

Method Summary

Modifier and Type	Method and Description
static java.lang.String	byteToHex(byte b) Convert a byte to it's hexadecimal equivalent.
static java.lang.String	encodeId(java.lang.String id) Construct a valid Doxia id.
static java.lang.String	encodeId(java.lang.String id, boolean chop) Construct a valid Doxia id.
static javax.swing.text.MutableAttributeSet	getImageAttributes(java.lang.String logo) Determine width and height of an image.
private static boolean	isAsciiDigit(char c)
private static boolean	isAsciiLetter(char c)
static boolean	isExternalLink(java.lang.String link) Checks if the given string corresponds to an external URI, ie is not a link within the same document nor a relative link to another document (a local link) of the same site.
static boolean	isInternalLink(java.lang.String link) Checks if the given string corresponds to an internal link, ie it is a link to an anchor within the same document.
static boolean	isLocalLink(java.lang.String link) Checks if the given string corresponds to a relative link to another document within the same site, ie it is neither an internal nor an external link.
static boolean	isValidId(java.lang.String text) Determines if the specified text is a valid id according to the rules laid out in encodeId(String).
static java.util.Date	parseDate(java.lang.String str) Parses a string representing a date by trying different date patterns.

Methods inherited from class java.lang.Object

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

Field Detail

MINUS_ONE

private static final int MINUS_ONE

See Also:

Constant Field Values

DATE_PARSER

private static final java.text.SimpleDateFormat DATE_PARSER

DATE_PARSE_POSITION

private static final java.text.ParsePosition DATE_PARSE_POSITION

DATE_PATTERNS

private static final java.lang.String[] DATE_PATTERNS

Constructor Detail

DoxiaUtils

private DoxiaUtils()

Method Detail

isInternalLink

public static boolean isInternalLink(java.lang.String link)

Checks if the given string corresponds to an internal link, ie it is a link to an anchor within the same document. If link is not null, then exactly one of the three methods isInternalLink(java.lang.String), isExternalLink(java.lang.String) and isLocalLink(java.lang.String) will return true.

Parameters:

link - The link to check. Not null.

Returns:

True if the link starts with "#".

Throws:

java.lang.NullPointerException - if link is null.

See Also:

isExternalLink(String), isLocalLink(String)

isExternalLink

public static boolean isExternalLink(java.lang.String link)

Checks if the given string corresponds to an external URI, ie is not a link within the same document nor a relative link to another document (a local link) of the same site. If link is not null, then exactly one of the three methods isInternalLink(java.lang.String), isExternalLink(java.lang.String) and isLocalLink(java.lang.String) will return true.

Parameters:

link - The link to check. Not null.

Returns:

True if the link (ignoring case) starts with either "http:/", "https:/", "ftp:/", "mailto:", "file:/", or contains the string "://". Note that Windows style separators "\" are not allowed for URIs, see http://www.ietf.org/rfc/rfc2396.txt , section 2.4.3.

Throws:

java.lang.NullPointerException - if link is null.

See Also:

isInternalLink(String), isLocalLink(String)

isLocalLink

public static boolean isLocalLink(java.lang.String link)

Checks if the given string corresponds to a relative link to another document within the same site, ie it is neither an internal nor an external link. If link is not null, then exactly one of the three methods isInternalLink(java.lang.String), isExternalLink(java.lang.String) and isLocalLink(java.lang.String) will return true.

Parameters:

link - The link to check. Not null.

Returns:

True if the link is neither an external nor an internal link.

Throws:

java.lang.NullPointerException - if link is null.

See Also:

isExternalLink(String), isInternalLink(String)

encodeId

public static java.lang.String encodeId(java.lang.String id)

Construct a valid Doxia id.

This method is equivalent to encodeId( id, false ).

Parameters:

id - The id to be encoded. May be null in which case null is returned.

Returns:

The trimmed and encoded id, or null if id is null.

See Also:

encodeId(java.lang.String, boolean)

encodeId

public static java.lang.String encodeId(java.lang.String id,
                                        boolean chop)

Construct a valid Doxia id.

A valid Doxia id obeys the same constraints as an HTML ID or NAME token. According to the HTML 4.01 specification section 6.2 SGML basic types:

ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods (".").

According to XHTML 1.0 section C.8. Fragment Identifiers:

When defining fragment identifiers to be backward-compatible, only strings matching the pattern [A-Za-z][A-Za-z0-9:_.-]* should be used.

To achieve this we need to convert the id String. Two conversions are necessary and one is done to get prettier ids:

1. Remove whitespace at the start and end before starting to process
2. If the first character is not a letter, prepend the id with the letter 'a'
3. Any spaces are replaced with an underscore '_'
4. Any characters not matching the above pattern are either dropped, or replaced according to the rules specified in the HTML specs.

For letters, the case is preserved in the conversion.

Here are some examples:

 DoxiaUtils.encodeId( null )        = null
 DoxiaUtils.encodeId( "" )          = "a"
 DoxiaUtils.encodeId( "  " )        = "a"
 DoxiaUtils.encodeId( " _ " )       = "a_"
 DoxiaUtils.encodeId( "1" )         = "a1"
 DoxiaUtils.encodeId( "1anchor" )   = "a1anchor"
 DoxiaUtils.encodeId( "_anchor" )   = "a_anchor"
 DoxiaUtils.encodeId( "a b-c123 " ) = "a_b-c123"
 DoxiaUtils.encodeId( "   anchor" ) = "anchor"
 DoxiaUtils.encodeId( "myAnchor" )  = "myAnchor"
 

Parameters:

id - The id to be encoded. May be null in which case null is returned.

chop - true if non-ASCII characters should be ignored. If false, any non-ASCII characters will be replaced as specified above.

Returns:

The trimmed and encoded id, or null if id is null. If id is not null, the return value is guaranteed to be a valid Doxia id.

Since:

1.1.1

See Also:

isValidId(java.lang.String)

byteToHex

public static java.lang.String byteToHex(byte b)

Convert a byte to it's hexadecimal equivalent.

Parameters:

b - the byte value.

Returns:

the result of Integer.toHexString( b & 0xFF ).

Since:

1.1.1

isValidId

public static boolean isValidId(java.lang.String text)

Determines if the specified text is a valid id according to the rules laid out in encodeId(String).

Parameters:

text - The text to be tested. May be null in which case false is returned.

Returns:

true if the text is a valid id, otherwise false.

See Also:

encodeId(String)

parseDate

public static java.util.Date parseDate(java.lang.String str)
                                throws java.text.ParseException

Parses a string representing a date by trying different date patterns.

The following date patterns are tried (in the given order):

"yyyy-MM-dd", "yyyy/MM/dd", "yyyyMMdd", "yyyy", "dd.MM.yyyy", "dd MMM yyyy",
  "dd MMM. yyyy", "MMMM yyyy", "MMM. dd, yyyy", "MMM. yyyy", "MMMM dd, yyyy",
  "MMM d, ''yy", "MMM. ''yy", "MMMM ''yy"

A parse is only sucessful if it parses the whole of the input string. If no parse patterns match, a ParseException is thrown.

As a special case, the strings "today" and "now" (ignoring case) return the current date.

Parameters:

str - the date to parse, not null.

Returns:

the parsed date, or the current date if the input String (ignoring case) was "today" or "now".

Throws:

java.text.ParseException - if no pattern matches.

java.lang.NullPointerException - if str is null.

Since:

1.1.1.

isAsciiLetter

private static boolean isAsciiLetter(char c)

isAsciiDigit

private static boolean isAsciiDigit(char c)

getImageAttributes

public static javax.swing.text.MutableAttributeSet getImageAttributes(java.lang.String logo)
                                                               throws java.io.IOException

Determine width and height of an image. If successful, the returned SinkEventAttributes contain width and height attribute keys whose values are the width and height of the image (as a String).

Parameters:

logo - a String containing either a URL or a path to an image file. Not null.

Returns:

a set of SinkEventAttributes, or null if no ImageReader was found to read the image.

Throws:

java.io.IOException - if an error occurs during reading.

java.lang.NullPointerException - if logo is null.

Since:

1.1.1