BCL easyPDF SDK
easyPDF SDK Usermanual
PDF Creator Programming API  |  Download Free Trial  |  Contact Us to Purchase

Native Java Printer API

Usage

The native Java API is very similar to the JACOB API, with only a few distinct differences.

First, you need to import com.bcl.easypdf.printer.*;.

The jar file is called easypdf.jar, and it is under c:\Program Files\Common Files\BCL Technologies\easyPDF 8\easypdf.jar.

Oracle JAVA SE Development Kit 1.5 or above is required.

COM exceptions were replaced by the new PrinterException.

The Printer class has a dispose() method, which means it really needs to be deterministically disposed. Relying on the garbage collector is not recommended, because each Printer object launches a separate worker process. Even though these worker processes are sleeping while not executing a function, they are still in the memory, and only really quit when the Printer object is disposed.

The Printer object should be treated as if it were an expensive resource, such as a file, mutex, or a database connection. If you would like to know what really is inside Printer, it is just a named pipe. However, the worker process is programmed to only quit when the pipe is closed.

If the customer's application crashes, the system automatically closes all pipes belonging to the process, which means all related worker processes automatically quit as well.

The minimal Java sample code looks like this:
(Note: all Native Java sample code and declarations have a light red background color)

Printer printer = new Printer();
try
{
   printer.getPrintJob().PrintOut("c:\\test\\input.docx", "c:\\test\\output.pdf");
}
catch(PrinterException e)
{
   System.out.println(e);
}
finally
{
   printer.dispose();
}

The key here is the finally block, which calls dispose().

Printer's constructor is designed to never throw exceptions. That's because it does not launch a worker process and does not create a named pipe, it merely initializes a few variables to their default values. In other words, creating a Printer object is extremely lightweight, like creating a Color object.

However, as soon as you do anything else, even getting a property, it instantly launches a worker process.

Notification Events

Notification events are new to the Java API, as they did not exist in JACOB. Here is an example that catches OnPageStart, which is called before printing each page:

SampleEvents handler = new SampleEvents();
Printer printer = new Printer();
try
{
   PrintJob printJob = printer.getPrintJob();
   printer.getPrintJobMonitor().events = handler;
   printJob.PrintOut("c:\\test\\input.docx", "c:\\test\\output.pdf");
}
catch(PrinterException e)
{
   System.out.println(e);
}
finally
{
   printer.dispose();
}

SampleEvents is your class, where you have a chance to respond to all events:

import com.bcl.easypdf.printer.*;

public class SampleEvents implements IPrintJobMonitorEvents
{
        public prnMonitorResponse OnPrinterInitEventHandler(int uID, PrintJobInfo jobInfo)
        {
                return prnMonitorResponse.PRN_MON_CONTINUE_CONVERSION;
        }

        public prnMonitorResponse OnPrinterUpdateEventHandler(int uID, PrintJobInfo jobInfo)
        {
                return prnMonitorResponse.PRN_MON_CONTINUE_CONVERSION;
        }

        public prnMonitorResponse OnPrinterStartEventHandler(int uID)
        {
                return prnMonitorResponse.PRN_MON_CONTINUE_CONVERSION;
        }

        public prnMonitorResponse OnPageStartEventHandler(int uID, int pageNumber)
        {
                System.out.print("Page ");
                System.out.print(pageNumber + 1);
                System.out.print("...");
                return prnMonitorResponse.PRN_MON_CONTINUE_CONVERSION;
        }

        public prnMonitorResponse OnPrinterEndEventHandler(int uID, int errCode)
        {
                return prnMonitorResponse.PRN_MON_CONTINUE_CONVERSION;
        }
}

Note that even if you just want to handle a single event, you are still required to handle them all at once.

Server-Side Operation

Printing from the server side has always required easyPDF Loader, a special service that helps execute functions under a different user account.

The Native Java SDK offers two possible solutions for server-side printing. One is called the Loader Service, and the other one is called Impersonation.

Customers who are printing from a web server or a system service should study both alternatives, and decide which one they prefer.

PrinterMonitor

PrinterMonitor does not exist in the native Java API at this moment.

Note that most customers do not need PrinterMonitor. Its sole purpose is to enable File > Print in a desktop environment. It was not designed for server-side operation anyway.

If you just want to get notification events while printing, please use PrintJobMonitor, which is part of the native Java API.

If you really need PrinterMonitor, please contact us at support@bcltechnologies.com, or visit our support page.