Citation (org.openidentityplatform.commons.parent 2.2.3 Documentation)

java.lang.Object
- org.forgerock.maven.plugins.xcite.Citation

```
public class Citation
extends Object
```
A citation references part of a text file to quote.
The string representation includes the path to the file to cite, and optionally start and end markers to frame the text to quote.
For example, [/path/to/script.sh:# start:# end]
Notice that the example has a UNIX-style path, /path/to/script.sh, a start marker, # start, and an end marker, # end. The file, script.sh, could have text to quote between the markers. For example, script.sh might have the following content:
```
 #!/bin/bash

 # start
 wall <<EOM
     Hello world
 EOM
 # end

 exit
 
```
In this case the quote would be the following:
```
 wall <<EOM
     Hello world
 EOM
 
```
Start and end markers depend on the language of the source text. Markers should make sense to people who mark up the source text, and so they should be composed of visible characters. Markers must not include the delimiter character that is used to separate the path and the markers.
Markers either both be on the same line as the text to quote, or should be on separate lines from the text to quote. In other words, you can prepare a text to quote a single line either by adding a start marker on the line before and an end marker on the line after, or by prepending a start marker to the line before the text to quote and appending an end marker after.
The following example shows markers on separate lines.
```
 #start
 This is the text to quote.
 #end
 
```
The following example shows markers on the same line as the text to quote.
```
 #start This is the text to quote. #end
 
```
More formally, the citation string representation is as follows.
```
 citation     = "[" path delimiter start-marker delimiter end-marker "]"
 citation     / "[" path delimiter start-marker "]"
 citation     / "[" path "]"

 path         = File.getPath()                ; Depends on the OS,
                                              ; does not include delimiter

 delimiter    = ":" / "%"                     ; Default: ":"

 start-marker = 1*(VCHAR excluding delimiter) ; Depends on source language

 end-marker   = 1*(VCHAR excluding delimiter) ; Depends on source language

 
```
Most systems allow file names that can cause problems with this scheme. Working around the problem is an exercise for the reader.

Constructor Summary

Constructors
Constructor and Description
`Citation(String path)` Construct a citation from a path alone.
`Citation(String path, char delimiter, String start)` Construct a citation from a path, delimiter, and start marker, when the start marker and the end marker are the same.
`Citation(String path, char delimiter, String start, String end)` Construct a citation from a path, delimiter, start marker, and end marker.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`char`	`getDelimiter()` Returns the value of the delimiter.
`String`	`getEnd()` Returns the value of the start marker, which can be empty.
`String`	`getPath()` Returns the value of the path.
`String`	`getStart()` Returns the value of the start marker, which can be empty.
`void`	`setDelimiter(char delimiter)` Sets the value of the delimiter.
`void`	`setEnd(String end)` Sets the value of the end marker, which must not contain the delimiter.
`void`	`setPath(String path)` Sets the pathname string for the file to quote.
`void`	`setStart(String start)` Sets the value of the start marker, which must not contain the delimiter.
`String`	`toString()` Returns the string representation of this citation.
`static Citation`	`valueOf(String citation)` Returns a Citation from the string representation, assuming the default delimiter, `:`.
`static Citation`	`valueOf(String citation, String delimiter)` Returns a Citation from the string representation.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Citation
```
public Citation(String path)
```
    Construct a citation from a path alone.
    The path cannot be null.
    
    Parameters:
    
    path - The pathname string for the file to quote. Not null.
    
    Throws:
    
    IllegalArgumentException - Path is broken somehow.
  - Citation
```
public Citation(String path,
                char delimiter,
                String start)
```
    Construct a citation from a path, delimiter, and start marker, when the start marker and the end marker are the same.
    The path cannot be null.
    The start marker cannot contain the delimiter.
    
    Parameters:
    
    path - The pathname string for the file to quote. Not null.
    
    delimiter - The delimiter for path, markers.
    
    start - The start marker. If null or "", only path is useful.
    
    Throws:
    
    IllegalArgumentException - Path or marker is broken somehow.
  - Citation
```
public Citation(String path,
                char delimiter,
                String start,
                String end)
```
    Construct a citation from a path, delimiter, start marker, and end marker.
    The path cannot be null.
    The markers cannot contain the delimiter.
    
    Parameters:
    
    path - The pathname string for the file to quote. Not null.
    
    delimiter - The delimiter for path, markers.
    
    start - The start marker. If null or "", only path is useful.
    
    end - The end marker. If null or "", start is both.
    
    Throws:
    
    IllegalArgumentException - Path or marker is broken somehow.
- Method Detail
  - getPath
```
public String getPath()
```
    Returns the value of the path.
    
    Returns:
    
    The value of the path.
  - setPath
```
public void setPath(String path)
```
    Sets the pathname string for the file to quote.
    
    Parameters:
    
    path - The pathname string for the file to quote.
    
    Throws:
    
    IllegalArgumentException - Path cannot be null.
  - getDelimiter
```
public char getDelimiter()
```
    Returns the value of the delimiter.
    
    Returns:
    
    The value of the delimiter.
  - setDelimiter
```
public void setDelimiter(char delimiter)
```
    Sets the value of the delimiter.
    
    Parameters:
    
    delimiter - The delimiter for path, markers.
  - getStart
```
public String getStart()
```
    Returns the value of the start marker, which can be empty.
    
    Returns:
    
    The value of the start marker, which can be empty.
  - setStart
```
public void setStart(String start)
```
    Sets the value of the start marker, which must not contain the delimiter.
    
    Parameters:
    
    start - The value of the start marker.
    
    Throws:
    
    IllegalArgumentException - Start marker contains the delimiter.
  - getEnd
```
public String getEnd()
```
    Returns the value of the start marker, which can be empty.
    
    Returns:
    
    The value of the start marker, which can be empty.
  - setEnd
```
public void setEnd(String end)
```
    Sets the value of the end marker, which must not contain the delimiter.
    
    Parameters:
    
    end - The value of the end marker.
    
    Throws:
    
    IllegalArgumentException - End marker contains the delimiter.
  - toString
```
public String toString()
```
    Returns the string representation of this citation.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    The string representation of this citation.
  - valueOf
```
public static Citation valueOf(String citation,
                               String delimiter)
```
    Returns a Citation from the string representation.
    
    Parameters:
    
    citation - The string representation.
    
    delimiter - One of ":" or "%".
    
    Returns:
    
    A Citation corresponding to the string representation, or null if the string representation does not parse.
  - valueOf
```
public static Citation valueOf(String citation)
```
    Returns a Citation from the string representation, assuming the default delimiter, :.
    
    Parameters:
    
    citation - The string representation.
    
    Returns:
    
    A Citation corresponding to the string representation, or null if the string representation does not parse.

Class Citation

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Citation

Citation

Citation

Method Detail

getPath

setPath

getDelimiter

setDelimiter

getStart

setStart

getEnd

setEnd

toString

valueOf

valueOf