DocumentFieldParser (Orchid 1.1.1 API)

All Known Implementing Classes:

DocumentFieldParserImpl
```
public interface DocumentFieldParser
```
This helper class is used by document parsing classes to extract individual fields from a directory document. The DocumentFieldParser also manages the InputStream which is the source of the document to parse. Parsing classes are implemented by creating an instance of the DocumentParsingHandler interface.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`int`	`argumentsRemaining()` Returns the number of unprocessed argument items on the current keyword line.
`void`	`endSignedEntity()` Set the current keyword line as the last line included in the current signature hash.
`String`	`getCurrentKeyword()` Return the keyword of the current keyword line.
`String`	`getRawDocument()` Return all lines from the current document as a single String.
`TorMessageDigest`	`getSignatureMessageDigest()` Return the internal message digest which is being used to calculate the signature over the current document.
`TorMessageDigest`	`getSignatureMessageDigest256()`
`void`	`logDebug(String message)` Log the specified message at the debug logging level.
`void`	`logError(String message)` Log the specified message at the error logging level.
`void`	`logWarn(String message)` Log the specified message at the warn logging level.
`IPv4Address`	`parseAddress()` Extract the next argument and interpret it as an IPv4 network address in dotted quad notation.
`HexDigest`	`parseBase32Digest()` Extract the next argument and interpret it as a base 32 encoded digest string.
`byte[]`	`parseBase64Data()` Extract the next argument and interpret it as Base64 encoded binary data.
`boolean`	`parseBoolean()` Extract the next argument and interpret it as an integer boolean value.
`String`	`parseConcatenatedString()` Take all remaining arguments on the current keyword line and return them as a single space delimited String.
`HexDigest`	`parseFingerprint()` Extract all remaining arguments and interpret the concatenated string as a hex encoded fingerprint string.
`HexDigest`	`parseHexDigest()` Extract the next argument and interpret it as a hex encoded digest string.
`int`	`parseInteger()` Extract the next argument and interpret it as an integer.
`int`	`parseInteger(String item)` Parse the `item` argument as an integer.
`int[]`	`parseIntegerList()` Extract the next argument and interpret it as a comma separated list of integers.
`String`	`parseNickname()` Extract the next argument item and return it as a `String` if it conforms to a legally formed router nickname (dir-spec.txt section 2.3).
`byte[]`	`parseNtorPublicKey()`
`DocumentObject`	`parseObject()` Extract a document object following the current keyword line and don't attempt to interpret it further.
`NameIntegerParameter`	`parseParameter()`
`int`	`parsePort()` Extract the next argument and interpret it as a network port value.
`int`	`parsePort(String item)` Parse the `item` arguement as a network port value.
`TorPublicKey`	`parsePublicKey()` Extract a document object following the current keyword line and interpret it as a PEM encoded public key.
`TorSignature`	`parseSignature()` Extract a document object following the current keyword line and interpret it as a Base64 encoded PKCS1 signature object.
`String`	`parseString()` Extract the next argument item and return it as a String
`Timestamp`	`parseTimestamp()` Extract the next two arguments and parse as a timestamp field.
`void`	`processDocument()` Run the document parser.
`void`	`resetRawDocument()` Empty the internal buffer which is capturing the raw data from the document which is being parsed.
`void`	`resetRawDocument(String initialContent)` Empty the internal buffer which is capturing raw data from document being parsed and set buffer contents to `initalContent`.
`void`	`setDelimiter(String delimeter)` The default delimiter between keyword line tokens is any whitespace.
`void`	`setHandler(DocumentParsingHandler handler)` Set the callback handler which is used to process the document.
`void`	`setRecognizeOpt()` Set a flag so that 'opt' tokens will be recognized at the start of keyword lines.
`void`	`setSignatureIgnoreToken(String token)` Tells the parser to not include lines that begin with `token` in the current signature calculation.
`void`	`startSignedEntity()` Reset the document signing state.
`void`	`verifyExpectedArgumentCount(String keyword, int argumentCount)` Test that the current keyword line has the correct number of arguments.
`boolean`	`verifySignedEntity(TorPublicKey publicKey, TorSignature signature)` Verify that current signature hash matches the specified `signature` signed with the public key `publicKey`

- Method Detail
  - processDocument
```
void processDocument()
```
    Run the document parser. The setHandler(DocumentParsingHandler) method must be called before calling this method to set a DocumentParsingHandler for processing this document.
    
    Throws:
    
    TorParsingException - If a parsing error occurs while processing the document.
  - argumentsRemaining
```
int argumentsRemaining()
```
    Returns the number of unprocessed argument items on the current keyword line.
    
    Returns:
    
    The number of remaining arguments.
  - parseString
```
String parseString()
```
    Extract the next argument item and return it as a String
    
    Returns:
    
    The next argument as a String
    
    Throws:
    
    TorParsingException - If no arguments are remaining on the current keyword line.
  - parseConcatenatedString
```
String parseConcatenatedString()
```
    Take all remaining arguments on the current keyword line and return them as a single space delimited String. If no arguments are remaining, then an empty String is returned.
    
    Returns:
    
    The remaining arguments on the current keyword line concatenated together.
  - parseBoolean
