org.lockss.pdf.PdfDocument Maven / Gradle / Ivy
Show all versions of lockss-core Show documentation
/*
* $Id$
*/
/*
Copyright (c) 2000-2016 Board of Trustees of Leland Stanford Jr. University,
all rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
STANFORD UNIVERSITY BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Except as contained in this notice, the name of Stanford University shall not
be used in advertising or otherwise to promote the sale, use or other dealings
in this Software without prior written authorization from Stanford University.
*/
package org.lockss.pdf;
import java.io.*;
import java.util.*;
import org.w3c.dom.Document;
/**
*
* Abstraction for a PDF document. In the PDF hierarchy represented by
* this package, a PDF document has zero or more PDF pages (
* {@link PdfPage}).
*
*
* Document-level metadata
*
*
* - {@link #getAuthor()} / {@link #setAuthor(String)} /
* {@link #unsetAuthor()}
* - {@link #getCreationDate()} / {@link #setCreationDate(Calendar)}
* / {@link #unsetCreationDate()}
* - {@link #getCreator()} / {@link #setCreator(String)} /
* {@link #unsetCreator()}
* - {@link #getKeywords()} / {@link #setKeywards(String)} /
* {@link #unsetKeywords()}
* - {@link #getLanguage()} / {@link #setLanguage(String)} /
* {@link #unsetLanguage()}
* - {@link #getModificationDate()} /
* {@link #setModificationDate(Calendar)} /
* {@link #unsetModificationDate()}
* - {@link #getProducer()} / {@link #setProducer(String)} /
* {@link #unsetProducer()}
* - {@link #getSubject()} / {@link #setSubject(String)} /
* {@link #unsetSubject()}
* - {@link #getTitle()} / {@link #setTitle(String)} /
* {@link #unsetTitle()}
* - {@link #getMetadataAsXmp()} / {@link #setMetadataFromXmp(Document)}
*
*
* Hierarchical
*
*
* - {@link #getNumberOfPages()} / {@link #getPage(int)} /
* {@link #getPages()} / {@link #removePage(int)}
*
*
* Structural
*
*
* - {@link #close()}
* - {@link #getTokenFactory()}
* - {@link #getTrailer()} / {@link #setTrailer(Map)}
* - {@link #save(OutputStream)}
*
*
* @author Thib Guicherd-Callin
* @since 1.56
*/
public interface PdfDocument {
/**
*
* Releases resources associated with this document when it is no
* longer in use. The behavior of this object if operations are
* performed on it after it is closed is undefined.
*
*
* @throws PdfException If there is a major error releasing
* resources associated with this object.
* @since 1.56
*/
void close() throws PdfException;
/**
*
* Retrieves the author field from the given document.
*
*
* @return The author field, or null if unset.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
String getAuthor() throws PdfException;
/**
*
* Retrieves the creation date field from the given document.
*
*
* @return The creation date field, or null if unset.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
Calendar getCreationDate() throws PdfException;
/**
*
* Retrieves the creator field from the given document.
*
*
* @return The creator field, or null if unset.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
String getCreator() throws PdfException;
/**
*
* Returns a PDF document factory instance suitable for this document.
*
*
* @return A PDF document factory instance.
* @since 1.70
*/
PdfDocumentFactory getDocumentFactory();
/**
*
* Retrieves the keywords field from the given document.
*
*
* @return The keywords field, or null if unset.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
String getKeywords() throws PdfException;
/**
*
* Retrieves the language field from the given document.
*
*
* @return The language field, or null if unset.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
String getLanguage() throws PdfException;
/**
*
* Retrieves the document metadata as a standalone string.
*
*
* Note that in PDF parlance, "metadata" is a field you can get and
* set, just like "author" is a field you can get and set.
*
*
* @return The metadata as a string, or null if unset.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
String getMetadata() throws PdfException;
/**
*
* Retrieves the document metadata as an XMP document.
*
*
* Note that in PDF parlance, "metadata" is a field you can get and
* set, just like "author" is a field you can get and set.
*
*
* @return The metadata as an XMP document, or null if
* unset.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
Document getMetadataAsXmp() throws PdfException;
/**
*
* Retrieves the modification date field from the given document.
*
*
* @return The creation date field, or null if unset.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
Calendar getModificationDate() throws PdfException;
/**
*
* Returns the number of pages in this document.
*
*
* @return The document's number of pages.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
int getNumberOfPages() throws PdfException;
/**
*
* Gets the page at the given zero-based index.
*
*
* @param index The page's index in the range from 0
* inclusive to {@link #getNumberOfPages()} exclusive.
* @return A {@link PdfPage} instance corresponding to the requested
* page.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
PdfPage getPage(int index) throws PdfException;
/**
*
* Gets a list of the pages in this document.
*
*
* @return A list of {@link PdfPage} instances
* @throws PdfException
* @since 1.56
*/
List getPages() throws PdfException;
/**
*
* Retrieves the producer field from the given document.
*
*
* @return The producer field, or null if unset.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
String getProducer() throws PdfException;
/**
*
* Retrieves the subject field from the given document.
*
*
* @return The subject field, or null if unset.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
String getSubject() throws PdfException;
/**
*
* Retrieves the title field from the given document.
*
*
* @return The title field, or null if unset.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
String getTitle() throws PdfException;
/**
*
* Retrieves the document's trailer dictionary.
*
*
* @return The non-null trailer dictionary, possibly
* empty.
* @throws PdfException If PDF processing fails.
* @since 1.56
* @see PdfToken
*/
Map getTrailer() throws PdfException;
/**
*
* Removes the page at the given zero-based index from this
* document.
*
*
* This affects the result of {@link #getNumberOfPages()},
* {@link #getPage(int)} and {@link #getPages()}.
*
*
* @param index The page's index in the range from 0
* inclusive to {@link #getNumberOfPages()} exclusive.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void removePage(int index) throws PdfException;
/**
*
* Externalizes this document into the given output stream. The
* output stream is not closed at the end of this call; it is the
* caller's responsibility to close it.
*
*
* @param outputStream An output stream.
* @throws IOException If the operation fails on the I/O level.
* @throws PdfException If the operation fails on the PDF level.
* @since 1.56
*/
void save(OutputStream outputStream) throws IOException, PdfException;
/**
*
* Sets the author field in the given document.
*
*
* @param author The non-null author string.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void setAuthor(String author) throws PdfException;
/**
*
* Sets the creation date field in the given document.
*
*
* @param author The non-null creation date.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void setCreationDate(Calendar date) throws PdfException;
/**
*
* Sets the creator field in the given document.
*
*
* @param author The non-null creator string.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void setCreator(String creator) throws PdfException;
/**
*
* Sets the keywords field in the given document.
*
*
* @param author The non-null keywords string.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void setKeywords(String keywords) throws PdfException;
/**
*
* Sets the language field in the given document.
*
*
* @param author The non-null language string.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void setLanguage(String language) throws PdfException;
/**
*
* Sets the document metadata as a standalone string.
*
*
* Note that in PDF parlance, "metadata" is a field you can get and
* set, just like "author" is a field you can get and set.
*
*
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void setMetadata(String metadata) throws PdfException;
/**
*
* Sets the document metadata as an XMP document.
*
*
* Note that in PDF parlance, "metadata" is a field you can get and
* set, just like "author" is a field you can get and set.
*
*
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void setMetadataFromXmp(Document xmpDocument) throws PdfException;
/**
*
* Sets the modification date field in the given document.
*
*
* @param author The non-null modification date.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void setModificationDate(Calendar date) throws PdfException;
/**
*
* Sets the producer field in the given document.
*
*
* @param author The non-null producer string.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void setProducer(String producer) throws PdfException;
/**
*
* Sets the subject field in the given document.
*
*
* @param author The non-null subject string.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void setSubject(String subject) throws PdfException;
/**
*
* Sets the title field in the given document.
*
*
* @param author The non-null title string.
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void setTitle(String title) throws PdfException;
/**
*
* Retrieves the document's trailer dictionary.
*
*
* @param trailerMapping The trailer dictionary.
* @throws PdfException If PDF processing fails.
* @since 1.56
* @see PdfToken
*/
void setTrailer(Map trailerMapping) throws PdfException;
/**
*
* Unsets the author field in the given document, such that
* {@link #getAuthor()} returns null.
*
*
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void unsetAuthor() throws PdfException;
/**
*
* Unsets the creation date field in the given document, such that
* {@link #getCreationDate()} returns null.
*
*
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void unsetCreationDate() throws PdfException;
/**
*
* Unsets the creator field in the given document, such that
* {@link #getCreator()} returns null.
*
*
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void unsetCreator() throws PdfException;
/**
*
* Unsets the keywords field in the given document, such that
* {@link #getKeywords()} returns null.
*
*
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void unsetKeywords() throws PdfException;
/**
*
* Unsets the language field in the given document, such that
* {@link #getLanguage()} returns null.
*
*
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void unsetLanguage() throws PdfException;
/**
*
* Unsets the document metadata, such that {@link #getMetadata()}
* returns null.
*
*
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void unsetMetadata() throws PdfException;
/**
*
* Unsets the modification date field in the given document, such
* that {@link #getModificationDate()} returns null.
*
*
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void unsetModificationDate() throws PdfException;
/**
*
* Unsets the producer field in the given document, such that
* {@link #getProducer()} returns null.
*
*
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void unsetProducer() throws PdfException;
/**
*
* Unsets the subject field in the given document, such that
* {@link #getSubject()} returns null.
*
*
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void unsetSubject() throws PdfException;
/**
*
* Unsets the title field in the given document, such that
* {@link #getTitle()} returns null.
*
*
* @throws PdfException If PDF processing fails.
* @since 1.56
*/
void unsetTitle() throws PdfException;
}