You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pdfbox.apache.org by le...@apache.org on 2022/11/06 13:09:21 UTC
svn commit: r1905094 - /pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/
Author: lehmi
Date: Sun Nov 6 13:09:21 2022
New Revision: 1905094
URL: http://svn.apache.org/viewvc?rev=1905094&view=rev
Log:
PDFBOX-4892: fix javadoc
Modified:
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDAbstractContentStream.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDAppearanceContentStream.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDDocument.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDDocumentCatalog.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPage.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPageContentStream.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPageTree.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PageLayout.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PageMode.java
pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/ResourceCache.java
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDAbstractContentStream.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDAbstractContentStream.java?rev=1905094&r1=1905093&r2=1905094&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDAbstractContentStream.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDAbstractContentStream.java Sun Nov 6 13:09:21 2022
@@ -117,7 +117,7 @@ abstract class PDAbstractContentStream i
* Sets the maximum number of digits allowed for fractional numbers.
*
* @see NumberFormat#setMaximumFractionDigits(int)
- * @param fractionDigitsNumber
+ * @param fractionDigitsNumber the maximum number of digits allowed for fractional numbers
*/
protected void setMaximumFractionDigits(int fractionDigitsNumber)
{
@@ -1307,7 +1307,7 @@ abstract class PDAbstractContentStream i
/**
* Begin a marked content sequence.
*
- * @param tag the tag
+ * @param tag the tag to be added to the content stream
* @throws IOException If the content stream could not be written
*/
public void beginMarkedContent(COSName tag) throws IOException
@@ -1317,11 +1317,10 @@ abstract class PDAbstractContentStream i
}
/**
- * Begin a marked content sequence with a reference to an entry in the page resources'
- * Properties dictionary.
+ * Begin a marked content sequence with a reference to an entry in the page resources' Properties dictionary.
*
- * @param tag the tag
- * @param propertyList property list
+ * @param tag the tag to be added to the content stream
+ * @param propertyList property list to be added to the content stream
* @throws IOException If the content stream could not be written
*/
public void beginMarkedContent(COSName tag, PDPropertyList propertyList) throws IOException
@@ -1344,7 +1343,7 @@ abstract class PDAbstractContentStream i
/**
* Set an extended graphics state.
*
- * @param state The extended graphics state.
+ * @param state The extended graphics state to be added to the content stream
* @throws IOException If the content stream could not be written.
*/
public void setGraphicsStateParameters(PDExtendedGraphicsState state) throws IOException
@@ -1356,10 +1355,11 @@ abstract class PDAbstractContentStream i
/**
* Write a comment line.
*
- * @param comment
+ * @param comment the comment to be added to the content stream
+ *
* @throws IOException If the content stream could not be written.
- * @throws IllegalArgumentException If the comment contains a newline. This is not allowed,
- * because the next line could be ordinary PDF content.
+ * @throws IllegalArgumentException If the comment contains a newline. This is not allowed, because the next line
+ * could be ordinary PDF content.
*/
public void addComment(String comment) throws IOException
{
@@ -1374,8 +1374,10 @@ abstract class PDAbstractContentStream i
/**
* Writes a real number to the content stream.
- * @param real
- * @throws java.io.IOException
+ *
+ * @param real the real number to be added to the content stream
+ *
+ * @throws IOException If the underlying stream has a problem being written to.
* @throws IllegalArgumentException if the parameter is not a finite number
*/
protected void writeOperand(float real) throws IOException
@@ -1400,8 +1402,9 @@ abstract class PDAbstractContentStream i
/**
* Writes an integer number to the content stream.
- * @param integer
- * @throws java.io.IOException
+ *
+ * @param integer the integer to be added to the content stream
+ * @throws IOException If the underlying stream has a problem being written to.
*/
protected void writeOperand(int integer) throws IOException
{
@@ -1411,8 +1414,9 @@ abstract class PDAbstractContentStream i
/**
* Writes a COSName to the content stream.
- * @param name
- * @throws java.io.IOException
+ *
+ * @param name the name to be added to the content stream
+ * @throws IOException If the underlying stream has a problem being written to.
*/
protected void writeOperand(COSName name) throws IOException
{
@@ -1422,38 +1426,31 @@ abstract class PDAbstractContentStream i
/**
* Writes a string to the content stream as ASCII.
- * @param text
- * @throws java.io.IOException
+ *
+ * @param text the text to be added to the content stream followed by a newline
+ * @throws IOException If the underlying stream has a problem being written to.
*/
protected void writeOperator(String text) throws IOException
{
- outputStream.write(text.getBytes(StandardCharsets.US_ASCII));
- outputStream.write('\n');
+ write(text);
+ writeLine();
}
/**
* Writes a string to the content stream as ASCII.
- * @param text
- * @throws java.io.IOException
+ *
+ * @param text the text to be added to the content stream
+ * @throws IOException If the underlying stream has a problem being written to.
*/
protected void write(String text) throws IOException
{
- outputStream.write(text.getBytes(StandardCharsets.US_ASCII));
+ writeBytes(text.getBytes(StandardCharsets.US_ASCII));
}
/**
- * Writes a byte[] to the content stream.
- * @param data
- * @throws java.io.IOException
- */
- protected void write(byte[] data) throws IOException
- {
- outputStream.write(data);
- }
-
- /**
* Writes a newline to the content stream as ASCII.
- * @throws java.io.IOException
+ *
+ * @throws IOException If the underlying stream has a problem being written to.
*/
protected void writeLine() throws IOException
{
@@ -1462,8 +1459,9 @@ abstract class PDAbstractContentStream i
/**
* Writes binary data to the content stream.
- * @param data
- * @throws java.io.IOException
+ *
+ * @param data as byte formatted to be added to the content stream
+ * @throws IOException If the underlying stream has a problem being written to.
*/
protected void writeBytes(byte[] data) throws IOException
{
@@ -1472,6 +1470,9 @@ abstract class PDAbstractContentStream i
/**
* Writes an AffineTransform to the content stream as an array.
+ *
+ * @param transform AffineTransfrom to be added to the content stream
+ * @throws IOException If the underlying stream has a problem being written to.
*/
private void writeAffineTransform(AffineTransform transform) throws IOException
{
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDAppearanceContentStream.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDAppearanceContentStream.java?rev=1905094&r1=1905093&r2=1905094&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDAppearanceContentStream.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDAppearanceContentStream.java Sun Nov 6 13:09:21 2022
@@ -77,10 +77,11 @@ public final class PDAppearanceContentSt
* Set the stroking color.
*
* <p>
- * The command is only emitted if the color is not null and the number of
- * components is > 0.
+ * The command is only emitted if the color is not null and the number of components is > 0.
*
* @param color The colorspace to write.
+ * @return true if the stroking color was set successfully
+ *
* @throws IOException If there is an error writing to the content stream.
* @see PDAbstractContentStream#setStrokingColor(PDColor)
*/
@@ -136,10 +137,11 @@ public final class PDAppearanceContentSt
* Set the non stroking color.
*
* <p>
- * The command is only emitted if the color is not null and the number of
- * components is > 0.
+ * The command is only emitted if the color is not null and the number of components is > 0.
*
* @param color The colorspace to write.
+ * @return true if the non stroking color was set successfully
+ *
* @throws IOException If there is an error writing to the content stream.
* @see PDAbstractContentStream#setNonStrokingColor(PDColor)
*/
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDDocument.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDDocument.java?rev=1905094&r1=1905093&r2=1905094&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDDocument.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDDocument.java Sun Nov 6 13:09:21 2022
@@ -886,11 +886,11 @@ public class PDDocument implements Close
}
/**
- * For internal PDFBox use when creating PDF documents: register a TrueTypeFont to make sure it
- * is closed when the PDDocument is closed to avoid memory leaks. Users don't have to call this
- * method, it is done by the appropriate PDFont classes.
+ * For internal PDFBox use when creating PDF documents: register a TrueTypeFont to make sure it is closed when the
+ * PDDocument is closed to avoid memory leaks. Users don't have to call this method, it is done by the appropriate
+ * PDFont classes.
*
- * @param ttf
+ * @param ttf the TrueTypeFont to be registered
*/
public void registerTrueTypeFontForClosing(TrueTypeFont ttf)
{
@@ -1410,6 +1410,8 @@ public class PDDocument implements Close
/**
* Returns the resource cache associated with this document, or null if there is none.
+ *
+ * @return the resource cache of the document
*/
public ResourceCache getResourceCache()
{
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDDocumentCatalog.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDDocumentCatalog.java?rev=1905094&r1=1905093&r2=1905094&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDDocumentCatalog.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDDocumentCatalog.java Sun Nov 6 13:09:21 2022
@@ -158,6 +158,8 @@ public class PDDocumentCatalog implement
/**
* Returns all pages in the document, as a page tree.
+ *
+ * @return PDPageTree providing all pages of the document
*/
public PDPageTree getPages()
{
@@ -209,6 +211,8 @@ public class PDDocumentCatalog implement
/**
* Returns the document's article threads.
+ *
+ * @return a list of all threads of the document
*/
public List<PDThread> getThreads()
{
@@ -455,6 +459,8 @@ public class PDDocumentCatalog implement
/**
* Returns the page display mode.
+ *
+ * @return the PageMode of the document, if not present PageMode.USE_NONE is returned
*/
public PageMode getPageMode()
{
@@ -489,6 +495,8 @@ public class PDDocumentCatalog implement
/**
* Returns the page layout.
+ *
+ * @return the PageLayout of the document, if not present PageLayout.SINGLE_PAGE is returned
*/
public PageLayout getPageLayout()
{
@@ -519,6 +527,8 @@ public class PDDocumentCatalog implement
/**
* Returns the document-level URI.
+ *
+ * @return the document level URI if present, otherwise null
*/
public PDURIDictionary getURI()
{
@@ -538,6 +548,8 @@ public class PDDocumentCatalog implement
/**
* Get the document's structure tree root, or null if none exists.
+ *
+ * @return the structure tree root if present, otherwise null
*/
public PDStructureTreeRoot getStructureTreeRoot()
{
@@ -557,6 +569,8 @@ public class PDDocumentCatalog implement
/**
* Returns the language for the document, or null.
+ *
+ * @return the language of the document if present, otherwise null
*/
public String getLanguage()
{
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPage.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPage.java?rev=1905094&r1=1905093&r2=1905094&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPage.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPage.java Sun Nov 6 13:09:21 2022
@@ -212,6 +212,8 @@ public class PDPage implements COSObject
/**
* Returns true if this page has one or more content streams.
+ *
+ * @return true if the page has a non empty content stream, otherwise false
*/
public boolean hasContents()
{
@@ -299,8 +301,10 @@ public class PDPage implements COSObject
}
/**
- * A rectangle, expressed in default user space units, defining the boundaries of the physical
- * medium on which the page is intended to be displayed or printed.
+ * A rectangle, expressed in default user space units, defining the boundaries of the physical medium on which the
+ * page is intended to be displayed or printed.
+ *
+ * @return the media box of the page
*/
public PDRectangle getMediaBox()
{
@@ -339,9 +343,10 @@ public class PDPage implements COSObject
}
/**
- * A rectangle, expressed in default user space units, defining the visible region of default
- * user space. When the page is displayed or printed, its contents are to be clipped (cropped)
- * to this rectangle.
+ * A rectangle, expressed in default user space units, defining the visible region of default user space. When the
+ * page is displayed or printed, its contents are to be clipped (cropped) to this rectangle.
+ *
+ * @return the cropbox of the page
*/
public PDRectangle getCropBox()
{
@@ -716,6 +721,8 @@ public class PDPage implements COSObject
/**
* Returns the resource cache associated with this page, or null if there is none.
+ *
+ * @return the resource cache of the current page
*/
public ResourceCache getResourceCache()
{
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPageContentStream.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPageContentStream.java?rev=1905094&r1=1905093&r2=1905094&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPageContentStream.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPageContentStream.java Sun Nov 6 13:09:21 2022
@@ -246,7 +246,7 @@ public final class PDPageContentStream e
@Deprecated
public void appendRawCommands(byte[] commands) throws IOException
{
- write(commands);
+ writeBytes(commands);
}
/**
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPageTree.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPageTree.java?rev=1905094&r1=1905093&r2=1905094&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPageTree.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PDPageTree.java Sun Nov 6 13:09:21 2022
@@ -243,9 +243,9 @@ public class PDPageTree implements COSOb
* Returns the page at the given index.
*
* @param index zero-based index
+ * @return the page at the given index
*
- * @throws IllegalStateException if the requested index isn't found or doesn't point to a valid
- * page dictionary
+ * @throws IllegalStateException if the requested index isn't found or doesn't point to a valid page dictionary
* @throws IndexOutOfBoundsException if the requested index is higher than the page count
*/
public PDPage get(int index)
@@ -422,8 +422,9 @@ public class PDPageTree implements COSOb
}
/**
- * Returns the number of leaf nodes (page objects) that are descendants of this root within the
- * page tree.
+ * Returns the number of leaf nodes (page objects) that are descendants of this root within the page tree.
+ *
+ * @return the number of leaf nodes, 0 if not present
*/
public int getCount()
{
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PageLayout.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PageLayout.java?rev=1905094&r1=1905093&r2=1905094&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PageLayout.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PageLayout.java Sun Nov 6 13:09:21 2022
@@ -72,6 +72,8 @@ public enum PageLayout
/**
* Returns the string value, as used in a PDF file.
+ *
+ * @return the string value
*/
public String stringValue()
{
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PageMode.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PageMode.java?rev=1905094&r1=1905093&r2=1905094&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PageMode.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/PageMode.java Sun Nov 6 13:09:21 2022
@@ -63,6 +63,8 @@ public enum PageMode
/**
* Returns the string value, as used in a PDF file.
+ *
+ * @return the string value
*/
public String stringValue()
{
Modified: pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/ResourceCache.java
URL: http://svn.apache.org/viewvc/pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/ResourceCache.java?rev=1905094&r1=1905093&r2=1905094&view=diff
==============================================================================
--- pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/ResourceCache.java (original)
+++ pdfbox/trunk/pdfbox/src/main/java/org/apache/pdfbox/pdmodel/ResourceCache.java Sun Nov 6 13:09:21 2022
@@ -36,72 +36,141 @@ public interface ResourceCache
{
/**
* Returns the font resource for the given indirect object, if it is in the cache.
+ *
+ * @param indirect the indirect reference of the font to be returned
+ * @return the cached instance of the referenced font, if available
+ *
+ * @throws IOException if the given indirect object could not be dereferenced
*/
PDFont getFont(COSObject indirect) throws IOException;
/**
* Returns the color space resource for the given indirect object, if it is in the cache.
+ *
+ * @param indirect the indirect reference of the colorspace to be returned
+ * @return the cached instance of the referenced colorspace, if available
+ *
+ * @throws IOException if the given indirect object could not be dereferenced
*/
PDColorSpace getColorSpace(COSObject indirect) throws IOException;
/**
- * Returns the external graphics state resource for the given indirect object, if it is in the
- * cache.
+ * Returns the extended graphics state resource for the given indirect object, if it is in the cache.
+ *
+ * @param indirect the indirect reference of the extended graphics state to be returned
+ * @return the cached instance of the referenced extended graphics state, if available
+ *
+ * @throws IOException if the given indirect object could not be dereferenced
*/
PDExtendedGraphicsState getExtGState(COSObject indirect);
/**
* Returns the shading resource for the given indirect object, if it is in the cache.
+ *
+ * @param indirect the indirect reference of the shading to be returned
+ * @return the cached instance of the referenced shading, if available
+ *
+ * @throws IOException if the given indirect object could not be dereferenced
*/
PDShading getShading(COSObject indirect) throws IOException;
/**
- *Returns the pattern resource for the given indirect object, if it is in the cache.
+ * Returns the pattern resource for the given indirect object, if it is in the cache.
+ *
+ * @param indirect the indirect reference of the pattern to be returned
+ * @return the cached instance of the referenced pattern, if available
+ *
+ * @throws IOException if the given indirect object could not be dereferenced
*/
PDAbstractPattern getPattern(COSObject indirect) throws IOException;
/**
* Returns the property list resource for the given indirect object, if it is in the cache.
+ *
+ * @param indirect the indirect reference of the property list to be returned
+ * @return the cached instance of the referenced property list, if available
+ *
+ * @throws IOException if the given indirect object could not be dereferenced
*/
PDPropertyList getProperties(COSObject indirect);
/**
* Returns the XObject resource for the given indirect object, if it is in the cache.
+ *
+ * @param indirect the indirect reference of the XObject to be returned
+ * @return the cached instance of the referenced XObject, if available
+ *
+ * @throws IOException if the given indirect object could not be dereferenced
*/
PDXObject getXObject(COSObject indirect) throws IOException;
/**
* Puts the given indirect font resource in the cache.
+ *
+ * @param indirect the indirect reference of the font to be cached
+ * @param font the font to be cached
+ *
+ * @throws IOException if the given indirect object could not be dereferenced
*/
void put(COSObject indirect, PDFont font) throws IOException;
/**
* Puts the given indirect color space resource in the cache.
+ *
+ * @param indirect the indirect reference of the colorspace to be cached
+ * @param font the colorspace to be cached
+ *
+ * @throws IOException if the given indirect object could not be dereferenced
*/
void put(COSObject indirect, PDColorSpace colorSpace) throws IOException;
/**
* Puts the given indirect extended graphics state resource in the cache.
+ *
+ * @param indirect the indirect reference of the extended graphics state to be cached
+ * @param font the extended graphics state to be cached
+ *
+ * @throws IOException if the given indirect object could not be dereferenced
*/
void put(COSObject indirect, PDExtendedGraphicsState extGState);
/**
* Puts the given indirect shading resource in the cache.
+ *
+ * @param indirect the indirect reference of the shading to be cached
+ * @param font the shading to be cached
+ *
+ * @throws IOException if the given indirect object could not be dereferenced
*/
void put(COSObject indirect, PDShading shading) throws IOException;
/**
* Puts the given indirect pattern resource in the cache.
+ *
+ * @param indirect the indirect reference of the pattern to be cached
+ * @param font the pattern to be cached
+ *
+ * @throws IOException if the given indirect object could not be dereferenced
*/
void put(COSObject indirect, PDAbstractPattern pattern) throws IOException;
/**
* Puts the given indirect property list resource in the cache.
+ *
+ * @param indirect the indirect reference of the property list to be cached
+ * @param font the property list to be cached
+ *
+ * @throws IOException if the given indirect object could not be dereferenced
*/
void put(COSObject indirect, PDPropertyList propertyList);
/**
* Puts the given indirect XObject resource in the cache.
+ *
+ * @param indirect the indirect reference of the XObject to be cached
+ * @param font the XObject to be cached
+ *
+ * @throws IOException if the given indirect object could not be dereferenced
*/
void put(COSObject indirect, PDXObject xobject) throws IOException;
}