```
boolean parseBoolean()
```
    Extract the next argument and interpret it as an integer boolean value. The legal values are '1' for true or '0' for false.
    
    Returns:
    
    Return the next argument interpreted as a boolean value.
    
    Throws:
    
    TorParsingException - If no arguments are remaining or if the current argument cannot be parsed as a boolean integer value.
  - parseNickname
```
String parseNickname()
```
    Extract the next argument item and return it as a String if it conforms to a legally formed router nickname (dir-spec.txt section 2.3). A router nickname must be between 1 and 19 alphanumeric characters ([A-Za-z0-9]) to be considered valid.
    
    Returns:
    
    The next argument as a String if it is a validly formatted nickname.
    
    Throws:
    
    TorParsingException - If no arguments are remaining or if the current argument is not a valid router nickname.
  - parseInteger
```
int parseInteger()
```
    Extract the next argument and interpret it as an integer.
    
    Returns:
    
    The next argument interpreted as an integer.
    
    Throws:
    
    TorParsingException - If no arguments are remaining or if the current argument cannot be parsed as an integer value.
  - parseInteger
```
int parseInteger(String item)
```
    Parse the item argument as an integer.
    
    Parameters:
    
    item - A string to parse as an integer.
    
    Returns:
    
    The integer value of the item argument.
    
    Throws:
    
    TorParsingException - If the item argument cannot be parsed as an integer value.
  - parseIntegerList
```
int[] parseIntegerList()
```
    Extract the next argument and interpret it as a comma separated list of integers.
    
    Returns:
    
    An array of integers.
    
    Throws:
    
    TorParsingException - If no arguments are remaining or if the current argument cannot be parsed as a list of integers.
  - parsePort
```
int parsePort()
```
    Extract the next argument and interpret it as a network port value. A valid port value is an integer between 0 and 65535 inclusive.
    
    Returns:
    
    The next argument interpreted as an integer port value.
    
    Throws:
    
    TorParsingException - If no arguments are remaining or if the current argument cannot be parsed as a legal port value.
  - parsePort
```
int parsePort(String item)
```
    Parse the item arguement as a network port value. A valid port value is an integer between 0 and 65535 inclusive.
    
    Parameters:
    
    item - A string to parse as an integer port value.
    
    Returns:
    
    The port integer value of the item argument
    
    Throws:
    
    TorParsingException - If the item argument cannot be parsed as a legal port value.
  - parseBase64Data
```
byte[] parseBase64Data()
```
    Extract the next argument and interpret it as Base64 encoded binary data.
    
    Returns:
    
    The bytes decoded from the Base64 encoded argument.
    
    Throws:
    
    TorParsingException - If no arguments are remaining or if the current argument cannot be parsed as Base64 encoded data.
  - parseTimestamp
```
Timestamp parseTimestamp()
```
    Extract the next two arguments and parse as a timestamp field. The format of a timestamp is: YYYY-MM-DD HH:MM:SS
    
    Returns:
    
    The parsed Timestamp value.
    
    Throws:
    
    TorParsingException - If there are not sufficient arguments remaining or if the current arguments could not be parsed as a timestamp field.
  - parseHexDigest
```
HexDigest parseHexDigest()
```
    Extract the next argument and interpret it as a hex encoded digest string.
    
    Returns:
    
    The parsed HexDigest value.
    
    Throws:
    
    TorParsingException - If no arguments are remaining or if the current argument cannot be parsed as a hex encoded digest string.
  - parseBase32Digest
```
HexDigest parseBase32Digest()
```
    Extract the next argument and interpret it as a base 32 encoded digest string.
    
    Returns:
    
    The parsed HexDigest value.
    
    Throws:
    
    TorParsingException - If no arguments are remaining or if the current argument cannot be parsed as a base 32 encoded digest string.
  - parseFingerprint
```
HexDigest parseFingerprint()
```
    Extract all remaining arguments and interpret the concatenated string as a hex encoded fingerprint string.
    
    Returns:
    
    The parsed HexDigest value extracted from the concatenated string.
    
    Throws:
    
    TorParsingException - If the concatenation of the remaining arguments could not be parsed as a hex encoded fingerprint string.
  - parseAddress
```
IPv4Address parseAddress()
```
    Extract the next argument and interpret it as an IPv4 network address in dotted quad notation.
    
    Returns:
    
    The parsed IPv4Address value.
    
    Throws:
    
    TorParsingException - If no arguments are remaining or if the current argument cannot be parsed as an IPv4 network address.
  - parsePublicKey
```
TorPublicKey parsePublicKey()
```
    Extract a document object following the current keyword line and interpret it as a PEM encoded public key.
    
    Returns:
    
    The extracted TorPublicKey value.
    
    Throws:
    
    TorParsingException - If no document object is found following the current keyword line, or if the document object cannot be parsed as a PEM encoded public key.
  - parseNtorPublicKey
```
byte[] parseNtorPublicKey()
```
  - parseSignature
