Improving support and documentation

We are always looking for ways to improve support and documentation for our users. So you will see 2 new changes this week.

Support

We have used the support forums built into Fogbugz. This integrates really nicely with our issue tracking software but it does not seem to get any developments from FogCreek software and is starting to feel dated. So we have kept the archived questions but moved the forum onto a new site using WordPress. At  http://support.idrsolutions.com/ you will find our brand new forums. This has lots of features missing in Fogbugz (better spam control, ability to upload files,etc). We hope you will give it a try…..

Documentation

We have had several requests to make the documentation better so we have looked at adding a class, ApiForJPedal which lists all public methods in the key classes, documents them or advises you which not to use. It will also make it much easier to track any API changes. The rest of this article is an example of what it will look like – so what do you think?

/**
         * PdfDecoderServer class
         *
         * org.jpedal.PdfDecoderServer
         *
         * Provides a class to open PDF files and extract Data and rasterize
         */
    public void Example_PdfDecoderServer(){
 
        //constructors
 
        /*
         * recommend usage
         */
        PdfDecoderServer serverDecoder=new PdfDecoderServer();
 
        /*
         * Allows user to set true/false. Set to false if only using for extraction and not rendering
         */
        PdfDecoderServer serverDecoder2=new PdfDecoderServer(booleanValue);
 
        //public methods you can use
 
        /*
         * See if file open - may not be open if user interrupted open or problem was encountered
         */
        booleanValue = serverDecoder.isOpen();
 
        /*
         * Get an XML file containing information about the marked content of a pdf document
         */
        documentValue = serverDecoder.getMarkedContent();
 
        /*
         * Get the current page rotation (in addition to rotation in file) in degrees
         * So if user turns page by 90º, value will be 90
         */
        intValue = serverDecoder.getDisplayRotation();
 
        /*
         * Get the current page number
         */
        intValue = serverDecoder.getPageNumber();
 
        /*
         * Set the page's rotation
         * A value of 90 will set the rotation to 90º
         */
        serverDecoder.setDisplayRotation(intValue);
 
        /*
         * Not currently implemented
         */
        displayValue = serverDecoder.getPages();
 
        /*
         * Get the page number for the last page decoded
         * Only use in SingleDisplay mode
         */
        intValue = serverDecoder.getlastPageDecoded();
 
        /*
         * Get the details on page for type (defined in org.jpedal.constants.PageInfo) or null if there are no values
         * Unrecognised key will throw a RunTime exception
         * Null will be returned if JPedal is not clear on result
         */
        iteratorValue = serverDecoder.getPageInfo(intValue);
 
        /*
         * Get an object containg the data for the outlines
         */
        outlineDataValue = serverDecoder.getOutlineData();
 
        /*
         * Track if file is still loaded in background
         */
        booleanValue = serverDecoder.isLoadingLinearizedPDF();
 
        /*
         * Get type of alignment for the pages if they're smaller than the panel
         */
        intValue = serverDecoder.getPageAlignment();
 
        /*
         * Set wether width data is embedded
         */
        PdfDecoderServer.init(booleanValue);
 
        /*
         * Remove all static elements
         * 
         * Only call when completely finished with JPedal as they will not be reinitialised
         */
        PdfDecoderServer.disposeAllStatic();
 
        /*
         * Remove all items from memory
         * Call disposeAllStatic() if you wish to clear all static objects as well
         */
        serverDecoder.dispose();
 
        /*
         * Close the current PDF file and release all resources/delete any temporary files
         */
        serverDecoder.closePdfFile();
 
        /*
         * Show if PDF document contains an outline
         */
        booleanValue = serverDecoder.hasOutline();
 
        /*
         * Get a high resolution image of the page at page number intValue
         */
        try {
            bufferedImageValue = serverDecoder.getPageAsHiRes(intValue);
        } catch (PdfException ex) {
 
        }
 
        /*
         * Get a high resolution image of the page at page number intValue (1st Parameter)
         * Override the static settings in modifyJPedalParameters for this instance only using mapValue (2nd Parameter)
         */
        try {
            bufferedImageValue = serverDecoder.getPageAsHiRes(intValue, mapValue);
        } catch (PdfException ex) {
 
        }
 
        /*
         * Get a high resolution image of the page at page number intValue (1st Parameter)
         * Override the static settings in modifyJPedalParameters for this instance only using mapValue (2nd Parameter)
         * Set if image is transparent or not using booleanValue (3rd Parameter)
         */
        try {
            bufferedImageValue = serverDecoder.getPageAsHiRes(intValue, mapValue, booleanValue);
        } catch (PdfException ex) {
 
        }
 
        /*
         * Get a high resolution image of the page at page number intValue (1st Parameter)
         * Set if image is transparent or not using booleanValue (2nd Parameter)
         */
        try {
            bufferedImageValue = serverDecoder.getPageAsHiRes(intValue, booleanValue);
        } catch (PdfException ex) {
 
        }
 
        /*
         * Get an image of the page at page number intValue
         */
        try {
            bufferedImageValue = serverDecoder.getPageAsImage(intValue);
        } catch (PdfException ex) {
 
        }
 
        /*
         * Get an image of the page at intValue with transparency set
         */
        try {
            bufferedImageValue = serverDecoder.getPageAsTransparentImage(intValue);
        } catch (PdfException ex) {
 
        }
 
        /*
         * Get the upscale factor applied to the last generated High Resolution image
         * If no upscaling applied a negative value will be returned and should be ignored
         */
        floatValue = serverDecoder.getHiResUpscaleFactor();
 
        /*
         * Clear objects to reclaim memory once written out
         * Set wether image data should be cleared as well with boolenValue
         */
        serverDecoder.flushObjectValues(booleanValue);
 
        /*
         * get data for the images
         */
        pdfImageDataValue = serverDecoder.getPdfImageData();
 
        /*
         * get data for the background images
         */
        pdfImageDataValue = serverDecoder.getPdfBackgroundImageData();
 
        /*
         * Set render mode for onscreen display (ie RENDERTEXT,RENDERIMAGES - add together to combine)
         * Only required if you do not wish to show all objects on screen (default is all)
         */
        serverDecoder.setRenderMode(intValue);
 
        /*
         * Set extraction mode telling JPedal what to extract (ie TEXT,RAWIMAGES,FINALIMAGES - add together to combine)
         * See org.jpedal.examples for specific extraction examples
         */
        serverDecoder.setExtractionMode(intValue);
 
        /*
         * Alter certain values in JPdeal such as Color
         * All Color and text highlighting values are static and common across the JVM
         */
        try {
            serverDecoder.modifyNonstaticJPedalParameters(mapValue);
        } catch (PdfException ex) {
 
        }
 
        /**
         * Alter certain values in JPedal such as Color
         *
         * If you are using getPageAsHiRes() AFTER passing additional parameters into JPedal using the static method
         * PdfDecoder.modifyJPedalParameters(), getPageAsHiRes() wont necessarily be thread safe.
         * If you want to use getPageAsHiRes() and pass in additional parameters in a thread safe manner, please use the method
         * getPageAsHiRes(int pageIndex, Map params) or getPageAsHiRes(int pageIndex, Map params, boolean isTransparent) and
         * pass the additional parameters in directly to the getPageAsHiRes() method without calling PdfDecoder.modifyJPedalParameters() first.
         *
         * Please see http://files.idrsolutions.com/samplecode/org/jpedal/examples/images/ConvertPagesToHiResImages.java.html for example usage
         * All Color and text highlighting values except page colour are static and common across the JVM
         */
        try {
            PdfDecoderServer.modifyJPedalParameters(mapValue);
        } catch (PdfException ex) {
 
        }
 
        /*
         * Get file metadata
         */
        pdfFileInformationValue = serverDecoder.getFileInformationData();
 
        /*
         * Get handle on PDFFactory which adjusts display size so it matches the size in Acrobat
         */
        dPIFactoryValue = serverDecoder.getDPIFactory();
 
        /*
         * Initialise panel and set size to fit PDF page with rotation set to the default
         * To keep existing scaling setting set scaling value to -1
         */
        serverDecoder.setPageParameters(floatValue, intValue);
 
        /*
         * Initialise panel and set size to fit PDF page with rotation set to the default
         * To keep existing scaling setting set scaling value to -1
         * Set rotation to draw page with intValue (3rd Parameter)
         */
        serverDecoder.setPageParameters(floatValue, intValue, intValue);
 
        /*
         * Get access to the PDF file
         */
        pdfObjectReaderValue = serverDecoder.getIO();
 
        /**
         * Decode a page - intValue
         * Page must be between 1 and PdfDecoder.getPageCount()
         * Will kill off if already running
         * returns a negative page if trying to open a linearized page that is not yet available
         */
        try {
            serverDecoder.decodePage(intValue);
        } catch (Exception ex) {
 
        }
 
        /*
         * See if page is available in Linearized mode
         * All pages are available in non-linearized mode
         */
        booleanValue = serverDecoder.isPageAvailable(intValue);
 
        /*
         * allow user to add graphical content on top of page - for display ONLY
         * Additional calls will overwrite current settings
         * 
         * ONLY works in SingleDisplay mode
         */
        try {
            serverDecoder.drawAdditionalObjectsOverPage(intValue, intArrayValue, colorArrayValue, objectArrayValue);
        } catch (PdfException ex) {
 
        }
 
        /*
         * Remove all additional graphical content from the page that are only for display
         * 
         * ONLY works in SingleDisplay mode
         */
        try {
            serverDecoder.flushAdditionalObjectsOnPage(intValue);
        } catch (PdfException ex) {
 
        }
 
        /*
         * Check if High Resolutions images will be used for the display
         */
        booleanValue = serverDecoder.isHiResScreenDisplay();
 
        /*
         * Use High Resolution images for a higher quality display
         * Downside is it is slower and uses more memory (default is false)
         * 
         * Not implemented in OS version
         */
        serverDecoder.useHiResScreenDisplay(booleanValue);        
 
        /*
         * Get the page count of the current PDF file
         */
        intValue = serverDecoder.getPageCount();
 
        /*
         * Check if the current PDF file is encrypted
         * If file is encrypted and not viewable (isFileViewable() is false) - a user specified password is needed
         */
        booleanValue = serverDecoder.isEncrypted();
 
        /*
         * Show if encryption password has been supplied or if a certificate has been set
         */
        booleanValue = serverDecoder.isPasswordSupplied();
 
        /*
         * Checks if the file can be viewed
         * If not, a password needs to be provided
         */
        booleanValue = serverDecoder.isFileViewable();
 
        /*
         * Checks if content can be extracted
         */
        booleanValue = serverDecoder.isExtractionAllowed();
 
        /*
         * Set a password for encryption.
         */
        try {
            serverDecoder.setEncryptionPassword(stringValue);
        } catch (PdfException ex) {
 
        }
 
        /**
         * Open a byte stream containing the PDF file and extract key info
         * from the PDF file so we can decode any pages.
         * Does not actually decode the pages themselves.
         * 
         * By default files over 16384 bytes are cached to disk
         * This can be altered by setting PdfFileReader.alwaysCacheInMemory to a maximum size or -1 to always keep in memory
         */
        try {
            serverDecoder.openPdfArray(byteArrayValue);
        } catch (PdfException ex) {
 
        }
 
        /*
         * Open file using Certificate and key.
         */
        try {
            serverDecoder.openPdfFile(stringValue, certificateValue, privateKeyValue);
        } catch (PdfException ex) {
 
        }
 
        /**
         * Open the PDF file (1st Parameter) and extract key info from the PDF file so we can
         * decode any pages and sets a password also (2nd Parameter).
         * Does not actually decode the pages themselves.
         * Also reads the form data. 
         * You must explicitly close your stream!!
         */
        try {
            serverDecoder.openPdfFileFromStream(objectValue, stringValue);
        } catch (PdfException ex) {
 
        }
 
        /**
         * Open the PDF file (1st Parameter) and extract key info from the PDF file so we can
         * decode any pages.
         * Does not actually decode the pages themselves.
         * Also reads the form data.
         * You must explicitly close any open files with closePdfFile() or Java will not release all the memory
         */
        try {
            serverDecoder.openPdfFile(stringValue);
        } catch (PdfException ex) {
 
        }
 
        /**
         * Open the PDF file (1st Parameter) and extract key info from the PDF file so we can
         * decode any pages and sets password also (2nd Parameter).
         * Does not actually decode the pages themselves. 
         * Also reads the form data.
         * You must explicitly close any open files with closePdfFile() or Java will not release all the memory
         */
        try {
            serverDecoder.openPdfFile(stringValue, stringValue);
        } catch (PdfException ex) {
 
        }
 
        /**
         * Open the PDF file via URL (1st Parameter) and extract key info from the PDF file so we
         * can decode any pages.
         * Does not actually decode the pages themselves
         * Also reads the form data - Based on an idea by Peter Jacobsen
         * 
         * You must explicitly close any open files with closePdfFile() or Java will not release all the memory
         *
         * If booleanValue is true (2nd Parameter), method will return a true value once Linearized part is read
         */
        try {
            booleanValue = serverDecoder.openPdfFileFromURL(stringValue, booleanValue);
        } catch (PdfException ex) {
 
        }
 
        /**
         * Open the PDF file via URL (1st Parameter) and extract key info from the PDF file so we
         * can decode any pages.
         * Does not actually decode the pages themselves.
         * Also reads the form data - Based on an idea by Peter Jacobsen.
         * 
         * You must explicitly close any open files with closePdfFile() or Java will not release all the memory.
         *
         * If booleanValue is true (2nd Parameter), method will return a true value once Linearized part is read.
         * 
         * A password is passed in as parameter stringValue (3rd Parameter)
         */
        try {
            booleanValue = serverDecoder.openPdfFileFromURL(stringValue, booleanValue, stringValue);
        } catch (PdfException ex) {
 
        }
 
        /**
         * Open the PDF file via InputStream (1st Parameter) and extract key info from the PDF file so we
         * can decode any pages.
         * Does not actually decode the pages themselves.
         * You must explicitly close any open files with closePdfFile() or Java will not release all the memory.
         *
         * If boolean supportLinearized is true, method will return a true value once Linearized part is read.
         * (we recommend use you false unless you know exactly what you are doing)
         * IMPORTANT NOTE: If the stream does not contain enough bytes, test for Linearization may fail.
         */
        try {
            booleanValue = serverDecoder.openPdfFileFromInputStream(inputStreamValue, booleanValue);
        } catch (PdfException ex) {
 
        }
 
        /**
         * Open the PDF file via URL (1st Parameter) and extract key info from the PDF file so we
         * can decode any pages.
         * Does not actually decode the pages themselves.
         * Also reads the form data - Based on an idea by Peter Jacobsen.
         * You must explicitly close any open files with closePdfFile() or Java will not release all the memory.
         *
         * If boolean supportLinearized is true, method will return a true value once Linearized part is read
         */
        try {
            booleanValue = serverDecoder.openPdfFileFromURL(stringValue, booleanValue, assignString);
        } catch (PdfException ex) {
 
        }
 
        /**
         * Checks if text extraction is set to XML or pure text.
         */
        booleanValue = serverDecoder.isXMLExtraction();
 
        /**
         * XML extraction is the default - pure text extraction is much faster.
         */
        serverDecoder.useTextExtraction();
 
        /**
         * XML extraction is the default - pure text extraction is much faster.
         */
        serverDecoder.useXMLExtraction();
 
        /**
         * Remove all displayed objects for JPanel display (wipes current page).
         */
        serverDecoder.clearScreen();
 
        /**
         * Allows user to cache large objects to disk to avoid memory issues.
         * 
         * Setting minimum size in bytes (of uncompressed stream) above certain objects
         * will ensure that they will be stored on disk if possible.
         * (default is -1 bytes which is all objects stored in memory)
         * Must be set before file opened.
         */
        serverDecoder.setStreamCacheSize(intValue);
 
        /**
         * Checks if embedded fonts are present on the page just decoded.
         */
        booleanValue = serverDecoder.hasEmbeddedFonts();
 
        /**
         * Checks if embedded fonts are contained and used within the whole PDF document.
         */
        try {
            booleanValue = serverDecoder.PDFContainsEmbeddedFonts();
        } catch (Exception ex) {
 
        }
 
        /**
         * Find out the page number of a page by providing a reference for PDF object.
         */
        intValue = serverDecoder.getPageFromObjectRef(stringValue);
 
        /**
         * Get a list of the fonts used on the current page that are decoded or null.
         * Can be of type PdfDictionary.Font or PdfDictionary.Image.
         */
        stringValue = serverDecoder.getInfo(intValue);
 
        /**
         * Get access to the Forms renderer object if needed.
         */
        acroRendererValue = serverDecoder.getFormRenderer();
 
        /**
         * Get access to Javascript object if needed.
         */
        javascriptValue = serverDecoder.getJavaScript();
 
        /**
         * Get any errors or other messages while calling decodePage().
         * If the string length is zero there were no problems.
         */
        stringValue = serverDecoder.getPageDecodeReport();
 
        /**
         * Get object which provides access to file images and name.
         */
        objectStoreValue = serverDecoder.getObjectStore();
 
        /**
         * Get decoder options as an object for the cases where a value is needed externally and can't be static.
         */
        decoderOptionsValue = serverDecoder.getDecoderOptions();
 
        /**
         * Get an object containing the grouped text of the last decoded page.
         * If no page has been decoded, a Runtime exception is thrown to warn the user.
         *
         * Please see org.jpedal.examples.text for example code.
         */
        try {
            pdfGroupingAlgorithmsValue = serverDecoder.getGroupingObject();
        } catch (PdfException ex) {
 
        }
 
        /**
         * Get an object containing grouped text from background groupings.
         * 
         * Please see org.jpedal.examples.text for example code.
         */
        pdfGroupingAlgorithmsValue = serverDecoder.getBackgroundGroupingObject();
 
        /**
         * Get PDF version of the file.
         */
        stringValue = serverDecoder.getPDFVersion();
 
        /**
         * Check to see if all images have been processed.
         * Used to check if a problem is suspected with some images.
         */
        booleanValue = serverDecoder.hasAllImages();
 
        /**
         * Check the state of flags in class org.jpedal.parser.DecoderStatus.
         */
        booleanValue = serverDecoder.getPageDecodeStatus(intValue);
 
        /**
         * Get page statuses.
         * (flags in class org.jpedal.parser.DecoderStatus)
         */
        stringValue = serverDecoder.getPageDecodeStatusReport(intValue);
 
        /**
         * Get the name of the currently open PDF file.
         */
        stringValue = serverDecoder.getFileName();
 
        /**
         * Checks if the currently open PDF file is a PDF form.
         */
        booleanValue = serverDecoder.isForm();
 
        /**
         * Get TextLines object that contains information on the lines of text for highlighting.
         */
        textLinesValue = serverDecoder.getTextLines();
 
        /**
         * Get the width of the PDF page.
         * 
         * It now includes any scaling factor you have set
         */
        intValue = serverDecoder.getPDFWidth();
 
        /**
         * Get the height of the PDF page.
         * 
         * It now includes any scaling factor you have set
         */
        intValue = serverDecoder.getPDFHeight();
 
        /**
         * Get view mode used for display.
         * (SINGLE_PAGE,CONTINUOUS,FACING,CONTINUOUS_FACING)
         * Not implemented in OS versions.
         */
        intValue = serverDecoder.getDisplayView();
 
        /**
         * Get the current scaling value used internally.
         */
        floatValue = serverDecoder.getScaling();
 
        /*
         * 
         * AVOID USING THESE METHODS AS THEY ARE NOT PART OF THE API!!
         * 
         */
 
        /**
         * NOT PART OF API
         */
        serverDecoder.resetViewableArea();
 
        /**
         * NOT PART OF API
         */
        pdfDataValue = serverDecoder.getPdfBackgroundData();
 
        /*
         * NOT PART OF THE API.
         */
        try {
            pdfDataValue = serverDecoder.getPdfData();
        } catch (PdfException ex) {
 
        }
 
        /**
         * NOT PART OF THE API.
         */
        documentValue = serverDecoder.getOutlineAsXML();
 
        /**
         * NOT PART OF THE API.
         */
        pdfPageDataValue = serverDecoder.getPdfPageData();
 
        /**
         * NOT PART OF THE API.
         */
        serverDecoder.setExtractionMode(intValue, floatValue);
 
        /*
         * NOT PART OF THE API.
         */
        serverDecoder.waitForDecodingToFinish();
 
        /**
         * NOT PART OF THE API.
         */
        dynamicVectorRendererValue = serverDecoder.getDynamicRenderer();
 
        /*
         * NOT PART OF THE API.
         */
        try {
            serverDecoder.decodePageInBackground(intValue);
        } catch (Exception ex) {
 
        }
 
        /**
         * NOT PART OF THE API.
         */
        objectValue = serverDecoder.getJPedalObject(intValue);
 
        /**
         * NOT PART OF THE API.
         */
        serverDecoder.setPageMode(intValue);
 
        /**
         * NOT PART OF THE API.
         */
        serverDecoder.setObjectStore(objectStoreValue);
 
        /**
         * NOT PART OF THE API.
         */
        serverDecoder.addExternalHandler(objectValue, intValue);
 
        /**
         * NOT PART OF THE API.
         */
        objectValue = serverDecoder.getExternalHandler(intValue);
 
    }

If you’re a first-time reader, or simply want to be notified when we post new articles and updates, you can keep up to date by social media (TwitterFacebook and Google+) or the Blog RSS.

Related Posts:

The following two tabs change content below.

Mark Stephens

System Architect and Lead Developer at IDRSolutions
Mark Stephens has been working with Java and PDF since 1999 and has diversified into HTML5, SVG and JavaFX. He also enjoys speaking at conferences and has been a Speaker at user groups, Business of Software, Seybold and JavaOne conferences. He has a very dry sense of humor and an MA in Medieval History for which he has not yet found a practical use.
Markee174

About Mark Stephens

Mark Stephens has been working with Java and PDF since 1999 and has diversified into HTML5, SVG and JavaFX. He also enjoys speaking at conferences and has been a Speaker at user groups, Business of Software, Seybold and JavaOne conferences. He has a very dry sense of humor and an MA in Medieval History for which he has not yet found a practical use.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>