```
TorSignature parseSignature()
```
    Extract a document object following the current keyword line and interpret it as a Base64 encoded PKCS1 signature object.
    
    Returns:
    
    The extracted TorSignature value.
    
    Throws:
    
    TorParsingException - If no document object is found following the current keyword line, or if the document object cannot be parsed as a signature.
  - parseObject
```
DocumentObject parseObject()
```
    Extract a document object following the current keyword line and don't attempt to interpret it further.
    
    Returns:
    
    The extracted DocumentObject.
    
    Throws:
    
    TorParsingException - If no document object is found following the current keyword line.
  - parseParameter
```
NameIntegerParameter parseParameter()
```
    Returns:
  - getCurrentKeyword
```
String getCurrentKeyword()
```
    Return the keyword of the current keyword line. The keyword is the first token on the line unless the first token is 'opt' and 'opt' recognition is enabled. In this case, the keyword is the token immediately following the 'opt' token.
    
    Returns:
    
    The keyword token of the current keyword line.
  - getRawDocument
```
String getRawDocument()
```
    Return all lines from the current document as a single String.
    
    Returns:
    
    The raw data from the current document.
  - resetRawDocument
```
void resetRawDocument()
```
    Empty the internal buffer which is capturing the raw data from the document which is being parsed.
  - resetRawDocument
```
void resetRawDocument(String initialContent)
```
    Empty the internal buffer which is capturing raw data from document being parsed and set buffer contents to initalContent.
    
    Parameters:
    
    initialContent - Initial raw document content.
  - startSignedEntity
```
void startSignedEntity()
```
    Reset the document signing state. Any lines read after calling this method will be included in the current signature hash.
  - endSignedEntity
```
void endSignedEntity()
```
    Set the current keyword line as the last line included in the current signature hash.
  - setSignatureIgnoreToken
```
void setSignatureIgnoreToken(String token)
```
    Tells the parser to not include lines that begin with token in the current signature calculation.
    
    Parameters:
    
    token - The parser will not include lines that begin with token in the current signature.
  - getSignatureMessageDigest
```
TorMessageDigest getSignatureMessageDigest()
```
    Return the internal message digest which is being used to calculate the signature over the current document.
    
    Returns:
    
    The TorMessageDigest instance or null if a signature is not being actively calculated.
  - getSignatureMessageDigest256
```
TorMessageDigest getSignatureMessageDigest256()
```
  - verifySignedEntity
```
boolean verifySignedEntity(TorPublicKey publicKey,
                           TorSignature signature)
```
    Verify that current signature hash matches the specified signature signed with the public key publicKey
    
    Parameters:
    
    publicKey - The public key used to verify the signature.
    
    signature - The signature to verify against the current signature hash.
    
    Returns:
    
    trueIf the signature argument matches the hash currently calculated document hash.
  - verifyExpectedArgumentCount
```
void verifyExpectedArgumentCount(String keyword,
                                 int argumentCount)
```
    Test that the current keyword line has the correct number of arguments.
    
    Parameters:
    
    keyword - The name of the current keyword. (used for errors)
    
    argumentCount - The expected number of arguments.
    
    Throws:
    
    TorParsingException - If the number of remaining arguments does not match argumentCount.
  - setRecognizeOpt
```
void setRecognizeOpt()
```
    Set a flag so that 'opt' tokens will be recognized at the start of keyword lines. If this flag is set, a token string 'opt' at the start of a keyword line will be ignored and the token following the 'opt' string will be interpreted as the keyword.
  - setDelimiter
```
void setDelimiter(String delimeter)
```
    The default delimiter between keyword line tokens is any whitespace. This method may be called to specify a different delimiter policy.
    
    Parameters:
    
    delimeter - A regular expression which matches the desired delimiter.
  - setHandler
```
void setHandler(DocumentParsingHandler handler)
```
    Set the callback handler which is used to process the document. This method must be called before calling processDocument().
    
    Parameters:
    
    handler - The callback handler.
  - logDebug
```
void logDebug(String message)
```
    Log the specified message at the debug logging level.
    
    Parameters:
    
    message - The message to log.
  - logWarn
```
void logWarn(String message)
```
    Log the specified message at the warn logging level.
    
    Parameters:
    
    message - The message to log.
  - logError
```
void logError(String message)
```
    Log the specified message at the error logging level.
    
    Parameters:
    
    message - The message to log.

Interface DocumentFieldParser

Method Summary

Method Detail

processDocument

argumentsRemaining

parseString

parseConcatenatedString

parseBoolean

parseNickname

parseInteger

parseInteger

parseIntegerList

parsePort

parsePort

parseBase64Data

parseTimestamp

parseHexDigest

parseBase32Digest

parseFingerprint

parseAddress

parsePublicKey

parseNtorPublicKey

parseSignature

parseObject

parseParameter

getCurrentKeyword

getRawDocument

resetRawDocument

resetRawDocument

startSignedEntity

endSignedEntity

setSignatureIgnoreToken

getSignatureMessageDigest

getSignatureMessageDigest256

verifySignedEntity

verifyExpectedArgumentCount

setRecognizeOpt

setDelimiter

setHandler

logDebug

logWarn

logError